nacha-mcp

nacha-mcp

Um servidor MCP (Model Context Protocol) para analisar e validar arquivos NACHA/ACH.

Requisitos

• Node.js 18 ou posterior
• npm

Configuração

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

Isso compila src/ para dist/. Execute npm run build novamente após baixar quaisquer atualizações.

Experimente

Um pequeno arquivo de exemplo aritmeticamente válido está incluído em examples/sample.ach. Após a compilação, você pode executar qualquer uma das ferramentas diretamente pela linha de comando sem um cliente MCP, para confirmar que tudo 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))"

Você deve ver "valid": true com um array issues vazio, um lote e uma entrada.

Ferramentas

• parse_nacha_file — Analisa um arquivo NACHA em um caminho específico para JSON estruturado completo: cabeçalho do arquivo, lotes (cabeçalho, entradas com addenda e controle) e controle do arquivo.
• summarize_nacha_file — Analisa um arquivo NACHA e retorna um resumo condensado: quantidade de lotes, total de entradas, totais de débito/crédito, códigos SEC presentes e problemas de validação.

Ambas as ferramentas recebem uma única entrada, file_path, um caminho absoluto para o arquivo no disco.

A análise inclui:

• Validação estrutural (comprimento do registro, ordenação do tipo de registro, pareamento cabeçalho/controle do lote).
• Validação aritmética — hash de entrada, totais de débito/crédito e contagens de entradas/addenda são recalculados a partir das entradas reais e verificados contra os valores declarados no Controle de Lote e no Controle de Arquivo. Divergências são reportadas como problemas de validação em vez de serem aceitas silenciosamente.
• Lotes IAT (International ACH Transaction) e códigos de tipo de addenda 10-18.

Execução autônoma

npm start

O servidor se comunica via stdio usando o protocolo MCP; ele não foi feito para ser executado interativamente por conta própria. Use-o por meio de um cliente MCP conforme descrito abaixo.

Conectar ao Claude Code

A partir do diretório do projeto, após a compilação:

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

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

Conectar ao GitHub Copilot (VS Code)

Crie .vscode/mcp.json no projeto em que você deseja usá-lo (ou adicione a ele se já existir), substituindo o caminho pelo caminho absoluto do seu clone deste repositório:

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

Alternativamente, execute MCP: Add Server na Paleta de Comandos (Ctrl+Shift+P / ⇧⌘P), escolha Workspace e aponte para node com os mesmos argumentos — o VS Code grava o mesmo .vscode/mcp.json para você.

Após salvar, abra o Copilot Chat, alterne para o modo Agent, e as ferramentas parse_nacha_file / summarize_nacha_file estarão disponíveis (o VS Code inicia o servidor sob demanda).

Conectar ao Claude Desktop ou outro cliente MCP

Adicione uma entrada à configuração do servidor MCP do cliente (ex.: claude_desktop_config.json), substituindo o caminho pelo caminho absoluto do seu clone deste repositório:

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

Reinicie o cliente após adicionar a configuração.

Estrutura do projeto

• src/constants.ts — códigos SEC, códigos de transação, consultas de país/moeda ISO.
• src/format.ts — análise de campos de dinheiro/data/hora.
• src/parser.ts — validação estrutural e análise de registros (arquivo/lote/entrada/addenda).
• src/validate.ts — validação aritmética (hashes, totais, contagens).
• src/analyze.ts — combina análise e validação aritmética.
• src/summarize.ts — visão resumida condensada.
• src/index.ts — servidor MCP e registro de ferramentas.

Nenhum teste unitário está incluído por design — a intenção é manter este um servidor pequeno e facilmente auditável.

Licença

MIT — veja LICENSE.