serving-brain-over-mcp

能力目标

让 Agent 把一个 brain 通过 MCP 协议暴露给支持 MCP 的 AI 工具（Claude Code / Cursor / Windsurf），使这些工具能用自然语言直接查询和操作 brain 内容；并能查看暴露的工具清单、按需起 HTTP 远程模式、以及换一个 brain 而不重学 MCP。

前置

• brain 数据已就绪（GBRAIN_HOME 指向的目录已 init 且 gbrain list 有输出）。GBRAIN_HOME 是贯穿所有命令的根控制变量——换 brain 只换这个路径。
• 三种部署模式：stdio（本地 subprocess，适合本地 AI 编辑器）、HTTP（网络服务 + Admin Dashboard，适合远程客户端）、HTTP + OAuth 2.1 PKCE（适合 ChatGPT 等需安全授权的远程客户端）。
• CLI、stdio MCP、HTTP MCP 三种接入共享同一 brain 底层引擎、工具名/参数/结果一致（thin wrappers identical ops）。

实操流程

1. stdio 接入 Claude Code。-e 传 GBRAIN_HOME（不传则默认读 ~/.gbrain、数据空时工具返回空结果）；-- 之后是启动命令：

   claude mcp add gbrain -e GBRAIN_HOME="/path/to/your-brain" -- gbrain serve
   claude mcp list          # gbrain 行应显示 ✓ Connected
   claude mcp get gbrain    # Type: stdio, Command: gbrain, Args: serve, Env: GBRAIN_HOME
   

   配置持久化在 ~/.claude/.claude.json 的 mcpServers（local scope），重启自动恢复。

2. 查看暴露的工具清单。工具发现用顶层 flag --tools-json（不是 gbrain call tools/list——call 子命令不支持、会报 Unknown tool）：

   GBRAIN_HOME="/path/to/your-brain" gbrain --tools-json \
     | python3 -c "import json,sys; d=json.load(sys.stdin); t=d if isinstance(d,list) else d.get('tools',[]); print('Total:',len(t)); [print(' -',x['name']) for x in t]"
   

   工具按前缀分类：get*（读数据，最大类）、search（BM25、无需 LLM）、query（hybrid、需 LLM）、think（多跳推理、需 LLM）、traverse_graph、put_page / list_pages 等。绝大多数工具本地运行、只有 query 与 think 依赖 LLM——API quota 耗尽时 search 仍可用。

3. 触发查询验证（Claude Code 中自然语言查询会自动调 mcp__gbrain__<tool>）。底层等价调用用 gbrain call：

   GBRAIN_HOME="/path/to/your-brain" gbrain call search '{"query":"lena"}'
   GBRAIN_HOME="/path/to/your-brain" gbrain call get_page '{"slug":"people/lena-kovac"}'
   GBRAIN_HOME="/path/to/your-brain" gbrain call list_pages '{"limit":5,"type":"person"}'
   

4. Cursor / Windsurf 接入：写 JSON 配置声明 MCP server，结构与 Claude Code 等价、仅文件路径不同：

   // Cursor: ~/.cursor/mcp.json    Windsurf: ~/.codeium/windsurf/mcp_config.json
   { "mcpServers": { "gbrain": {
       "command": "gbrain", "args": ["serve"],
       "env": { "GBRAIN_HOME": "/path/to/your/brain" } } } }
   

   重启编辑器后 MCP servers 列表应显示 gbrain ✓ Connected。

5. （进阶可选）HTTP 模式接远程客户端。起服务、查 health、访问 Admin Dashboard：

   GBRAIN_HOME="/path/to/your-brain" gbrain serve --http --port 3131 > /tmp/mcp-http.log 2>&1 &
   sleep 3
   curl --noproxy localhost -s http://localhost:3131/health          # {"status":"ok",...}
   curl --noproxy localhost -s http://localhost:3131/admin/          # 必须带尾部斜杠
   

   Admin token 在启动日志 /tmp/mcp-http.log 里；Dashboard 可注册 OAuth client（ChatGPT 等远程接入）。用完清理：pkill -f 'gbrain serve --http'。

6. 换 brain（核心复用路径 = 换 GBRAIN_HOME、MCP 协议层不变）：

   claude mcp remove gbrain -s local
   claude mcp add gbrain -e GBRAIN_HOME="/path/to/my-personal-brain" -- gbrain serve
   claude mcp list
   

校验回路

• claude mcp list 中 gbrain 显示 ✓ Connected；claude mcp get gbrain 确认 Type: stdio + 正确的 GBRAIN_HOME。
• gbrain --tools-json 返回完整工具清单（含 search / get_page / query / traverse_graph 等）。
• gbrain call search '{"query":"..."}' 返回带 slug + title + type + score 的命中；同一 query 经 CLI（gbrain search）与 MCP（gbrain call search）top 结果排名一致、score 高度接近——证明三种接入共用同一引擎。
• HTTP 模式：curl .../health 返回 status: ok；curl .../admin/（带斜杠）返回 Dashboard HTML。

常见陷阱

• 不传 -e GBRAIN_HOME → 工具返回空：gbrain 默认读 ~/.gbrain，该目录空或损坏时 MCP 调用返回空结果。务必用 -e 明确指定 brain 路径。
• 工具发现命令：用 gbrain --tools-json（顶层 flag），不是 gbrain call tools/list（后者报 Unknown tool）。若 --tools-json 不可用，改在编辑器里直接查看已注册的 MCP 工具列表。
• query 工具在 API quota 耗尽时返回空数组：hybrid 需 Anthropic LLM；改用 search（BM25、纯本地）覆盖日常查询。
• Admin Dashboard /admin 返回 404：URL 必须以 /admin/ 结尾（带尾部斜杠），不带斜杠报 Cannot GET /admin。
• localhost 请求超时：系统配了 http_proxy 时被代理拦截，curl 加 --noproxy localhost、浏览器把 localhost 加入代理例外。
• 移除配置：claude mcp remove gbrain -s local。pkill HTTP server 不影响 stdio MCP 配置（stdio 是 Claude Code 按需 spawn 的子进程、不依赖独立 HTTP 服务）。