nacha-mcp

NACHA/ACH 파일을 파싱하고 검증하기 위한 MCP(Model Context Protocol) 서버입니다.

요구 사항

• 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 배열, 배치 1개, 항목 1개가 표시되어야 합니다.

도구

• parse_nacha_file — 지정된 경로의 NACHA 파일을 완전한 구조화된 JSON으로 파싱합니다: 파일 헤더, 배치(헤더, 추가 레코드가 포함된 항목, 컨트롤), 파일 컨트롤.

• summarize_nacha_file — NACHA 파일을 파싱하고 요약 정보를 반환합니다: 배치 수, 총 항목 수, 총 차변/대변 금액, 존재하는 SEC 코드, 검증 문제.

두 도구 모두 단일 입력인 file_path(디스크에 있는 파일의 절대 경로)를 받습니다.

파싱에는 다음이 포함됩니다:

• 구조적 검증(레코드 길이, 레코드 유형 순서, 배치 헤더/컨트롤 페어링).

• 산술 검증 — 항목 해시, 차변/대변 합계, 항목/추가 레코드 수가 실제 항목에서 다시 계산되어 선언된 배치 컨트롤 및 파일 컨트롤 값과 교차 확인됩니다. 불일치는 조용히 수락되지 않고 검증 문제로 보고됩니다.

• IAT(국제 ACH 거래) 배치 및 추가 레코드 유형 코드 10-18.

독립 실행

npm start

서버는 MCP 프로토콜을 사용하여 stdio를 통해 통신합니다. 단독으로 대화형으로 실행하도록 만들어진 것이 아닙니다. 아래 설명된 대로 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"]
    }
  }
}

또는 명령 팔레트(Ctrl+Shift+P / ⇧⌘P)에서 MCP: Add Server를 실행하고, 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 — 구조적 검증 및 레코드 파싱(파일/배치/항목/추가 레코드).

• src/validate.ts — 산술 검증(해시, 합계, 수).

• src/analyze.ts — 파싱과 산술 검증을 결합.

• src/summarize.ts — 요약 보기.

• src/index.ts — MCP 서버 및 도구 등록.

의도적으로 단위 테스트는 포함되지 않습니다 — 이 서버는 작고 쉽게 감사할 수 있는 상태로 유지되도록 설계되었습니다.

라이선스

MIT — LICENSE 참조.