shop-mcp

shop-mcp

A Model Context Protocol server that lets an LLM agent answer questions about aShopify store's catalogue and stock — over stdio, from a single file, usingonly the Python standard library.

No MCP SDK. No requests. No GraphQL client. python3 shop_mcp.py is the wholeinstall.

$ python3 shop_mcp.py --self-test
all green: 200 assertions

That command needs no credentials and no network. It is the point of the repo:the protocol layer and the tool layer are both exercised for real, because theShopify transport is replaced at a seam rather than mocked at the boundary.

Installed from PyPI, the same command reports 183, and the seventeen-assertiondifference is a packaging fact rather than a weaker check:

$ uvx --from shop-mcp shop-mcp --self-test
all green: 183 assertions

manifest.json (5 assertions), llms-install.md (11) and README.md (1) aredeliberately not shipped into site-packages — the manifest's entry_pointnames a bundle path that does not exist in an installed copy, so packaging itwould make a correct install fail. All three groups skip rather than fail whentheir file is absent, which is why the count moves and the verdict does not.Clone the repo to run all 200.

This server is the worked example, not a product line. I build the same shape —a stdio MCP server over data you already have, with a self-test suite and proofthat the suite catches injected defects — as a fixed-price job:hello532.github.io/services.html,or [email protected]. Nothing on this page needs paying for; issues and PRsare welcome either way.

Why write the protocol by hand

Because the failure modes of a stdio MCP server are all invisible locally andall fatal in a host. Each one below is a real defect this file is built to nothave, and each has an assertion naming it:

• A diagnostic on stdout. One stray print() corrupts the client's nextparse. Nothing looks wrong when you run the server yourself. Every diagnostichere goes to stderr, and a test asserts stdout stays byte-empty across a fullsession.
• Answering a notification. notifications/initialized has no id, so areply to it is a message with no pending request. Strict clients treat that asa protocol violation and drop the connection.
• id: 0 read as a notification. if msg.get("id") is falsy for zero, so aclient that numbers requests from zero has its first call silently dropped.Presence, not truthiness.
• Tool failures sent as JSON-RPC errors. A JSON-RPC error is for a malformedrequest. A tool that ran and failed must return a normal result withisError: true and the reason as text — otherwise the model never sees themessage and cannot correct its own arguments.
• Echoing an unknown protocolVersion. If a client asks for a revision theserver does not know, agreeing to it leaves both sides believing a spec is inuse that neither implements. This falls back to 2025-03-26, the spec's owndefault, and says so.
• Pretty-printing the reply. Indented JSON contains newlines, and newline isthe frame delimiter. One message becomes several broken ones.

Tools

Four tools, chosen because each answers a question a shop owner actually asks. Awider surface would be easy and would make the model worse at picking.

The correctness that is not protocol

Three of the assertions cover mistakes that produce confidently wrong answers,which are worse than errors:

• An unquoted SKU. sku:SH 1 is a different query from sku:"SH 1". Thefirst silently matches the wrong variants and reports their stock as if itwere yours. SKUs are quoted and internal quotes escaped.
• A null quantity read as zero. Shopify returns null for a variant thatdoes not track inventory. Coerced to 0, it appears in every restock reportforever. Untracked and out-of-stock are different facts and stay different.
• scan_exhausted. low_stock_report scans a bounded number of variants. Ifthe scan hit its limit, "nothing is low" is indistinguishable from "I did notlook far enough" — so the result says which it was, and the model can say sotoo.

Plus the transport rules any Shopify client needs and most skip: a THROTTLEDGraphQL response is a 200 and must be retried, not read as success; a 401 mustnot be retried, because waiting will not fix a bad token; backoff must actuallygrow.

Verified, and not verified

Verified, by the self-test, on every run: 200 assertions covering thehandshake, framing, notification handling, id presence, error mapping, schemastrictness, retry and backoff policy, SKU quoting, null-quantity handling,threshold boundaries, and scan exhaustion. Wire shapes were taken from theofficial mcp Python SDK's types.py (LATEST_PROTOCOL_VERSION,CallToolResult, ServerCapabilities), not from memory.

