内容
# MCP 工具优化模式
设计不良的 MCP 工具会导致大型语言模型（LLM）猜测错误的參數值、重试失败的调用，并消耗模型推理所需的上下文。最常见的解决方法是丰富工具描述，添加有效的数值和映射，这提高了准确性，但每次调用都会增加 token 成本。每种改进 MCP 工具的方法都需要在为 LLM 提供足够的指导和保持上下文精简之间取得平衡。
本仓库演示了各种优化模式的权衡。六个版本的相同 K-12 教育内容搜索 API，每个版本都应用了不同的 MCP 层设计模式。相同的后端、相同的测试数据 — 只有工具设计有所不同。代码中的注释详细讨论了每种方法。
## 选择优化模式
每个版本代表一个独立的设计选择，具有其自身的权衡。请选择适合您的使用场景的版本 — 它们不是必需的逐步升级。
| 版本 | 方法 | 权衡 |
|---------|----------|----------|
| **V1** | 原始 API 直连 | 最小努力，但 LLM 准确性较差 |
| **V2** | 丰富的描述 | 高准确性，但工具定义较大 |
| **V3** | 模式强制的枚举 | 防止无效值，定义比 V2 更小 |
| **V4** | 延迟加载的分类法 | 最简洁的基准，但需要额外的往返请求 |
| **V5** | LLM 自省 | 专家解读模糊查询，但需要支付推理费用 |
| **V6** | 代理后端 | 直接控制和完全封装，但基础设施成本最高 |
没有一个版本在所有方面都胜过其他版本。正确的选择取决于您的字段数量、词汇稳定性、延迟预算以及您在不同客户端之间需要一致行为的程度。
## 开始使用
### 前提条件
- [Python 3.13+](https://www.python.org/downloads/)
- [uv](https://github.com/astral-sh/uv#installation)（Python 包管理器）
- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html) 配置了 [Amazon Bedrock 模型访问](https://docs.aws.amazon.com/bedrock/latest/userguide/model-access.html)（仅 V5 和 V6 需要）
- [Node.js 20+](https://nodejs.org/)（仅 V6 需要）
- [`@aws/agentcore` CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html) — 使用 `npm install -g @aws/agentcore` 安装（仅 V6 需要）
- 一个 MCP 客户端（[Kiro](https://kiro.dev/) — 免费层可用，Kiro IDE，Amazon Q CLI 等）
### 启动服务器
所有版本都使用 streamable-http 传输。每个版本都是一个独立的 Python MCP 服务器，监听自己的端口。使用启动脚本启动 V1-V5：
```bash
./scripts/start_all.sh
```
这会在后台运行每个服务器，使用 `uv run`，它会在首次运行时自动从 `pyproject.toml` 安装依赖项：
| 版本 | 端口 | 端点 |
|---------|------|----------|
| V1 | 8001 | http://127.0.0.1:8001/mcp |
| V2 | 8002 | http://127.0.0.1:8002/mcp |
| V3 | 8003 | http://127.0.0.1:8003/mcp |
| V4 | 8004 | http://127.0.0.1:8004/mcp |
| V5 | 8005 | http://127.0.0.1:8005/mcp |
V6 单独运行，通过 Amazon Bedrock AgentCore CLI（端口 8000 必须可用）：
```bash
cd v6 && agentcore dev --skip-deploy --logs
```
停止 V1-V5：
```bash
./scripts/stop_all.sh
```
V6 通过 Ctrl+C 在其终端中停止。
### 连接您的 MCP 客户端
`setup_agents.py` 为每个版本在 `~/.kiro/agents/` 中创建了一个 Kiro 代理配置文件。每个配置文件都指向一个服务器的端点，因此您可以无需编辑配置文件即可在版本之间切换：
```bash
python scripts/setup_agents.py
```
然后在 Kiro 中切换版本：
/agent swap v1-passthrough
/agent swap v4-lazy
/agent swap v6-agent
清除历史记录：/clear
> **注意：** `setup_agents.py`、`/agent swap` 和 `/clear` 特定于 Kiro CLI（当前版本）。生成的代理配置文件使用 Kiro CLI 代理格式，与 Kiro v3 预览版不兼容。如果您使用 Kiro IDE、v3 预览版或其他 MCP 客户端，请手动配置它以指向任何服务器的端点：
```json
{
"mcpServers": {
"content-search": {
"url": "http://127.0.0.1:8004/mcp"
}
}
}
```
## 测试查询
现在服务器已启动，您的 MCP 客户端已连接，请尝试以下查询，并使用每个版本进行比较：
1. `"为我的 7 年级学生找一个关于分数的测验"` — 同义词映射 + 年级解释
2. `"您有适合初中西班牙语教学的课程吗?"` — 主题 + 年级范围推断
3. `"我需要适合中学生进行分数学习的 TEKS 对齐内容"` — 多重翻译（同义词 + 标准 + 年级）
4. `"我可以搜索哪些类型的内容?"` — 发现 / 分类法
5. `"我可以获取有关 n-sc-1096 的详细信息吗?"` — 资源详细信息检索
当您运行每个查询时，请在不同版本之间进行比较：
- LLM 是否在第一次调用中选择了正确的过滤器值
- 它进行了多少次工具调用
- 工具定义消耗了多少上下文
**模型切换：** 尝试在 Kiro 中使用 `/model` 切换模型，并尝试相同的查询。V5 和 V6 无论客户端模型如何，都能产生一致的结果。早期版本更依赖客户端模型解释工具描述的能力。
每个版本的源文件都以注释块开头，解释其方法、上下文权衡和从上一版本的变化。请阅读这些注释块和代码，以了解每个版本的作用和要查找的内容。
## 文件
| 文件 | 用途 |
|------|---------|
| `v1_passthrough.py` | 原始 API 字段、简单描述（反模式基准） |
| `v2_better_descriptions.py` | 丰富的文档字符串描述，包含有效值和同义词 |
| `v3_rethought_schema.py` | LLM 友好的名称、Literal 枚举、层叠工具 |
| `v4_lazy_loading.py` | 最简洁的描述 + 按需分类法工具 |
| `v5_llm_introspect.py` | Amazon Bedrock Converse 调用在搜索前解释查询 |
| `v6/` | V6 的 AgentCore 项目 — 单个 MCP 工具后面的 Strands 代理（参见 `v6/README.md`） |
| `mock_bff_sqlite.py` | 共享后端 — 所有版本都调用相同的函数 |
| `anycompany_content.db` | SQLite 数据库（940 条模拟 K-12 内容记录） |
| `seed_anycompany_content_sqlite.sql` | 种子脚本，用于重建数据库 |
| `scripts/setup_agents.py` | 为所有版本生成 Kiro 代理配置文件 |
| `scripts/start_all.sh` | 在后台启动 V1-V5 |
| `scripts/stop_all.sh` | 停止 V1-V5 |
| `pyproject.toml` | Python 依赖项（由 `uv run` 使用） |
**注意：** `mock_bff_sqlite.py` 和 `anycompany_content.db` 在 `v6/app/v6/` 中重复，用于 AgentCore 兼容性。如果您修改后端或种子数据，请更新两个副本。
## AWS 服务
- **[Amazon Bedrock](https://docs.aws.amazon.com/bedrock/latest/userguide/)** — Converse API，适用于 Amazon Nova 2 Lite（V5 自省）和 Anthropic 的 Claude Sonnet 4.6（V6 代理）
- **[Amazon Bedrock AgentCore](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/)** — 在开发期间本地托管 V6，并在不管理基础设施的情况下部署到云端。AgentCore 提供：
- **[运行时](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/agents-tools-runtime.html)** — 部署和运行 MCP 服务器和代理作为托管端点
- **[网关](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/gateway.html)** — 跨多个 MCP 服务器的语义工具发现
- **[内存](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/memory.html)** — 跨会话的持久上下文
- **[CLI](https://docs.aws.amazon.com/bedrock-agentcore/latest/devguide/runtime-get-started-cli.html)** — 使用 `agentcore dev` 进行本地开发、脚手架和部署（`npm install -g @aws/agentcore`）
- **[Strands Agents SDK](https://strandsagents.com/)** — 为 V6 的内部推理循环提供支持的代理框架
## 清理和成本
**V1-V4** 在本地运行，无需 AWS 费用。
**V5 和 V6** 调用 Amazon Bedrock，并为模型调用产生按需计费费用。停止服务器时请勿使用：
- V1-V5：`./scripts/stop_all.sh`
- V6：Ctrl+C `agentcore dev` 进程
## License
本项目根据 MIT-0 License 授权。
