# mcp-edi

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

An [MCP](https://modelcontextprotocol.io) 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.

![CI](https://github.com/MaestroMed/mcp-edi/actions/workflows/ci.yml/badge.svg)
![Node](https://img.shields.io/badge/node-%E2%89%A520-brightgreen)
![License](https://img.shields.io/badge/license-MIT-blue)
![TypeScript](https://img.shields.io/badge/TypeScript-strict-3178c6)

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

```bash
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):

```json
{
  "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

```bash
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](LICENSE) — Mehdi Nafaa