mcp-server

# SignalEDI MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io) server that exposes the
SignalEDI Core API (`/api/v1`) as tools, so AI clients — **Claude Desktop, Cursor,
Windsurf, Claude Code**, and any other MCP host — can parse, validate, send, and
inspect X12 EDI documents directly in a conversation or agent loop.

It is mostly a thin adapter over the hosted SignalEDI engine, with a few local X12
helper surfaces for demo mode and model grounding: synthetic templates, a small
validation/error dictionary, prompts, and bundled resources. The hosted API remains
the source of truth for production parse, validate, send, transaction, kit, and
QuickBooks flows.

| | |
| --- | --- |
| **Package** | `@signaledi/mcp-server` (npm) |
| **MCP Registry** | `io.github.SignalEDI/mcp-server` ([registry.modelcontextprotocol.io](https://registry.modelcontextprotocol.io)) |
| **Transport** | stdio |
| **Runtime** | Node 18+ (uses global `fetch`) |
| **Runtime deps** | `@modelcontextprotocol/sdk` only |
| **Auth** | Optional — **demo mode** without a key (parse/validate via public playground; generate/dictionary tools local); set `SIGNALEDI_API_KEY` for send/partner/transaction/QBO tools. |

Discoverable in the official MCP Registry and the directories that crawl it
(Smithery, Glama, mcp.so, PulseMCP). The `server.json` in this folder is the registry
manifest; `package.json` carries the matching `mcpName` ownership marker.

## Tools

| Tool | What it does |
| --- | --- |
| `parse_edi` | Parse a raw X12 interchange into structured JSON + a validation summary. |
| `validate_edi` | Validate a raw interchange against X12 structural rules (summary only). |
| `send_outbound_document` | Serialize a JSON payload to EDI and send it to a trading partner (async, webhook-acked). |
| `list_transactions` | List your recent transactions (newest first), scoped to the API key. |
| `get_transaction` | Fetch one transaction by id with full lifecycle status. |
| `quickbooks_status` | Show QuickBooks Online connection status without returning tokens. |
| `quickbooks_sync_to_qbo` | Push eligible EDI transactions into QuickBooks Online. |
| `quickbooks_export_to_edi` | Pull QBO invoices or purchase orders and emit outbound EDI payloads. |
| `quickbooks_list_entities` | List QBO invoices, purchase orders, customers, vendors, or items for preview/mapping. |
| `quickbooks_disconnect` | Revoke and remove the workspace QBO connection. |
| `list_partner_kits` | List packaged API kits (requires key). |
| `get_partner_kit` | Fetch one kit by `kitId`, with `partnerId` accepted as an alias (requires key). |
| `explain_edi_error` | Local X12 dictionary lookup for ack/validation errors. |
| `generate_test_document` | Render synthetic X12 850/810/856/837 samples (works in demo mode). |
| `lookup_x12` | Search segment and acknowledgement reference. |
| `validate_x12_structure` | Alias for `validate_edi`, tuned for tool discovery. |
| `parse_segments` | Alias for `parse_edi`, tuned for tool discovery. |
| `lookup_element_definition` | Alias for `lookup_x12`; accepts `query` or `element`. |

Bad arguments and API errors are returned as structured MCP tool errors with stable
codes (so the model can recover from them) rather than crashing the server. Results
include both backwards-compatible text content and native `structuredContent`.

### Mutation safety

Tools that send EDI, write to QuickBooks, or disconnect QuickBooks require both
`confirm: true` and a unique `idempotencyKey` (at least eight characters). The
server adds a request id, tool name, and idempotency header to outbound API calls.
Dry-run QuickBooks export remains available without confirmation. Tool listings
advertise read-only versus destructive behavior and required capability scopes.

The client rejects non-HTTPS base URLs except for localhost, caps EDI payloads at
64 KiB, retries transient failures within a total deadline, and emits redacted
per-tool latency/success metrics to stderr. Set `SIGNALEDI_MCP_TELEMETRY=0` to
disable local metric lines.

## Quick start

1. **Try without a key (demo mode).** Run `npx -y @signaledi/mcp-server` with no env vars —
   `parse_edi` and `validate_edi` call the public playground; `generate_test_document`,
   `explain_edi_error`, `lookup_x12`, and the alias tools use local X12 templates/dictionary
   data. Keyed tools return a structured `demo_mode` error with a link to create a key.
2. **Add a platform key for production flows.** Create a workspace key with the `platform`
   scope at [signaledi.com/console/keys](https://signaledi.com/console/keys) and set
   `SIGNALEDI_API_KEY`.

### One-click install

- **Cursor:** [Install in Cursor](cursor://anysphere.cursor-deeplink/mcp/install?name=signaledi&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBzaWduYWxlZGkvbWNwLXNlcnZlciJdLCJlbnYiOnsiU0lHTkFMRURJX0FQSV9LRVkiOiIifX0) (same deeplink as the developer site chip).
- **Claude Code:** `claude mcp add signaledi -- npx -y @signaledi/mcp-server`

### Claude Desktop / Claude Code

Add to your MCP config (`claude_desktop_config.json`, or `.mcp.json` for Claude Code):

```json
{
  "mcpServers": {
    "signaledi": {
      "command": "npx",
      "args": ["-y", "@signaledi/mcp-server"],
      "env": {
        "SIGNALEDI_API_KEY": "sk_live_…"
      }
    }
  }
}
```

### Cursor / Windsurf

Same shape under the editor's MCP settings (`command: npx`, `args: ["-y",
"@signaledi/mcp-server"]`, and the `SIGNALEDI_API_KEY` env var).

## Demo mode

Without a key, the server runs in demo mode (stderr notice): `parse_edi` and `validate_edi` call the public playground; local template/dictionary tools run without network; keyed tools return JSON `{ "error": "demo_mode" }`; successful demo results append `— demo mode; responses rate-limited`.

## Configuration

| Env var | Required | Default | Notes |
| --- | --- | --- | --- |
| `SIGNALEDI_API_KEY` | — (demo mode) / ✅ (full access) | — | Workspace key with the `platform` scope for send/partner/QBO tools. |
| `SIGNALEDI_BASE_URL` | — | `https://signaledi.com` | Point at a custom domain or a preview deployment. |

The server speaks JSON-RPC over **stdout**; all logs go to **stderr**, so it never
corrupts the protocol channel.

## Example prompts

> "Parse this 850 and tell me the PO number and ship-to." *(paste raw EDI)*
> "Validate this interchange and list any structural errors."
> "Show my last 10 transactions and flag any that missed SLA."
> "Send an 810 invoice to partner `acme-co` with these line items…"

## Local development

```bash
node test.mjs        # dependency-free unit tests (mock fetch, no network)
SIGNALEDI_API_KEY=… npm start   # run the stdio server against the live API
```

The client (`src/client.mjs`) and tools (`src/tools.mjs`) are pure and unit-tested;
`src/index.mjs` is the only file that depends on the MCP SDK.

## How it fits

```
MCP client (Claude/Cursor/…) ⇄ @signaledi/mcp-server (stdio) ⇄ SignalEDI Core API (/api/v1)
                                      └ local X12 templates/dictionary/resources for demo + guidance
```

See the [SDK](../../packages/sdk) for a programmatic TypeScript client and
[`docs/openapi/v1`](../../docs/openapi/v1) for the full API reference.
## GitHub mirror

[![npm version](https://img.shields.io/npm/v/@signaledi/mcp-server.svg)](https://www.npmjs.com/package/@signaledi/mcp-server)
[![MCP Registry](https://img.shields.io/badge/MCP-io.github.SignalEDI%2Fmcp--server-blue)](https://registry.modelcontextprotocol.io)

The public GitHub repo [`SignalEDI/mcp-server`](https://github.com/SignalEDI/mcp-server) mirrors **this folder only**. The GitLab monorepo stays the source of truth; the mirror updates on each npm publish (see [`MIRROR.md`](MIRROR.md) and the operator runbook [`docs/internal/runbooks/GITHUB_MCP_MIRROR.md`](../../../docs/internal/runbooks/GITHUB_MCP_MIRROR.md)).

### Examples

| Script | Purpose |
| --- | --- |
| [`examples/parse-demo.mjs`](examples/parse-demo.mjs) | Parse synthetic 850 via demo-mode client |
| [`examples/generate-validate.mjs`](examples/generate-validate.mjs) | Generate 850 locally, then validate |
| [`examples/agent-transcript.md`](examples/agent-transcript.md) | Illustrative agent conversation (no secrets) |

Run from this directory: `node examples/parse-demo.mjs`

Issue templates for the GitHub repo live under [`examples/.github/ISSUE_TEMPLATE/`](examples/.github/ISSUE_TEMPLATE/) (copied to repo root on mirror sync). Layout: [`examples/github-mirror-layout.md`](examples/github-mirror-layout.md).

### Mirror security checklist

Before every mirror push:

- No internal URLs, API keys, engine code, or employee/customer data in the tree
- Examples use synthetic EDI only; transcripts are fictional
- Badges and links point at public npm, MCP registry, and signaledi.com only