claude-plugins/infraestrutura/skills/mcp-dev/SKILL.md

name, description

name	description
mcp-dev	Desenvolvimento e teste de servidores MCP — criação, configuração e gestão de MCPs customizados seguindo os padrões Descomplicar com transporte StreamableHTTP.

/mcp-dev - Desenvolvimento de MCPs

Skill para criação, configuração e gestão de servidores MCP customizados.

Contexto NotebookLM

Consultar ANTES de executar:

mcp__notebooklm__notebook_query({
  notebook_id: "73102308-70ef-403e-9be9-eae0cfc62d55",
  query: "<adaptar ao contexto do pedido>"
})

Procedimentos obrigatórios — consultar antes de criar/modificar MCPs:

• PROC-MCP-Desenvolvimento.md — Guia oficial v2.4
• PROC-MCP-Troubleshooting-Erro-471.md
• PROC-MCP-Google-Auth.md

Regra #48: Novos MCPs são desenvolvidos no container dev (server:"dev", path /root/Dev/<nome-mcp>). Após validação, mover para /home/ealmeida/mcp-servers/ em produção.

---

Comandos

Comando	Descrição
/mcp-dev create <nome>	Criar scaffold TypeScript completo
/mcp-dev config <nome>	Configurar MCP em ~/.claude.json
/mcp-dev test <nome>	Testar conexão e listar ferramentas
/mcp-dev eval <nome>	Executar evaluations do MCP
/mcp-dev docs <nome>	Gerar documentação Obsidian
/mcp-dev list	Listar MCPs em ~/mcp-servers/
/mcp-dev status	Estado dos MCPs activos na sessão

---

Workflow de 4 Fases

Fase 1: Research

1. Consultar NotebookLM (notebook acima)
2. Verificar MCPs existentes — evitar duplicação
3. Identificar ferramentas necessárias e nomear segundo padrão
4. Definir transporte: HTTP (recomendado) ou stdio
5. Criar spike/PoC se tecnologia desconhecida

Nomenclatura de tools: {serviço}_{acção}_{recurso} em snake_case, máx. 40 caracteres.

# Correcto
get_customer_notes, create_project_task, list_invoice_items

# Errado
getCustomerNotes (camelCase), get_customer_notes_with_all_billing_details (>40 chars)

Fase 2: Implementation

1. Scaffold no container dev: /root/Dev/<nome-mcp>/
2. Implementar tools com annotations obrigatórias e validação Zod
3. Definir capabilities completas (tools + resources + prompts)
4. Responses em dual format: Markdown (text) + JSON (structuredContent)
5. Erros accionáveis: causa + próximos passos

Annotations obrigatórias em cada tool:

annotations: {
  readOnlyHint: true,       // não modifica estado
  destructiveHint: false,   // não é destrutiva
  idempotentHint: true,     // mesmo resultado em chamadas repetidas
  openWorldHint: false,     // opera em sistema fechado (interno)
}

Usar inferAnnotations() do SDK para inferência automática:

import { inferAnnotations } from '@modelcontextprotocol/sdk/server/utils.js';
const annotated = inferAnnotations(tool);

Capabilities — sempre completas (anti-erro 471):

capabilities: { tools: {}, resources: {}, prompts: {} }

Dual format de resposta:

return {
  content: [{ type: 'text', text: `# Cliente ${d.name}\n**Email:** ${d.email}` }],
  structuredContent: { id: d.id, name: d.name, email: d.email }
};

Erros accionáveis:

return {
  content: [{
    type: 'text',
    text: [
      `Erro ao obter cliente ID ${id}.`,
      `Causa: ${error.message}`,
      `Verificar: 1) ID existe  2) Permissões  3) Conexão BD`
    ].join('\n')
  }],
  isError: true
};

Fase 3: Review

1. Checklist de segurança (ver references/best-practices.md)
2. pnpm audit — sem vulnerabilidades críticas
3. Validar limites de nomes de tools (máx. 40 chars)
4. Testar build: npm run build
5. Testar manualmente: echo '{"jsonrpc":"2.0","method":"tools/list","id":1}' | node dist/index.js
6. Documentar decisões em ADR se necessário

Grep de validação rápida:

grep -rn '`.*\${.*}`' src/ | grep -i 'select\|insert\|update\|delete'
grep -rn 'Math.random' src/