Not verified: this has never been run against a live Shopify store. There isno credential in this repo and no recorded API session. The Shopify AdminGraphQL queries are written to the documented schema, and every code path aroundthem is tested against a transport double — but the round trip against a realshop is unproven, and the test doubles are my model of Shopify's behaviour, notShopify.

That distinction is the honest one, and it is the same line drawn ingpt-ads-feed. A README that blursit is asking to be trusted on the wrong thing.

Assertions that can fail

mutation_test.sh injects known defects into copies of the source and asserts--self-test goes red for each, naming which assertion caught it. It also flagsa NO-OP EDIT when a search pattern has gone stale — because a mutation thatdoes not apply tests nothing while looking green, which is the failure mode thatmakes a suite worse than useless: trusted and empty.

It found real weaknesses in the suite on its first run, and all three were thesame shape: the defect was detected, but by an exception rather than by anamed assertion, so the message explained nothing and every assertion after itnever ran.

Two were an unhandled KeyError: 'result', from indexing a reply that thedefect had turned into a JSON-RPC error. Fixed by routing result access througha shape guard, so the same defect now reports a tool crash returns a result, so the loop survives: reply is a JSON-RPC error {'code': -32603, ...} and thethree following assertions each still report their own verdict.

The third was a bare setup call — S.Tools(c).search_products(...), presentonly to make the assertion below it meaningful. When the throttle branch wasdisabled it raised, aborting the test before that assertion ran. Fixed withcompletes(), the exact inverse of raises(): the defect now reportsa 200-with-THROTTLED is survivable, not a hard failure: raised ShopifyError: Throttled [THROTTLED], naming the rule and keeping the cause.

Three more defects surfaced only when the server was packaged as an .mcpbbundle and launched the way a host launches it, which no test had ever done:

1. The code read SHOPIFY_SHOP; this README and the bundle manifest both toldusers to export SHOPIFY_SHOP_DOMAIN. Anyone following the docs got apermanently unconfigured server. Every one of the 180 assertions passed,because none of them compared the code against the docs.
2. tools/list returned [] until credentials existed, so a host saw an emptyserver and reported it broken — and the readable no store is configuredmessage on tools/call was unreachable, since nothing was listed to call.The docstring above that code stated the opposite requirement, and the testbelow it asserted the defect: eq(tools, [], ...). The list never dependedon credentials; descriptors() touched no instance state at all, and is nowa staticmethod.
3. --self-test was advertised in the module docstring but crashed inside thebundle, which shipped only the server file. The bundle now ships the suite.

The first fix then broke the harness in a way worth recording. The newassertion failed when README.md was absent, and the harness copied only twofiles, so it fired inside every mutant. The run still printed 17 caught,but six of those were credited to README.md is present instead of their ownlabels: six real assertions could have been dead with the suite still green.A missing README is a packaging fact, not a code defect. The load-bearingcomparison now runs against the module docstring, which travels with thesource, and the harness copies the README so the cross-check is real.

All 23 mutations are caught by an assertion that names what broke, and each iscredited to its own label.

Use it

Installed from PyPI — nothing to clone:

export SHOPIFY_SHOP_DOMAIN=your-shop.myshopify.com
export SHOPIFY_ADMIN_TOKEN=shpat_...          # read_products, read_inventory
uvx shop-mcp                                  # or: pip install shop-mcp && shop-mcp

Claude Desktop / any MCP host:

{
  "mcpServers": {
    "shop": {
      "command": "uvx",
      "args": ["shop-mcp"],
      "env": {
        "SHOPIFY_SHOP_DOMAIN": "your-shop.myshopify.com",
        "SHOPIFY_ADMIN_TOKEN": "shpat_..."
      }
    }
  }
}

From a clone instead, when you want to read the source before running it — whichis the point of a single dependency-free file, and the only way to get the full200-assertion suite:

python3 shop_mcp.py --self-test    # 200 here, 183 installed; see above
python3 shop_mcp.py

{ "command": "python3", "args": ["/absolute/path/to/shop_mcp.py"] }

With no credentials set it still completes a handshake and serves tools/list,then returns isError with the missing variable named. A host that cannot readtools/list reports "broken server" and sends you looking in the wrong place.

MIT.