MCP项目实践-DailySearch

Table of contents

1. 什么是 MCP？

MCP（Model Context Protocol） 是面向 AI Agent 的工具扩展标准协议。它约定了一套与具体业务无关的交互方式：

2. Builtin 的优缺点是什么？为什么使用 MCP？

2.1 Builtin 是什么

Builtin 指在 FastAPI 后端用 Python @tool 装饰器 + builtin_registry 直接注册、在进程内执行的函数。

2.2 优点

• 延迟低：同进程调用，无子进程或跨机 RPC。
• 上手快：写一个 handler、注册进 registry 即可给 LLM 用。
• 适合零依赖小工具：例如 get_current_time 这类高频、无子进程开销的工具（迁移计划中也建议长期保留）。

2.3 缺点（本项目里真实踩过的坑）

2.4 为什么改用 MCP

1. 统一协议：服务端 MCP（Docker 内 fetch、tavily）与客户端 MCP（插件内 obsidian）都用 tools/list + tools/call，Catalog 里 source 可标为 mcp / client_mcp。
2. 新增能力 ≈ 配置 + Skill：接入社区 MCP（如 mcp-server-fetch）或自研 packages/obsidian-mcp-server，不必改 tool_agent 主循环。
3. 边界清晰：云端做网页抓取；本机 Obsidian 做 vault 读写——MCP 统一的是调用方式，不是强行合并运行环境。

4. 本项目中 MCP 解决了哪些原有问题？

4.1 云端无法直接调用用户本机 CLI

问题：FastAPI 跑在 Docker 或远程机器时，无法执行用户电脑上的 obsidian CLI，也无法访问用户 vault 的真实路径。

MCP 解法：

• 结构化工具名：mcp_client__obsidian__vault_read_note
• 参数为 JSON：{ "path": "Daily/2026-05-20.md" }（见 obsidian_cli.skill.md），禁止再传 obsidian read file="..." 这类 CLI 字符串。
• 后端 ClientToolBridge.mcp_invoke 经 WebSocket 发 mcp_call，插件 PluginMcpHost 用 Obsidian App API 读文件，结果经 mcp_result 返回。

测试中的真实帧（backend/tests/test_client_tool_bridge.py）：

{
  "type": "mcp_call",
  "server_id": "obsidian",
  "method": "tools/call",
  "params": {
    "name": "vault_read_note",
    "arguments": { "path": "a.md" }
  }
}

4.2 云端误用「本机绝对路径」读 vault

问题：若在后端 Builtin 里用 open("/Users/xxx/vault/note.md")，在 Docker 里路径不存在或根本不是用户的库。

MCP 解法：

• 路径语义统一为 相对 vault 根（如 Projects/foo.md）。
• 实际 IO 只在插件进程内完成（packages/obsidian-mcp-server 的 vault_read_note 等）。
• 后端与插件不再解析 CLI 字符串，降低路径注入与解析分歧风险。

4.3 双份 CLI 白名单与 client_mcp__ 伪协议

问题（迁移文档「现状 vs 目标」表）：

• Python 与 TypeScript 各维护 Obsidian CLI 规则；
• tool_invoke + 工具名字符串，每加一个工具要改 orchestrator.ts 分支。

MCP 解法：

• 自研 dailysearch-obsidian（packages/obsidian-mcp-server/），安全策略集中在 security.ts（allowed_operations、writeEnabled 默认关）。
• WebSocket 从 tool_invoke 演进到 mcp_call / mcp_result，载荷对齐 JSON-RPC 语义。
• 遗留名 client_mcp__vault_read 仍兼容，但 Skill 与 README 要求优先 mcp_client__obsidian__*。

4.4 客户端工具超时

问题：插件未响应时 Agent 一直等。

项目举例：test_client_tool_bridge.py 的 test_timeout 在 timeout_s=0.05 时返回 {"ok": false, "error": "client tool timeout"}——说明桥接层必须处理超时，而不是假设本机永远在线。

5. 云端 / Docker 使用 MCP 统一前后端的优势

