# EDI MCP Server

[![Python](https://img.shields.io/badge/python-3.10%2B-blue.svg)](https://www.python.org/)
[![MCP](https://img.shields.io/badge/MCP-1.29.1-6f42c1.svg)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](#)
[![Status](https://img.shields.io/badge/status-portfolio%20project-orange.svg)](#)

An MCP (Model Context Protocol) server that exposes EDI (Electronic Data
Interchange) document processing as tools an AI model like Claude can call.

Built as a portfolio project extending real-world EDI translation experience
into an agent-callable tool server using Anthropic's Model Context Protocol.

## Table of contents

- [What it does](#what-it-does)
- [How it works](#how-it-works)
- [Project structure](#project-structure)
- [Setup](#setup)
- [Running it](#running-it)
- [Connecting to Claude Desktop](#connecting-to-claude-desktop)
- [Next steps / ideas to extend this](#next-steps--ideas-to-extend-this)
- [Why this project](#why-this-project)

## What it does

Exposes tools over MCP:

| Tool | What it does |
|---|---|
| `parse_edi_document` | Parses raw X12 EDI text into structured JSON (interchange, functional group, transaction set, segments) |
| `convert_edi_format` | Converts raw X12 EDI text into clean, named-field JSON (PO/invoice number, date, ship-to, line items) |
| `validate_edi_transaction` | Checks the document has a valid envelope (ISA/GS/ST...SE/GE/IEA) and required segments for its transaction type |
| `get_transaction_summary` | Produces a plain-English summary (transaction type, sender/receiver, PO/invoice number, line item count) |

Currently supports **X12 850 (Purchase Order)** and **810 (Invoice)**
transaction sets. The parser (`edi_parser.py`) is deliberately simplified —
it's a portfolio-scale implementation covering the core X12 envelope
structure, not a certified EDI translator.

## How it works

```mermaid
flowchart LR
    A[Claude / MCP Client] -->|tool call| B(server.py<br/>FastMCP wrappers)
    B --> C(edi_parser.py<br/>parsing · validation · summary)
    C --> D[Raw X12 EDI text]
    C --> E[Structured JSON output]
    B -->|tool result| A
```

`server.py` is a thin MCP layer; all real logic lives in `edi_parser.py`,
which stays framework-free so it can be tested and reused on its own.

## Project structure

```
edi-mcp-server/
├── server.py        # MCP tool definitions (thin wrappers using FastMCP)
├── edi_parser.py     # Core parsing/validation/summary logic (no MCP code)
├── sample_850.edi    # Sample X12 850 Purchase Order for testing
├── test_client.py    # Standalone script that calls the server like a real MCP client would
├── requirements.txt
└── README.md
```

## Setup

```bash
python3 -m venv venv
source venv/bin/activate        # Windows: venv\Scripts\activate
pip install -r requirements.txt
```

> **Note on MCP SDK versions:** this project pins `mcp==1.29.1`. The `mcp`
> package released a 2.0 version that renamed `FastMCP` to `MCPServer` and
> moved its module path — if you `pip install mcp` without pinning, you may
> get the newer API and the imports in `server.py` won't match. Stick to the
> pinned version, or check the SDK's migration notes if you want to upgrade.

## Running it

Test the parsing logic directly:

```bash
python3 -c "
from edi_parser import summarize_x12
print(summarize_x12(open('sample_850.edi').read()))
"
```

Run the full MCP server + simulated client call:

```bash
python3 test_client.py
```

Run the server standalone (for connecting a real MCP client):

```bash
python3 server.py
```

## Connecting to Claude Desktop

Add this to your Claude Desktop MCP config file
(`claude_desktop_config.json` — find it via Claude Desktop's settings):

```json
{
  "mcpServers": {
    "edi-processor": {
      "command": "python3",
      "args": ["/absolute/path/to/edi-mcp-server/server.py"]
    }
  }
}
```

Restart Claude Desktop, and you should be able to ask it things like
*"Validate this EDI document"* or *"Summarize this purchase order"* while
pasting in EDI text — Claude will call your tools directly.

## Next steps / ideas to extend this

- Add more transaction types (856 Ship Notice, 997 Functional Acknowledgment)
- Add EDIFACT support alongside X12
- Swap the stdio transport for HTTP so it can run as a hosted service
- Add proper unit tests (pytest) for `edi_parser.py`

## Why this project

Built to demonstrate the ability to take existing backend/EDI domain
knowledge and expose it as agent-callable tools via MCP — the same pattern
companies are adopting to make internal systems accessible to AI agents.