# nacha-mcp

An MCP (Model Context Protocol) server for parsing and validating NACHA/ACH files.

[![Listed on mcpservers.org](https://mcpservers.org/badge.svg)](https://mcpservers.org/servers/msuresh007/nacha-mcp) 

## Requirements

- Node.js 18 or later
- npm

## Setup

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

This compiles `src/` to `dist/`. Re-run `npm run build` after pulling any updates.

## Try it out

A small, arithmetically-valid sample file is included at `examples/sample.ach`. Once built,
you can run either tool directly from the command line without an MCP client, to confirm
everything works:

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

You should see `"valid": true` with an empty `issues` array, one batch, and one entry.

## Tools

- **parse_nacha_file** — Parses a NACHA file at a given path into full structured JSON:
  file header, batches (header, entries with addenda, control), and file control.
- **summarize_nacha_file** — Parses a NACHA file and returns a condensed summary: batch
  count, total entries, total debit/credit amounts, SEC codes present, and validation issues.

Both tools take a single input, `file_path`, an absolute path to the file on disk.

Parsing includes:
- Structural validation (record length, record type ordering, batch header/control pairing).
- Arithmetic validation — entry hash, debit/credit totals, and entry/addenda counts are
  recomputed from the actual entries and cross-checked against the declared Batch Control
  and File Control values. Mismatches are reported as validation issues rather than silently
  accepted.
- IAT (International ACH Transaction) batches and addenda type codes 10-18.

## Running standalone

```
npm start
```

The server communicates over stdio using the MCP protocol; it's not meant to be run
interactively on its own. Use it through an MCP client as described below.

## Connect to Claude Code

From the project directory, after building:

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

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

## Connect to GitHub Copilot (VS Code)

Create `.vscode/mcp.json` in the project you want to use it from (or add to it if it already
exists), replacing the path with the absolute path to your clone of this repo:

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

Alternatively, run **MCP: Add Server** from the Command Palette (`Ctrl+Shift+P` /
`⇧⌘P`), choose **Workspace**, and point it at `node` with the same args — VS Code
writes the same `.vscode/mcp.json` for you.

Once saved, open Copilot Chat, switch to **Agent** mode, and the `parse_nacha_file` /
`summarize_nacha_file` tools will be available (VS Code starts the server on demand).

## Connect to Claude Desktop or another MCP client

Add an entry to the client's MCP server config (e.g. `claude_desktop_config.json`),
replacing the path with the absolute path to your clone of this repo:

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

Restart the client after adding the config.

## Project layout

- `src/constants.ts` — SEC codes, transaction codes, ISO country/currency lookups.
- `src/format.ts` — money/date/time field parsing.
- `src/parser.ts` — structural validation and record parsing (file/batch/entry/addenda).
- `src/validate.ts` — arithmetic validation (hashes, totals, counts).
- `src/analyze.ts` — combines parsing and arithmetic validation.
- `src/summarize.ts` — condensed summary view.
- `src/index.ts` — MCP server and tool registration.

No unit tests are included by design — this is meant to stay a small, easily auditable server.

## License

MIT — see [LICENSE](LICENSE).