Eclipse Pantry MCP

Powered by Cyan Eclipse Technologies — https://cetech.ai

Eclipse Pantry — the unattended-retail module: it reads vending fleets' own telemetry, predicts stock-outs, and plans the route before the truck rolls. It never touches card data.

Why this exists

A vending route runs on telemetry the machines already produce — DEX audit exports carry per-selection sales, cash counters, and fault events — but the data usually sits in a platform dashboard until someone opens it, often after a machine has sat empty for days. Pantry C0 is the read layer that fixes the first half of that: a local, governed MCP surface over the fleet's own DEX exports, where every number carries its provenance and every read leaves a receipt.

Related MCP server: forecast-mcp

Status — honest labels

v0.1.0, phase C0 only (read-only telemetry, Tier 0). Local stdio transport, Python stdlib only, no network calls anywhere in the code, and the shipped fixtures are synthetic (fictional locations, invented serials). No certification claimed — bench pending.

C0 is the first phase of the Commercial Environment addendum (~/workspace/cyan-eclipse/eclipse-commercial-environment-addendum-20261025.md §3, §5). Explicitly NOT in v0.1, by spec: price changes, planogram changes (Tier 2, phase C2), route plans and pre-kitting manifests (Tier 1, phase C1), fault-ticket drafts (C1), and restock ordering — the closed loop runs through Eclipse Procure under Agent Wallet policy; Pantry supplies the forecast that starts it and the DEX read that closes it, nothing more.

Tools (6 — Tier 0 only)

The Machine Registry

Only enrolled machines exist in the tool surface — the Device Registry rule from the Procure Environment module, applied to fleets. Enrollment is an operator file edit (registry.json beside the server: machine id, type, location label, platform source, DEX serial), never an agent tool. A machine with no telemetry, or no registry entry, is invisible to Pantry — not estimated, not guessed. An ingest whose machine id is unenrolled, or whose DEX serial does not match the registry, is rejected and receipted.

PCI law (encoded + tested)

Card data lives with the reader processors. Pantry works in tokens and aggregates only; no PAN surface exists anywhere in the tool design. The ingest schema has no card-number-shaped field, and the parser scans every file before parsing: a Luhn-valid 13–19-digit sequence anywhere in the file rejects the ingest with a named PAN_DETECTED error. The value itself is never stored, logged, or echoed — only its line number is recorded. A unit test proves the PAN appears nowhere in the state file or the error after a rejected ingest.

DEX format

A DEX/UCS-style subset — asterisk-delimited records, one per line: DXS header (serial, audit counter), ID1 machine identity, DT1 collection time, RS1 counter-reset time, PA1 product assignments (selection, name, price), VA2 sales since reset, IN1 inventory snapshot (standing in for telemeter/platform inventory reads — raw DEX counters alone don't carry current counts), CA3 cash totals (cash / cashless / cashless count), EA1 event & fault records, SE1/DXE trailer. Validation is strict: unknown records, wrong field counts, non-integer counters, a sales record with no product assignment, inventory above capacity, or a missing trailer each reject the file at the offending line.

Receipts

Every ingest — accepted, duplicate, or rejected — and every read verdict appends a hash-chained receipt to the store, append-only and machine-verifiable (verify_receipt_chain; tamper detection is unit-tested). The audit trail covers what was attempted, not just what landed.

Data & IP

Fleet exhaust — per-machine, per-selection sales velocity, stock-out events, fault histories — is the operator's own first-party data (rank (a) under the Procure Data Rights Ledger). Pantry never pools one operator's location data into another operator's product, benchmarks, or models absent an explicit written agreement.

Run it

python3 server.py            # MCP over stdio, stdlib only, no dependencies
python3 smoke.py             # end-to-end smoke over real stdio (temp state)
python3 -m unittest discover tests   # 14 tests

State persists in data/state.json beside the server (override with ECLIPSE_PANTRY_STATE); the registry is registry.json beside the server (override with ECLIPSE_PANTRY_REGISTRY). data/ is gitignored — a real fleet's telemetry never belongs in a repo.

Fixtures

fixtures/ ships three synthetic DEX exports — a drink machine, a snack machine, and a combo machine, each with sales by selection, cash totals, inventory counts, and fault events, with totals a test verifies by hand-computed sums — plus two rejection fixtures: dex-malformed.txt (a non-numeric counter at line 7, an unknown record behind it) and dex-with-pan.txt (a card number pasted into a note record — the ingest must refuse it before parsing), and the registry.json that enrolls the three machines.

Roadmap (per addendum §5)

• C1 — Pantry planning: route_plan, prekitting_manifest, fault_watch ticket drafts (Tier 1 — documents; dispatch stays the operator's act). Porter pilot runs in the same phase, property-gated.

• C2 — price_change_prep / planogram_prep (Tier 2: prepared batches, executed through the platform only after operator approval), per operator policy.

License / attribution

A Cyan Eclipse Technologies product. The "Powered by Cyan Eclipse Technologies" attribution travels with it.