feat(infraestrutura): mcp-dev v3.0 — SDK TypeScript v2 e transporte HTTP obrigatórios
Regra de Ouro adicionada ao topo da skill: SDK v2 (@modelcontextprotocol/server), API de alto nível McpServer+registerTool (API de baixo nível Server+setRequestHandler proibida), transporte HTTP obrigatório (stdio só como excepção documentada), e proibição explícita de interpolação de dados em comandos shell/SSH. Motivado por revisão de segurança ao mcp-kivicare (19-08-2026): 8 bugs reais corrigidos em produção, incluindo injecção de comandos shell crítica e hooks nativos disparados com o tipo errado. Regras adicionadas para nunca mais acontecer em silêncio. - SKILL.md: nova secção Regra de Ouro, API/annotations/capabilities actualizadas para v2, transportes HTTP obrigatório, changelog v3.0.0, healing log com os 3 bugs mais graves do incidente. - references/templates.md: reescrito para createMcpHandler + createMcpExpressApp (HTTP) e serveStdio (excepção), package.json com pacotes v2. - references/best-practices.md: capabilities/annotations/error handling actualizados para API v2, checklist de segurança com regra anti-injecção de comandos shell, tabela de transportes com HTTP obrigatório. - references/evaluation-guide.md: script de evaluations reescrito para Client+StreamableHTTPClientTransport in-process (sem porta/socket). - infraestrutura: 1.2.2 -> 1.3.0
This commit is contained in:
@@ -65,38 +65,27 @@ Cada tool deve declarar as suas annotations para orientar o modelo:
|
||||
| `idempotentHint` | boolean | Resultado idêntico em múltiplas chamadas |
|
||||
| `openWorldHint` | boolean | Interage com sistemas externos/web |
|
||||
|
||||
**Inferência automática com `inferAnnotations()`:**
|
||||
|
||||
```typescript
|
||||
import { inferAnnotations } from '@modelcontextprotocol/sdk/server/utils.js';
|
||||
|
||||
// Inferir automaticamente a partir do nome e descrição da tool
|
||||
const annotated = inferAnnotations(tool);
|
||||
```
|
||||
**v2 não tem `inferAnnotations()`** (era só v1) — declarar sempre `annotations` inline na config de `registerTool`, como no exemplo acima. Nunca inventar um passo de inferência que o SDK actual não tem.
|
||||
|
||||
---
|
||||
|
||||
## Capabilities Obrigatórias (Regra de Ouro)
|
||||
## Capabilities — derivadas automaticamente (nunca declarar à mão)
|
||||
|
||||
`McpServer` (SDK v2) deriva `capabilities` de `registerTool`/`registerResource`/`registerPrompt` automaticamente — **não existe** `capabilities: {...}` nem `setRequestHandler(...)` na API de alto nível obrigatória.
|
||||
|
||||
```typescript
|
||||
// ERRADO: capabilities incompletas -> erro 471
|
||||
capabilities: { tools: {} }
|
||||
// ERRADO — API de baixo nível v1, proibida nesta casa
|
||||
import { Server } from '@modelcontextprotocol/sdk/server/index.js';
|
||||
const server = new Server({...}, { capabilities: { tools: {} } }); // causava erro 471 em v1
|
||||
server.setRequestHandler(ListToolsRequestSchema, async () => ({...}));
|
||||
|
||||
// CORRECTO: sempre declarar as três, mesmo vazias
|
||||
capabilities: {
|
||||
tools: {},
|
||||
resources: {},
|
||||
prompts: {}
|
||||
}
|
||||
// CORRECTO — API de alto nível v2, a única aceite
|
||||
import { McpServer } from '@modelcontextprotocol/server';
|
||||
const server = new McpServer({ name: 'mcp-<nome>', version: '1.0.0' });
|
||||
server.registerTool('get_customer', { description: '...', inputSchema: z.object({...}) }, async (args) => {...});
|
||||
```
|
||||
|
||||
**Handlers mínimos obrigatórios:**
|
||||
```typescript
|
||||
server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: [...] }));
|
||||
server.setRequestHandler(ListResourcesRequestSchema, async () => ({ resources: [] }));
|
||||
server.setRequestHandler(ListPromptsRequestSchema, async () => ({ prompts: [] }));
|
||||
server.setRequestHandler(CallToolRequestSchema, async (req) => { ... });
|
||||
```
|
||||
O erro 471 (capabilities incompletas) era uma armadilha da API de baixo nível v1 — deixa de poder acontecer ao usar `McpServer`/`registerTool` do v2. Se algum código ainda usa `Server` + `setRequestHandler(Schema, ...)`, é sinal de que está a reintroduzir o v1 — migrar antes de continuar (ver `SKILL.md` §Regra de Ouro).
|
||||
|
||||
---
|
||||
|
||||
@@ -148,7 +137,7 @@ return {
|
||||
## Validação com Zod
|
||||
|
||||
```typescript
|
||||
import { z } from 'zod';
|
||||
import * as z from 'zod/v4';
|
||||
|
||||
const GetCustomerSchema = z.object({
|
||||
customer_id: z.number().int().positive(),
|
||||
@@ -156,42 +145,40 @@ const GetCustomerSchema = z.object({
|
||||
date_from: z.string().regex(/^\d{4}-\d{2}-\d{2}$/).optional(),
|
||||
});
|
||||
|
||||
// No handler
|
||||
const validated = GetCustomerSchema.parse(args);
|
||||
// Zod lança ZodError automaticamente se inválido
|
||||
server.registerTool(
|
||||
'get_customer',
|
||||
{ description: 'Obtém dados de um cliente', inputSchema: GetCustomerSchema },
|
||||
async ({ customer_id, include_invoices, date_from }) => {
|
||||
// O SDK v2 já validou e rejeitou argumentos inválidos antes de este handler correr —
|
||||
// nunca chamar `.parse()`/`.safeParse()` outra vez aqui, é redundante e esconde a
|
||||
// mensagem de erro accionável que o SDK já produziu.
|
||||
// ... lógica aqui
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Error Handling
|
||||
|
||||
```typescript
|
||||
server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
const { name, arguments: args } = request.params;
|
||||
No v2, um handler que atira (`throw`) é convertido automaticamente num resultado `isError: true` — não existe `setRequestHandler(CallToolRequestSchema, ...)` para envolver manualmente (isso é API de baixo nível v1). Ver [errors.md](https://ts.sdk.modelcontextprotocol.io/v2/servers/errors.md) para o detalhe completo (`ProtocolError` para resources/prompts, subclasses tipadas).
|
||||
|
||||
try {
|
||||
const result = await handleTool(name, args);
|
||||
return result;
|
||||
} catch (error) {
|
||||
if (error instanceof z.ZodError) {
|
||||
```typescript
|
||||
server.registerTool(
|
||||
'get_customer',
|
||||
{ description: 'Obtém dados de um cliente pelo ID', inputSchema: z.object({ customer_id: z.number() }) },
|
||||
async ({ customer_id }) => {
|
||||
const customer = await db.getCustomer(customer_id);
|
||||
if (!customer) {
|
||||
// Devolver isError explicitamente dá controlo total sobre o `content`
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: `Parâmetros inválidos:\n${error.errors.map(e => ` - ${e.path.join('.')}: ${e.message}`).join('\n')}`
|
||||
}],
|
||||
isError: true
|
||||
content: [{ type: 'text', text: `Cliente ${customer_id} não encontrado. Verificar: 1) ID existe na BD 2) Permissões de acesso` }],
|
||||
isError: true,
|
||||
};
|
||||
}
|
||||
|
||||
return {
|
||||
content: [{
|
||||
type: 'text',
|
||||
text: `Erro: ${error instanceof Error ? error.message : String(error)}`
|
||||
}],
|
||||
isError: true
|
||||
};
|
||||
}
|
||||
});
|
||||
return { content: [{ type: 'text', text: `Cliente: ${customer.name}` }], structuredContent: customer };
|
||||
},
|
||||
);
|
||||
```
|
||||
|
||||
---
|
||||
@@ -199,7 +186,9 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
|
||||
## Logging
|
||||
|
||||
```typescript
|
||||
// SEMPRE usar console.error (não console.log — interfere com stdio)
|
||||
// SEMPRE usar console.error (não console.log — interfere com o framing stdio quando o
|
||||
// MCP corre em modo stdio excepcional; em HTTP não framing-crítico mas mantém-se a
|
||||
// convenção para consistência entre os dois entry points)
|
||||
console.error(`[MCP:${toolName}] Início — params: ${JSON.stringify(args)}`);
|
||||
console.error(`[MCP:${toolName}] Concluído em ${duration}ms`);
|
||||
```
|
||||
@@ -210,12 +199,14 @@ console.error(`[MCP:${toolName}] Concluído em ${duration}ms`);
|
||||
|
||||
- [ ] SQL injection: inputs validados antes de entrar em queries?
|
||||
- [ ] Interpolação directa em SQL proibida sem validação
|
||||
- [ ] **Comandos shell/SSH: nunca interpolar dados do utilizador num comando (`ssh ... "$var"`, `exec(\`cmd ${var}\`)`); dados sempre por STDIN (texto ou base64)** — regra escrita depois de uma injecção de comandos real corrigida em produção (`mcp-kivicare`, 19-08-2026)
|
||||
- [ ] Transacções em operações multi-query relacionadas
|
||||
- [ ] Recursos (pool.connect) têm `finally` com release
|
||||
- [ ] Cleanup (ROLLBACK) tem try-catch próprio
|
||||
- [ ] `crypto.randomBytes()` em vez de `Math.random()`
|
||||
- [ ] Secrets em variáveis de ambiente, nunca hardcoded
|
||||
- [ ] `pnpm audit` sem vulnerabilidades críticas
|
||||
- [ ] Se o MCP faz ponte para um sistema nativo (WP-CLI, API externa, …): o formato exacto de escrita (ex.: JSON vs PHP serialize, hooks disparados com objecto vs escalar) foi confirmado por leitura do código-fonte real do sistema alvo, nunca assumido
|
||||
|
||||
**Grep de validação:**
|
||||
```bash
|
||||
@@ -227,6 +218,9 @@ grep -rn 'Math.random' src/
|
||||
|
||||
# connect() sem finally
|
||||
grep -rn '\.connect()' src/
|
||||
|
||||
# Comandos shell/ssh interpolados — qualquer resultado exige revisão manual
|
||||
grep -rn 'exec(\|execSync(\|spawn(.*sh\b' src/ | grep -i '\${'
|
||||
```
|
||||
|
||||
---
|
||||
@@ -257,9 +251,9 @@ tblleads, tblleads_sources, tblstaff, tbltaskstimers, tblexpenses
|
||||
|
||||
| Transporte | Estado | Uso |
|
||||
|------------|--------|-----|
|
||||
| StreamableHTTP | Recomendado | Novos MCPs, acesso remoto |
|
||||
| stdio | Válido | Claude Code local, scripts |
|
||||
| SSE | Deprecated | Retrocompatibilidade apenas |
|
||||
| Streamable HTTP (SDK v2) | **Obrigatório** | Todos os MCPs novos — acesso remoto, gateway |
|
||||
| stdio (SDK v2, `serveStdio`) | Excepção documentada | Só quando o host lança o processo directamente e não há gateway — justificar no README |
|
||||
| SSE | Deprecated | Retrocompatibilidade apenas — nunca em MCP novo |
|
||||
|
||||
**Portas HTTP reservadas (3200+):**
|
||||
|
||||
@@ -284,4 +278,4 @@ tblleads, tblleads_sources, tblstaff, tbltaskstimers, tblexpenses
|
||||
|
||||
---
|
||||
|
||||
*best-practices.md v2.0 | 2026-03-10*
|
||||
*best-practices.md v3.0 | 2026-08-19*
|
||||
|
||||
Reference in New Issue
Block a user