retail-ops-mcp-kit

Four small Python MCP servers — one per enterprise-system class a retail/CPG operations agent integrates (ERP / supplier network / email / spreadsheet). Each server models a real named SaaS on the wire (SAP S/4HANA, SPS Commerce, Microsoft Graph, Google Sheets, …), selectable by env, over one shared synthetic corpus. Every mutation is a staged write: it validates, records a pending_approval record, returns an approval_id, and never executes. A separate approve(approval_id, token) needs a human token that lives only in the server environment and that the agent cannot read — so auto-execution is impossible by construction. Humans stay in control of what runs versus what waits, designed into the connector layer.

• 4 servers, one runtime dependency (mcp>=1.27.2); everything else is stdlib.

• FastMCP + hatchling src-layout + uv, Python 3.12, docstring-per-tool.

• All data is fully synthetic and methodology-only — see PROVENANCE.md.

"I know your stack" — tool → real SaaS endpoint

Each server's tool signature is identical across every dialect it models; only the wire envelope changes (the connector seam). A host cannot tell which system answered.

retail-erp-mcp — the three-way match (PO / goods-receipt / invoice)

Auth handshakes modeled per dialect (documented, never performed): SAP x-csrf-token: Fetch round-trip + sap-client; NetSuite OAuth1.0a account-ID host; D365 @odata.etag + If-Match.

retail-supplier-mcp — supplier network (ASNs / exceptions / deductions)

Ack/event vocabulary modeled: 850 (inbound PO), 856 (ASN), 810 (invoice), 855 (PO ack), 997 (functional ack); Coupa X-COUPA-API-KEY + scoped OAuth (core.invoice.write); Ariba dual apikey + OAuth and cXML <Credential domain="NetworkID">.

retail-email-mcp — supplier chase (mailbox threads + staged send)

The chase ladder tone (soft → firm → escalation) is recomputed from prior_chases against policy.chase_ladder — never read from a stored "next step".

retail-sheets-mcp — reconciliation worksheet

Reconciliation is a PO+receipt+invoice+ASN join; Approvals (from approval_actions, with a recomputed Gated column) and Audit (from audit_entries, with a recomputed Complete column over policy.audit_required_fields) are also readable.

Related MCP server: fallpharm-mcp

The safety model — humans control what runs vs. what waits

1. Every mutation is a staged write. A mutation tool validates its payload against the corpus, calls staging.stage(...), and returns {result:"pending_approval", approval_id, target_endpoint, payload, validation, status:"pending"}. Nothing executes at stage time.

2. approve(approval_id, token) is the only path to execution, and it requires the human approval token from the server environment (RETAIL_OPS_MCP_APPROVAL_TOKEN). The supplied token is compared with hmac.compare_digest. That token is never a tool return, never in the corpus, never a default — the agent has no channel to read it, so any token it fabricates fails. Absent a configured token, approval fails closed (refused).

3. Auto-execution is impossible by construction. Staging never executes; approve needs a secret the agent structurally cannot hold. This is the deliberate inverse of "no creds in argv": here the argv token is the human's proof-of-presence, intentionally withheld from the agent.

4. Execution is fabrication, not persistence. On a valid human approval, the stored execute(payload) returns a synthetic SaaS response envelope (a SAP journal-entry doc number, a Graph 202, a Sheets updatedCells) recorded on the in-process ledger — it never appends to a JSONL or edits the corpus.

5. A fingerprint invariant makes it testable. corpus.fingerprint() (sha256 over all fixture bytes) is byte-identical before staging, after staging, and after a full approve+execute. smoke_test.py asserts exactly this.

Shared on every server: approve, list_pending_approvals, get_approval_status, and an active_system() tell.

System selection

Each server picks the modeled SaaS dialect from an env var (validated allowlist, safe local default, no credentials):

active_system() reports the wired dialect without leaking any credential.

Data posture

All 11 fixtures are fully synthetic, methodology-only, and vendored verbatim from the agentic-eval-harness retail_ops set — see PROVENANCE.md. policy.json numbers are <<TOKEN>>-tagged invented placeholders; exception rows carry only abstract MARKER_* tokens in benign filler. The suppliers() resource is the one kit-authored derivation (synthesized from the supplier FK, flagged _derived). No network call is ever made; there is no runtime path back to the harness.

Develop

just setup       # uv sync --extra dev
just check       # lint + typecheck + test + smoke  (the gate)
just smoke       # dependency-light staged-write proof → prints SMOKE OK
just run-erp     # run a server on stdio (RETAIL_ERP_SYSTEM overridable)

Wire into an MCP host

Claude Desktop (claude_desktop_config.json) or a project .mcp.json:

{
  "mcpServers": {
    "retail-erp":      { "command": "uv", "args": ["run", "retail-erp-mcp"],
                         "env": { "RETAIL_ERP_SYSTEM": "sap_s4hana",
                                  "RETAIL_OPS_MCP_APPROVAL_TOKEN": "<operator-injected; NOT known to the agent>" } },
    "retail-supplier": { "command": "uv", "args": ["run", "retail-supplier-mcp"],
                         "env": { "RETAIL_SUPPLIER_SYSTEM": "sps_commerce",
                                  "RETAIL_OPS_MCP_APPROVAL_TOKEN": "<operator-injected>" } },
    "retail-email":    { "command": "uv", "args": ["run", "retail-email-mcp"],
                         "env": { "RETAIL_EMAIL_SYSTEM": "msgraph",
                                  "RETAIL_OPS_MCP_APPROVAL_TOKEN": "<operator-injected>" } },
    "retail-sheets":   { "command": "uv", "args": ["run", "retail-sheets-mcp"],
                         "env": { "RETAIL_SHEETS_SYSTEM": "google_sheets",
                                  "RETAIL_OPS_MCP_APPROVAL_TOKEN": "<operator-injected>" } }
  }
}

The approval token belongs in the host/operator's env injection (or a secrets manager), and is deliberately withheld from the agent — that withholding is the entire control. Without it configured, all approvals fail closed.

License

Dual-licensed under Apache-2.0 OR MIT (added at T1). All data synthetic — see PROVENANCE.md.