mcp-dev v3.0.1: esclarecer pacote v2 ≠ API v2 e politica de migracao/terceiros

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*
 
 ---