Shop MCP Server

用于在线商店 SQLite 数据库分析的本地 MCP 服务器。AI 代理调用 MCP 工具，服务器将请求转换为安全的 SQL SELECT，直接读取 shop.db 并返回结构化结果。

Host-приложение
├── AI-агент / LLM
└── MCP-клиент
        │ JSON-RPC / stdio
        ▼
    Shop MCP Server
        │ read-only SQLite
        ▼
    data/shop.db

功能

• 直接连接 SQLite，无需 HTTP 和独立的数据库服务器；

• MCP 传输 stdio；

• 通过 tools/list 发现 query_shop 和 inspect_database；

• 工具描述和 JSON Schema 中有八个示例任务；

• 普通文本、JSON intent 或现成的安全 SELECT；

• 从所有分析中排除 cancelled 订单；

• 分页和结果限制；

• 多层只读保护。

Related MCP server: Shop Analytics MCP Server

安装

需要 Python 3.11 或更高版本。

python3 -m venv .venv
.venv/bin/python -m pip install -e '.[dev]'

准备好的数据库已位于 data/shop.db 中。其中有 150 个客户，customers.country 字段已为所有客户填写，其中 45 个客户属于 Germany。

重新准备数据库

原始数据库不会被修改。该命令创建新的工作副本，并添加带有可重现合成值的 country TEXT NOT NULL：

.venv/bin/shop-prepare-db /path/to/original/shop.db ./data/shop.db

分布仅取决于 customers.id，因此重复准备会产生相同的值。国家/地区是测试数据，不描述客户的实际位置。

路径配置

路径按以下顺序确定：

1. SHOP_DB_PATH；

2. 来自 SHOP_MCP_CONFIG 或 config/shop_mcp.json 的 JSON 文件；

3. 相对于工作目录的 data/shop.db。

环境变量示例位于 .env.example 中，MCP 客户端配置位于 config/mcp.example.json 中。将 /absolute/path/to/MCPDeveloper 替换为项目的绝对路径。

启动

通常，MCP 客户端会从其配置中启动服务器。要手动启动进程：

SHOP_DB_PATH=./data/shop.db .venv/bin/python -m shop_mcp.server

stdout 保留用于 MCP JSON-RPC。诊断信息不会输出到协议流中。

工具

inspect_database

参数：

{"action": "list_tables"}

或：

{"action": "describe_table", "table": "customers"}

query_shop

参数：

{
  "request": "Сколько клиентов из Германии?",
  "limit": 100,
  "offset": 0
}

通过 tools/list 声明的示例：

1. 数据库中有哪些表，它们有哪些字段？

2. 有多少来自德国的客户？

3. 哪个国家的客户最多？

4. 哪个客户消费最多？返回姓名、电子邮件和总金额。

5. 按销售数量和收入显示前 5 种商品。

6. 按收入显示前 3 个类别。

7. 2025 年的收入是多少？

8. 哪个客户下的订单最多？

可以传递结构化 intent：

{
  "request": "{\"intent\": \"revenue_by_year\", \"year\": 2025}"
}

或现成的查询：

{
  "request": "SELECT name, category FROM products ORDER BY name"
}

业务规则

• orders.status = 'cancelled' 不参与指标计算。

• 客户支出和年收入按 orders.total_amount 计算。

• 商品和类别的收入按 quantity * unit_price 计算。

• 年份区间为半开区间：从 1 月 1 日（含）到次年 1 月 1 日（不含）。

• 在提供的数据库中，所有订单都属于 2026 年，因此 2025 年的收入为 0。

安全性

服务器通过 mode=ro 打开 SQLite，启用 query_only，设置 SQLite authorizer，禁止多个语句、DML、DDL、ATTACH、修改性 PRAGMA、扩展加载，并限制执行时间。

任何尝试执行非 SELECT 操作都会返回精确的答案：

Не доступный вариант запроса

SQLite 内部错误、堆栈跟踪和本地路径不会返回给客户端。

验证

.venv/bin/pytest
.venv/bin/ruff check .
.venv/bin/ruff format --check .

测试包括以子进程方式实际启动 MCP 服务器、通过 stdio 连接 ClientSession、tools/list、调用两个工具、分析场景以及尝试修改数据库。

完整且已批准的规范位于 docs/specification.md 中。