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

# /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](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-MCP-Desenvolvimento.md) — Guia oficial v2.4
- [PROC-MCP-Troubleshooting-Erro-471.md](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/PROC-MCP-Troubleshooting-Erro-471.md)
- [PROC-MCP-Google-Auth.md](file:///media/ealmeida/Dados/Hub/06-Operacoes/Procedimentos/D7-Tecnologia/MCP/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:**
```typescript
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:
```typescript
import { inferAnnotations } from '@modelcontextprotocol/sdk/server/utils.js';
const annotated = inferAnnotations(tool);
```

**Capabilities — sempre completas (anti-erro 471):**
```typescript
capabilities: { tools: {}, resources: {}, prompts: {} }
```

**Dual format de resposta:**
```typescript
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:**
```typescript
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:**
```bash
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á