feat(infraestrutura): adiciona plugin infraestrutura (agents, skills, knowledge e metadados do projeto)
This commit is contained in:
@@ -0,0 +1,147 @@
|
||||
---
|
||||
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á
|
||||
Reference in New Issue
Block a user