Legacy

MCP-ifying a legacy system: governed, business-language tools over a SOAP + stored-procedure stand-in — with a semantic data dictionary, compensation for transactionless writes, and measured load protection.

Suggested GitHub repo name: legacy-mcp

---

Why this project exists

Enterprises run on decades-old systems: SOAP services, stored-procedure databases, cryptic schemas nobody fully remembers. The current wave of forward-deployed work is making those systems usable by AI agents without replacing them — wrapping legacy interfaces in governed, modern tool layers. The craft is not the MCP part; it's the archaeology (what does PROC_UPD_47 actually do?), the safe-write patterns on a backend with no cross-call transactions, and the duty of care toward infrastructure that dies if you hammer it.

This project builds the legacy system and the wrapper, so every claim is checkable end to end.

The legacy stand-in (authentically awful, on purpose)

A wholesale order-management backend, reachable only through a SOAP-style XML endpoint fronting stored procedures:

• tables T_CST/T_ITM/T_ORD_H/T_ORD_L; columns like C_STS CHAR(1) with magic letters (A/H/X), money in integer cents, dates as YYYYMMDD ints
• positional parameters (<P1>, <P2>…), faults like ERR-3007 CONSTRAINT VIOLATION SEGMENT 4
• no cross-call transactions: creating an order is a three-procedure protocol (HDR_INS → LN_INS per line → FIN); die in the middle and an incomplete header is stranded forever (the seed data ships with orphan order 9005 as the exhibit)
• undocumented side effects: PROC_UPD_47 "sets customer status" but also recalculates the credit-block flag from open order exposure — so releasing a hold does not necessarily unblock the customer
• fragility: above ~5 calls/s it faults ERR-9999 SYSTEM BUSY; under injected latency it just gets slower

The wrapper never imports the database — it speaks the XML wire only, like a real engagement.

The deliverables

1. The semantic data dictionary (docs/data_dictionary.md) — every table, column, status letter, procedure contract, error code, and landmine, with how each was recovered (trial calls, audit-log diffing). semantics.py is its executable form; tests pin them to each other.

2. Governed MCP tools (official SDK) designed around business operations, not endpoints: lookup_customer, get_customer_credit, check_item_availability, get_order_status, list_orders, place_order, cancel_order, release_hold, set_customer_status, cleanup_incomplete_orders. Statuses are words, money is decimal, dates are ISO. Every failure — including a malformed argument from the agent — arrives as one actionable sentence: what happened, what to do, and the raw code for the humans. Verbatim:

ERR-3007 → Blocked during order creation for customer 4711: the customer is on hold or over their credit limit. Use get_customer_credit to see exposure vs limit; release_hold clears a hold but will NOT clear an over-limit credit flag. [legacy: ERR-3007 CONSTRAINT VIOLATION SEGMENT 4]

3. Compensation for transactionless writes. place_order drives the three-call protocol; on any mid-protocol failure it deletes the incomplete order and says so. The failed-order path is tested down to "no orphan rows, stock untouched."

4. Load protection, measured live. Every legacy call passes a token bucket (throttle by waiting, not shedding) and a circuit breaker (open on consecutive infra failures; half-open probe; business faults never count).

Measured results

All produced by commands in this repo on 2026-07-31 (results/ committed). Tests: 75/75 passed.

Before/after capability (legacy-mcp capability)

