mcp-shop-server

MCP-сервер，为 AI 代理提供对在线商店 SQLite 数据库（customers、products、orders、order_items）的 只读 访问。代理通过它回答数据分析类问题：数据库结构、按客户、商品、类别和营收的聚合统计。传输方式 — stdio。

按设计（by design）无法写入数据库：三层独立防护 — 连接 mode=ro、执行前校验请求（仅 SELECT / WITH ... SELECT）以及 sqlite3-authorizer。

测量数据、证明和与任务书的偏差 — REPORT.md。

使用方法

1. 克隆

git clone https://github.com/andreykutsenko/mcp-shop-server.git
cd mcp-shop-server

仓库中已包含 shop.db（150 个客户、50 件商品、750 个订单、1900 个订单项）。

2. 安装依赖

uv venv .venv
uv pip install --python .venv/bin/python -r requirements.txt

不使用 uv — 用标准工具做同样的事：

python3 -m venv .venv
.venv/bin/pip install -r requirements.txt

需要 Python 3.11+。依赖项：mcp（官方 MCP SDK）和用于测试的 pytest；数据库操作使用标准库中的 sqlite3。

3. 写入代理配置

最小配置形式：

{
  "command": "python",
  "args": ["/absolute/path/to/mcp-shop-server/server.py"]
}

适用于带 mcpServers 块的客户端（Claude Desktop、Cursor 及兼容客户端）的工作示例：

{
  "mcpServers": {
    "shop-db": {
      "command": "/absolute/path/to/mcp-shop-server/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-shop-server/server.py"],
      "env": {
        "MCP_SHOP_DB": "/absolute/path/to/mcp-shop-server/shop.db"
      }
    }
  }
}

对于 Claude Code，一条命令即可：

claude mcp add shop-db -- /absolute/path/to/mcp-shop-server/.venv/bin/python /absolute/path/to/mcp-shop-server/server.py

MCP_SHOP_DB 为可选项：如果未设置该变量，服务器会使用 server.py 旁边的 shop.db。如果数据库位于其他位置，请指定该变量。解释器最好使用 .venv 中的 — 否则系统 python 可能找不到 mcp 包。

4. 启动

服务器由代理启动，手动操作很少需要：

.venv/bin/python server.py

进程静默等待 stdin 上的 JSON-RPC；诊断信息输出到 stderr，stdout 专用于 MCP 协议。

5. 验证和向代理提问

.venv/bin/python -m pytest -q

连接后，代理可以看到三个工具。问题用自然语言提出。

家庭作业文本中的八项任务 — 建议运行这些任务进行验证：

1. Show me all available tables and explain what information each table contains.
2. How many customers are from Germany?
3. Which country has the most customers?
4. Who is the customer who spent the most money?
5. What are the top 5 best-selling products?
6. What are the top 3 product categories by revenue?
7. How much revenue did we generate in 2025?
8. Which customer placed the most orders?

⚠️ 任务 2、3 和 7 在随附的数据库中没有解决方案，这是预期行为。 customers 中没有国家列 — 所有 150 个客户都是俄罗斯电话号码； 所有 750 个订单日期均为 2026 年，没有 2025 年的数据。

在这种情况下，服务器不会编造数据：它会报告模式中没有该字段， 并列出现有列。代码中没有硬编码任何内容 — 模式从数据库读取， 因此在存在 country 列的其他数据库上，相同的问题可以正常工作。

另外还会验证数据库能完全回答的问题：按订单金额排名的前 5 名客户、按类别的营收、按状态的订单分布、平均客单价、商品库存。

写入保护验证。 对于「Delete all cancelled orders」，代理会收到明确的拒绝而不是错误：服务器只读运行，102 个已取消订单保持不变。

工具

输出有限制：默认 100 行，最大 1000 行。截断时，响应会报告返回了多少行、总共找到多少行以及使用哪个 offset 继续读取。

如果请求的字段在数据库中不存在（例如客户国家），服务器会如实说明并列出现有列 — 不会臆造不存在的字段。

Related MCP server: Shop Analytics MCP Server

实现方式

项目由单个提示词生成 — 文件 SPEC-mcp-shop.md， 一次性完整发送给代理，无后续澄清。

内部代理按照技能 repo-task-proof-loop （Denis Shiryaev，Apache-2.0）循环工作：冻结规格 → 构建 → 打包证明 → 用新会话验证 → 最小修改 → 再次验证，直到 PASS 判定。

运行证明存放在仓库的 .agent/tasks/mcp-shop-server/ 中：

• spec.md — 冻结的规格，包含验收标准 AC1…AC17；

• evidence.md / evidence.json — 每个标准的判定和具体证明；

• verdict.json — 新会话独立验证的结果；

• problems.md — 验证者发现的差异；

• raw/ — 运行的原始日志：测试、实时 MCP 会话、stdout 纯净性检查。

验证的不是源代码，而是服务器与真实代理的行为：harness raw/mcp_session_check.py 通过 stdio 用真正的 MCP 客户端启动 server.py， 调用所有工具，运行八项分析任务，获得删除操作的拒绝， 并核对 stdout 只包含 JSON-RPC 帧。

开发技能本身位于本地 .claude/skills/ 中，不会提交到仓库 — 这是第三方代码。

对任务书歧义的处理决定