shop-mcp

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

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

$ 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 the Shopify transport is replaced at a seam rather than mocked at the boundary.

Installed from PyPI, the same command reports 183, and the seventeen-assertion difference 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) are deliberately not shipped into site-packages — the manifest's entry_point names a bundle path that does not exist in an installed copy, so packaging it would make a correct install fail. All three groups skip rather than fail when their 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 proof that the suite catches injected defects — as a fixed-price job: hello532.github.io/services.html, or coolun.337@gmail.com. Nothing on this page needs paying for; issues and PRs are welcome either way.

Why write the protocol by hand

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

• A diagnostic on stdout. One stray print() corrupts the client's next parse. Nothing looks wrong when you run the server yourself. Every diagnostic here goes to stderr, and a test asserts stdout stays byte-empty across a full session.
• Answering a notification. notifications/initialized has no id, so a reply to it is a message with no pending request. Strict clients treat that as a protocol violation and drop the connection.
• id: 0 read as a notification. if msg.get("id") is falsy for zero, so a client 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 malformed request. A tool that ran and failed must return a normal result with isError: true and the reason as text — otherwise the model never sees the message and cannot correct its own arguments.
• Echoing an unknown protocolVersion. If a client asks for a revision the server does not know, agreeing to it leaves both sides believing a spec is in use that neither implements. This falls back to 2025-03-26, the spec's own default, and says so.
• Pretty-printing the reply. Indented JSON contains newlines, and newline is the frame delimiter. One message becomes several broken ones.

Tools

Four tools, chosen because each answers a question a shop owner actually asks. A wider 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". The first silently matches the wrong vari

... View full README on GitHub