Emanuel Almeida
6b3a6f2698
- All SKILL.md files now <500 lines (avg reduction 69%) - Detailed content extracted to references/ subdirectories - Frontmatter standardised: only name + description (Anthropic standard) - New skills: brand-guidelines, spec-coauthor, report-templates, skill-creator - Design skills: anti-slop guidelines, premium-proposals reference - Removed non-standard frontmatter fields (triggers, version, author, category) Plugins affected: infraestrutura, marketing, dev-tools, crm-ops, gestao, core-tools, negocio, perfex-dev, wordpress, design-media Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
277 lines
8.5 KiB
Markdown
277 lines
8.5 KiB
Markdown
---
|
|
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.
|
|
---
|
|
|
|
# /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á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:**
|
|
```bash
|
|
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):**
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"<nome>": { "type": "http", "url": "http://127.0.0.1:32XX/mcp" }
|
|
}
|
|
}
|
|
```
|
|
|
|
**~/.claude.json (stdio — local):**
|
|
```json
|
|
{
|
|
"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*
|