Skip to content
Back to search

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.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/hburaker--mcp-retail-server/badge.svg)](/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

i

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
  1. # Northwind Apparel MCP Server
  2. [![CI](https://github.com/hburaker/mcp-retail-server/actions/workflows/ci.yml/badge.svg)](https://github.com/hburaker/mcp-retail-server/actions/workflows/ci.yml)
  3. [![Python](https://img.shields.io/badge/python-3.10%E2%80%933.14-blue.svg)](pyproject.toml)
  4. [![MCP SDK](https://img.shields.io/badge/MCP%20Python%20SDK-2.x-6f42c1.svg)](https://github.com/modelcontextprotocol/python-sdk)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)
  6. A small, production-style **Model Context Protocol (MCP) server** that gives an AI assistant
  7. (Claude Desktop, Claude Code, or any MCP host) safe, read-only access to the back office of
  8. **Northwind Apparel**, a *fictional* fashion retailer: product catalogue, per-store inventory and
  9. customer orders.
  10. Ask your assistant *"Which sizes are sold out in Istanbul?"* or *"Draft a reply to the customer
  11. asking about order NW-100002"* and it answers from live data through typed, validated tools —
  12. no copy-pasting from dashboards.
  13. > The project is deliberately small in scope. It aims to show MCP fundamentals done properly:
  14. > clean separation of layers, typed schemas, input validation, helpful errors, read-only safety
  15. > and tests that exercise the real client/server protocol.
  16. ---
  17. ## Contents
  18. - [What is MCP?](#what-is-mcp)
  19. - [Architecture](#architecture)
  20. - [Capabilities](#capabilities)
  21. - [Quickstart](#quickstart)
  22. - [Connecting a host](#connecting-a-host)
  23. - [Example conversation](#example-conversation)
  24. - [Project layout](#project-layout)
  25. - [Testing](#testing)
  26. - [Security notes](#security-notes)
  27. - [Next steps](#next-steps)
  28. - [Türkçe Özet](#türkçe-özet)
  29. ## What is MCP?
  30. The [Model Context Protocol](https://modelcontextprotocol.io) is an open standard for connecting
  31. LLM applications to external data and actions through a common JSON-RPC interface.
  32. | Role | In this project |
  33. |---|---|
  34. | **Host** | The AI application the user talks to — Claude Desktop, Claude Code, an IDE. |
  35. | **Client** | A connector inside the host that keeps a 1:1 session with one server. |
  36. | **Server** | This package. It advertises capabilities and executes requests. |
  37. A server exposes three kinds of primitives:
  38. - **Tools** — functions the *model* decides to call (e.g. `check_stock`). They take typed
  39. arguments and return results.
  40. - **Resources** — read-only context addressed by URI (e.g. `policy://returns`) that the *host or
  41. user* attaches to the conversation.
  42. - **Prompts** — reusable, parameterised workflows the *user* picks (e.g. a slash command such as
  43. `/restock_analysis`).
  44. ## Architecture
  45. ```mermaid
  46. flowchart LR
  47. subgraph Host["MCP Host (Claude Desktop / Claude Code)"]
  48. LLM["LLM"]
  49. Client["MCP Client"]
  50. LLM <--> Client
  51. end
  52. subgraph Server["mcp-retail-server (this repo)"]
  53. direction TB
  54. MCP["server.py<br/>MCPServer: tools, resources, prompts<br/>schema validation + error mapping"]
  55. Repo["repository.py<br/>RetailRepository: business rules,<br/>input normalisation, parameterised SQL"]
  56. Models["models.py<br/>Pydantic models = output schemas"]
  57. MCP --> Repo
  58. MCP -.-> Models
  59. Repo -.-> Models
  60. end
  61. DB[("SQLite<br/>northwind.db<br/>(opened read-only)")]
  62. Seed["seed.py<br/>northwind-seed"]
  63. Client <-- "JSON-RPC over stdio" --> MCP
  64. Repo --> DB
  65. Seed -- "creates & seeds" --> DB
  66. ```
  67. **Request flow:** the model chooses a tool → the client sends `tools/call` over stdio → the SDK
  68. validates arguments against the JSON Schema generated from the Python type hints → the tool calls
  69. the repository → the repository validates and normalises identifiers and runs a parameterised,
  70. read-only query → a Pydantic model is returned as `structuredContent` (plus a text rendering).
  71. Anticipated failures (unknown SKU, malformed order ID) come back as `isError: true` with a message
  72. the model can act on.
  73. ## Capabilities
  74. ### Tools
  75. All tools are annotated `readOnlyHint: true`, `destructiveHint: false`, `idempotentHint: true`
  76. and return structured output with a published `outputSchema`.
  77. | Tool | Arguments | Returns |
  78. |---|---|---|
  79. | `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 |
  80. | `check_stock` | `sku: str` (e.g. `NW-OUT-001`, case-insensitive), `store?: str` | Units on hand per store and size, plus total |
  81. | `get_order_status` | `order_id: str` (`NW-100003`, `100003` or `#NW-100003`) | Status, lines, totals, timestamps, tracking number |
  82. | `low_stock_report` | `threshold: int` (0–1000), `store?: str` | Store/SKU/size rows with quantity ≤ threshold, most urgent first |
  83. ### Resources
  84. | URI | Type | Description |
  85. |---|---|---|
  86. | `catalog://categories` | `application/json` | Categories with product counts and price ranges |
  87. | `catalog://stores` | `application/json` | Store directory with opening hours |
  88. | `policy://returns` | `text/markdown` | Returns & exchanges policy (static document) |
  89. | `store://{store_id}` | `application/json` | **Resource template** — one store's profile and units on hand per category |
  90. ### Prompts
  91. | Prompt | Arguments | Purpose |
  92. |---|---|---|
  93. | `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 |
  94. | `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 |
  95. ### Demo data
  96. Four locations (`IST-01` Istanbul, `ANK-01` Ankara, `IZM-01` Izmir, `WH-01` online fulfilment
  97. centre), 24 products across 7 categories, 432 inventory rows (store × SKU × size) and 8 orders covering every status.
  98. The seed is deterministic, so numbers in tests and demos are stable. All names are invented.
  99. ## Quickstart
  100. Requirements: Python 3.10+.
  101. ```bash
  102. git clone https://github.com/hburaker/mcp-retail-server.git
  103. cd mcp-retail-server
  104. python -m venv .venv
  105. # macOS / Linux
  106. source .venv/bin/activate
  107. # Windows (PowerShell)
  108. .venv\Scripts\Activate.ps1
  109. pip install -e ".[dev]"
  110. # Optional: create the database explicitly (the server also seeds it on first start)
  111. northwind-seed
  112. # Run the server on stdio (it waits for an MCP client on stdin/stdout)
  113. mcp-retail-server # or: python -m mcp_retail_server
  114. ```
  115. ### Database location
  116. Resolved in this order:
  117. 1. `--db PATH` command-line flag
  118. 2. `NORTHWIND_DB_PATH` environment variable
  119. 3. `~/.mcp-retail-server/northwind.db`
  120. If the file does not exist the server creates and seeds it. Use `northwind-seed --force` to reset it.
  121. ### Verify the wire protocol
  122. `scripts/smoke_stdio.py` spawns the server and speaks raw JSON-RPC (standard library only):
  123. ```text
  124. $ python scripts/smoke_stdio.py
  125. initialize -> northwind-retail v0.1.0 (protocol 2025-11-25)
  126. capabilities: prompts, resources, tools
  127. tools/list -> 4 tools
  128. - search_products: Search the product catalogue.
  129. - check_stock: Show units on hand for a SKU, broken down by store and size.
  130. - get_order_status: Look up an order's status, line items, total and tracking number.
  131. - low_stock_report: List store/SKU/size combinations that are at or below a stock threshold.
  132. ```
  133. ## Connecting a host
  134. Use **absolute paths** — hosts do not start the server from your project directory.
  135. ### Claude Desktop
  136. Edit `claude_desktop_config.json`
  137. (macOS: `~/Library/Application Support/Claude/`, Windows: `%APPDATA%\Claude\`) and restart Claude Desktop:
  138. ```json
  139. {
  140. "mcpServers": {
  141. "northwind-retail": {
  142. "command": "/absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server",
  143. "args": [],
  144. "env": {
  145. "NORTHWIND_DB_PATH": "/absolute/path/to/northwind.db"
  146. }
  147. }
  148. }
  149. }
  150. ```
  151. On Windows the command is
  152. `C:\\path\\to\\mcp-retail-server\\.venv\\Scripts\\mcp-retail-server.exe` (note the escaped backslashes).
  153. ### Claude Code
  154. ```bash
  155. # Project-local (default scope)
  156. claude mcp add northwind-retail -- /absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server
  157. # With an explicit database and available in every project
  158. claude mcp add northwind-retail --scope user \
  159. -e NORTHWIND_DB_PATH=/absolute/path/to/northwind.db \
  160. -- /absolute/path/to/mcp-retail-server/.venv/bin/mcp-retail-server
  161. claude mcp list # verify the connection
  162. ```
  163. Inside Claude Code, `/mcp` shows the server's status, and the prompts appear as slash commands
  164. (e.g. `/mcp__northwind-retail__restock_analysis`).
  165. ### MCP Inspector
  166. The [MCP Inspector](https://github.com/modelcontextprotocol/inspector) is a browser UI for
  167. exploring and calling a server's tools, resources and prompts by hand:
  168. ```bash
  169. npx @modelcontextprotocol/inspector .venv/bin/python -m mcp_retail_server
  170. # Windows
  171. npx @modelcontextprotocol/inspector .venv\Scripts\python.exe -m mcp_retail_server
  172. ```
  173. ## Example conversation
  174. > **User:** A customer in our Ankara store wants the Leather Chelsea Boots in size 42. Can we get them a pair?
  175. >
  176. > **Claude** *(calls `search_products(query="chelsea")` → `NW-FTW-001`, then `check_stock(sku="NW-FTW-001")`)*:
  177. > Size 42 is **sold out at ANK-01**. It is available at IST-01 (15), IZM-01 (15) and the online
  178. > fulfilment centre WH-01 (22). The fastest option is an online order shipped from WH-01, or an
  179. > inter-store transfer from Istanbul.
  180. >
  181. > **User:** Run a restock analysis for Ankara.
  182. >
  183. > **Claude** *(uses the `restock_analysis` prompt → `low_stock_report(threshold=3, store="ANK-01")`)*:
  184. >
  185. > | Priority | Store | SKU | Product | Size | On hand | Suggested action |
  186. > |---|---|---|---|---|---|---|
  187. > | 1 | ANK-01 | NW-FTW-001 | Leather Chelsea Boots | 42 | 0 | Transfer 4 from WH-01 |
  188. > | 2 | ANK-01 | NW-FTW-001 | Leather Chelsea Boots | 43 | 1 | Transfer 3 from WH-01 |
  189. > | … | | | | | | |
  190. >
  191. > **User:** Where is order 100002?
  192. >
  193. > **Claude** *(calls `get_order_status(order_id="100002")`)*: Order **NW-100002** (Minimal White
  194. > Sneakers, size 42) was **shipped** on 17 Nov 2026 with tracking number `NWX7741200457`.
  195. ## Project layout
  196. ```text
  197. mcp-retail-server/
  198. ├── src/mcp_retail_server/
  199. │ ├── __init__.py # package version
  200. │ ├── __main__.py # python -m mcp_retail_server
  201. │ ├── server.py # MCP layer: tools, resources, prompts, entry point
  202. │ ├── repository.py # data-access layer (no MCP imports)
  203. │ ├── models.py # Pydantic models / output schemas
  204. │ ├── seed.py # schema + deterministic seed data (northwind-seed)
  205. │ ├── config.py # database path resolution
  206. │ └── content/returns_policy.md
  207. ├── tests/
  208. │ ├── conftest.py # seeded DB + in-process MCP client fixtures
  209. │ ├── test_seed.py
  210. │ ├── test_repository.py # business rules, validation, read-only guarantee
  211. │ ├── test_server.py # tools/resources/prompts through the MCP client
  212. │ └── test_stdio.py # real subprocess over stdio (initialize + tools/list)
  213. ├── scripts/smoke_stdio.py # raw JSON-RPC smoke test
  214. ├── .github/workflows/ci.yml
  215. ├── pyproject.toml
  216. └── LICENSE
  217. ```
  218. ## Testing
  219. ```bash
  220. pytest # 61 tests, fully offline
  221. ruff check . && ruff format --check .
  222. ```
  223. The suite has three levels:
  224. 1. **Repository unit tests** — validation, normalisation, LIKE-wildcard escaping, SQL-injection
  225. style inputs, and a check that the connection really is read-only.
  226. 2. **In-process protocol tests** — an MCP `Client` connected to the server in memory lists
  227. tools/resources/prompts, checks schemas and annotations, and calls every primitive,
  228. including error paths (`isError`, schema rejections, unknown resources).
  229. 3. **Stdio integration test** — launches `python -m mcp_retail_server` as a subprocess and performs
  230. the `initialize` handshake, `tools/list` and a tool call, as a real host would.
  231. CI runs lint, tests and the smoke script on Python 3.10–3.14 (Ubuntu) and Windows.
  232. ## Security notes
  233. - **Read-only by default.** The SQLite file is opened with `mode=ro`; there are no write tools,
  234. and every tool carries `readOnlyHint: true`. A test asserts that writes fail.
  235. - **Layered input validation.** JSON Schema constraints (lengths, ranges) are enforced by the SDK
  236. before the tool runs; the repository re-validates formats (`NW-XXX-000`, `NW-000000`), checks
  237. identifiers against known values and rejects `NaN`/`inf`.
  238. - **No SQL injection surface.** All values are bound parameters; `LIKE` wildcards in search terms
  239. are escaped.
  240. - **Helpful, non-leaky errors.** Anticipated errors return actionable messages (e.g. listing valid
  241. store IDs). Unexpected exceptions are reduced by the SDK to a generic message; details stay in
  242. server logs on stderr.
  243. - **Minimal data.** Customer records hold a display name only — no emails, addresses or payment
  244. data. The `customer_reply` prompt tells the model to treat customer text as untrusted data.
  245. - **No secrets.** The server needs no API keys or credentials; configuration is a single file path.
  246. - **stdio transport** means the server is only reachable by the local host process that spawned
  247. it — no open network port.
  248. ## Next steps
  249. - **Streamable HTTP transport** (`server.run(transport="streamable-http")`) to host the server
  250. remotely and share it across a team.
  251. - **Authentication & authorisation** — OAuth 2.1 via the SDK's `auth` settings / `TokenVerifier`,
  252. with per-role tool visibility (store staff vs. head office).
  253. - **Guarded write tools** such as `reserve_item`, using `destructiveHint`, idempotency keys and
  254. user confirmation via elicitation.
  255. - **Production data source** — swap the repository for a Postgres or ERP-API implementation
  256. behind the same interface.
  257. - **Observability** — structured logging and the SDK's OpenTelemetry hooks.
  258. ## Implementation note
  259. Built on the official [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) **2.x**.
  260. In 2.x the high-level server class formerly known as `FastMCP` is `mcp.server.MCPServer`; the
  261. decorator API (`@mcp.tool()`, `@mcp.resource()`, `@mcp.prompt()`) is the same idea.
  262. ## License
  263. [MIT](LICENSE) © 2026 Halit Burak Eroğlu
  264. ---
  265. ## Türkçe Özet
  266. Bu proje, **Model Context Protocol (MCP)** temellerini gösteren küçük ama üretim kalitesinde bir
  267. portföy çalışmasıdır. Kurgusal bir moda perakendecisi olan **Northwind Apparel**'ın ürün kataloğu,
  268. mağaza bazlı stok ve sipariş verilerini Claude Desktop / Claude Code gibi yapay zekâ asistanlarına
  269. **salt-okunur** olarak açar.
  270. - **Araçlar (tools):** `search_products`, `check_stock`, `get_order_status`, `low_stock_report` —
  271. tipli parametreler, şema doğrulaması ve anlaşılır hata mesajlarıyla.
  272. - **Kaynaklar (resources):** `catalog://categories`, `catalog://stores`, `policy://returns` ve
  273. `store://{store_id}` şablonu.
  274. - **İstem şablonları (prompts):** `restock_analysis` (stok yenileme planı) ve `customer_reply`
  275. (müşteri yanıtı taslağı).
  276. - **Mimari:** MCP katmanı (`server.py`) ile veri erişim katmanı (`repository.py`) ayrıdır; SQLite
  277. veritabanı deterministik bir seed betiğiyle oluşturulur ve salt-okunur modda açılır.
  278. - **Testler:** Depo katmanı birim testleri, MCP istemcisi üzerinden bellek içi protokol testleri ve
  279. stdio üzerinden gerçek alt süreç testi — tamamı çevrimdışı çalışır.
  280. Kurulum: `pip install -e ".[dev]"`, çalıştırma: `mcp-retail-server`, test: `pytest`.

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.