内容
# MCPantry — 生产环境MCP服务器，附带使用分析
> 一个真正的 **模型上下文协议（MCP）** 服务器，向AI代理（Claude Desktop / Claude Code / 任意MCP客户端）公开受控的分析工具 — 加上一个 **工具调用分析** 层，跟踪代理实际使用的工具、速度和失败率。
   
MCP是2026年代理AI的连接组织 — 它是助手安全访问您的数据和工具的方式。很少有人部署过真正的、非琐碎的MCP服务器，而且几乎没有人对其进行监控。MCPantry两者皆有。
## 查看其工作 — Claude实时调用这些工具
这是 **真实捕获** 的Claude Code连接到MCPantry，通过MCP，自动调用 `top_n` 工具，并从结果中回答 — 同时MCPantry的分析层记录调用：
> 重现它：使用捆绑的 `claude_desktop_config.example.json` （或 `--mcp-config` ）注册服务器，并询问任何MCP客户端“按收入划分的 top 地区是什么？”
---
## 问题
团队希望他们的AI助手在 *他们的数据* 上回答问题（“上周按收入划分的 top 地区是什么？”），而无需复制粘贴CSV或给予模型原始数据库访问权限。MCP是标准答案 — 但一个裸露的MCP示例，公开 `add(a,b)` ，证明不了什么。一旦代理开始调用您的工具， **您不知道哪些工具重要，哪些工具慢，或者哪些工具出错** — MCP尚无可观测性。
MCPantry是一个真正的分析MCP服务器 **附带** 可观测性。
## 谁在使用它
- **平台/数据团队** 公开受控的指标给内部AI助手。
- **AI工程师** 构建需要真实工具访问的代理（非虚构数据）。
- 任何需要 **MCP可观测性** 的人 — 代理工具调用的使用分析。
## 它证明了什么（技能）
真正的MCP服务器实现（FastMCP），工具/注册表设计，一个干净的SDK独立工具层（可在不传输的情况下进行单元测试），以及一个 **可观测性层** （SQLite支持的使用分析，延迟和错误跟踪）。这是协议这个助手使用的 — 即时区分。
---
## 架构
```
MCP客户端（Claude Desktop / Code）
│ 标准输入输出（MCP协议）
▼
┌──────────────────────────────┐
│ FastMCP服务器（server.py） │ 工具：list_datasets，query_metric，top_n
│ 每个调用都由 ───┐ │
│ UsageTracker.track() │ │
└────────────┬───────────────┘ │
▼ ▼
data.py（查询引擎） usage.py（SQLite：工具，延迟，成功/错误）
合成'orders' │
数据集（或您的数据仓库） └──► stats(): 调用/错误率/延迟每个工具
```
工具逻辑（ `tools.py` / `data.py` ）与MCP SDK故意解耦，以便进行单元测试，您可以公开相同的函数通过REST或CLI。在生产环境中，将 `data.py` 指向您的数据仓库 — 或指向 **MetricForge** 以获取受控的指标。
| 模块 | 责任 |
|--------|----------------|
| `data.py` | 确定的合成数据集 + 聚合查询 |
| `tools.py` | SDK独立的工具注册表 + `call_tool()` |
| `usage.py` | `UsageTracker` — 记录每个调用，计算每个工具的统计信息 |
| `server.py` | FastMCP服务器连接工具 + 使用情况跟踪 |
| `cli.py` | `serve`，`tools`，`demo` |
---
## 技术栈
**Python 3.10+ · `mcp` SDK（FastMCP）1.x · SQLite · Typer + Rich · pytest · Docker**
---
## 快速开始
```bash
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt && pip install -e .
mcpantry tools # 列出公开的工具
mcpantry demo # 调用工具离线 + 显示使用分析
mcpantry serve # 作为MCP标准输入输出服务器运行
```
### 在Claude Desktop / Claude Code中注册
将以下内容添加到您的MCP客户端配置中（参见 `claude_desktop_config.example.json` ）：
```json
{ "mcpServers": { "mcpantry": { "command": "mcpantry", "args": ["serve"] } } }
```
然后询问您的助手： *"使用mcpantry，哪些地区按收入排名前3？"*
---
## 截图
> 真实的实时输出快照。随时使用 `python scripts/make_screenshots.py` 重新生成（将实际的Rich表格渲染为SVG — 无需模拟）。
**通过MCP公开的工具** — 代理连接时发现的内容：
**工具调用结果** — 代理从 `top_n` 接收的内容：
**使用分析** — 可观测层：每个工具的调用量、错误率和延迟（包括强制错误以显示错误率跟踪）：
> 💡 查看 [实时代理捕获](#查看其工作--claude实时调用这些工具) 以获取真实AI代理调用这些工具的端到端证明。对于更丰富的可视化，请在 **Claude Desktop** （GUI）中使用 `claude_desktop_config.example.json` 注册服务器并截图聊天记录。
---
## MVP vs. 高级
**MVP（此仓库）：** 具有3个分析工具、SDK独立 + 测试的工具层、SQLite使用分析（调用/延迟/错误）、CLI、Docker、客户端配置示例的FastMCP服务器。
**高级路线图：**
- MCP **资源** 和 **提示** （而不仅仅是工具）；身份验证 + 每个客户端的作用域。
- 真实的数据仓库后端；将工具连接到 **MetricForge** 以获取受控的指标。
- 使用分析仪表板 + 异常警报（工具错误率激增）。
- 每个工具的速率限制/成本防护；代理操作的审计日志。
- 跨多个MCP服务器的多服务器注册表视图。
## 测试
```bash
pytest -q # 7个测试：查询引擎，按日期范围过滤，使用跟踪（包括错误），服务器连接
```
## 简历要点
- *构建了 **MCPantry** ，一个生产环境的模型上下文协议服务器（FastMCP），向AI代理公开受控的分析工具，带有 **使用分析层** 跟踪每个工具的调用量、延迟和错误率 — MCP可观测性在现成产品中不存在。*
- *将工具逻辑与MCP传输解耦，以便进行全面单元测试的工具注册表（7个测试），并交付了Claude Desktop/Code集成配置。*
## 为什么招聘者关心
部署2026年的真实MCP服务器表明您处于代理AI的前沿 — 这是助手用于访问工具和数据的协议。添加可观测性显示了产品成熟度，而不仅仅是一个玩具。它与 **MetricForge** （数据源）、 **PromptLedger** 和 **EvalForge** 组合，呈现一个连贯的“AI平台”产品组合。
## 许可证
MIT