Fase 4: Evaluations

Criar e executar testes estruturados antes do deploy.

10 evaluations obrigatórias por MCP (ver references/evaluation-guide.md):

#	Pergunta	Cenário
1	Tool principal funciona com input válido?	Input mínimo válido
2	Input inválido retorna erro accionável?	Parâmetro obrigatório em falta
3	Recurso inexistente retorna erro claro?	ID=99999
4	Operações idempotentes são estáveis?	Chamada repetida com mesmos params
5	Operações destrutivas apagam correctamente?	Delete em recurso existente
6	Tools read-only não alteram estado?	Get + verificar estado antes/depois
7	Paginação funciona com listas grandes?	1000+ registos, página 2
8	Auth inválida é rejeitada graciosamente?	API key removida
9	structuredContent é consistente com text?	Comparar campos nos dois formatos
10	Performance < 5s em p95?	10 chamadas consecutivas

Executar:

npm run eval       # evaluations
npm run eval:ci    # build + evaluations (para CI/CD)

---

Estrutura de Projecto

/root/Dev/mcp-<nome>/          # Desenvolvimento (container dev)
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts               # Entry point stdio
│   ├── index-http.ts          # Entry point HTTP
│   └── tools/
│       └── index.ts           # Definição de tools
├── eval/
│   └── run-evals.ts           # Evaluations automáticas
├── .env.example
├── README.md
└── .gitignore

/home/ealmeida/mcp-servers/mcp-<nome>/   # Produção

---

Configuração

~/.claude.json (HTTP — recomendado):

{
  "mcpServers": {
    "<nome>": { "type": "http", "url": "http://127.0.0.1:32XX/mcp" }
  }
}

~/.claude.json (stdio — local):

{
  "mcpServers": {
    "<nome>": { "command": "node", "args": ["/home/ealmeida/mcp-servers/<nome>/dist/index.js"] }
  }
}

---

Transportes

Transporte	Estado	Quando usar
StreamableHTTP	Recomendado	Novos MCPs, acesso remoto, gateway
stdio	Válido	Claude Code local, scripts únicos
SSE	Deprecated	Retrocompatibilidade apenas

---

MCPs Existentes (Referência)

MCP	Path	Tools	Transporte
desk-crm-v3	~/mcp-servers/desk-crm-v3/	150+	SSE :3100
memory-supabase	~/mcp-servers/memory-supabase/	5	SSE :3101
google-workspace	(npm package)	42	stdio
filesystem	(npm package)	8	stdio

---

Referências

Ficheiro	Conteúdo
references/best-practices.md	Nomenclatura, annotations, segurança, SQL Perfex
references/evaluation-guide.md	Guia completo de evaluations, script automatizado
references/templates.md	Templates TypeScript prontos (stdio, HTTP, systemd)

Agente especializado: mcp-protocol-developer — desenvolvimento complexo, debug, optimização.

---

Changelog

v2.0.0 (2026-03-10)

• Refactorização: SKILL.md de 1163 para <500 linhas (progressive disclosure)
• Fase 4: Evaluations adicionada ao workflow (padrão mcp-builder Anthropic)
• Nomenclatura tools: {serviço}_{acção}_{recurso} snake_case documentada
• Annotations obrigatórias (readOnlyHint, destructiveHint, idempotentHint, openWorldHint)
• inferAnnotations() mencionado como padrão automático
• Dual format de resposta (JSON + Markdown) documentado
• Erros accionáveis com causa + próximos passos
• Extracto para references/: best-practices, evaluation-guide, templates

v1.3.0 (2026-01-31)

• HTTP StreamableHTTP como padrão oficial
• SSE marcado como deprecated
• Checklist de segurança (audit 164 tools)

v1.2.0 (2026-01-27)

• Template SSE com http nativo
• systemd service template

v1.0.0 (2026-01-27)

• Versão inicial

---

Quando NÃO Usar

• Para tarefas fora do domínio de desenvolvimento MCP
• Quando outra skill mais específica está disponível
• Para operações simples que não requerem MCP

Protocolo

1. Consultar NotebookLM e PROCs relevantes
2. Executar as 4 fases: Research -> Implementation -> Review -> Evaluations
3. Validar resultados antes de concluir
4. Reportar status e próximos passos

---

Skill v2.0.0 | Descomplicar® | 2026-03-10