🏗️ A ponte do seu sistema

No módulo 2.2 a ponte leu runtime/exemplos/agenda.csv e runtime/exemplos/erp-vendas.csv. Esses arquivos imitam o que um sistema sem API entrega: uma exportação.

O primeiro passo é achar esse arquivo no seu sistema. Procure nos menus por "Exportar", "Relatórios" ou "Salvar como CSV". No ERP do cliente da Sônia, é o relatório de vendas do mês, salvo numa pasta fixa.

Como ler o desenho: as setas azuis vão sempre da esquerda para a direita. O sistema gera o arquivo, o arquivo cai numa pasta e a ponte (caixa em destaque) lê essa pasta. Nada volta para o ERP: é isso que mantém o risco baixo.

A ponte não tem o caminho dos arquivos gravado em pedra. Logo no começo do server.mjs ela pergunta: existe PONTE_DADOS? Se existe, lê dali. Se não, usa a pasta runtime/exemplos/.

Esta é a linha real do arquivo do kit:

const pastaExemplos = process.env.PONTE_DADOS || join(dirname(fileURLToPath(import.meta.url)), '..', '..', 'exemplos');

function lerCsv(nome) {
  const [cabecalho, ...linhas] = readFileSync(join(pastaExemplos, nome), 'utf8').trim().split('\n');
  const campos = cabecalho.split(',');
  return linhas.map(l => Object.fromEntries(l.split(',').map((v, i) => [campos[i], v])));
}

A receita R3 manda pôr a variável no .mcp.json, no campo env. Assim, toda vez que o Claude Code liga a ponte, ela já nasce olhando para a sua pasta.

{
  "mcpServers": {
    "ponte-modelo": {
      "command": "node",
      "args": ["runtime/pontes/mcp-modelo/server.mjs"],
      "env": { "PONTE_DADOS": "/caminho/da/exportacao" }
    }
  }
}

claude mcp list

ponte-modelo: node runtime/pontes/mcp-modelo/server.mjs - ✔ Connected

O que olhar na tabela: a última linha evita confusão. O --selftest continua provando o modelo com os exemplos; quem lê a sua pasta é a ponte ligada pelo agente.

Cada ferramenta da ponte tem uma função run(): é ali que a conta acontece. E ali estão os nomes das colunas do CSV de exemplo. Este é o run() real da ferramenta resumo_vendas:

run({ agrupar_por = 'cliente' } = {}) {
  const grupos = {};
  let total = 0;
  for (const r of lerCsv('erp-vendas.csv')) {
    const v = Number(r.quantidade) * Number(r.valor_unitario);
    grupos[r[agrupar_por]] = (grupos[r[agrupar_por]] || 0) + v;
    total += v;
  }
  const linhas = Object.entries(grupos).map(([k, v]) => `${k}: R$ ${v.toFixed(2)}`);
  return [...linhas, `TOTAL: R$ ${total.toFixed(2)}`].join('\n');
},

Como ler o desenho: à esquerda, um cabeçalho inventado de um ERP qualquer; à direita, os nomes que o código espera. As duas setas acesas são as que entram na conta. Trocar o nome no código é ligar a seta certa: a regra (quantidade vezes preço) não muda.

Você não precisa editar o código à mão. Peça ao agente, com limite escrito: só trocar nomes dentro do run(), sem criar ferramenta que escreve.

Leia runtime/pontes/mcp-modelo/server.mjs e a primeira linha do meu arquivo </caminho/da/exportacao/vendas.csv>.
Na ferramenta resumo_vendas, troque só os nomes de colunas usados em run() e o nome do arquivo em lerCsv pelos do meu arquivo.
Se o meu arquivo usar ponto e vírgula, ajuste a separação em lerCsv.
Não crie ferramenta que escreve e não mexa em listar_horarios_livres.
Antes de salvar, me mostre o antes e o depois de cada linha alterada.

O próprio server.mjs traz a regra num comentário: "POLITICA: as duas tools só LEEM (N4). Tool que escreve precisa de outro nível e de confirmação."

Ler é N4: o agente faz sozinho, sem aviso, porque nada muda no mundo. A tentação aparece logo. A Clara vai querer que o agente marque consulta, não só liste horário. Isso já é escrever, e a receita R3 é clara: ferramenta que escreve sobe para "alterar" na POLITICA.md, N2, pede antes.

Uma ponte nova só vale depois de uma conta que você mesmo fez. Não porque o código erra muito, mas porque um nome de coluna trocado errado não dá erro: dá um número errado com cara de certo.

Treine com os dados da Sônia, que você conhece. Rode o selftest e refaça o total com calculadora.

node runtime/pontes/mcp-modelo/server.mjs --selftest

tools: 2 (listar_horarios_livres, resumo_vendas)
2026-10-06 09:00 · Dra. Ana
2026-10-06 10:00 · Dra. Ana
2026-10-06 15:00 · Dr. Bruno
TOTAL: R$ 856.00

O que olhar na tabela: por cliente, a mesma conta dá Mercado Sol 393,00 (185 + 208), Padaria Lua 352,00 (130 + 222) e Empório Mar 111,00. Somando os três, 856,00 de novo. Quando a ponte ler os dados reais, faça o mesmo com três ou quatro linhas que você consegue somar.

Use a tool resumo_vendas da ponte-modelo agrupando por cliente. Mostre a resposta da ferramenta sem arredondar e sem comentar.

A regra do runtime/CAPACIDADES.md vale aqui: sistema sem linha não é usado pelo agente. A ponte só entra no mapa depois da conta na mão, e com a data do teste.

O arquivo já traz um exemplo para o caso da Sônia, marcado como pendente:

| ERP sem API                  | Exportação CSV diária   | 6 | ler ~/erp/export/*.csv          | ler (N4)        | pendente |

| ERP da distribuidora | Exportação CSV + ponte MCP | 6 | tool resumo_vendas da ponte-modelo | ler (N4) | <AAAA-MM-DD> ok |

Acrescente uma linha na tabela de runtime/CAPACIDADES.md para a ponte-modelo lendo a minha exportação: via ponte local por MCP, nível 6, política ler (N4), testado em <data de hoje> ok. Não mude as outras linhas. Mostre a linha antes de salvar.

Como ler o desenho: os três primeiros passos são técnicos; o quarto (em destaque) é o que libera o uso. Pular a linha no mapa é deixar o agente usar um sistema que ninguém registrou.