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)

MCP tool	Kind	SAP S/4HANA (default)	Oracle NetSuite	MS Dynamics 365 F&O
get_purchase_order	read	GET …/API_PURCHASEORDER_PROCESS_SRV/A_PurchaseOrder('…')?$expand=to_PurchaseOrderItem → {"d":{…}}	GET /services/rest/record/v1/purchaseOrder/{id} → {id,tranId,entity,item:{items[]}}	GET /data/PurchaseOrderHeadersV2(dataAreaId='usmf',PurchaseOrderNumber='…') → {@odata.etag,…}
get_goods_receipt	read	GET …/API_MATERIAL_DOCUMENT_SRV/A_MaterialDocumentHeader (GM type 101)	GET …/record/v1/itemReceipt/{id}	GET /data/ProductReceiptHeaders
get_invoice	read	GET …/API_SUPPLIERINVOICE_PROCESS_SRV/A_SupplierInvoice('…')	GET …/record/v1/vendorBill/{id}	GET /data/VendorInvoiceHeaders
list_open_pos	read	GET …/A_PurchaseOrder?$filter=… → {"d":{"results":[]}}	GET …/record/v1/purchaseOrder?q=status:open → {items,hasMore,offset}	GET /data/PurchaseOrderHeadersV2?$filter=PurchaseOrderStatus eq 'Backorder'
stage_invoice_payment	staged-write	POST …/API_JOURNALENTRYITEMBASIC_SRV/A_JournalEntryItemBasic (x-csrf-token)	POST …/record/v1/vendorPayment	POST /data/VendorPaymentJournalHeaders
stage_po_amendment	staged-write	PATCH …/A_PurchaseOrder('…') (If-Match / x-csrf)	PATCH …/record/v1/purchaseOrder/{id}	PATCH /data/PurchaseOrderHeadersV2(…) (If-Match etag)
simulate_po_event	webhook seam	Advanced Event Mesh CloudEvent sap/s4/beh/purchaseorder/v1/…/Created/v1	SuiteScript user-event https.post callback	Business Events → Azure Event Grid

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)

MCP tool	Kind	SPS Commerce (default)	Coupa	SAP Ariba
get_asn	read	EDI-856 Universal-JSON: hierarchicalLevels[] (S→O→T→I), carrier.scac, sscc18	REST ASN document	cXML ShipNoticeRequest
get_shipment_status	read	214-style status {shipmentIdentification, carrier, trackingNumber, status}	ASN status document	cXML StatusUpdateRequest
get_supplier	read	trading-partner {tradingPartnerId, senderId, …} (derived)	supplier record (derived)	supplier + NetworkID (derived)
list_exceptions	read	exception-queue rows [{id, po_id, evidence_text}] (gold_* withheld)	— same abstraction —	— same abstraction —
stage_credit_note	staged-write	EDI 810-variant	Coupa document-type:"credit_note"	InvoiceDetailRequest purpose="creditMemo"
stage_debit_note	staged-write	SPS debit doc	Coupa negative invoice	InvoiceDetailRequest purpose="debitMemo"
acknowledge_exception	staged-write	EDI 855 PO-ack (itemStatusCode IA/IB/IR) + 997 functional ack	POST /documents/{id}/acknowledge	cXML confirmation
simulate_inbound_asn	webhook seam	{eventType:"document.received", transactionType:"856", …} + the 856 payload	{event:"purchase_order.updated", …}	cXML StatusUpdateRequest

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)

MCP tool	Kind	Microsoft Graph (default)	Gmail API
list_chase_thread	read	GET /me/messages?$filter=conversationId eq '…' → {"value":[…]}	GET /users/me/threads/{id}
get_supplier_reply	read	GET /me/messages/{id}	messages.get?format=full (base64url payload)
stage_chase_email	staged-write	POST /me/sendMail (202, no body)	messages.send {raw, threadId}
stage_escalation_email	staged-write	POST /me/sendMail with ccRecipients	messages.send {raw, threadId}
simulate_change_notification	webhook seam	Graph change-notification + validationToken echo	Pub/Sub {message:{data:<base64>}} + historyId cursor

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

MCP tool	Kind	Google Sheets (default)	MS Graph Excel
read_reconciliation_sheet	read	GET /v4/spreadsheets/{id}/values/Reconciliation!A1:I11 → {range,majorDimension,values}	#microsoft.graph.workbookRange (values/text/numberFormat/valueTypes, JSON-number cells)
get_range	read	GET …/values/{range} over Reconciliation / Approvals / Audit	…/worksheets('…')/range(address='…')
stage_cell_update	staged-write	PUT …/values/{range}?valueInputOption=USER_ENTERED	PATCH …/range(address='…')
stage_row_append	staged-write	values:append	…/tables/{name}/rows/add {values:[[…]]}
simulate_change_notification	webhook seam	Drive files.watch push channel (Sheets values have no native webhook)	driveItem change-notification (+ 409/423 stale workbook-session)

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.

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):

Server	Env var	Allowlist	Default
retail-erp-mcp	RETAIL_ERP_SYSTEM	sap_s4hana, netsuite, dynamics365	sap_s4hana
retail-supplier-mcp	RETAIL_SUPPLIER_SYSTEM	sps_commerce, coupa, ariba	sps_commerce
retail-email-mcp	RETAIL_EMAIL_SYSTEM	msgraph, gmail	msgraph
retail-sheets-mcp	RETAIL_SHEETS_SYSTEM	google_sheets, msgraph_excel	google_sheets

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.