nacha-mcp

nacha-mcp

Un servidor MCP (Model Context Protocol) para analizar y validar archivos NACHA/ACH.

Requisitos

• Node.js 18 o posterior
• npm

Configuración

git clone https://github.com/msuresh007/nacha-mcp.git
cd nacha-mcp
npm install
npm run build

Esto compila src/ a dist/. Vuelve a ejecutar npm run build después de obtener cualquier actualización.

Pruébalo

Se incluye un archivo de muestra pequeño y aritméticamente válido en examples/sample.ach. Una vez compilado, puedes ejecutar cualquiera de las dos herramientas directamente desde la línea de comandos sin un cliente MCP, para confirmar que todo funciona:

node -e "const {analyzeNachaFile}=require('./dist/analyze.js');const fs=require('fs');console.log(JSON.stringify(analyzeNachaFile(fs.readFileSync('examples/sample.ach','utf-8')),null,2))"

Deberías ver "valid": true con un arreglo issues vacío, un lote y una entrada.

Herramientas

• parse_nacha_file — Analiza un archivo NACHA en una ruta determinada y lo convierte en JSON estructurado completo: encabezado de archivo, lotes (encabezado, entradas con addenda y control), y control de archivo.
• summarize_nacha_file — Analiza un archivo NACHA y devuelve un resumen condensado: cantidad de lotes, total de entradas, total de montos de débito/crédito, códigos SEC presentes y problemas de validación.

Ambas herramientas reciben una única entrada, file_path, una ruta absoluta al archivo en disco.

El análisis incluye:

• Validación estructural (longitud de registro, orden de tipos de registro, emparejamiento de encabezado/control de lote).
• Validación aritmética: el hash de entradas, los totales de débito/crédito y los conteos de entradas/addenda se recalculan a partir de las entradas reales y se comparan con los valores declarados en el Control de Lote y el Control de Archivo. Las discrepancias se reportan como problemas de validación en lugar de aceptarse silenciosamente.
• Lotes IAT (Transacción ACH Internacional) y códigos de tipo de addenda 10-18.

Ejecución independiente

npm start

El servidor se comunica a través de stdio usando el protocolo MCP; no está diseñado para ejecutarse de forma interactiva por sí solo. Úsalo a través de un cliente MCP como se describe a continuación.

Conectar a Claude Code

Desde el directorio del proyecto, después de compilar:

claude mcp add nacha -- node "$(pwd)/dist/index.js"

(En Windows PowerShell: claude mcp add nacha -- node "$PWD\dist\index.js")

Conectar a GitHub Copilot (VS Code)

Crea .vscode/mcp.json en el proyecto desde el que quieras usarlo (o agrégalo si ya existe), reemplazando la ruta con la ruta absoluta a tu clon de este repositorio:

{
  "servers": {
    "nacha": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/nacha-mcp/dist/index.js"]
    }
  }
}

Alternativamente, ejecuta MCP: Add Server desde la Paleta de Comandos (Ctrl+Shift+P / ⇧⌘P), elige Workspace y apúntalo a node con los mismos argumentos: VS Code escribe el mismo .vscode/mcp.json por ti.

Una vez guardado, abre Copilot Chat, cambia al modo Agent y las herramientas parse_nacha_file / summarize_nacha_file estarán disponibles (VS Code inicia el servidor bajo demanda).

Conectar a Claude Desktop u otro cliente MCP

Agrega una entrada a la configuración del servidor MCP del cliente (por ejemplo, claude_desktop_config.json), reemplazando la ruta con la ruta absoluta a tu clon de este repositorio:

{
  "mcpServers": {
    "nacha": {
      "command": "node",
      "args": ["/absolute/path/to/nacha-mcp/dist/index.js"]
    }
  }
}

Reinicia el cliente después de agregar la configuración.

Estructura del proyecto

• src/constants.ts — códigos SEC, códigos de transacción, búsquedas de país/divisa ISO.
• src/format.ts — análisis de campos de dinero/fecha/hora.
• src/parser.ts — validación estructural y análisis de registros (archivo/lote/entrada/addenda).
• src/validate.ts — validación aritmética (hashes, totales, conteos).
• src/analyze.ts — combina análisis y validación aritmética.
• src/summarize.ts — vista de resumen condensado.
• src/index.ts — servidor MCP y registro de herramientas.

No se incluyen pruebas unitarias por diseño: este servidor está pensado para mantenerse pequeño y fácilmente auditable.

Licencia

MIT — consulta LICENSE.