mcp-edi

EDI meets AI agents: give Claude the ability to read, validate and write EDIFACT, ANSI X12 and cXML.

An MCP server that turns 40 years of B2B message formats into something an AI agent can work with natively — built by an EDI consultant with 20 years of EDIFACT/X12/cXML integrations behind him.

The parsers are written by hand — no EDI library, no XML dependency. Tokenizing UNA service strings, deducing X12 delimiters from the ISA header, verifying UNT/SE/GE/UNZ/IEA control counters: that is the point. The only runtime dependencies are the official MCP SDK and zod.

Quick start

git clone https://github.com/MaestroMed/mcp-edi.git
cd mcp-edi
npm install && npm run build

Claude Desktop / Claude Code

Add to claude_desktop_config.json (or .mcp.json for Claude Code):

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

Restart the client — six EDI tools appear.

Tools

Tool	What it does
parse_edifact	Raw UN/EDIFACT → structured JSON. UNA-aware (custom separators, release character), UNB/UNZ + UNH/UNT envelopes, type recognition (ORDERS, DESADV, INVOIC, ORDRSP...), UNT/UNZ counter checks.
parse_x12	Raw ANSI X12 → structured JSON. Delimiters deduced from the ISA itself, ISA/GS/ST hierarchy, type recognition (850, 856, 810, 997...), SE/GE/IEA counter and control-number checks.
parse_cxml	cXML e-procurement → JSON: PunchOutSetupRequest/Response and OrderRequest, From/To/Sender credentials, items and amounts. SharedSecret values are detected but never echoed.
validate_message	Auto-detects the standard, verifies envelope structure, mandatory segments per message type, and every counter. Returns actionable errors/warnings: segment, position, expected, found.
explain_segment	Built-in dictionary — 35 EDIFACT + 28 X12 segments. BGM? HL? AK9? Plain-English role, key elements, realistic example. Ambiguous tags (DTM, LIN) return both standards.
generate_edifact	Simple JSON (parties, dates, line items) → valid EDIFACT ORDERS D.96A interchange with correct envelopes, escaping and counters. Round-trips through parse_edifact with zero issues.

Example session

You: Our supplier says our order file is broken. Here it is: (pastes EDIFACT)

Claude (calls validate_message): The interchange is invalid — two problems:

1. UNT declares 18 segments but the message contains 20 (UNT_COUNT_MISMATCH, position 21). Your mapper is not counting the two PRI segments added last week.
2. UNZ control reference ICR0002 does not match UNB reference ICR0001 — the envelope was rebuilt from a stale template.

You: Fix the counters and show me what line 2 orders.

Claude (calls parse_edifact): Line 2 orders 24 PCE of EAN 8718123400022 ("Industrial widget size L") at 15.75 EUR net.

Why

EDI is not legacy — it is the installed base of world trade. Every retailer, carrier and marketplace still speaks EDIFACT or X12, and every e-procurement platform speaks cXML. What is changing is who reads these messages: agents are starting to negotiate, order and invoice on behalf of companies.

Agent-to-agent commerce will not replace the EDI rails; it will drive them. The missing piece is a translation layer the agent can trust — deterministic parsing, real envelope validation, counters checked, nothing hallucinated. That layer is what this server provides: the LLM does the reasoning, the parsers do the arithmetic.

Development

npm test        # vitest — 81 tests: nominal, custom UNA separators, truncated
                # messages, wrong counters, generate→parse round-trips
npm run build   # tsc, strict mode
npm run smoke   # spawns the compiled server, runs the MCP handshake on stdio,
                # checks tools/list and a live tools/call

samples/ contains six anonymized messages (ACME Corp / Globex — fictional data only): ORDERS, DESADV, INVOIC, 850, 856, PunchOutSetupRequest. Every sample validates clean; the test suite enforces it.

Roadmap

• AS2 headers inspector — MDN, MIC and disposition debugging for transport-level issues
• Peppol UBL — parse and validate BIS 3.0 invoices/orders
• SAP IDoc — ORDERS05/DESADV parsing from flat-file IDocs

License

MIT — Mehdi Nafaa