agent-package — a pasta src/mcp/

1 · Em uma frase

Esta pasta é o coração do /mcp: recebe tools/list e tools/call do protocolo, decide quem pode ver/chamar o quê, roda a tool (ou encaminha para um servidor MCP externo), mede, audita e sela a resposta no envelope único da casa.

Ela não é o servidor HTTP (isso é src/mcp-server.ts + src/routes/mcp.ts), não é o registro das tools (isso mora em src/tools/** e entra por registry.ts), e não guarda estado: o gateway é stateless, cada request monta o seu servidor mcp-server.ts:136. Duas famílias de tool convivem aqui:

2 · Mapa dos arquivos

16 arquivos, 3.399 linhas. A leitura natural é por camada: quem declara, quem cataloga, quem despacha, quem observa, e as faces do protocolo (resources, prompts, instructions).

3 · O fluxo de um tools/call

routes/mcp.ts ── createMcpServer() ──▶ mcp-server.ts:136
                                            │
                       handler de tools/call mcp-server.ts:159
                       acha a entrada no catálogo (:163)
                                            ▼
                          callCatalogTool  tool-call.ts:53
                                            │
          ┌─────────────────────────────────┴─────────────────────────────────┐
   entry.kind === "builtin"                                          entry.kind === "proxied"
          │                                                                       │
  instrumentToolCall (tool-call.ts:72)                                  instrumentToolCall (:76)
          │                                                                       │
   callBuiltin (:153) — roda DENTRO do callback                     callProxied (proxy-call.ts:53)
   ├─ checkToolAccess (:166) ─ negado → toolError (:167)               resultado INTACTO (sem selo;
   ├─ args.parse (:169)                                                  salvo aviso/falha)
   ├─ handler (:170)
   └─ catch → toolError (:174) ◀── tool-envelope.ts:42
          │
   seal (:97) → sealEnvelope (tool-kit.ts:283)
   meta = { tool: entry.name, version: entry.tool.version } (:98)
          │
   auditToolCall (:79) — pula se isError (:139) ou readOnlyHint (:140)

1. O servidor é por request. routes/mcp.ts chama createMcpServer mcp-server.ts:136 — um Protocol do SDK serve um transporte por vez e o transporte é stateless (por isso tools/listChanged é false, mcp-server.ts:147-149). O caro e compartilhado é o catálogo pré-computado, não o servidor.
2. O handler acha a entrada e delega. tools/call é registrado com um schema que só prende o método mcp-server.ts:90; a entrada sai do catálogo :163 e o despacho é callCatalogTool :168.
3. No despacho tool-call.ts:53: preenche o projeto default :59-62 e bifurca em built-in ou proxied :67-78.
4. Ordem real no caminho built-in: instrumentToolCall envolve o callback :72-74, e dentro dele correm checkToolAccess :166 (negado → toolError :167, antes de parsear argumentos), o parse do zod :169 e o handler :170. A ordem cronológica é instrumenta → checa → executa → sela.
5. Exceção é capturada no despacho, não no handler. O try/catch de callBuiltin :168-175 converte tudo em toolError tool-envelope.ts:42, que classifica (ZodError → VALIDATION_ERROR, AppError → o próprio código, Prisma P2025/P2003, resto → INTERNAL_ERROR), avisa a instrumentação (de onde sai o errorId) e monta o corpo de falha.
6. O selo. De volta ao despacho, a função privada seal tool-call.ts:97 chama sealEnvelope :101 (definida em tool-kit.ts:283) com meta = { tool, version } :98 — o único ponto que carimba as duas no envelope selado (o catálogo também as publica em _meta, mas não sela resposta).
7. Auditoria. auditToolCall :79 grava linha em audit_events só em escrita bem-sucedida: pula se isError :139 ou se a built-in é readOnlyHint :140. Toda proxied conta como escrita, sem exceção — anotação de servidor externo não é garantia.
8. Fora do toolError: erro de protocolo do JSON-RPC passa pelo withInternalErrorGuard mcp-server.ts:232-245 (McpError segue; o resto vira -32603 com errorId).

4 · O envelope (TB-22 / ADR-016)

Antes da TB-22 conviviam seis formas de resposta. Hoje toda built-in responde com uma só, montada num lugar só (o despacho) — decisão registrada no ADR-016 e normatizada no PADRAO-MCP.md §2.

{
  "ok": true,
  "data": { … o que a tool produziu … },
  "meta": {
    "tool": "agentpack_project_list",
    "version": "1.2.0"
  }
}

{
  "ok": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid tool arguments",
    "retryable": false, "hint": "…", "errorId": "…"
  },
  "meta": { … }
}
// + isError: true no resultado

5 · Quem fala com quem

O que a pasta importa de fora

Grafo interno (acíclico)

base (não importam nada de dentro):
  tool-kit · toolsets · instructions · json-schema · resources

camadas em cima:
  tool-access ─▶ tool-kit
  registry     ─▶ tool-kit, toolsets          default-project ─▶ tool-kit
  instrument   ─▶ tool-access
  catalog      ─▶ registry, tool-access, tool-kit, toolsets, default-project, json-schema
  tool-envelope─▶ instrument, tool-kit        meta-tools ─▶ tool-access, tool-kit, toolsets
  metrics      ─▶ catalog                     prompts ─▶ instructions, resources, toolsets
  proxy-call   ─▶ catalog, instrument, tool-envelope, tool-access, tool-kit
  tool-call     ─▶ catalog, proxy-call, instrument, tool-envelope, tool-access, default-project, tool-kit

sinks (nada dentro de mcp/ importa): tool-call · meta-tools · metrics · prompts

Quem importa desta pasta

41 arquivos fora de src/mcp/ importam dela: src/tools/ 30 (core 10, github 11, render 8, raiz 1) · src/services/ 7 · src/routes/ 2 (health.ts, mcp.ts) · src/middleware/ 1 (authz.ts) · src/mcp-server.ts. É por isso que a pasta é o centro de gravidade do app: quase tudo que é tool passa por aqui.

6 · Design vs. dívida

Regra da casa ao ler esta pasta: separe o que foi decidido do que está em aberto. A lista canônica das pendências é o PADRAO-MCP.md §8 “O que ainda está em aberto” PADRAO-MCP.md:384 — os itens 1–5, 8, 9 e 10 são dívida; o 6 é decisão registrada; o 7 é decisão de produto.

7 · Para mexer aqui