内容
# 🔌 MCP 分析服务器 — 通过模型上下文协议与数据库对话
> 一个 **MCP 服务器**，通过模型上下文协议将 SQLite 电子商务数据库暴露给任何 MCP 客户端（如 Claude Desktop、Cursor、Anthropic SDK 等），提供 **安全、结构化、类型化的工具**，以及一个 **Claude 代理**，通过调用这些工具来回答业务问题。基于标准的 `mcp` Python SDK（FastMCP）构建。包括一个 **只读 SQL 守护进程**、一个 **身份验证门控突变** 和一个 **模式资源**。
MCP 是 2026 年连接代理与工具和数据的标准 — 已经有超过 10,000 个服务器发布，ChatGPT、Claude、Cursor、Copilot 和 VS Code 中均有原生支持。该仓库是一个干净的、生产环境中可用的示例，展示了团队需要的功能：**一个受控的网关，用于连接大型语言模型和数据库** — 不是原始的 SQL 访问，而是带有守护进程和授权的类型化工具。
---
## 提供的内容
| 工具 | 类型 | 备注 |
|---|---|---|
| `list_tables` | 读取 | 数据库中的表 |
| `describe_table(table)` | 读取 | 列、类型、主键 |
| `run_query(sql)` | 读取 | **只读**的临时 SELECT/WITH 查询 — 单语句，阻止突变关键词，行数上限 |
| `top_products(limit)` | 读取 | 按销量（已完成订单）排名的产品 |
| `revenue_summary()` | 读取 | 收入 + 订单/客户数量 |
| `create_support_ticket(...)` | **写入** | **身份验证门控** — 需要写入 API 密钥 |
| `schema://database` | 资源 | 完整的 SQL 模式 |
关键点在于：**bash/raw-SQL 工具**赋予模型无边界的权力；这些是 **专用的、类型化的工具**，宿主可以验证、门控和审计。`run_query` 是只读的，并且有行数上限；唯一的突变操作需要 API 密钥。
---
## 驱动方式
```bash
PY=~/miniconda3/envs/personal/bin/python
$PY -m pip install -e ".[all]"
# 1) 离线 — 练习完整的 MCP 协议，无需 API 密钥，无需大型语言模型：
$PY -m mcp_analytics.client demo
# [mcp] 已连接 — 6 个工具：list_tables、describe_table、run_query 等
# [mcp] revenue_summary -> {"revenue": 184293.5, "orders": 968, "customers": 188}
# [mcp] top_products(3) -> [{"name": "Product 7", "category": "Books", "units": 142}, ...]
# [mcp] 阻止突变 -> 工具错误：仅允许 SELECT / WITH 查询
# 2) 代理 — 让 Claude 通过调用工具回答问题（需要密钥）：
export ANTHROPIC_API_KEY=sk-ant-...
$PY -m mcp_analytics.client ask "哪个国家的客户最多，总收入是多少？"
```
服务器本身通过 **stdio** 运行（`python -m mcp_analytics.server`）— 将 Claude Desktop / Cursor / 任何 MCP 客户端指向该命令，工具就会出现。
### 从 Claude Desktop / Cursor 使用
```json
{
"mcpServers": {
"analytics": { "command": "python", "args": ["-m", "mcp_analytics.server"] }
}
}
```
---
## 架构
```
MCP 客户端（Claude Desktop · Cursor · Anthropic SDK · 本客户端）
│ JSON-RPC via stdio
▼
FastMCP 服务器（server.py） ──工具──► list_tables · describe_table · run_query
│ top_products · revenue_summary
│ create_support_ticket（身份验证门控）
│ ──资源──► schema://database
▼
db.py 纯粹、可测试的查询层 ──► SQLite 电子商务数据库（客户 · 产品
只读守护进程 · 身份验证 · 种子 订单 · 订单项目 · 工单）
```
工具 **逻辑** 位于 `db.py`（在不使用协议的情况下进行单元测试）；`server.py` 是薄的 FastMCP 适配器。Claude 代理（`client.py`）通过 `anthropic.lib.tools.mcp` 将服务器的 MCP 工具转换为 Anthropic 工具，并运行工具循环。
---
## 安全性和治理
- **只读 SQL 守护进程** — `run_query` 仅接受单个 `SELECT`/`WITH` 查询，拒绝 `INSERT/UPDATE/DELETE/DROP/ALTER/ATTACH/PRAGMA/CREATE`，阻止多语句注入，并限制行数。在 `mode=ro` SQLite 连接上执行作为纵深防御。
- **身份验证门控突变** — `create_support_ticket` 需要写入 API 密钥（`MCP_WRITE_API_KEY`）；其他所有工具都是只读的。
- **验证输入** — 未知的表/客户引发类型错误，并反馈给代理。
这些守护进程是安全关键的表面，由测试套件覆盖。
---
## 仓库布局
```
mcp-analytics-server/
├── src/mcp_analytics/
│ ├── db.py SQLite 模式 + 种子 + 纯粹的查询层（只读守护进程，身份验证）
│ ├── server.py FastMCP 服务器：工具 + 模式资源（stdio）
│ ├── client.py MCP 客户端：离线协议 `demo` + Claude `ask` 代理
│ └── config.py 路径，写入 API 密钥，模型
├── tests/ 数据库 + 查询守护进程 + 身份验证测试（无密钥）— 11 个案例
└── pyproject.toml · Dockerfile · Makefile · .github/workflows/ci.yml
```
---
## 简介
> *构建了一个 MCP（模型上下文协议）服务器，通过受控的、类型化的工具暴露数据库 — 只读 SQL 守护进程、身份验证门控突变和模式资源 — 基于标准的 `mcp` SDK；以及一个 Claude 代理，通过它来回答业务问题。演示了 2026 年的代理集成标准端到端（stdio 传输、工具转换、工具循环）。*
## 许可证
MIT (`LICENSE`).
