merchant-catalog-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., "@merchant-catalog-mcp search for running shoes"
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.
merchant-catalog-mcp
A small, production-quality MCP (Model Context Protocol) server in TypeScript. It exposes a mock merchant catalog to any MCP-compatible client (Claude Desktop, the MCP Inspector, IDE agents, etc.) through three tools — search, availability, and ordering. The data is intentionally in-memory: this project is a clear, readable demonstration of the protocol, not a data layer.
What it does
The server exposes three tools over the MCP stdio transport:
Tool | Input | What it returns |
|
| Products whose name/description match the query, optionally filtered by category. |
|
| Stock status ( |
|
| Validates against stock, decrements it, and returns a mock order confirmation. Errors (bad id, not enough stock) come back as tool results flagged |
Every tool also declares an outputSchema and returns structuredContent,
so clients receive typed objects, not just text.
It also exposes the other two MCP primitives:
Primitive | Name | What it is |
Resource |
| The full catalog as a read-only JSON resource the host can pull into context. |
Prompt |
| A user-invoked template ( |
Related MCP server: UCP MCP Storefront
How the MCP pieces fit (the 60-second tour)
Host / client / server. A host app (Claude Desktop, the Inspector) runs an MCP client that connects to one or more servers. This repo is one server.
A server exposes three kinds of things. Tools (model-callable actions), resources (read-only data the app pulls by URI), and prompts (user-invoked templates). This server demonstrates all three: three tools, a
catalog://productsresource, and agift_finderprompt.Transport = the pipe. Messages are JSON-RPC 2.0. With the stdio transport, the client launches this server as a subprocess and exchanges messages over stdin/stdout. (Because stdout is the protocol channel, all diagnostics in this server go to stderr.)
Input schema = the contract. Each tool declares its arguments with a
zodschema. The SDK converts it to JSON Schema, advertises it during discovery, and validates every incoming call against it before the handler runs. The schema is what tells the model exactly how it's allowed to call the tool.Output schema = the response contract. Each tool also declares an
outputSchemaand returnsstructuredContent— a typed object the client gets directly, validated by the SDK — instead of only stringified JSON in text.Lifecycle.
initialize(capability handshake) →tools/list(discovery) →tools/call(invocation) → structured result. State (stock levels) persists for the life of the process, so an order visibly reduces availability.
Project structure
src/
catalog.ts Domain layer: Product type, in-memory data, pure lookup/search/mutate helpers.
No MCP imports — this is the "swap-in-a-database-here" seam.
index.ts Protocol layer: creates the McpServer, registers the three tools
(input + output schema + handler), the catalog resource, and the
gift_finder prompt, then connects the stdio transport.The split is deliberate: business logic in catalog.ts, protocol wiring in
index.ts. The tools are thin adapters over logic that could just as easily sit
behind a real API or database.
Requirements
Node.js 18+ (developed on Node 24 LTS)
Install
npm installRun
# Dev: run the TypeScript directly, no build step
npm run dev
# Production: compile to dist/ then run the compiled server
npm run build
npm startOn startup the server prints merchant-catalog-mcp running on stdio to stderr
and then waits for JSON-RPC messages on stdin. (Running it in a bare terminal and
seeing it "hang" is correct — it's waiting for a client to speak to it.)
Verify it works
Option A — MCP Inspector, UI mode
npm run inspectThis launches the official MCP Inspector and opens a browser panel. Steps:
It auto-connects to this server over stdio.
Open the Tools tab and click List Tools — you'll see all three, each with a form generated from its input schema.
Select
search_products, enter aquery(e.g.speaker), and Run Tool.Try
place_orderwithproductId=sku-003,quantity=2, then runcheck_availabilityon the same id to watch stock drop.
Option B — MCP Inspector, CLI mode (scriptable)
# Discover tools
npx @modelcontextprotocol/inspector --cli node dist/index.js --method tools/list
# Call a tool
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call --tool-name search_products --tool-arg query=speaker
# Place an order
npx @modelcontextprotocol/inspector --cli node dist/index.js \
--method tools/call --tool-name place_order \
--tool-arg productId=sku-002 --tool-arg quantity=1Option C — raw JSON-RPC (what a client does under the hood)
{
printf '%s\n' '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"raw","version":"1.0.0"}}}'
printf '%s\n' '{"jsonrpc":"2.0","method":"notifications/initialized"}'
printf '%s\n' '{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}'
printf '%s\n' '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_products","arguments":{"query":"headphones"}}}'
sleep 0.5
} | node dist/index.jsUse it from Claude Desktop
Build first (npm run build), then add this server to your Claude Desktop MCP
config. The file lives at:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"merchant-catalog": {
"command": "/absolute/path/to/node",
"args": ["/absolute/path/to/merchant-catalog-mcp/dist/index.js"]
}
}
}Then fully quit and reopen Claude Desktop (it loads MCP servers only at startup). The three tools will appear in the tools menu.
Gotcha — use absolute paths for both
commandandargs. Claude Desktop is a GUI app, so it launches this server with the system environment, not your shell's — it does not read~/.zshrc/~/.bashrcand therefore may not findnodeon itsPATH. Pointingcommandat the absolute path of your Node binary (find it withwhich node) avoids a "spawn node ENOENT" failure.
Catalog
Eight products across four categories (audio, wearables, home,
accessories), including deliberately low-stock (sku-003, sku-008) and
out-of-stock (sku-004) items so you can exercise the availability and
validation paths. See src/catalog.ts.
Possible next steps
Swap
catalog.tsfor a real database — the protocol layer wouldn't change.Add an HTTP/SSE transport for remote hosting (only the transport lines in
index.tschange).Add unit tests over
catalog.tsand a CI workflow that runstsc+ tests.
License
MIT
Available Tools
3 toolscheck_availabilityCheck availabilityA
Check the stock status and on-hand quantity for a single product, given its product id.
Inputs: productId (required). Returns: id, name, status, quantity
place_orderPlace orderA
Place an order for a given quantity of a product. Validates the product exists and that enough stock is available, decrements stock, and returns a mock order confirmation.
Inputs: quantity (required), productId (required). Returns: name, total, status, orderId, +4 more
search_productsSearch productsA
Search the merchant catalog by keyword, with an optional category filter. Returns matching products with id, name, price, and stock.
Inputs: query (required), category. Returns: count, products
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: searching products, checking stock, and placing orders. There is no overlap or ambiguity.
All tool names follow a consistent verb_noun pattern (search_products, check_availability, place_order), making them predictable.
Three tools is well-scoped for a simple merchant catalog server, covering the core search, stock check, and order operations without excess.
The tool set covers search, stock inquiry, and ordering. A minor gap is the lack of a dedicated get_product_details tool, but search can compensate.
Maintenance
Related MCP Connectors
Sample shop MCP server: paginated search, idempotent orders, guarded cancellation. Four languages.
Remote MCP server for product discovery catalog and retrieving product details.
Directory and matchmaker of MCP servers for e-commerce, with guides and a glossary. Read-only.
Live Mayneart MCP server exposing the dynamic SELLABLE catalog with x402 execution.
Related MCP Servers
- AlicenseAqualityDmaintenanceAn MCP server that provides echo resource, tool, and prompt functionality for testing and demonstration.917 npm1MIT
- AlicenseAqualityDmaintenanceA UCP-compliant MCP storefront server that exposes product catalog operations (search, cart, checkout) as MCP tools, following UCP schema version 2026-04-08.5MIT
- FlicenseNot gradedqualityDmaintenanceDemo MCP server that exposes order and customer data as read-only tools for AI assistants, simulating a business API or internal data source.-
- FlicenseAqualityDmaintenanceAn MCP server that enables natural language catalog search, cart management, and checkout workflows against the Fake Store API, with strict schemas and session-persistent carts.8-