nacha-mcp

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

Requisitos

• Node.js 18 o posterior

• npm

Related MCP server: acmt001-mcp

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 incorporar cualquier actualización.

Pruébalo

Se incluye un pequeño archivo de ejemplo 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 array issues vacío, un lote y una entrada.

Herramientas

• parse_nacha_file — Analiza un archivo NACHA en una ruta dada y lo convierte en JSON estructurado completo: cabecera de archivo, lotes (cabecera, entradas con addenda y control) y control de archivo.

• summarize_nacha_file — Analiza un archivo NACHA y devuelve un resumen condensado: número de lotes, total de entradas, totales de débito/crédito, códigos SEC presentes y problemas de validación.

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

El análisis incluye:

• Validación estructural (longitud de registro, orden de los tipos de registro, emparejamiento de cabecera/control de lote).

• Validación aritmética — el hash de entrada, los totales de débito/crédito y los recuentos 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 notifican como problemas de validación en lugar de aceptarse silenciosamente.

• Lotes IAT (International ACH Transaction) y códigos de tipo de addenda 10-18.

Ejecución independiente

npm start

El servidor se comunica a través de stdio mediante el protocolo MCP; no está pensado 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 añádelo si ya existe), reemplazando la ruta con la ruta absoluta de 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 Espacio de trabajo y apúntalo a node con los mismos argumentos: VS Code te escribe el mismo .vscode/mcp.json.

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 o a otro cliente MCP

Añade una entrada a la configuración del servidor MCP del cliente (p. ej., claude_desktop_config.json), sustituyendo la ruta con la ruta absoluta de tu clon de este repositorio:

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

Reinicia el cliente después de añadir la configuración.

Estructura del proyecto

• src/constants.ts — códigos SEC, códigos de transacción, búsquedas de países/divisas 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, recuentos).

• src/analyze.ts — combina el análisis y la 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: esto significa mantener un servidor pequeño y fácilmente auditable.

Licencia

MIT — consulta LICENSE.