Same six tasks; a scripted generic-competence operator against the raw SOAP surface vs the same shell using the MCP tools. Judged only by end-state database checkers and exact numbers — no graders. (Methodology and the raw operator's generous assumptions are documented in capability.py; the knowledge it lacks — status letters, the three-call protocol, cents, fault semantics — is precisely what the wrapper packages.)

task	raw interface	MCP tools	wrapped detail
place-simple-order	FAIL	PASS	pending order, correct total, stock decremented
blocked-order-explained	FAIL	PASS	diagnosed: hold AND over-limit; release won't fix
partial-failure-cleanup	FAIL	PASS	failure explained, no orphans, stock untouched
cancel-and-restock	FAIL	PASS	cancelled; restock observed (8 → 18)
janitor-incomplete-orders	FAIL	PASS	orphan 9005 identified and removed
credit-headroom	FAIL	PASS	12,000.00 limit − 1,540.00 open = 10,460.00

raw 0/6 — wrapped 6/6. Representative raw failures: the order left stranded in I because nothing advertises that OP_ORD_FIN exists; headroom computed from cents and shipped orders; "stuck orders" invisible because I is just a letter.

Protection under a degraded backend (legacy-mcp protection-demo, real sockets)

Slow backend (2s/call, wrapper timeout 0.5s, breaker threshold 3):

call	outcome	wall (s)
1–3	timeout	~0.50 each
4–8	fast-fail, circuit open	0.000
9 (after recovery + cool-down)	ok — half-open probe closed the circuit	0.003

The breaker held total backend calls to 4 across the whole episode (3 timed-out probes + 1 recovery probe); five agent calls were answered instantly with an actionable "backend degraded, retry in Ns" instead of hanging.

Busy backend (faults above 5 calls/s), 25 reads:

caller	succeeded	SYSTEM BUSY faults	wall
unthrottled	5/25	20	0.08s
wrapped (bucket 1 + 4/s)	25/25	0	6.11s

The wrapper spent 5.8s deliberately waiting — trading its own latency for the backend's health, which is the entire duty of care. Successes are reported next to faults on purpose: "zero busy faults" would also be true of a caller that fast-failed everything, so the table has to show that all 25 calls actually completed. The first sizing attempt (bucket 4 + 4/s) still produced 2 busy faults because burst + refill exceeded the backend's ceiling in the first second; the fix (capacity 1) is kept in the code comment as the lesson: size the bucket to the backend's measured capacity, not to a round number.

Quickstart

uv sync --extra dev
cp .env.example .env

.venv/bin/pytest                     # 75 tests: stand-in, semantics, compensation, protection
.venv/bin/legacy-mcp capability      # the before/after table -> results/capability.md
.venv/bin/legacy-mcp protection-demo # live slow/busy scenarios -> results/protection.md
.venv/bin/legacy-mcp raw-peek        # feel the raw interface yourself

# run it for a real agent
.venv/bin/legacy-mcp serve-legacy &                    # the legacy stand-in (:8093)
.venv/bin/legacy-mcp serve-mcp                         # MCP over stdio, wired to it
# degrade the backend and watch the wrapper cope:
LEGACY_SLOW_MS=2000 .venv/bin/legacy-mcp serve-legacy

protection-demo stands up its own backends on SOAP_PORT and the two ports above it, so stop a backgrounded serve-legacy first or point it elsewhere with SOAP_PORT=8200. It says which port it could not bind rather than hanging.

Repository layout

legacy-mcp/
├── docs/data_dictionary.md         # the archaeology deliverable
├── results/                        # committed capability + protection evidence
├── src/legacy_mcp/
│   ├── legacy/db.py                # the stand-in: procs, protocol, faults, fragility
│   ├── legacy/soap.py              # XML envelope endpoint (the only wall socket)
│   ├── legacy/client.py            # typed wire client; adds no meaning
│   ├── semantics.py                # recovered meaning: codes, units, error translation
│   ├── tools.py                    # business-operation tools + compensation
│   ├── protection.py               # token bucket + circuit breaker (Guard)
│   ├── protection_demo.py          # live measured scenarios
│   ├── capability.py               # before/after suite, end-state checkers
│   ├── server.py                   # MCP registration (official SDK)
│   └── cli.py                      # serve-legacy | serve-mcp | capability | protection-demo
└── tests/                          # 75 tests, incl. the agent-facing failure contract

Honesty notes

• The "raw operator" in the capability suite is scripted, not an LLM; its generic competence and its ignorance are both explicit in code. The suite measures what the interface affords, and the strict test (raw 0/6, wrapped 6/6) fails in both directions if either side drifts.
• The legacy stand-in is self-built, so its awfulness is curated rather than accreted. Every quirk it has is one documented from real systems (transactionless multi-call writes, overloaded error codes, side-effecting status procs, cents/YYYYMMDD encodings, SYSTEM BUSY ceilings).
• The protection numbers come from real sockets and real timeouts, not mocks; the deterministic breaker/bucket unit tests use a simulated transport and say so.
• The failure contract is tested, not asserted in prose: tests/test_error_contract.py renders every fault template against every operation phrase the tools actually pass, and drives fifteen kinds of malformed argument through place_order to prove nothing escapes as a raw exception. Both suites exist because both properties were broken — the templates read "Customer order creation for customer 4711 is blocked" and bad quantities surfaced a TypeError.