Metadata-Version: 2.5
Name: mcp-server-ecommerce
Version: 0.1.0
Summary: MCP server exposing the e-commerce multi-agent workflow tool inventory (70 tools) over stdio
Project-URL: Homepage, https://github.com/ayeshakhalid13/ecom-repo
Project-URL: Repository, https://github.com/ayeshakhalid13/ecom-repo
License: MIT
Keywords: ai-agents,ecommerce,mcp,model-context-protocol,stdio
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: jsonschema>=4.20.0
Requires-Dist: mcp>=1.2.0
Description-Content-Type: text/markdown

# 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](https://modelcontextprotocol.io) 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

```bash
# 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

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

```jsonc
// 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

```bash
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

| Var | Default | Meaning |
|-----|---------|---------|
| `ECOM_ADAPTER` | `sqlite` | `sqlite` = persistent file store; `memory` = in-memory fixtures |
| `ECOM_DB_PATH` | `<user-data-dir>/mcp-server-ecommerce/ecommerce.db` | SQLite database file location |

`<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`).
