mcp-server-ecommerce

MCP server exposing the e-commerce multi-agent workflow tool inventory (70 tools) over stdio.

mcp-server-ecommerce is a Model Context Protocol server that exposes a complete e-commerce business inventory — orders, payments, refunds, logistics, sellers, support, content, reporting, escalation and ops — to any MCP-capable client (Claude Code, Cursor, VS Code, OpenClaw, …).

Status: synthetic fixtures only. A persistent SQLite data layer is seeded on first run; no real customer data lives here. Not production-wired until a real DB/HTTP adapter replaces the in-memory store.

Install

# zero-install, runs the latest version every time (recommended)
uvx mcp-server-ecommerce

# or install it
pip install mcp-server-ecommerce
pipx install mcp-server-ecommerce

Configure

# Claude Code
claude mcp add ecommerce -- uvx mcp-server-ecommerce

// Cursor / VS Code (.mcp.json / mcp.json)
{
  "mcpServers": {
    "ecommerce": { "command": "uvx", "args": ["mcp-server-ecommerce"] }
  }
}

Any other MCP client: command uvx, args ["mcp-server-ecommerce"] (or run mcp-server-ecommerce directly after a pip/pipx install).

The MCP server name is ecommerce, so tools appear to clients as ecommerce__<tool_name> (e.g. ecommerce__order_get) where the host prefixes servers.

Universal contract (enforced once, in register.py)

• Schema-validated inputs; invalid input → {success:false, error_type:"VALIDATION", retryable:false} — never a crash.
• Result envelope: {success, found, data, status} or {success:false, error_type, retryable, message, status:"FAILED"}.
• found:false = successful lookup with no record, not a failure (spec 10).
• Every Execute/File tool requires idempotency_key (added centrally): missing → rejected, replay → cached first result (spec 16).
• Auth classes in the description prefix: [Read] / [Recommend] / [Execute] / [File].
• MCP annotations derived from the auth class: Read/Recommend → readOnlyHint, Execute → destructiveHint, Execute/File → idempotentHint.

Layout

src/mcp_ecommerce/
  envelope.py       # result contract: {success, found, data, status | error_type, retryable}
  manifest.py       # SINGLE SOURCE OF TRUTH: 70 tools, auth classes, agents
  register.py       # the one wrapper enforcing schema + idempotency + envelopes
  server.py         # registers all tools + zero-drift assertion vs manifest
  cli.py            # stdio entry (stdout = MCP protocol only; logs → stderr)
  profiles.py       # generates profiles/<agent>.json + toolFilter snippets
  probe.py          # stdio probe: list tools + live call + contract check
  data/             # entity types + MemoryAdapter + SQLiteAdapter + seed fixtures
  tools/            # 13 domain packages — one file per tool (70 modules)
tests/              # pytest suite: contract, idempotency, manifest, domains, SQLite

Commands

uv sync                      # install deps (mcp, jsonschema, pytest)
uv run pytest                 # full test suite
uv run mcp-server-ecommerce   # run the stdio server
uv run python -m mcp_ecommerce.probe   # expects "tools listed: 70" + PROBE OK
uv run python -m mcp_ecommerce.profiles  # regenerate profiles/

Environment variables

<user-data-dir> is %LOCALAPPDATA% on Windows, $XDG_DATA_HOME or ~/.local/share elsewhere — never inside the package directory, so uvx/pip installs stay writable-cache-safe.

Adding a tool

1. Entry in src/mcp_ecommerce/manifest.py (name, domain, auth_class, description, agents).
2. New module src/mcp_ecommerce/tools/<domain>/<tool_name>.py with NAME, DESCRIPTION, AUTH_CLASS, INPUT_SCHEMA, handle(args, ctx) and TOOL = ToolDef(...).
3. Register it in the domain package __init__.py.
4. Test in tests/.
5. python -m mcp_ecommerce.profiles → profiles regenerate automatically.
6. pytest fails on any manifest↔handler drift (assert_no_drift).