# edi-mcp

**Let AI agents read, validate and acknowledge EDI documents.**

An MCP (Model Context Protocol) server that parses raw **X12** and **EDIFACT** interchanges into structured JSON, validates envelope integrity, produces plain-language summaries, and generates 997 Functional Acknowledgments. Zero runtime dependencies beyond the MCP SDK - the tokenizer is hand-rolled and reads delimiters from the wire, the way real-world files demand.

Works with Claude (Desktop, Code, API), Cursor, and any MCP-compatible client.

## Why

EDI predates JSON by decades and still moves most B2B commerce: purchase orders (850/ORDERS), invoices (810/INVOIC), ship notices (856). None of it is reachable by no-code AI connectors - there is no REST API to point Zapier at, just structured text flowing over AS2/SFTP. This server gives an AI agent eyes on that traffic:

- "Summarize the PO that just landed in the inbox folder"
- "Does this 810 match the PO number and line totals we sent?"
- "Draft the 997 acknowledgment for this interchange"

## Tools

| Tool | What it does |
|------|--------------|
| `parse_edi` | Raw X12/EDIFACT (auto-detected) → structured JSON: envelope, groups, transactions, segments |
| `validate_edi` | Envelope integrity: control number agreement (ISA/IEA, GS/GE, ST/SE, UNB/UNZ, UNH/UNT) + declared counts |
| `summarize_edi` | Plain-language business summary. Deep support: X12 850/810/856, EDIFACT ORDERS/INVOIC. Other types get a segment inventory |
| `generate_997_ack` | X12 997 Functional Acknowledgment answering an interchange, sender/receiver swapped, AK2/AK5 per transaction |

## Quick start

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

**Claude Code:**

```bash
claude mcp add edi -- node /path/to/edi-mcp/dist/index.js
```

**Claude Desktop** (`claude_desktop_config.json`):

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

Then try: *"Parse samples/850-purchase-order.edi and tell me the PO number, ship-to address and order value."*

## Example

Input (X12 850, abbreviated):

```
ISA*00*...*ZZ*ACMECORP*ZZ*WIDGETSUPPLY*260719*1030*U*00401*000000101*0*P*>~
GS*PO*ACMECORP*WIDGETSUPPLY*20260719*1030*101*X*004010~
ST*850*0001~
BEG*00*SA*PO-2026-4521**20260719~
PO1*1*48*EA*9.75**VP*WS-4417*UP*012345678905~
...
```

`summarize_edi` output:

```
X12 interchange 000000101 - ACMECORP → WIDGETSUPPLY, dated 2026-07-19

## 850 Purchase Order (control 0001)
- Purchase Order PO-2026-4521 dated 2026-07-19 (type SA)
- Ship-to: Acme Corp Warehouse 7
- Line 1: 48 EA @ 9.75 - VP WS-4417, UP 012345678905
- Line 2: 12 CS @ 142.00 - VP WS-9902
- Computed order value: 2172.00
- CTT declares 2 line item(s)
```

## Design notes

- **Delimiters come from the wire, not from config.** X12 delimiters are read from the ISA segment itself; EDIFACT service characters from UNA when present, standard defaults otherwise. EDIFACT release-character escaping (`?+` → literal `+`) is honored.
- **Lenient parse, strict validate.** `parse_edi` recovers what it can and reports anomalies as warnings; `validate_edi` is the strict pass. Real-world EDI is messy - a parser that throws on the first oddity is useless for triage.
- **Acknowledgment policy is explicit.** `decideAckStatus()` in `src/ack997.ts` maps validation results to A/E/R. Default: clean → A, structural errors → R. Trading partner agreements differ; the policy is one small function on purpose.

## Scope and roadmap

Current scope is read/triage/acknowledge - the 80% of daily EDI pain that needs no certification. Not yet included: 999 Implementation Acknowledgment, transaction-set-level schema validation (dictionaries per version), generating outbound 810/856, AS2 transport. Tracking the MCP 2026-07-28 spec revision.

## Custom integrations

I build custom MCP servers for systems that no off-the-shelf connector covers: legacy ERPs, proprietary internal tools, SOAP/EDI/flat-file pipelines. If your business runs on a system your AI tools can't see, reach out: **anhphong.pham@gmail.com** · [anhphong.dev](https://anhphong.dev)

## License

MIT