mcp-retail-server
Model Context Protocol (MCP) server exposing a retail back-office (products, stock, orders) as read-only tools, resources and prompts.
Safety scan
A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.
Badge for your README
Markdown
[](/listings/hburaker--mcp-retail-server)HTML
<a href="/listings/hburaker--mcp-retail-server"><img src="/api/listings/hburaker--mcp-retail-server/badge.svg" alt="findsafeskills safety rating" /></a>Install
Install instructions from the README
As written by the repo's author. findsafeskills has not verified these steps.
Requirements: Python 3.10+.
git clone https://github.com/hburaker/mcp-retail-server.git cd mcp-retail-server python -m venv .venv # macOS / Linux source .venv/bin/activate # Windows (PowerShell) .venv\Scripts\Activate.ps1 pip install -e ".[dev]" # Optional: create the database explicitly (the server also seeds it on first start) northwind-seed # Run the server on stdio (it waits for an MCP client on stdin/stdout) mcp-retail-server # or: python -m mcp_retail_server
Database location
Resolved in this order:
1. `--db PATH` command-line flag 2. `NORTHWIND_DB_PATH` environment variable 3. `~/.mcp-retail-server/northwind.db`
If the file does not exist the server creates and seeds it. Use `northwind-seed --force` to reset it.
Verify the wire protocol
`scripts/smoke_stdio.py` spawns the server and speaks raw JSON-RPC (standard library only):
$ python scripts/smoke_stdio.py initialize -> northwind-retail v0.1.0 (protocol 2025-11-25) capabilities: prompts, resources, tools tools/list -> 4 tools - search_products: Search the product catalogue. - check_stock: Show units on hand for a SKU, broken down by store and size. - get_order_status: Look up an order's status, line items, total and tracking number. - low_stock_report: List store/SKU/size combinations that are at or below a stock threshold.
What was scanned
The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.
README.md · README · 358 lines
- # Northwind Apparel MCP Server
- [](https://github.com/hburaker/mcp-retail-server/actions/workflows/ci.yml)
- [](pyproject.toml)
- [](https://github.com/modelcontextprotocol/python-sdk)
- [](LICENSE)
- A small, production-style **Model Context Protocol (MCP) server** that gives an AI assistant
- (Claude Desktop, Claude Code, or any MCP host) safe, read-only access to the back office of
- **Northwind Apparel**, a *fictional* fashion retailer: product catalogue, per-store inventory and
- customer orders.
- Ask your assistant *"Which sizes are sold out in Istanbul?"* or *"Draft a reply to the customer
- asking about order NW-100002"* and it answers from live data through typed, validated tools —
- no copy-pasting from dashboards.
- > The project is deliberately small in scope. It aims to show MCP fundamentals done properly:
- > clean separation of layers, typed schemas, input validation, helpful errors, read-only safety
- > and tests that exercise the real client/server protocol.
- ---
- ## Contents
- - [What is MCP?](#what-is-mcp)
- - [Architecture](#architecture)
- - [Capabilities](#capabilities)
- - [Quickstart](#quickstart)
- - [Connecting a host](#connecting-a-host)
- - [Example conversation](#example-conversation)
- - [Project layout](#project-layout)
- - [Testing](#testing)
- - [Security notes](#security-notes)
- - [Next steps](#next-steps)
- - [Türkçe Özet](#türkçe-özet)
- ## What is MCP?
- The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting
- LLM applications to external data and actions through a common JSON-RPC interface.
- | Role | In this project |
- |---|---|
- | **Host** | The AI application the user talks to — Claude Desktop, Claude Code, an IDE. |
- | **Client** | A connector inside the host that keeps a 1:1 session with one server. |
- | **Server** | This package. It advertises capabilities and executes requests. |
- A server exposes three kinds of primitives:
- - **Tools** — functions the *model* decides to call (e.g. `check_stock`). They take typed
- arguments and return results.
- - **Resources** — read-only context addressed by URI (e.g. `policy://returns`) that the *host or
- user* attaches to the conversation.
- - **Prompts** — reusable, parameterised workflows the *user* picks (e.g. a slash command such as
- `/restock_analysis`).
- ## Architecture
- ```mermaid
- flowchart LR
- subgraph Host["MCP Host (Claude Desktop / Claude Code)"]
- LLM["LLM"]
- Client["MCP Client"]
- LLM <--> Client
- end
- subgraph Server["mcp-retail-server (this repo)"]
- direction TB
- MCP["server.py<br/>MCPServer: tools, resources, prompts<br/>schema validation + error mapping"]
- Repo["repository.py<br/>RetailRepository: business rules,<br/>input normalisation, parameterised SQL"]
- Models["models.py<br/>Pydantic models = output schemas"]
- MCP --> Repo
- MCP -.-> Models
- Repo -.-> Models
- end
- DB[("SQLite<br/>northwind.db<br/>(opened read-only)")]
- Seed["seed.py<br/>northwind-seed"]
- Client <-- "JSON-RPC over stdio" --> MCP
- Repo --> DB
- Seed -- "creates & seeds" --> DB
- ```
- **Request flow:** the model chooses a tool → the client sends `tools/call` over stdio → the SDK
- validates arguments against the JSON Schema generated from the Python type hints → the tool calls
- the repository → the repository validates and normalises identifiers and runs a parameterised,
- read-only query → a Pydantic model is returned as `structuredContent` (plus a text rendering).
- Anticipated failures (unknown SKU, malformed order ID) come back as `isError: true` with a message
- the model can act on.
- ## Capabilities
- ### Tools
- All tools are annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`
- and return structured output with a published `outputSchema`.
- | Tool | Arguments | Returns |
- |---|---|---|
- | `search_products` | `query: str` (≤100 chars, may be empty if a filter is set), `category?: str`, `max_price?: float` (>0) | Up to 20 products with price, sizes, colour and network-wide stock |
- | `check_stock` | `sku: str` (e.g. `NW-OUT-001`, case-insensitive), `store?: str` | Units on hand per store and size, plus total |
- | `get_order_status` | `order_id: str` (`NW-100003`, `100003` or `#NW-100003`) | Status, lines, totals, timestamps, tracking number |
- | `low_stock_report` | `threshold: int` (0–1000), `store?: str` | Store/SKU/size rows with quantity ≤ threshold, most urgent first |
- ### Resources
- | URI | Type | Description |
- |---|---|---|
- | `catalog://categories` | `application/json` | Categories with product counts and price ranges |
- | `catalog://stores` | `application/json` | Store directory with opening hours |
- | `policy://returns` | `text/markdown` | Returns & exchanges policy (static document) |
- | `store://{store_id}` | `application/json` | **Resource template** — one store's profile and units on hand per category |
- ### Prompts
- | Prompt | Arguments | Purpose |
- |---|---|---|
- | `restock_analysis` | `store_id?` (empty = all), `threshold?` (default 3) | Guides the model through `low_stock_report` → `check_stock` to produce a prioritised transfer/reorder table |
- | `customer_reply` | `order_id`, `customer_message`, `tone?` | Drafts a grounded customer email using `get_order_status` and `policy://returns`; treats the customer text as data, not instructions |
- ### Demo data
- Four locations (`IST-01` Istanbul, `ANK-01` Ankara, `IZM-01` Izmir, `WH-01` online fulfilment
- centre), 24 products across 7 categories, 432 inventory rows (store × SKU × size) and 8 orders covering every status.
- The seed is deterministic, so numbers in tests and demos are stable. All names are invented.
- ## Quickstart
- Requirements: Python 3.10+.
- ```bash
- git clone https://github.com/hburaker/mcp-retail-server.git
- cd mcp-retail-server
- python -m venv .venv
- # macOS / Linux
- source .venv/bin/activate
- # Windows (PowerShell)
- .venv\Scripts\Activate.ps1
- pip install -e ".[dev]"
- # Optional: create the database explicitly (the server also seeds it on first start)
- northwind-seed
- # Run the server on stdio (it waits for an MCP client on stdin/stdout)
- mcp-retail-server # or: python -m mcp_retail_server
- ```
- ### Database location
- Resolved in this order:
- 1. `--db PATH` command-line flag
- 2. `NORTHWIND_DB_PATH` environment variable
- 3. `~/.mcp-retail-server/northwind.db`
- If the file does not exist the server creates and seeds it. Use `northwind-seed --force` to reset it.
- ### Verify the wire protocol
- `scripts/smoke_stdio.py` spawns the server and speaks raw JSON-RPC (standard library only):
- ```text
- $ python scripts/smoke_stdio.py
- initialize -> northwind-retail v0.1.0 (protocol 2025-11-25)
- capabilities: prompts, resources, tools
- tools/list -> 4 tools
- - search_products: Search the product catalogue.
- - check_stock: Show units on hand for a SKU, broken down by store and size.
- - get_order_status: Look up an order's status, line items, total and tracking number.
- - low_stock_report: List store/SKU/size combinations that are at or below a stock threshold.
- ```
- ## Connecting a host
- Use **absolute paths** — hosts do not start the server from your project directory.
- ### Claude Desktop
- Edit `claude_desktop_config.json`
- (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and restart Claude Desktop:
- ```json
- {
- "mcpServers": {
- "northwind-retail": {
- "command": "/absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server",
- "args": [],
- "env": {
- "NORTHWIND_DB_PATH": "/absolute/path/to/northwind.db"
- }
- }
- }
- }
- ```
- On Windows the command is
- `C:\\path\\to\\mcp-retail-server\\.venv\\Scripts\\mcp-retail-server.exe` (note the escaped backslashes).
- ### Claude Code
- ```bash
- # Project-local (default scope)
- claude mcp add northwind-retail -- /absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server
- # With an explicit database and available in every project
- claude mcp add northwind-retail --scope user \
- -e NORTHWIND_DB_PATH=/absolute/path/to/northwind.db \
- -- /absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server
- claude mcp list # verify the connection
- ```
- Inside Claude Code, `/mcp` shows the server's status, and the prompts appear as slash commands
- (e.g. `/mcp__northwind-retail__restock_analysis`).
- ### MCP Inspector
- The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser UI for
- exploring and calling a server's tools, resources and prompts by hand:
- ```bash
- npx @modelcontextprotocol/inspector .venv/bin/python -m mcp_retail_server
- # Windows
- npx @modelcontextprotocol/inspector .venv\Scripts\python.exe -m mcp_retail_server
- ```
- ## Example conversation
- > **User:** A customer in our Ankara store wants the Leather Chelsea Boots in size 42. Can we get them a pair?
- >
- > **Claude** *(calls `search_products(query="chelsea")` → `NW-FTW-001`, then `check_stock(sku="NW-FTW-001")`)*:
- > Size 42 is **sold out at ANK-01**. It is available at IST-01 (15), IZM-01 (15) and the online
- > fulfilment centre WH-01 (22). The fastest option is an online order shipped from WH-01, or an
- > inter-store transfer from Istanbul.
- >
- > **User:** Run a restock analysis for Ankara.
- >
- > **Claude** *(uses the `restock_analysis` prompt → `low_stock_report(threshold=3, store="ANK-01")`)*:
- >
- > | Priority | Store | SKU | Product | Size | On hand | Suggested action |
- > |---|---|---|---|---|---|---|
- > | 1 | ANK-01 | NW-FTW-001 | Leather Chelsea Boots | 42 | 0 | Transfer 4 from WH-01 |
- > | 2 | ANK-01 | NW-FTW-001 | Leather Chelsea Boots | 43 | 1 | Transfer 3 from WH-01 |
- > | … | | | | | | |
- >
- > **User:** Where is order 100002?
- >
- > **Claude** *(calls `get_order_status(order_id="100002")`)*: Order **NW-100002** (Minimal White
- > Sneakers, size 42) was **shipped** on 17 Nov 2026 with tracking number `NWX7741200457`.
- ## Project layout
- ```text
- mcp-retail-server/
- ├── src/mcp_retail_server/
- │ ├── __init__.py # package version
- │ ├── __main__.py # python -m mcp_retail_server
- │ ├── server.py # MCP layer: tools, resources, prompts, entry point
- │ ├── repository.py # data-access layer (no MCP imports)
- │ ├── models.py # Pydantic models / output schemas
- │ ├── seed.py # schema + deterministic seed data (northwind-seed)
- │ ├── config.py # database path resolution
- │ └── content/returns_policy.md
- ├── tests/
- │ ├── conftest.py # seeded DB + in-process MCP client fixtures
- │ ├── test_seed.py
- │ ├── test_repository.py # business rules, validation, read-only guarantee
- │ ├── test_server.py # tools/resources/prompts through the MCP client
- │ └── test_stdio.py # real subprocess over stdio (initialize + tools/list)
- ├── scripts/smoke_stdio.py # raw JSON-RPC smoke test
- ├── .github/workflows/ci.yml
- ├── pyproject.toml
- └── LICENSE
- ```
- ## Testing
- ```bash
- pytest # 61 tests, fully offline
- ruff check . && ruff format --check .
- ```
- The suite has three levels:
- 1. **Repository unit tests** — validation, normalisation, LIKE-wildcard escaping, SQL-injection
- style inputs, and a check that the connection really is read-only.
- 2. **In-process protocol tests** — an MCP `Client` connected to the server in memory lists
- tools/resources/prompts, checks schemas and annotations, and calls every primitive,
- including error paths (`isError`, schema rejections, unknown resources).
- 3. **Stdio integration test** — launches `python -m mcp_retail_server` as a subprocess and performs
- the `initialize` handshake, `tools/list` and a tool call, as a real host would.
- CI runs lint, tests and the smoke script on Python 3.10–3.14 (Ubuntu) and Windows.
- ## Security notes
- - **Read-only by default.** The SQLite file is opened with `mode=ro`; there are no write tools,
- and every tool carries `readOnlyHint: true`. A test asserts that writes fail.
- - **Layered input validation.** JSON Schema constraints (lengths, ranges) are enforced by the SDK
- before the tool runs; the repository re-validates formats (`NW-XXX-000`, `NW-000000`), checks
- identifiers against known values and rejects `NaN`/`inf`.
- - **No SQL injection surface.** All values are bound parameters; `LIKE` wildcards in search terms
- are escaped.
- - **Helpful, non-leaky errors.** Anticipated errors return actionable messages (e.g. listing valid
- store IDs). Unexpected exceptions are reduced by the SDK to a generic message; details stay in
- server logs on stderr.
- - **Minimal data.** Customer records hold a display name only — no emails, addresses or payment
- data. The `customer_reply` prompt tells the model to treat customer text as untrusted data.
- - **No secrets.** The server needs no API keys or credentials; configuration is a single file path.
- - **stdio transport** means the server is only reachable by the local host process that spawned
- it — no open network port.
- ## Next steps
- - **Streamable HTTP transport** (`server.run(transport="streamable-http")`) to host the server
- remotely and share it across a team.
- - **Authentication & authorisation** — OAuth 2.1 via the SDK's `auth` settings / `TokenVerifier`,
- with per-role tool visibility (store staff vs. head office).
- - **Guarded write tools** such as `reserve_item`, using `destructiveHint`, idempotency keys and
- user confirmation via elicitation.
- - **Production data source** — swap the repository for a Postgres or ERP-API implementation
- behind the same interface.
- - **Observability** — structured logging and the SDK's OpenTelemetry hooks.
- ## Implementation note
- Built on the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) **2.x**.
- In 2.x the high-level server class formerly known as `FastMCP` is `mcp.server.MCPServer`; the
- decorator API (`@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()`) is the same idea.
- ## License
- [MIT](LICENSE) © 2026 Halit Burak Eroğlu
- ---
- ## Türkçe Özet
- Bu proje, **Model Context Protocol (MCP)** temellerini gösteren küçük ama üretim kalitesinde bir
- portföy çalışmasıdır. Kurgusal bir moda perakendecisi olan **Northwind Apparel**'ın ürün kataloğu,
- mağaza bazlı stok ve sipariş verilerini Claude Desktop / Claude Code gibi yapay zekâ asistanlarına
- **salt-okunur** olarak açar.
- - **Araçlar (tools):** `search_products`, `check_stock`, `get_order_status`, `low_stock_report` —
- tipli parametreler, şema doğrulaması ve anlaşılır hata mesajlarıyla.
- - **Kaynaklar (resources):** `catalog://categories`, `catalog://stores`, `policy://returns` ve
- `store://{store_id}` şablonu.
- - **İstem şablonları (prompts):** `restock_analysis` (stok yenileme planı) ve `customer_reply`
- (müşteri yanıtı taslağı).
- - **Mimari:** MCP katmanı (`server.py`) ile veri erişim katmanı (`repository.py`) ayrıdır; SQLite
- veritabanı deterministik bir seed betiğiyle oluşturulur ve salt-okunur modda açılır.
- - **Testler:** Depo katmanı birim testleri, MCP istemcisi üzerinden bellek içi protokol testleri ve
- stdio üzerinden gerçek alt süreç testi — tamamı çevrimdışı çalışır.
- Kurulum: `pip install -e ".[dev]"`, çalıştırma: `mcp-retail-server`, test: `pytest`.
Ratings and comments
Sign in to rate this skill.
Sign inFree to use. If it’s helped, pass it on.