{"_id":"@bikramdas1/swift-iso20022-mcp","name":"@bikramdas1/swift-iso20022-mcp","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@bikramdas1/swift-iso20022-mcp","version":"0.1.0","description":"MCP server exposing SWIFT MT and ISO 20022 MX (pacs.008/pacs.009) message validation, BIC/IBAN checks, and MT103->pacs.008 field mapping as tools for AI agents.","main":"src/index.js","bin":{"swift-iso20022-mcp":"src/index.js"},"scripts":{"start":"node src/index.js","start:http":"node src/http-server.js","test":"node test/swift-core.test.js","test:manual":"node test/manual-client.js"},"keywords":["mcp","swift","iso20022","payments","banking","mt103","pacs008"],"author":{"name":"Bikramaditya","url":"KK"},"license":"MIT","repository":{"type":"git","url":"git+https://github.com/techybiky/swift_mcp.git"},"homepage":"https://github.com/techybiky/swift_mcp#readme","bugs":{"url":"https://github.com/techybiky/swift_mcp/issues"},"dependencies":{"@modelcontextprotocol/sdk":"^1.29.0","express":"^4.21.2","zod":"^4.4.3"},"_id":"@bikramdas1/swift-iso20022-mcp@0.1.0","gitHead":"dd5769dee4fdb7c774508116aa702506d49828cb","_nodeVersion":"22.17.1","_npmVersion":"10.9.2","dist":{"integrity":"sha512-rbh2skWgBfdyeMvW7Mm9/6Paqi82NkGhAyCRcTfHoJqfpSKf1Q4CgjuBRoqpsX5duOMlqWpmDH2mcoiWS/z9Tg==","shasum":"5fbc6ac552bfc1ab5a4d505bad6bf850f994ca48","tarball":"https://registry.npmjs.org/@bikramdas1/swift-iso20022-mcp/-/swift-iso20022-mcp-0.1.0.tgz","fileCount":6,"unpackedSize":31158,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQDeToJkGzG25g/4sfGizw7+RJTHb0VvV/WFkqWik5tXkwIhAIn5FSuWCM/16FmxnnGCv/74M55L3FesBRvOFuX7DRjK"}]},"_npmUser":{"name":"bikramdas1","email":"bikramadityadas1@gmail.com"},"directories":{},"maintainers":[{"name":"bikramdas1","email":"bikramadityadas1@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/swift-iso20022-mcp_0.1.0_1784372782754_0.6889893259253805"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-18T11:06:22.552Z","0.1.0":"2026-07-18T11:06:22.915Z","modified":"2026-07-18T11:06:23.149Z"},"maintainers":[{"name":"bikramdas1","email":"bikramadityadas1@gmail.com"}],"description":"MCP server exposing SWIFT MT and ISO 20022 MX (pacs.008/pacs.009) message validation, BIC/IBAN checks, and MT103->pacs.008 field mapping as tools for AI agents.","homepage":"https://github.com/techybiky/swift_mcp#readme","keywords":["mcp","swift","iso20022","payments","banking","mt103","pacs008"],"repository":{"type":"git","url":"git+https://github.com/techybiky/swift_mcp.git"},"author":{"name":"Bikramaditya","url":"KK"},"bugs":{"url":"https://github.com/techybiky/swift_mcp/issues"},"license":"MIT","readme":"# swift-iso20022-mcp\n\nAn MCP (Model Context Protocol) server that gives any AI agent — Claude,\nChatGPT, Cursor, Windsurf, or any other MCP-compatible client, local or\nremote — tools to validate SWIFT MT and ISO 20022 MX payment messages,\ncheck BIC/IBAN correctness, and map between MT and MX formats, without the\nagent hallucinating message-format rules.\n\nBuilt from real SWIFT MT/ISO 20022 test-automation experience in banking and\npayments (SWIFT MT/MX, ACH, SEPA, RTGS, FEDWIRE).\n\n## Why this exists\n\nGeneric AI agents get SWIFT/ISO 20022 formatting wrong constantly — mandatory\nfields, BIC shape, IBAN checksums, charges codes, and (as of the SWIFT\nCBPR+ milestone in November 2026) structured vs. unstructured postal\naddresses. This server gives an agent ground truth instead of a guess.\n\n## Two transports — this is what makes it \"universal\"\n\nMCP itself is the cross-vendor standard (Anthropic, OpenAI, Google, and\nMicrosoft all support it), but a server still has to expose the right\n**transport** to be reachable by every kind of client:\n\n| Transport | Entrypoint | Who connects this way |\n|---|---|---|\n| **stdio** | `src/index.js` | Local clients that spawn your process directly: Claude Desktop, Cursor, Windsurf, Cline |\n| **Streamable HTTP** | `src/http-server.js` | Remote clients that connect over a URL: hosted connectors, web-based agents, anything that can't spawn a local process |\n\nSame tools, same logic (`src/server-factory.js` is shared by both) — only\nthe wire format differs. Run whichever one matches where you want to be\nreachable, or both at once on different machines.\n\n## Tools exposed\n\n| Tool | What it does |\n|---|---|\n| `validate_mt_message` | Validates an MT103 or MT202 message body: mandatory fields, date/currency/amount format, BIC shape, IBAN checksum, charges code |\n| `validate_mx_message` | Validates a pacs.008/pacs.009 XML message: MsgId presence, currency shape, BICFI validity, IBAN checksum, unstructured-address warning |\n| `validate_bic` | Structural BIC/SWIFT code check (8 or 11 chars) |\n| `validate_iban` | IBAN shape + ISO 7064 mod-97 checksum |\n| `convert_mt103_to_pacs008` | Maps MT103 fields to pacs.008 (customer credit transfer, has Dbtr/Cdtr) |\n| `convert_mt202_to_pacs009` | Maps MT202 fields to pacs.009 (bank-to-bank transfer, has InstgAgt/InstdAgt BICs instead of customer parties) |\n| `convert_pacs008_to_mt103` | Reverse direction: maps pacs.008 XML back to MT103 field tags, for coexistence-period systems that still expect MT |\n\n## Install & test\n\n```bash\ncd swift-mcp\nnpm install\n```\n\nThere are three ways to verify it works, in order of speed:\n\n### 1. Unit tests — checks the logic in isolation\n\n```bash\nnpm test\n```\n\nRuns 18 assertions against `swift-core.js` directly. No MCP protocol\ninvolved — fastest signal that the validation/mapping logic is correct.\n\n### 2. Manual protocol test — checks the stdio server\n\n```bash\nnpm run test:manual\n```\n\nSpawns the actual stdio server and talks to it over real JSON-RPC (the same\ntransport Claude Desktop uses), calling all 7 tools with realistic data.\n\nYou can also inspect either transport interactively with the official MCP\nInspector:\n\n```bash\nnpx @modelcontextprotocol/inspector node src/index.js\n```\n\n### 3. Manual test for the HTTP transport\n\n```bash\nnpm run start:http\n# in another terminal:\ncurl http://localhost:3000/health\ncurl -X POST http://localhost:3000/mcp \\\n  -H \"Content-Type: application/json\" \\\n  -H \"Accept: application/json, text/event-stream\" \\\n  -d '{\"jsonrpc\":\"2.0\",\"id\":1,\"method\":\"tools/call\",\"params\":{\"name\":\"validate_bic\",\"arguments\":{\"bic\":\"DEUTDEFF\"}}}'\n```\n\n### 4. Live test in a real client\n\nAdd the config below for whichever client you're using, and try prompts like:\n\n> \"Validate this MT103: :20:REF123...\\n:23B:CRED\\n:32A:250115USD1000,00...\"\n> \"Is DE89370400440532013000 a valid IBAN?\"\n> \"Convert this MT202 to pacs.009: ...\"\n\nWatch for the tool-use block in the client's UI — that confirms it's calling\nyour server instead of guessing.\n\n## Connect it — local clients (stdio)\n\nClaude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`\non macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"swift-iso20022\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/swift-mcp/src/index.js\"]\n    }\n  }\n}\n```\n\nCursor, Windsurf, and Cline use the same shape in their own MCP config files\n— just the `command`/`args` pair pointing at `src/index.js`.\n\n## Connect it — remote clients (Streamable HTTP)\n\nRun the HTTP server:\n\n```bash\nnpm run start:http    # listens on PORT env var, default 3000\n```\n\nDeploy it anywhere Node.js runs — Render, Railway, Fly.io, a VPS — and point\nany HTTP-based MCP client at:\n\n```\nhttps://your-deployed-host/mcp\n```\n\n### Securing the public endpoint\n\nSet `MCP_API_KEY` in the deployment environment to require a bearer token on\nevery request. If it's unset, the endpoint stays open (fine for local/manual\ntesting, not for a public deploy):\n\n```bash\nMCP_API_KEY=your-secret-key npm run start:http\n```\n\nClients must then send:\n\n```\nAuthorization: Bearer your-secret-key\n```\n\nThis is what lets a client that can't spawn a local process (a hosted\nconnector, a web app, a teammate who doesn't have your code checked out)\nreach the same tools. It runs statelessly — every request gets a fresh\nserver instance, so there's no session state to lose on a restart, which\nalso makes it trivial to run on serverless platforms.\n\n## Roadmap (next steps if you take this further)\n\n- [x] MT202 -> pacs.009 mapping\n- [x] Reverse MX -> MT mapping (pacs.008 -> MT103)\n- [x] Streamable HTTP transport for remote/universal access\n- [ ] Reverse pacs.009 -> MT202 mapping (currently only pacs.008 -> MT103 exists)\n- [ ] Full XSD schema validation for MX messages (current MX check is structural, not schema-complete)\n- [x] Auth (API key) on the HTTP endpoint via `MCP_API_KEY` — optional, off by default for local testing\n- [x] Publish to npm as `@bikramdas1/swift-iso20022-mcp` so it can be installed with `npx`\n- [ ] Submit to the MCP server directory / registry once it has real usage\n- [ ] Wire this same `src/swift-core.js` logic into Coexist as a shared package, so the SaaS UI and the MCP server never drift apart\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-bc19e145d46d57ce490bcd27d64aa2ba"}