内容
# 引用 MCP 服务器 — 个人 AI 助手演示
演示代码，用于演讲 **"为个人 AI 助手定制 MCP 服务器架构"**（Pesona AI 峰会，7 月 21 日）。它是 *设计多智能体 AI 系统使用 MCP* 第 7 章的实践伴侣。
整个项目是一个小型 MCP 服务器，加上从代理框架（AI-6）和三个编码代理（Claude Code、Codex、OpenCode）使用的线路。重点是展示构建自定义 MCP 服务器需要多少内容，以及 *相同的* 服务器如何插入每个 MCP 感知主机。
> **继续跟进？** 查看 **[WALKTHROUGH.md](WALKTHROUGH.md)** 以获取可复制的、可以直接复制粘贴的步骤。本 README 是概述。
## 它做了什么
一组按类别分组的引用生活在 [`quotes.json`](quotes.json) 中。 [`quote_server/quote_mcp_server.py`](quote_server/quote_mcp_server.py) 中的服务器通过 STDIO 传输暴露了两个工具：
| 工具 | 输入 | 返回 |
| --- | --- | --- |
| `list_categories` | — | 有引用的类别，以逗号分隔 |
| `get_quote` | `category` | 该类别的随机引用，如果类别未知或为空，则 **无** |
它建立在官方的 [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk) `FastMCP` 助手之上 — 每个工具都只是一个装饰函数。就是这样一个服务器。
## 布局
```
summit-ai-mcp-demo/
├── quotes.json # 按类别整理的引用
├── quote_server/
│ ├── quote_mcp_server.py # MCP 服务器（FastMCP）
│ └── try_server.py # STDIO 烟雾测试客户端（无 LLM）
├── ai6/
│ ├── config.yaml # 指向服务器的 AI-6 配置
│ ├── quote_assistant.py # 使用它的微型 AI-6 CLI
│ └── native_tools/ # （空）AI-6 本地工具目录
├── .mcp.json # Claude Code MCP 配置（参考）
├── opencode.json # OpenCode MCP 配置（参考）
├── pyproject.toml # 依赖项：mcp[cli]，ai-six
├── WALKTHROUGH.md # 与会者逐步指南
└── README.md
```
## 快速开始
```bash
uv sync # 将所有内容安装到 .venv 中
# 1. 在 STDIO 上测试服务器（无需 API 密钥，无需浏览器）：
uv run python try_server.py
# 2. 与使用它的 AI-6 助手聊天（需要 OPENAI_API_KEY）：
export OPENAI_API_KEY=sk-...
uv run python ai6/quote_assistant.py
```
（更喜欢可视化工具？`uv run mcp dev quote_server/quote_mcp_server.py` 打开 MCP 检查器 — 请参阅 [WALKTHROUGH.md](WALKTHROUGH.md#12--optional-the-visual-mcp-inspector) 以获取检查器需要的单个手动步骤。）
```
👤 [您]：给我一个斯多葛主义的名言
🤖 [助手]：
🔧 [list_categories()] -> 创造力、工程学、幽默、动力学、斯多葛主义
🔧 [get_quote(category='stoicism')] -> “不要再浪费时间争论一个好人应该是什么样。成为一个。” — 马库斯·奥勒留斯
“不要再浪费时间争论一个好人应该是什么样。成为一个。” — 马库斯·奥勒留斯
```
## AI-6 如何获取它
[`ai6/config.yaml`](ai6/config.yaml) 是一个普通的 AI-6 配置。引入我们服务器的一行是 `mcp_tools_dirs`：
```yaml
mcp_tools_dirs:
- ${DEMO_DIR}/quote_server
```
AI-6 扫描该目录，在 STDIO 上启动它找到的每个 MCP 服务器，发现它们的工具，并将它们交给代理，就像它们是原生工具一样。没有胶水代码 — 只有配置。AI-6 本身是一个 PyPI 依赖项（`ai-six`），因此无需克隆任何额外的内容。
## 从编码代理使用服务器
同一个服务器适用于任何 MCP 主机。所有三个代理都通过 `uv` 启动它，因此它在存储库的虚拟环境中运行，其中安装了 `mcp`。完整的步骤和验证请参见 [WALKTHROUGH.md](WALKTHROUGH.md#part-3--use-it-from-coding-agents-no-api-key-needed-for-setup)；一行程序：
```bash
# Claude Code（写入 .mcp.json）
claude mcp add quotes --scope project \
-- uv --directory ~/git/summit-ai-mcp-demo run python quote_server/quote_mcp_server.py
# Codex（写入 ~/.codex/config.toml）
codex mcp add quotes \
-- uv --directory ~/git/summit-ai-mcp-demo run python quote_server/quote_mcp_server.py
# OpenCode：编辑 opencode.json 中的路径，然后 `opencode mcp list`
```
## 要点
一个 ~65 行的服务器，一次编写针对 MCP 接口，适用于代理框架和三个不同的编码代理。 这就是 MCP 的承诺：一次构建工具，到处使用。
## 资源
- 📖 **[使用 MCP 和 A2A 设计多智能体 AI 系统](https://www.amazon.com/Design-Multi-Agent-Systems-Using-MCP/dp/1806116472)** — 查看第 7 章
- 📝 **[Claude Code 深入探讨：MCP 解放](https://medium.com/@the.gigi/claude-code-deep-dive-mcp-unleashed-0c7692f9c2c2)** — Medium 文章
- 🔬 **[创建 SPACE：用于长期运行代理的安全高效运行时](https://research.perplexity.ai/articles/making-space-secure-and-efficient-runtimes-for-long-running-agents)** — Perplexity 研究
