Shop SQLite MCP

用于安全分析现有电商网站 SQLite 数据库的本地 stdio MCP 服务器。服务器从 sqlite_master 和 SQLite PRAGMA 动态读取模式，因此不依赖预先已知的列名。

功能

• list_tables — 表和视图；

• describe_table — 列、主键、外键和索引；

• get_schema — 完整模式图；

• run_select_query — 单个受限的 SELECT / WITH ... SELECT；

• 专用分析工具：count_customers_by_country、top_customers_by_spend、top_products_by_units、top_categories_by_revenue、revenue_in_year、top_customers_by_order_count；

• SQLite 物理只读模式、query_only 和授权器；

• 阻止 DML、DDL、PRAGMA、ATTACH 和多条语句；

• 分页：limit 1–500 和 offset。

安装

一条命令完成所有操作：选择安装方式、安装依赖（或构建 Docker 镜像）、查找数据库、验证模式读取并写入现成的 mcp.json。

python3 install.py

脚本会询问启动方式（.venv 或 Docker）和数据库路径。无需提问的方式：

python3 install.py --mode venv --db /absolute/path/to/shop.db
python3 install.py --mode docker --db /absolute/path/to/shop.db

需要 Python 3.11+；对于 --mode docker，需要已安装 Docker。

默认情况下，数据库取自 data/shop.db。如果文件不存在，脚本将停止并显示明确的错误，不会创建空数据库。

无需单独手动启动——服务器已从配置中启动。用于调试：

.venv/bin/python -m shop_mcp.print_schema

连接到代理

运行 install.py 后只剩一步。文件 mcp.json 已包含选定的启动命令和数据库的绝对路径——无需编辑任何内容。

通过以下方式之一将其连接到代理：

• Cursor：将此文件夹作为工作区打开（副本位于 .cursor/mcp.json）或将根目录的 mcp.json 导入 MCP 设置；

• Claude Desktop / 其他客户端：将 mcp.json 的内容复制到 MCP 配置中。

连接后，直接提出 ASSIGNMENT.md 中的问题。代理的第一个操作是 get_schema 或专用分析工具。如果工具返回 SCHEMA_MISMATCH，请使用 run_select_query。

带占位符的模板只有 mcp.json.example。绝对路径只存在于客户端配置中，不在 Python 代码中。

Docker

无需单独命令：python3 install.py --mode docker 会自动构建 shop-sqlite-mcp:local 镜像，以只读方式挂载数据库，并将 docker run -i --rm 启动命令写入 mcp.json。

数据库以 /data/shop.db:ro 方式挂载，不使用 -t 标志，因为 MCP 通过 stdin/stdout 通信。

docker-compose.yml 构建相同的镜像，可用于本地构建验证；给代理使用 mcp.json。

测试

.venv/bin/pytest

测试使用临时 fixture 数据库，其表名对服务器未知。它们验证运行时内省、结果限制、无模式硬编码以及拒绝破坏性 SQL。

连接后如需手动验证，请提出 ASSIGNMENT.md 中的问题，包括：

Delete all cancelled orders.

工具响应应包含 WRITE_DENIED，且数据库保持不变。

项目文件

• install.py — 唯一的安装命令：依赖/镜像、数据库路径、配置生成；

• mcp.json — 现成的连接配置（命令 + 数据库路径）；

• PROMPT.md — AI 编码代理创建服务器所用的提示词；

• src/shop_mcp/ — MCP、模式内省、SQL 防护、分析工具；

• tests/ — 自动安全、发现和分析测试；

• Dockerfile / docker-compose.yml — 容器化 stdio MCP；

• NOTES.md — 关于任务歧义的决策记录。