MCP 迁移决策文档
文档版本: 1.0 创建日期: 2026-03-24 状态: 讨论中
背景
考虑将 zhineng-bridge 从当前的 WebSocket 架构迁移到 MCP (Model Context Protocol) 服务器架构，参考 ChromeDevTools/chrome-devtools-mcp 的设计。
当前架构
zhineng-bridge (现有架构)
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Web UI │────────→│ WebSocket │────────→│ Session Manager │
│ (HTML/CSS) │ │ Server │ │ (Python) │
└─────────────┘ └──────────────┘ └────────┬─────────┘
│
↓
┌──────────────────┐
│ AI 工具集成 │
│ (8种工具) │
└──────────────────┘
技术栈
- 前端: 原生 JavaScript, HTML, CSS
- 协议: 自定义 WebSocket 协议
- 后端: Python 3.8+ (asyncio, websockets)
- 通信: JSON 消息
- UI: 响应式 Web 界面
当前工具列表
- Crush (Charmbracelet)
- Claude Code (Anthropic)
- iFlow CLI (阿里巴巴)
- Cursor (Anysphere)
- Trae (字节跳动)
- Droid (Factory)
- OpenClaw
- GitHub Copilot
参考架构: chrome-devtools-mcp
MCP 服务器架构
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ AI 客户端 │────────→│ MCP 协议 │────────→│ MCP 服务器 │
│ (多种工具) │ │ (标准化) │ │ (Node.js) │
└─────────────┘ └──────────────┘ └────────┬─────────┘
│
↓
┌──────────────────┐
│ Chrome 浏览器 │
│ (DevTools) │
└──────────────────┘
技术栈
- 前端: TypeScript
- 协议: MCP (Model Context Protocol)
- 后端: Node.js 20+
- 通信: MCP 标准化消息
- 工具定义: 结构化工具注册系统
工具分类
- Input automation (9 tools): click, drag, fill, type_text, etc.
- Navigation automation (6 tools): navigate_page, list_pages, etc.
- Emulation (2 tools): emulate, resize_page
- Performance (4 tools): performance_analyze, lighthouse_audit, etc.
- Network (2 tools): list_network_requests, get_network_request
- Debugging (6 tools): screenshot, take_snapshot, console messages, etc.
改造成本分析
收益 ✅
| 类别 | 项目 | 说明 |
|---|---|---|
| 标准化 | 统一接口 | 使用 MCP 标准，支持更多 AI 工具（Cursor、Copilot、Gemini、Claude 等） |
| 生态系统 | 工具自动发现 | MCP 客户端自动发现可用工具，无需手动配置 |
| 文档 | 自动生成 | 从工具定义自动生成 API 文档，减少维护成本 |
| 参数验证 | 内置验证 | 使用 Zod schema 自动验证参数，减少错误 |
| 错误处理 | Self-healing | 返回可操作的错误信息，包含上下文和建议 |
| 可扩展性 | 插件架构 | 更容易添加新工具类型和第三方集成 |
| 社区支持 | 成熟生态 | MCP 有大量现成的工具和客户端支持 |
成本 ❌
| 类别 | 项目 | 说明 |
|---|---|---|
| 开发 | 重大重构 | 需要重写整个后端架构，从 Python/WebSocket 改为 Node.js/MCP |
| 前端 | 客户端适配 | Web UI 需要完全重写，从 WebSocket 客户端改为 MCP 客户端 |
| 迁移 | 兼容性风险 | 现有用户配置可能不兼容，需要迁移工具 |
| 学习 | 团队培训 | 团队需要学习 MCP 协议和 TypeScript/Node.js 生态 |
| 维护 | 双倍负担 | 过渡期需要同时维护 WebSocket 和 MCP 两个版本 |
| 测试 | 全面重测 | 所有现有功能需要重新测试，确保 MCP 实现正确 |
| 部署 | 基础设施 | 需要新的部署流程和监控 |
风险评估
| 风险 | 严重性 | 概率 | 缓解措施 |
|---|---|---|---|
| 破坏现有用户体验 | 高 | 中 | 逐步迁移，保持向后兼容 |
| 性能下降 | 中 | 低 | 充分测试，对比性能指标 |
| 技术债务 | 中 | 高 | 代码审查，定期重构 |
| 用户流失 | 高 | 低 | 提供详细迁移指南，提供支持 |
| 过度设计 | 中 | 中 | 根据实际需求选择方案 |
建议方案
方案 A: 完全改造为 MCP 服务器
描述: 彻底废弃 WebSocket 架构，完全迁移到 MCP
架构:
┌─────────────┐ ┌──────────────┐ ┌──────────────────┐
│ Web UI │────────→│ MCP 客户端 │────────→│ MCP 服务器 │
│ (React/TS) │ │ (前端) │ │ (Node.js) │
└─────────────┘ └──────────────┘ └────────┬─────────┘
│
↓
┌──────────────────┐
│ Session Manager │
│ (重构为TS) │
└────────┬─────────┘
│
↓
┌──────────────────┐
│ AI 工具集成 │
└──────────────────┘
适用场景: - 计划支持 10+ 种 AI 工具 - 需要标准化和自动化 - 团队愿意投入 4-6 周时间
工作量估算: - 后端重构 (Python → Node.js): 2-3 周 - 前端重构 (JS → TypeScript): 1-2 周 - 工具迁移: 1 周 - 测试和文档: 1 周 - 总计: 5-7 周
风险: - 🔴 高风险：破坏性变更 - 🔴 需要维护两个版本（过渡期）
收益: - ✅ 长期技术债务清除 - ✅ 完全符合 MCP 标准 - ✅ 社区生态完全兼容
方案 B: WebSocket + MCP 混合模式
描述: 保持 WebSocket 服务器不变，新增 MCP 适配层，同时支持两种协议
架构:
┌─────────────────────────────┐
│ 协议适配层 (Python) │
└────────┬──────────────────┘
│
┌──────────────┼──────────────┐
│ │ │
↓ ↓ ↓
┌─────────────┐ ┌──────────────┐ ┌──────────────┐
│ Web UI │ │ MCP 客户端 │ │其他 AI 工具 │
│ (WebSocket) │ │ (标准化) │ │ │
└─────────────┘ └──────────────┘ └──────────────┘
│ │
└──────────────┼──────────────┘
↓
┌──────────────────┐
│ Session Manager │
└────────┬─────────┘
│
↓
┌──────────────────┐
│ AI 工具集成 │
└──────────────────┘
适用场景: - 需要保持现有 Web UI - 同时需要支持 MCP 客户端 - 团队资源有限
工作量估算: - MCP 适配层开发: 1 周 - 协议路由和转换: 0.5 周 - 测试: 0.5 周 - 总计: 2 周
风险: - 🟡 中风险：协议转换可能引入 Bug - 🟡 代码复杂度增加
收益: - ✅ 向后兼容，不破坏现有体验 - ✅ 支持 MCP 客户端，扩展生态 - ✅ 低风险，可以快速回退
方案 C: 保持现状，仅参考 MCP 设计
描述: 保持 WebSocket 架构不变，仅借鉴 MCP 的设计原则和最佳实践
改进方向: 1. 工具定义标准化 - 添加 schema 验证（类似 Zod） - 改进错误消息格式 - 添加工具元数据（category, readOnlyHint）
- 文档自动化
- 从工具定义自动生成文档
-
版本化管理
-
错误处理优化
- Self-healing 错误
-
提供上下文和建议
-
响应优化
- 语义化摘要
- Token 优化
适用场景: - 需求稳定，不需要大量新功能 - 团队资源紧张 - 用户对当前方案满意
工作量估算: - 工具定义重构: 0.5 周 - 文档生成脚本: 0.5 周 - 错误处理改进: 0.5 周 - 测试: 0.5 周 - 总计: 2 周
风险: - 🟢 低风险：渐进式改进 - 🟢 不破坏现有功能
收益: - ✅ 改善代码质量 - ✅ 不引入新风险 - ✅ 快速见效
方案 D: 逐步迁移
描述: 分阶段迁移，并行运行两种协议，最终根据实际情况决定是否完全切换
阶段规划:
阶段 1: 并行支持 (1-2 周)
- 保持现有 WebSocket 服务器不变
- 新增 MCP 服务器适配层
- 实现协议路由
- 目标: 双协议并行，无破坏性变更
阶段 2: 工具迁移 (2-3 周)
- 将核心工具迁移为 MCP 工具定义
- 保持 Web UI 继续使用 WebSocket
- 支持 AI 客户端使用 MCP
- 目标: 验证 MCP 的实际价值
阶段 3: 评估和决策 (1 周)
- 收集用户反馈
- 评估两种协议的使用情况
- 分析性能和用户体验差异
- 目标: 数据驱动的决策
阶段 4: 可选切换 (1-2 周，可选)
- 如果 MCP 表现优异，考虑完全切换
- 如果 WebSocket 仍有优势，保持现状
- 目标: 最终方案落地
适用场景: - 需要平滑过渡 - 团队不确定 MCP 的实际价值 - 希望降低风险
工作量估算: - 阶段 1: 2 周 - 阶段 2: 3 周 - 阶段 3: 1 周 - 阶段 4: 2 周（可选） - 总计: 6-8 周（完整）或 6 周（停止在阶段 3）
风险: - 🟢 低风险：可以随时回退 - 🟢 渐进式改进
收益: - ✅ 最大灵活性 - ✅ 数据驱动决策 - ✅ 可以根据实际情况调整 - ✅ 团队学习曲线平缓
方案对比
| 维度 | 方案 A: 完全改造 | 方案 B: 混合模式 | 方案 C: 保持现状 | 方案 D: 逐步迁移 |
|---|---|---|---|---|
| 开发时间 | 5-7 周 | 2 周 | 2 周 | 6-8 周 |
| 技术风险 | 🔴 高 | 🟡 中 | 🟢 低 | 🟢 低 |
| 兼容性 | ❌ 破坏性 | ✅ 向后兼容 | ✅ 完全兼容 | ✅ 渐进式 |
| 灵活性 | 🔒 固定 | 🟡 中等 | 🔓 中等 | 🔓 高 |
| MCP 生态 | ✅ 完全支持 | ✅ 支持 | ❌ 不支持 | ✅ 完全支持 |
| Web UI | 🔄 需要重写 | ✅ 保持不变 | ✅ 保持不变 | ✅ 保持不变 |
| 回退能力 | ❌ 困难 | ✅ 容易 | ✅ N/A | ✅ 容易 |
| 维护成本 | 🟢 低（长期） | 🟡 中等 | 🟡 中等 | 🟡 中等 |
| 用户体验 | 🟡 可能中断 | 🟢 平滑 | 🟢 无变化 | 🟢 平滑 |
关键决策因素
1. 用户群体
- 主要用户: Web UI 用户还是 AI 助手用户？
- 用户规模: 有多少活跃用户？
- 用户反馈: 当前方案的痛点是什么？
2. 功能优先级
- 标准化: 支持 10+ AI 工具 vs 保持 8 种工具
- 性能: 响应速度 vs 丰富功能
- 易用性: 自动发现 vs 手动配置
3. 团队资源
- 人力: 有多少开发者可以参与？
- 时间: 有多长的开发窗口？
- 技能: 团队对 TypeScript/Node.js 的熟悉程度？
4. 业务目标
- 增长: 需要 MCP 生态来吸引新用户？
- 稳定性: 当前方案已经满足需求，不需要激进改动？
- 差异化: MCP 是否能带来竞争优势？
5. 技术债务
- 现有债务: 当前代码库的维护成本如何？
- 长期规划: 3-5 年后的技术栈预期？
推荐方案
首选: 方案 D (逐步迁移)
理由: 1. ✅ 风险最低: 可以随时回退，不会破坏现有体验 2. ✅ 灵活性高: 根据实际数据调整最终方案 3. ✅ 学习平滑: 团队可以逐步学习 MCP 生态 4. ✅ 价值验证: 通过实际使用验证 MCP 的价值 5. ✅ 成本可控: 可以在阶段 3 停止，避免过度投资
备选: 方案 B (混合模式)
适用条件: - 团队时间紧张（2 周内完成） - 明确需要同时支持 Web UI 和 AI 客户端 - 团队对 MCP 价值有信心
不推荐: 方案 A (完全改造)
原因: - 🔴 风险过高，可能丢失现有用户 - 🔴 破坏性变更，难以回退 - 🔴 缺乏实际数据支持
行动计划
立即行动（本周内）
- 收集信息
- [ ] 调研用户群体和需求
- [ ] 分析现有 WebSocket 方案的痛点
- [ ] 评估团队技能和资源
-
[ ] 了解 MCP 生态的实际应用情况
-
技术调研
- [ ] 深入研究 MCP 协议
- [ ] 评估 TypeScript/Node.js 学习曲线
- [ ] 分析其他 MCP 服务器的实现
-
[ ] 测试 MCP 客户端的实际体验
-
决策准备
- [ ] 与团队讨论各方案的优劣
- [ ] 制定详细的实施计划
- [ ] 评估风险和缓解措施
- [ ] 准备用户沟通方案
下一步（决策后）
- [ ] 开始实施选定的方案
- [ ] 每周进度评估
- [ ] 持续收集用户反馈
- [ ] 根据实际情况调整计划
附录: MCP 核心概念
工具定义
interface ToolDefinition {
name: string;
description: string;
schema: ZodSchema;
annotations: {
category: ToolCategory;
readOnlyHint: boolean;
conditions?: string[];
};
handler: async (request, response, context) => void;
}
设计原则
- Agent-Agnostic API: 不锁定到特定 LLM
- Token-Optimized: 返回语义化摘要，而非大量数据
- Small, Deterministic Blocks: 提供可组合的小工具
- Self-Healing Errors: 返回可操作的错误信息
- Human-Agent Collaboration: 机器可读且人类可读
- Progressive Complexity: 简单默认，高级可选
- Reference over Value: 大型资产返回路径，而非原始数据
文档维护者: AI Assistant 最后更新: 2026-03-24 下一步: 等待团队讨论和决策