From bce12944ae6d1885db06368db59ec385174d67be Mon Sep 17 00:00:00 2001 From: Claude Code Date: Wed, 26 Aug 2026 19:55:44 +0100 Subject: [PATCH] =?UTF-8?q?mcp-dev=20v3.0.1:=20esclarecer=20pacote=20v2=20?= =?UTF-8?q?=E2=89=A0=20API=20v2=20e=20politica=20de=20migracao/terceiros?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- infraestrutura/skills/mcp-dev/SKILL.md | 16 +++++++++++++--- 1 file changed, 13 insertions(+), 3 deletions(-) diff --git a/infraestrutura/skills/mcp-dev/SKILL.md b/infraestrutura/skills/mcp-dev/SKILL.md index 3f927b5..75494ea 100644 --- a/infraestrutura/skills/mcp-dev/SKILL.md +++ b/infraestrutura/skills/mcp-dev/SKILL.md @@ -10,7 +10,7 @@ Skill para criação, configuração e gestão de servidores MCP customizados. ## Regra de Ouro — obrigatória, sem excepção silenciosa -Todo MCP novo, e toda a edição estrutural de um MCP existente, tem de cumprir isto: +Todo MCP próprio da Descomplicar — novo, existente, ou sob edição estrutural — tem de cumprir isto. A regra aplica-se ao código que nós escrevemos; ver §Política para MCPs de terceiros mais abaixo. Um MCP que falhe qualquer ponto abaixo está fora de conformidade e tem de ser migrado (não "deixado como está" por funcionar). 1. **SDK oficial v2** ([ts.sdk.modelcontextprotocol.io/v2](https://ts.sdk.modelcontextprotocol.io/v2/)) — pacotes `@modelcontextprotocol/server` (+ `@modelcontextprotocol/client` só em testes/evaluations). **`@modelcontextprotocol/sdk` (v1) está descontinuado nesta casa** — nunca instalar, nunca copiar código de um MCP antigo que o use sem migrar primeiro. API de alto nível `McpServer` + `registerTool`/`registerResource`/`registerPrompt` — a API de baixo nível `Server` + `setRequestHandler(Schema, …)` está **proibida** (reintroduz classes de bugs que o v2 elimina por desenho, incluindo o anti-padrão de capabilities manuais que causava o erro 471). 2. **Transporte HTTP obrigatório** — `createMcpHandler` (Streamable HTTP), tipicamente montado com `@modelcontextprotocol/express` + `@modelcontextprotocol/node`. `stdio` (`serveStdio`) só é aceitável quando o host tem de lançar o processo directamente e não existe gateway — nesse caso documentar a excepção no README do MCP com a razão concreta, e usar sempre `serveStdio` do SDK v2 (nunca `StdioServerTransport` manual). @@ -19,6 +19,14 @@ Todo MCP novo, e toda a edição estrutural de um MCP existente, tem de cumprir Se qualquer um destes 4 pontos não puder ser cumprido, **parar e perguntar** antes de prosseguir — não decidir sozinho por uma alternativa mais rápida. +**⚠️ Armadilha — pacote v2 ≠ API v2.** Importar `@modelcontextprotocol/server` não garante conformidade: um MCP só está conforme se usar a API de alto nível `McpServer` + `registerTool`. Se o código (mesmo importando o pacote v2) chamar `setRequestHandler` ou instanciar `Server`, está a usar a API de baixo nível proibida — é não-conforme. Verificação: `grep -oE 'setRequestHandler|McpServer\(|registerTool' dist/*.js | sort | uniq -c` — deve mostrar `McpServer` + `registerTool` e **zero** `setRequestHandler`. Caso real: `mcp-desk-project-minimal` (26-08-2026) importava só o pacote v2 mas usava `setRequestHandler` — não-conforme apesar do pacote certo. + +## Política para MCPs de terceiros e migração de existentes + +**MCPs de terceiros** (pacotes npm/uvx que apenas instalamos e corremos — ex.: `deepl`, `lighthouse`, `notebooklm`, `puppeteer`, `echarts`, `pixabay`, `authentik`, `spaceship`, `replicate`, `context7`, `gitea-mcp`): a Regra de Ouro **não lhes aplica** — não controlamos o código deles e não os podemos migrar (só dar fork ou substituir). Correm como estão, em v1. Só substituir se uma alternativa v2/nativa (ex.: Python FastMCP) fizer sentido para os mais usados — decisão por caso, não política global. + +**MCPs próprios já existentes em v1** (ex.: `desk-crm-v3`, `moloni`, `mem0`, `wikijs`, `cwp`, `reonic`, `imap-enterprise`, `youtube-research`, `carl-mcp`, `mcp-wayland`, `gestix-mcp` stdio): estão fora de conformidade e devem ser migrados para v2. Antes de cada migração em produção: **fazer snapshot do código e dist actual** (git commit ou cópia) para rollback rápido se o build v2 partir algo. Migrar é mudança de API, não bump de versão — é trabalho por servidor, não automatizável em massa. + ## Contexto NotebookLM Consultar ANTES de executar: @@ -242,7 +250,9 @@ npm run eval:ci # build + evaluations (para CI/CD) --- -## Changelog +### v3.0.1 (2026-08-26) +- **Esclarecida a armadilha "pacote v2 ≠ API v2"** — importar `@modelcontextprotocol/server` não basta; um MCP só está conforme com `McpServer` + `registerTool`, nunca `setRequestHandler`/`Server`. Motivo: `mcp-desk-project-minimal` importava o pacote v2 mas usava a API de baixo nível proibida. Incluído comando de verificação rápida. +- **Política de migração explícita** — a Regra de Ouro aplica-se a todos os MCPs próprios (novos, existentes, edição estrutural); existentes em v1 devem ser migrados, com snapshot para rollback antes de tocar produção. MCPs de terceiros (npm/uvx) ficam fora do âmbito — não os controlamos, não os migramos. ### v3.0.0 (2026-08-19) - **SDK TypeScript v2 obrigatório** (`@modelcontextprotocol/server`, ver [ts.sdk.modelcontextprotocol.io/v2](https://ts.sdk.modelcontextprotocol.io/v2/)) — `@modelcontextprotocol/sdk` v1 descontinuado nesta casa. @@ -293,7 +303,7 @@ npm run eval:ci # build + evaluations (para CI/CD) --- -*Skill v3.0.0 | Descomplicar® | 2026-08-19* +*Skill v3.0.1 | Descomplicar® | 2026-08-26* ---