nacha-mcp

Сервер MCP (Model Context Protocol) для разбора и проверки файлов NACHA/ACH.

Требования

• Node.js 18 или новее

• npm

Related MCP server: acmt001-mcp

Установка

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

Это компилирует src/ в dist/. Повторно запускайте npm run build после получения любых обновлений.

Попробуйте

Небольшой арифметически корректный пример файла включён в examples/sample.ach. После сборки вы можете запустить любой из инструментов напрямую из командной строки без MCP-клиента, чтобы убедиться, что всё работает:

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

Вы должны увидеть "valid": true с пустым массивом issues, один batch и одну запись.

Инструменты

• parse_nacha_file — Разбирает файл NACHA по указанному пути в полный структурированный JSON: заголовок файла, batch'и (заголовок, записи с addenda, контроль), и контроль файла.

• summarize_nacha_file — Разбирает файл NACHA и возвращает сжатое резюме: количество batch'ей, общее количество записей, общие суммы дебета/кредита, присутствующие коды SEC и проблемы валидации.

Оба инструмента принимают один входной параметр, file_path, — абсолютный путь к файлу на диске.

Разбор включает:

• Структурную валидацию (длина записи, порядок типов записей, сопоставление заголовка/контроля batch'а).

• Арифметическую валидацию — хэш записей, итоги дебета/кредита и количество записей/addenda пересчитываются на основе фактических записей и сверяются с объявленными значениями Batch Control и File Control. Несоответствия сообщаются как проблемы валидации, а не молча принимаются.

• Batch'и IAT (International ACH Transaction) и коды типов addenda 10-18.

Запуск в автономном режиме

npm start

Сервер общается через stdio по протоколу MCP; он не предназначен для интерактивного запуска сам по себе. Используйте его через MCP-клиент, как описано ниже.

Подключение к Claude Code

Из каталога проекта, после сборки:

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

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

Подключение к GitHub Copilot (VS Code)

Создайте .vscode/mcp.json в проекте, в котором вы хотите его использовать (или добавьте в него, если он уже существует), заменив путь на абсолютный путь к вашему клону этого репозитория:

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

В качестве альтернативы запустите MCP: Add Server из палитры команд (Ctrl+Shift+P / ⇧⌘P), выберите Workspace и укажите node с теми же аргументами — VS Code сам запишет тот же .vscode/mcp.json для вас.

После сохранения откройте Copilot Chat, переключитесь в режим Agent, и инструменты parse_nacha_file / summarize_nacha_file будут доступны (VS Code запускает сервер по требованию).

Подключение к Claude Desktop или другому MCP-клиенту

Добавьте запись в конфигурацию MCP-сервера клиента (например, claude_desktop_config.json), заменив путь на абсолютный путь к вашему клону этого репозитория:

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

Перезапустите клиент после добавления конфигурации.

Структура проекта

• src/constants.ts — коды SEC, коды транзакций, справочники стран/валют ISO.

• src/format.ts — разбор полей денег/даты/времени.

• src/parser.ts — структурная валидация и разбор записей (файл/batch/запись/addenda).

• src/validate.ts — арифметическая валидация (хэши, итоги, количества).

• src/analyze.ts — объединяет разбор и арифметическую валидацию.

• src/summarize.ts — сжатое резюме.

• src/index.ts — MCP-сервер и регистрация инструментов.

Модульные тесты намеренно не включены — предполагается, что это останется небольшим и легко проверяемым сервером.

Лицензия

MIT — см. LICENSE.