统一的不是运行位置，而是调用契约：云端与用户端仍分割（见下文架构图），但 Agent、Skill、Catalog 只认「限定工具名 + JSON 参数」。

6. 云端 + 用户端：MCP 整体结构

6.1 逻辑架构（迁移目标）

6.2 一次 vault 读笔记的端到端流程（与 docx 提纲一致）

1. 云端 Agent 根据 Skill obsidian_cli 决定调用 mcp_client__obsidian__vault_read_note，参数 { "path": "Daily/2026-05-20.md" }。
2. tool_agent 识别为 client-side 工具（is_client_side_tool → mcp_client__ 前缀）。
3. ClientToolBridge 组装 mcp_call 帧，经 WebSocket 发给插件。
4. 插件 wsChat.ts 收到 mcp_call，交给 PluginMcpHost → ObsidianMcpHost → vault_read_note。
5. Obsidian API 在用户本机读 vault 文件。
6. 结果 JSON 经 mcp_result 回传，tool_agent 继续生成回复。

要点：

• MCP Host：在插件进程内，把结构化调用转成 Obsidian API，并执行 security.ts 中的读写策略。
• WebSocket：只负责把后端的「调用 obsidian 服务器的 vault_read_note」送到插件并带回结果；WS 本身不读文件。

6.3 插件连接条件

7. MCP Host 可以解决什么问题？

7.1 核心问题：没有 Host 时的「双份维护」

原先：云端 Agent 与插件为了能执行同一套 Obsidian CLI 规则，需要在 Python 与 TypeScript 各维护一份白名单和解析逻辑（obsidian_tools.py vs obsidianCliRunner.ts）。

有 Host 之后：

• 业务规则与安全策略集中在 packages/obsidian-mcp-server（例如 TOOL_SECURITY、writeEnabled 默认 false）。
• 插件侧 PluginMcpHost 进程内嵌 ObsidianMcpHost，对外暴露 listTools / callTool。
• 后端只发标准 mcp_call，不再解析 obsidian read ... 字符串。

7.2 Host 还解决的问题

8. WebSocket 通信结构

8.1 帧类型演进

8.2 mcp_call 示例（与迁移文档一致）

{
  "type": "mcp_call",
  "turn_id": "...",
  "call_id": "...",
  "server_id": "obsidian",
  "method": "tools/call",
  "params": {
    "name": "vault_read_note",
    "arguments": { "path": "folder/note.md" }
  }
}

8.3 插件侧处理（wsChat.ts）

• 无 mcpCallHandler 时返回：插件未注册 MCP 处理器。
• 有 handler 时执行 callTool，再通过 sendMcpResult 回传。

8.4 与会话其他消息的关系

• 用户消息、流式 delta、done 等仍走原有 chat 协议。
• 工具调用是并行通道：bridge 用 call_id 匹配 pending Future（见 ClientToolBridge.resolve）。

9. MCP 架构：Adapter → 注册 → MCP Server

9.1 服务端（Docker / 本机后端）

McpServerConfig (环境变量 / PUT /settings/mcp)
        ↓
McpServerSession.connect()   # stdio 子进程
        ↓
McpToolAdapter.sync_into(registry)   # tools/list → 注册 ToolDef
        ↓
限定名例如 mcp_fetch__fetch、mcp_tavily__tavily-search
        ↓
tool_agent 调用 handler → session.tools/call

关键代码：backend/app/services/mcp/adapter.py 的 sync_into 为每个 MCP 工具生成 mcp_{serverId}__{toolName} 并建立 routing 表。

9.2 客户端（Obsidian 插件）

PluginMcpHost (in-process)
        ↓
@dailysearch/obsidian-mcp-server / ObsidianMcpHost
        ↓
vault_* / editor_* 工具
        ↓
WebSocket mcp_call / mcp_result 与后端 ClientToolBridge 对接

后端 client_proxy 负责把 mcp_client__obsidian__* 映射到 server_id=obsidian 的 mcp_invoke。

9.3 Skill 层如何挂接

Skill 在匹配时注入 prompt 片段；tool_agent 主循环不变，只在边界做 MCP 路由。