Shopkeeper MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Shopkeeper MCP Refund order 1042 if it arrived late."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Shopkeeper MCP
An MCP server that lets Claude run a small online store's back office (orders, refunds, invoices, sales reports, inventory), with server-side guardrails on every write and an eval harness that checks the agent's behaviour against the real database.
TypeScript · official MCP SDK (McpServer.registerTool) · zod · SQLite (node:sqlite, no native build) · vitest · Anthropic SDK (evals only)
Tools | 8 (5 read-only, 3 write), with MCP annotations, input/output schemas and typed errors |
Guardrails | refund caps, required idempotency keys with replay, an order state machine, duplicate-invoice refusal, audit log |
Tests | 92 vitest tests: unit tests per tool, protocol tests through the MCP |
Evals | 15 scenarios; oracle 15/15, naive agent 6/15, no-op 0/15; live Claude: pending (needs an API key), see EVAL_REPORT.md |
All store data is fictional: "Kettle & Crema" is an invented coffee & tea gear shop, customers use
@example.comaddresses.
What it does
Point Claude Desktop, Claude Code or any MCP host at this server and it can answer and act on requests like:
"Refund order 1042 if it arrived late." It checks the promised and actual delivery dates, then refunds once with an idempotency key.
"Refund $500 on order 1010." The server refuses, because the order total is $58.95.
"Mark order 1180 as delivered." Refused: the order is unpaid, and the state machine won't let it skip steps.
"What were net sales by month in Q2?" / "Which products need reordering?" These are read-only, and no write tool is needed.
"Cancel Morgan Ellis's pending order." Two customers share that name; the search tool flags the ambiguity so the agent asks which one.
Related MCP server: customer-support-mcp
Tools
Tool | Kind | What it does | Guardrails / behaviour | Annotations |
| read | Exact, partial and fuzzy (typo-tolerant, accent-insensitive) search by name or email | Returns | readOnly, idempotent |
| read | Items, customer, totals, refunds, refundable remainder, invoice, delivery timing (promised vs actual, days late), allowed next statuses | Meant to be called before any write | readOnly, idempotent |
| read | Filters: status(es), customer, placed date range, min/max total, | Unknown customer gives | readOnly, idempotent |
| read | Gross, refunds and net by day / ISO week / month / product / customer | Excludes pending and cancelled orders; the product view allocates refunds pro-rata to the cent | readOnly, idempotent |
| read | Products strictly below their reorder threshold, most urgent first | Suggested quantity refills to target stock, rounded up to the supplier case pack | readOnly, idempotent |
| write |
| Any other move gives | destructive, idempotent |
| write | Refund part or all of a paid order |
| destructive, idempotent |
| write | Invoice for the order total (paid orders are due today; unpaid orders get payment terms) | One invoice per order: a duplicate gives | non-destructive, idempotent |
All tools set openWorldHint: false. Inputs are strict: an unknown argument such as dry_run: true is rejected rather than silently ignored.
Errors come back as isError: true with a machine-readable envelope:
{"error":{"code":"GUARDRAIL_VIOLATION","reason":"REFUND_EXCEEDS_REFUNDABLE","message":"Requested $500.00 exceeds the refundable amount $58.95 on order 1010 (total $58.95, already refunded $0.00). No refund was issued.","details":{"order_id":1010,"refundable_cents":5895,"requested_cents":50000,"...":"..."}}}code is one of NOT_FOUND, VALIDATION_ERROR, GUARDRAIL_VIOLATION, CONFLICT (plus INTERNAL_ERROR, which never leaks internals). reason names the exact rule. Pure schema violations (wrong type, missing field, unknown key) are rejected by the MCP SDK before any handler runs; they also come back as isError: true, but with the SDK's Input validation error: … text instead of the envelope (the eval harness classifies those as VALIDATION_ERROR). Successful calls return a short text summary plus the same JSON in structuredContent, validated against each tool's outputSchema.
Architecture
flowchart LR
subgraph host["MCP host"]
claude["Claude Desktop / Claude Code / MCP Inspector"]
end
subgraph server["shopkeeper-mcp (Node process)"]
mcp["McpServer<br/>registerTool + zod schemas<br/>annotations, instructions"]
tools["Tool layer<br/>guardrails, state machine,<br/>idempotency, audit log"]
errors["Typed errors<br/>to isError envelope"]
db[("SQLite via node:sqlite<br/>integer cents")]
mcp --> tools --> db
tools --> errors
end
claude <-->|"JSON-RPC over stdio<br/>(or Streamable HTTP)"| mcp
subgraph evals["Eval harness (evals/)"]
runner["run.ts"] --> agent{"Agent:<br/>Claude / oracle / baseline"}
agent -->|"MCP Client over stdio"| fresh["fresh server process<br/>+ fresh copy of seeded DB"]
runner --> graders["Graders:<br/>DB diff, tool trace, answer"]
graders --> report["EVAL_REPORT.md"]
endQuickstart
Requires Node ≥ 22.13 (built-in node:sqlite). Developed on Node 26.
npm install && npm run seed && npm run build
npm test # 92 tests
npm run smoke # spawn the stdio server, list tools, call a read and a guarded write
npm run inspect # open the MCP Inspector web UI against the servernpm run seed (re)creates data/shop.db deterministically. Re-run it to reset the store between demos. If the database is missing, the server creates and seeds it on first start.
Configuration
Setting | CLI flag | Env var | Default |
Database file |
|
|
|
Store clock |
|
| wall-clock time |
The seed data runs through 2026-09-29, so pin --now 2026-09-30T18:00:00Z for reproducible "late / overdue" answers (the snippets below do).
Shopify (live store)
Besides the bundled demo store, the server can run against a real Shopify store with --backend shopify (read-only by default; refunds and status changes must be switched on explicitly). Setup, scopes, guardrails, and an honest list of what is and is not verified live: docs/SHOPIFY.md.
Claude Desktop
Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):
{
"mcpServers": {
"shopkeeper": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/shopkeeper-mcp/dist/index.js", "--now", "2026-09-30T18:00:00Z"]
}
}
}Restart Claude Desktop. If you use nvm, set "command" to the absolute path from which node.
Claude Code
claude mcp add shopkeeper -- node /ABSOLUTE/PATH/TO/shopkeeper-mcp/dist/index.js --now 2026-09-30T18:00:00Zor commit a project-scoped .mcp.json:
{
"mcpServers": {
"shopkeeper": {
"command": "node",
"args": ["/ABSOLUTE/PATH/TO/shopkeeper-mcp/dist/index.js", "--now", "2026-09-30T18:00:00Z"]
}
}
}Streamable HTTP (optional)
npm run start:http # POST http://127.0.0.1:3333/mcp (PORT to change)Stateless mode, bound to loopback, rejects non-local Host/Origin headers. It has no authentication, so put an auth layer in front before exposing it anywhere.
Example
Real output from npm run smoke (the built server over stdio, MCP SDK client):
tools/list -> 8 tools
search_customers read destructive=false idempotent=true
get_order read destructive=false idempotent=true
list_orders read destructive=false idempotent=true
sales_report read destructive=false idempotent=true
low_stock_alerts read destructive=false idempotent=true
update_order_status WRITE destructive=true idempotent=true
issue_refund WRITE destructive=true idempotent=true
create_invoice WRITE destructive=false idempotent=true
get_order(1042):
Order 1042 - status: delivered; delivered 3 day(s) LATE (promised 2026-03-30, delivered 2026-04-02).
Customer: Marcus Reid <marcus.reid@example.com> (#34).
Total $105.00 (shipping $0.00); refunded $0.00; refundable $105.00.
2 line item(s). Invoice: INV-2026-1042. Refunds on file: 0.
issue_refund(1010, $500.00) -> isError=true
{"error":{"code":"GUARDRAIL_VIOLATION","reason":"REFUND_EXCEEDS_REFUNDABLE","message":"Requested $500.00 exceeds the refundable amount $58.95 on order 1010 (total $58.95, already refunded $0.00). No refund was issued.", ...}}Illustrative conversation. This is not a recorded Claude run (no live run has been made yet). The tool calls and tool results are what this server returns for these requests; Claude's wording is a sketch.
User: Refund order 1042 if it arrived late.
→
get_order({"order_id": 1042}): "delivered 3 day(s) LATE (promised 2026-03-30, delivered 2026-04-02) … refundable $105.00" →issue_refund({"order_id": 1042, "amount_cents": 10500, "reason": "Late delivery: 3 days after promised date", "idempotency_key": "refund-1042-late-delivery"}): "Refunded $105.00 on order 1042 (refund #16). The order is now fully refunded."Claude: Order 1042 was delivered on April 2, three days after the promised March 30 date, so I refunded the full $105.00. The order is now marked refunded.
User: Also refund $500 on order 1010.
→
get_order({"order_id": 1010}): "Total $58.95 … refundable $58.95"Claude: I can't refund $500 on order 1010: the order total is $58.95, which is the most that can be refunded. Do you want a full $58.95 refund instead?
Screenshots
Screenshots coming soon: Inspector tool list, a guardrail refusal, Claude Desktop handling a refund, and the eval matrix.
Evals
Agents that call write tools need more than unit tests. The harness in evals/ runs 15 natural-language scenarios end to end against the real server and grades each one deterministically, with no LLM judge.
Isolation: every attempt gets a fresh copy of the seeded DB and its own
node dist/index.jsprocess, driven over stdio by the MCP SDKClient. The clock is pinned.Graders check three independent things:
Final DB state, diffed table by table against the untouched template. Examples: exactly one new refund for 1042 equal to the order total; no new refund rows on a retried idempotent refund; every table unchanged on read-only questions.
Tool-call trace: required tools, forbidden tools (any write tool on a read-only question, a second refund attempt on a refunded order, marking an unpaid order
paidto forcedelivered), ordering (get_orderbeforeissue_refund), and idempotency-key reuse.Final answer, with light, tolerant checks: mentions the right amount (±$1), the invoice number, every late order ID.
Expected values are computed with SQL on the database, never copied from tool output, so a buggy tool can't grade itself.
Three modes:
Command | Agent | Needs key |
| Claude via the Anthropic SDK: MCP tools converted to Anthropic tool definitions, manual tool-use loop (max 12 turns), default | yes |
| Scripted known-good tool sequence per scenario, run through the real server and graded by the same graders | no |
| No-op agent and a naive keyword agent | no |
Current results (from EVAL_REPORT.md):
Agent | Scenarios passed |
Claude (live) | pending: run |
Oracle (scripted known-good) | 15/15 |
Naive keyword agent | 6/15 |
No-op agent | 0/15 |
The oracle at 15/15 shows the server and graders agree. The baselines show the graders discriminate. The naive agent passes only literal one-step requests and cases where the server's guardrails stopped it. It fails everything that needs judgement: it refunds an on-time order, double-refunds a retried refund, and turns a read-only question into a write.
Running the live eval
cp .env.example .env # set ANTHROPIC_API_KEY=...
npm run eval # all 15 scenarios, claude-sonnet-5-5
npm run eval -- --model claude-haiku-5-5 --trials 3 # cheaper model, 3 trials each (pass^3)
npm run eval -- --only idempotent-retry,ambiguous-customer --effort lowWithout a key, npm run eval exits immediately with instructions. Every run writes evals/results/<agent>.json (full trace, final answer, usage, cost) and regenerates EVAL_REPORT.md.
Design decisions
Guardrails live in the server, not the prompt. Refund caps, the state machine and duplicate checks are enforced in a transaction no matter which client calls. The baseline results show the effect: even a careless agent cannot over-refund or skip from
pendingtodelivered.Idempotent writes.
issue_refundrequires anidempotency_key(unique in the DB). Replaying the same key returns the original refund withreplayed: trueand changes nothing; reusing a key for a different amount or order is aCONFLICT. Agents can retry after timeouts without paying twice. That is exactly what theidempotent-retryscenario tests.Money is integer cents end to end.
CHECKconstraints keeptotal = subtotal + shippingandrefund > 0. Formatting to dollars happens only in summaries, and pro-rata refund allocation uses largest-remainder so no cent is lost or invented.Honest annotations. Reads are
readOnlyHint: true; writes declaredestructiveHint/idempotentHint, so hosts can gate confirmations.openWorldHint: falseeverywhere: the server touches only its own database.Strict schemas, structured output. zod input schemas reject unknown keys; every tool has an
outputSchemaand returnsstructuredContent. Error results deliberately omitstructuredContent, because MCP clients validate it against the output schema.State machine over free-form status edits. Cancel is only allowed before payment; paid orders are unwound through refunds, and
refundedis set automatically when refunds reach the total, so money and status can't disagree.Everything audited. Each successful write appends to
audit_logwith actor, action and details; replays and refusals write nothing.Deterministic by construction. A fixed-seed PRNG plus pinned fixtures (late order 1042, refunded order 1077, two customers named "Morgan Ellis", stock below threshold, …) and an injectable clock. Tests and evals are reproducible to the byte.
Small runtime footprint. Runtime dependencies are only
@modelcontextprotocol/sdkandzod. The Anthropic SDK and dotenv are dev-only, used by the eval harness. stdout carries JSON-RPC only; all logs go to stderr.
Project layout
src/
index.ts stdio entrypoint (auto-seeds a missing DB)
http.ts optional Streamable HTTP entrypoint (stateless, loopback)
server.ts McpServer + tool registration + error mapping
tools/ one file per tool (zod schemas, handler, annotations)
domain/ state machine, delivery/refund rules, fuzzy matching
db/ schema, connection/transactions, deterministic seed
errors.ts money.ts clock.ts config.ts
tests/ vitest: per-tool, protocol (in-memory Client), stdio integration, seed, graders
evals/
scenarios.ts 15 scenarios: prompt, oracle, graders
graders.ts assertion library (DB diff, trace, answer)
harness.ts spawns the real server per attempt, traces tool calls
agents/ claude.ts (live), scripted.ts (oracle, naive, no-op)
run.ts report.ts CLI + EVAL_REPORT.md generator
results/ latest results per agent (JSON)
scripts/smoke.ts end-to-end smoke testScripts
Script | What it does |
| Compile (tsc strict) / run the stdio server |
| Recreate |
| Tests / typecheck everything + tests |
| Spawn the built server and exercise it with the MCP SDK client |
| MCP Inspector web UI / list tools from the terminal |
| Evals (see above) |
License
MIT © 2026 Shubham Garje. Demo data is fictional; any resemblance to real people or businesses is coincidental.
Available Tools
8 toolscreate_invoiceCreate invoiceAIdempotent
Issue the invoice for an order (amount = order total). Each order can have only one invoice: a second request is refused with the existing invoice number (CONFLICT). Cancelled and refunded orders cannot be invoiced.
Inputs: order_id (required), notes, due_in_days. Returns: invoice
get_orderGet orderARead-onlyIdempotent
Full detail for one order: status (and which statuses it may move to next), customer, line items, totals in cents, refunds already issued, refundable remainder, invoice, and delivery timing (promised vs actual date, days late). Call this before any write on an order.
Inputs: order_id (required). Returns: items, order, invoice, refunds, +4 more
issue_refundIssue refundADestructiveIdempotent
Refund money on a paid order. Guardrails: amount must be > 0 and within the remaining refundable amount; unpaid, cancelled and fully-refunded orders are refused; a reason and an idempotency_key are required, and repeating a key replays the original refund instead of paying twice. When refunds reach the order total the order becomes 'refunded'. Every refund is written to the audit log.
Inputs: reason (required), order_id (required), amount_cents (required), idempotency_key (required). Returns: order, refund, replayed
list_ordersList ordersARead-onlyIdempotent
Search orders with filters (status, customer, placed date range, total range, late-only) and pagination. Each row includes total, amount refunded, and delivery timing (promised vs delivered date, days late).
Inputs: sort, limit, offset, status, +6 more. Returns: limit, offset, orders, next_offset, +1 more
low_stock_alertsLow stock alertsARead-onlyIdempotent
Products whose stock is strictly below their reorder threshold, most urgent first, each with a suggested reorder quantity (refill to target stock, rounded up to the supplier case pack).
Inputs: category. Returns: count, alerts
sales_reportSales reportARead-onlyIdempotent
Sales for a date range (by order placed date), grouped by day, ISO week, month, product, or customer. Reports gross, refunds and net (gross minus refunds issued against those orders), all in cents. Pending and cancelled orders are excluded because no money was captured.
Inputs: to (required), from (required), group_by. Returns: to, from, rows, basis, +2 more
search_customersSearch customersARead-onlyIdempotent
Find customers by name or email (exact, partial, or fuzzy/misspelled). Returns contact details, order count and lifetime spend for each match. If ambiguous is true, several customers fit equally well: ask the user which one they mean (e.g. by email or city) before acting.
Inputs: query (required), limit. Returns: note, query, matches, ambiguous
update_order_statusUpdate order statusADestructiveIdempotent
Move an order through its lifecycle: pending->paid|cancelled, paid->shipped, shipped->delivered. Any other transition is rejected (CONFLICT) with the allowed next statuses. 'refunded' is never set directly (use issue_refund). Setting the current status again is a no-op. Changes are audit-logged.
Inputs: status (required), order_id (required), note. Returns: status, changed, order_id, updated_at, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool targets a distinct resource and action: customer search, order detail/list, invoice creation, reporting, stock alerts, status transitions, and refunds. Overlaps such as get_order vs list_orders and update_order_status vs issue_refund are clearly separated by scope and guardrails.
Most tools use a predictable verb_noun pattern (search_customers, get_order, create_invoice, update_order_status, issue_refund), with only minor noun-phrase deviations like sales_report and low_stock_alerts.
Eight tools is well-scoped for a shop operations server, covering the main back-office workflows without feeling bloated or thin.
Core order read/update/refund and invoicing operations are present, but there are notable gaps: no order creation, no customer creation/update, no product catalog or stock adjustment, and no invoice retrieval/listing. These omissions could block common shopkeeper workflows.
Maintenance
Related MCP Connectors
Intelligence for your AI agents: what they need to know, at the moment they decide. NEXUS connects Claude Code, Claude, ChatGPT, Cursor and OpenClaw to one shared record of your decisions, rules and past incidents, so an agent doesn't repeat a costly mistake or undo what was already decided. What one agent learns, the others already know. Every item is graded (measured, reported or inferred), outdated facts are marked as superseded, and contradictions are flagged. Before an important action, agents can call antes_de_actuar to get the rules that apply. Remote server with OAuth. Free plan, no credit card: https://nexus.eblas.link
Warehouse ops from Claude: orders, stock, forecasts, parcel rates, labels you buy in the console
The system of record for AI agents — open-source (MIT) database where agents and people share data.
Build and manage AI-native customer support agents from Claude or any MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs to interact with a SQLite e-commerce database via safe, typed MCP tools with read-only guards and auth-gated mutations, plus a Claude agent for answering business questions.1MIT
- FlicenseAqualityCmaintenanceEnables Claude to manage customers and support tickets through database-backed CRUD tools, contextual customer and knowledge resources, and a reusable ticket-triage prompt.13-
- AlicenseAqualityCmaintenanceEnables Claude to answer questions about a small business's own data by providing predefined sales, customer, refund, and inventory tools, plus a guarded read-only SQL query tool with audit logging.6MIT
- AlicenseAqualityCmaintenanceEnables Claude to answer business questions from a SQL database safely, using read-only queries and bounded summaries, while requiring confirmation and audit logging for order-status changes.7MIT