E-commerce MCP Server

Enterprise-ready Model Context Protocol server exposing catalog, cart, and checkout tools over FastMCP, backed by the public Fake Store API.

Features

• 8 MCP tools — catalog search, cart lifecycle, and checkout with order confirmation
• Strict Pydantic contracts — validated inputs (range/length constraints) and structured outputs, never raw strings
• Async everywhere — httpx.AsyncClient with retry + exponential backoff for connection errors and 5xx
• Typed error taxonomy — upstream failures surface as structured, human-readable tool errors
• Fake Store adapter — transparently maps Fake Store's native payloads (plain arrays, title/category/image, no pagination, no order endpoint) onto the project's schemas
• Session-persistent carts — lock-protected in-memory store, safe under concurrent tool calls
• Layered architecture — thin FastMCP entrypoint over isolated models, services, and tools layers

Architecture

src/
├── server.py            # Thin entrypoint: DI wiring + FastMCP registration (stdio + HTTP)
├── models/              # Strict Pydantic data contracts
│   ├── product.py       #   Product, ProductSummary, ProductListResponse
│   ├── cart.py          #   Cart, CartItem
│   └── checkout.py      #   CheckoutRequest, OrderConfirmation, pricing helpers
├── services/            # External I/O and mutable state
│   ├── store_api.py     #   Typed async client w/ retry, error taxonomy, Fake Store adapter
│   └── cart_store.py    #   Lock-protected, session-persistent cart store
└── tools/               # Class-based FastMCP tool handlers
    ├── catalog.py       #   list_products, get_product
    ├── cart.py          #   create_cart, get_cart, add_to_cart, update_cart_item, remove_cart_item
    └── checkout.py      #   checkout
tests/
├── test_models.py       # Model + pricing unit tests
├── test_server.py       # Tool-surface integration tests (respx-mocked upstream)
└── test_fakestore_adapter.py  # Fake Store payload adaptation tests

Requirements

• Python >= 3.11
• uv (package manager)

Setup

uv sync                          # install deps (incl. dev group)
# .env is tracked; edit STORE_API_* values if you target a different upstream
uv run pytest                    # 57 tests
uv run ruff check .              # lint
uv run mypy src tests            # typecheck

Configuration

.env is loaded by pydantic-settings at server start:

Variable	Default	Description
STORE_API_BASE_URL	https://fakestoreapi.com	Upstream store API base URL
STORE_API_TIMEOUT_SECONDS	10	Per-request read/connect timeout
STORE_API_MAX_RETRIES	2	Retries for connection errors and 5xx

When the base URL points at fakestoreapi.com, the client auto-adapts: title → name, float price → decimal string, category → categories, image → image URL, rating.count → stock approximation; catalog pages are paginated locally; checkout submits to POST /carts (Fake Store has no order endpoint) and returns a locally-computed OrderConfirmation. Any other base URL is consumed as-is (paginated {items, total, limit, offset} listing and POST /orders).

Running the server

stdio (default MCP transport)

uv run python -c "import sys; sys.path.insert(0, 'src'); from server import main; main()"

HTTP (Streamable HTTP, for Postman / remote clients)

uv run python -c "import sys; sys.path.insert(0, 'src'); from server import main_http; main_http()"

Serves POST http://127.0.0.1:8765/mcp.

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ecommerce-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/ecommerce-mcp",
        "run",
        "python",
        "-c",
        "import sys; sys.path.insert(0, 'src'); from server import main; main()"
      ]
    }
  }
}

Restart Claude Desktop, then try: "List products", "Add 2 of product 1 to a cart", "Checkout with Ada Lovelace, ada@example.com, London GB, card".

Testing with Postman

The HTTP transport is session-based MCP. Send every request to POST http://127.0.0.1:8765/mcp with headers:

Content-Type: application/json
Accept: application/json, text/event-stream

1. Initialize (capture the mcp-session-id response header, then send it on all later requests):

{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"postman","version":"1.0"}}}

2. List tools:

{"jsonrpc":"2.0","id":2,"method":"tools/list","params":{}}

3. Call a tool:

{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"list_products","arguments":{"limit":5,"offset":0}}}

Suggested demo flow: list_products → create_cart → add_to_cart → get_cart → checkout.

Tools

Tool	Description
list_products	Paginated catalog search (limit 1–100, offset ≥ 0)
get_product	Single product by id (≥ 1)
create_cart	New empty cart
get_cart	Snapshot of a cart
add_to_cart	Add/merge a product line (max 999 units/line)
update_cart_item	Overwrite a line quantity
remove_cart_item	Remove a line entirely
checkout	Place an order; returns OrderConfirmation with computed shipping/tax/total