🏗️ El puente de tu sistema

En el módulo 2.2, el puente leyó runtime/exemplos/agenda.csv e runtime/exemplos/erp-vendas.csv. Estos archivos imitan lo que entrega un sistema sin API: una exportación.

El primer paso es encontrar ese archivo en tu sistema. Busca en los menús opciones como «Exportar», «Informes» o «Guardar como CSV». En el ERP del cliente de Sônia, es el informe de ventas del mes, guardado en una carpeta fija.

Cómo leer el diagrama: las flechas azules siempre van de izquierda a derecha. El sistema genera el archivo, el archivo cae en una carpeta y el puente (caja resaltada) lee esa carpeta. Nada vuelve al ERP: eso es lo que mantiene bajo el riesgo.

El puente no tiene fijada de antemano la ruta de los archivos. Al principio del server.mjs ella pregunta: ¿existe PONTE_DADOS? Si existe, lo lee de ahí. Si no, usa la carpeta runtime/exemplos/.

Esta es la línea real del archivo del 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])));
}

La receta R3 indica que pongas la variable en el .mcp.json, en el campo env. Así, cada vez que Claude Code activa el puente, este ya se inicia mirando tu carpeta.

{
  "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

Qué revisar en la tabla: la última línea evita confusiones. El --selftest sigue probando el modelo con los ejemplos; quien lee tu carpeta es el puente conectado por el agente.

Cada herramienta del puente tiene una función run(): ahí se hacen los cálculos. Y ahí están los nombres de las columnas del CSV de ejemplo. Este es el run() real de la herramienta 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');
},

Cómo leer el diagrama: a la izquierda, un encabezado inventado de cualquier ERP; a la derecha, los nombres que espera el código. Las dos flechas iluminadas son las que se tienen en cuenta. Cambiar el nombre en el código es conectar la flecha correcta: la regla (cantidad por precio) no cambia.

No tienes que editar el código a mano. Pídele al agente, con un límite por escrito: cambiar nombres solo dentro del run(), sin crear una herramienta que escriba.

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.

El propio server.mjs incluye la regla en un comentario: "POLITICA: las dos tools solo LEEN (N4). Una tool que escribe necesita otro nivel y confirmación."

Leer es N4: el agente lo hace por su cuenta, sin avisar, porque nada cambia en el mundo. La tentación aparece enseguida. Clara querrá que el agente marca consulta, no solo enumeres horarios. Eso ya es escribir, y la receta R3 es clara: una herramienta que escribe sube a «modificar» en la POLITICA.md, N2, lo pide antes.

Un puente nuevo solo sirve después de que tú mismo hayas hecho una cuenta. No porque el código se equivoque mucho, sino porque cambiar el nombre de una columna por error no genera un error: da un número equivocado que parece correcto.

Practica con los datos de Sônia, que ya conoces. Ejecuta el selftest y vuelve a calcular el total con una 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

Qué revisar en la tabla: por cliente, la misma cuenta da Mercado Sol 393,00 (185 + 208), Padaria Lua 352,00 (130 + 222) y Empório Mar 111,00. Al sumar los tres, 856,00 de nuevo. Cuando el puente lea los datos reales, haz lo mismo con tres o cuatro filas que puedas sumar.

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

La regla de runtime/CAPACIDADES.md aquí se aplica: el sistema sin línea no lo usa el agente. El puente solo se agrega al mapa después de tener el cálculo a mano y la fecha de la prueba.

El archivo ya incluye un ejemplo para el caso de Sônia, marcado como pendiente:

| 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.

Cómo leer el diagrama: los tres primeros pasos son técnicos; el cuarto (resaltado) es el que habilita el uso. Saltarte esa línea en el mapa es dejar que el agente use un sistema que nadie registró.