thilimcp
OfficialThis server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
thilimcp
A small, hackable MCP server. A seeded e-commerce backend served over the Model Context Protocol — tools, a resource, a parameterized prompt template, two transports, and a hand-rolled bridge to a real LLM's tool-use loop. No framework hides the mechanism; every primitive is registered with a plain decorator you can read top to bottom.
⚠️ Educational reference implementation, not production. Error handling, auth, and persistence are deliberately minimal — the point is to see every moving part of MCP, not to harden it.
📚 Built lesson-by-lesson in a Learn Fast course
thilimcp is the reference implementation for the Learn Fast
course "Build an MCP Server." You don't import a framework — you build the server and the client
bridge yourself, from a model that can't call anything to one that completes a real multi-turn
task through a protocol-served backend.
Lesson | You build | Files |
1 · The model-context problem | — (a plain-README baseline, no code to carry forward) | — |
2 · Stand up the shop | the seeded schema |
|
3 · The first tool |
|
|
4 · Tool vs. resource | the product catalog, fixed as a resource |
|
5 · A second tool and a prompt |
|
|
6 · Transport | stdio, then streamable-HTTP, same tool logic |
|
7 · Connect a real client | the MCP-client ↔ Claude tool-use bridge |
|
8 · The architecture you just built | — (names lesson 7's code; no new files) | — |
9 · Contracts and errors |
|
|
Every lesson's server logic is the same build_server() — transport, resources, and error
handling layer on top of it without rewriting it.
Related MCP server: retail-mcp
Grown by a later course, not just lfmcpserver
get_order_items (server/tools.py) was added after "Build an MCP Server" shipped — that
course's own lessons never needed an order's line items, only the order itself. The next course in
this path, "Build an A2A Agent," does: answering whether an order is still returnable needs to
know which product category it actually contains, and nothing else here exposed that link.
get_order_items's own output grew again for "Orchestrate a Multi-Agent System" — a price_cents
and tax_rate_percent per line item, so a new Refund Agent has a real amount to compute. Both
fields come straight from products (tax_rate_percent is a fixed per-category value, seeded the
same way return_window_days already was — not a new random draw, so every order's existing price
and date stay exactly as earlier courses verified them). This is the intended shape of a reference
repo that gets reused, not re-taught — it grows when a real downstream consumer needs something
new, not speculatively ahead of one.
Quickstart (no API key)
pip install -e ".[dev]"
python examples/quickstart.py
pytest tests/conformance.py -qimport asyncio
from thilimcp import build_server, connect, call
async def main():
mcp_server = build_server("shop.db", reseed=True)
async with connect(mcp_server) as mcp_client:
print(await call(mcp_client, "get_order", order_id=123))
asyncio.run(main())Connecting a real model (needs ANTHROPIC_API_KEY)
import asyncio
from thilimcp import build_server, connect, mcp_tools_as_claude_tools, ask
async def main():
mcp_server = build_server("shop.db", reseed=True)
async with connect(mcp_server) as mcp_client:
claude_tools = await mcp_tools_as_claude_tools(mcp_client)
answer = await ask("What's the status of order #123?", mcp_client, claude_tools)
print(answer)
asyncio.run(main())ask() is the exact loop Claude Desktop and Claude Code run internally every time they use an MCP
server — nothing hidden, ~30 lines, in client/claude_bridge.py.
Why tool vs. resource matters
The product catalog is deliberately not a tool. A tool the model has to call with a guessed
query produces a sharp, silent failure: three plausible queries return zero results, and only an
empty string works. A resource needs no argument at all — the model just reads it. See
server/resources.py and lesson 4.
Why errors are part of the contract
Raising a plain exception inside a tool doesn't crash the server once a real Client is in front
of it — the protocol layer catches it — but it does strip the real reason, leaving only a generic
"Error executing tool ..." message. server/errors.py's not_found() raises ToolError
instead, which keeps the author's own words intact for the model to actually read. See lesson 9.
License
MIT © 2026 thili.ai
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hosted MCP for e-commerce: live product catalog, stock, and pricing for AI agents.
Agentic commerce gateway: discovery, trust and checkout. Demo store; x402 sandbox, AP2 planned.
Build, deploy and manage MaShop e-commerce projects from Claude, Cursor or any MCP client.
Hosted Magento MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
Related MCP Servers
- FlicenseNot gradedqualityFmaintenanceA Model Context Protocol server that enables AI assistants to interact with a complete e-commerce application, providing authentication, product browsing, and shopping cart management through standardized MCP tools.-
- FlicenseBqualityDmaintenanceConnects AI clients to retail customer, inventory, sales, order, and support capabilities through the Model Context Protocol.31-
- AlicenseAqualityBmaintenanceA local-first Model Context Protocol server that provides LLM agents with structured access to e-commerce data (products, inventory, orders, sales analytics) using a realistic mock dataset, zero configuration, and a swappable DataProvider interface for live APIs.8MIT
- AlicenseAqualityCmaintenanceEnables building and evaluating shopping/support agents against a deterministic synthetic retail store with in-memory fixtures. Provides tools, resources, and prompts for product search, cart and order flows, inventory, and policy retrieval over stdio or Streamable HTTP.639 PyPIMIT