fix(backend): 接口适配 MCP 2.0

[ImLaoBJie]

为什么改

MCP 2.0 移除了旧版 FastMCP 接口，导致后端服务无法正常启动。

改动要点

• 迁移到 MCPServer 及新版 ToolAnnotations
• 将 MCP 依赖约束为 2.x
• 更新相关开发文档
• 通过测试
• 改动量不大

Closes #2729

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro Plus

Run ID: 9de9f99b-15e3-4669-87ad-e40821c4a56b

📥 Commits

Reviewing files that changed from the base of the PR and between c16372a and 86e7f03.

⛔ Files ignored due to path filters (1)

• uv.lock is excluded by !**/*.lock

📒 Files selected for processing (10)

• docs/develop/zzz/backend/design-principles.md
• docs/develop/zzz/backend/entry.md
• docs/develop/zzz/backend/mcp-implementation.md
• docs/develop/zzz/backend/mcp.md
• pyproject.toml
• src/zzz_od/backend/entry/server.py
• src/zzz_od/backend/http/routes.py
• src/zzz_od/backend/http/service_routes.py
• src/zzz_od/backend/mcp/app.py
• src/zzz_od/backend/mcp/prompts.py

Included review availability: Your plan provides up to 8 included reviews per hour; 7 remain after this review.

---

📝 Walkthrough

变更（Changed）

• 将后端 MCP 实现从 FastMCP 迁移至 MCPServer。
• 更新工具和提示词注册函数的类型标注及构造方式。
• 将 ToolAnnotations 参数统一为 read_only_hint 和 destructive_hint。
• 将 mcp 依赖约束为 >=2.0.0,<3。
• 更新 HTTP 路由和后端文档中的 MCP 2.x API 说明。
• 补充同步工具在线程池执行及 GPU 调用串行化要求。

修复（Fixed）

• 修复 MCP 2.0 移除 mcp.server.fastmcp 后导致后端服务无法启动的问题。

Walkthrough

项目将 mcp 依赖约束更新为 >=2,<3，并将后端服务、工具注解、提示注册和 HTTP 路由类型迁移到 MCPServer API。文档同步说明 snake_case 字段和线程执行约束。

Changes

MCP 2 迁移

Layer / File(s)	Summary
SDK 依赖与 API 约定 pyproject.toml, docs/develop/zzz/backend/{entry.md,design-principles.md,mcp-implementation.md}	将 mcp 依赖限制为 >=2,<3。文档统一使用 MCPServer 和 snake_case 注解字段，并补充参数 schema 与线程执行说明。
MCPServer 创建与工具注册 src/zzz_od/backend/mcp/app.py, src/zzz_od/backend/mcp/prompts.py, docs/develop/zzz/backend/mcp.md	服务器创建、返回类型、工具注册和提示注册改用 MCPServer。工具注解字段改用 read_only_hint 和 destructive_hint。
HTTP 路由类型集成 src/zzz_od/backend/http/routes.py, src/zzz_od/backend/http/service_routes.py, src/zzz_od/backend/entry/server.py	HTTP 路由注册函数和共享应用实例的类型标注及说明改为 MCPServer。路由处理逻辑未改变。

Estimated code review effort: 2 (Simple) | ~10 minutes

Merge Risk: ⚪ Minimal · up to 86e7f

This PR updates the backend MCP integration and dependency constraints for MCP 2.0; no actionable merge-blocking risk remains beyond normal checks and review.

Suggested reviewers: doctorreid

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	标题明确说明后端已适配 MCP 2.0，准确概括了主要变更。
Description check	✅ Passed	描述说明了 MCP 2.0 兼容问题、迁移内容、依赖约束和关联 issue，与变更内容一致。
Linked Issues check	✅ Passed	代码已迁移至 MCPServer，更新 ToolAnnotations 和 MCP 2.x 依赖，并保留现有工具、提示词及路由调用方式，符合 #2729 目标。
Out of Scope Changes check	✅ Passed	变更集中于 MCP 2.0 迁移、依赖约束及相关文档更新，未发现与 #2729 无关的代码改动。
Docstring Coverage	✅ Passed	Docstring check was indeterminate for this PR — some files could not be analyzed in time. Not blocking.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}