# ADR-006: MCP 协议迁移预留

## 修改记录

| 日期 | 变更 |
|------|------|
| 2026-07-18 | 初始创建 |

## ADR-006++

| 状态 | 项 | 说明 | 验证 |
|------|-----|------|------|
| ⏸ | MCP 迁移 | 工具数增长到 3-5 个时迁移 | 未开始 |

## 状态

**⏸ 待触发**（工具数达 3-5 个时迁移）。

当前维持手写 Function Calling。原决策见 [ADR-005 § 决策 3](005.md#决策-3mvp-不上-mcp)。

## 背景

当前 Agent 的工具调用采用**手写 Function Calling** 方式：

- 工具定义在 `prompts.py:POI_TOOL_DEF`（1 个工具 `poi_lookup`）
- 注册在 `tools/__init__.py:TOOL_REGISTRY`
- 调用链路在 `routes.py` 聊天端点：两阶段——先非流式检测 `tool_call` → 执行工具 → SSE 发 `tool_result` → 再流式输出 LLM 回复

当前工具数仅 1 个时，这套手写方案明确够用。但当工具数增长到 3-5 个时，管理和扩展的开销会上升。

## 现状 vs MCP

| 维度 | 手写 FC（现状） | MCP 协议 |
|------|---------------|----------|
| 工具注册 | `TOOL_REGISTRY` 字典，手动维护 | 通过 MCP Server 动态发现 |
| 调用协议 | 硬编码 HTTP→高德 API | 标准化 JSON-RPC |
| 工具拆分 | 所有函数同进程 | 每个工具可独立部署 |
| 扩展新工具 | 改 routes.py + TOOL_REGISTRY | 加 MCP Server |
| 依赖 | 无额外依赖 | `mcp` Python 包 |
| 复杂度 | 简单直接 | 引入序列化/传输/协议层 |

## 迁移路径（预留方案）

当工具数增长到 3-5 个时，按以下步骤迁移：

1. **创建 MCP Server**：包装 `TOOL_REGISTRY` 中的函数，通过 `FastMCP` 暴露为标准工具
2. **MCP Client 替换**：`routes.py` 聊天端点改用 MCP Client 调用，替代手写 `tool_call` 检测
3. **逐步迁移**：新旧并存，新工具通过 MCP Server 注册，旧工具保持手写
4. **全量切换**：确认所有工具通过 MCP 运作后，移除手写 FC 路径

## 数据流

```
TOOL_REGISTRY ──→ MCP Server ──→ MCP Client ──→ routes.py chat 端点
                                                      ↓
                                                SSE tool_result
```