Open Brain MCP 服务器

使用说明

• 项目简介
  • 该仓库实现了一个 MCP 服务器，用于向大语言模型客户端提供可查询的知识上下文和外部工具。核心功能包括：注册并暴露工具、基于向量嵌入的语义检索、以及对知识进行捕获和管理。服务器通过 JSON-RPC 与客户端进行通信，支持通过 OAuth 发现与鉴权。
• 主要功能点
  • 工具（Tools）：capture、semantic_search、search_by_person、search_by_topic、list_recent、stats、delete_thought 等，支持对个人知识库进行捕获、查询、统计与删除操作。
  • 数据存储与向量化：使用 Neon Postgres + pgvector 保存原始文本、嵌入向量、元数据（类型、人物、主题、行动项等），并提供基于向量距离的近似检索。
  • 身份与授权：通过 Clerk 实现 OAuth 2.1 授权流程，MCP 请求通过 bearer token 进行鉴权，支持发现元数据端点。
  • 部署与传输：实现了基于 HTTP 的 Streamable 传输（WebStandardStreamableHTTPServerTransport），并提供 API 路由用于 MCP 请求处理；同时包含本地 Python 版本作为 stdio 传输的替代实现。
• 安装步骤
  • Node.js / Next.js 版本（部署于 Vercel 等云端：open-brain，URL 由部署决定）
    1. 克隆仓库并安装依赖：pnpm install
    2. 配置数据库与 API 密钥：在 .env.local 填写 DATABASE_URL、OPENAI_API_KEY、CLERK_SECRET_KEY、NEXT_PUBLIC_CLERK_PUBLISHABLE_KEY 等必要变量
    3. 运行数据库 schema：psql $DATABASE_URL -f src/migrations/001_schema.sql
    4. 部署应用：vercel deploy 或 push 到 GitHub 触发自动部署
    5. 将 MCP 服务器地址配置为客户端连接 URL，示例为 https://your-app.vercel.app/api/mcp
  • 本地 Python 版本（stdios 传输，便于自测）
    1. 进入 src/mcp-server 目录，创建并激活虚拟环境：python3 -m venv .venv && source .venv/bin/activate
    2. 安装依赖：pip install -r requirements.txt
    3. 复制并配置环境变量：cp .env.example .env，填入 DATABASE_URL 与 OPENAI_API_KEY 等
    4. 以本地方式启动 MCP 服务器（示例命令，实际客户端如 Claude Code 可按此路径注册）：claude mcp add open-brain -- $(pwd)/.venv/bin/python $(pwd)/server.py
• 服务器配置（MCP 客户端所需的启动信息，JSON 格式） { "server_name": "open-brain", "command": "python3", "args": ["src/mcp-server/server.py"] } 注释：
  • server_name：服务器在客户端注册时的名称，仓库实现中使用的是开放名称“open-brain”。
  • command/args：用于本地调试时启动 MCP 服务器的命令及参数。若在云端部署（如 Vercel 的 Next.js 版本）则客户端也可以通过远程地址进行连接，而无需本地启动命令。
• 基本使用方法
  • 客户端接入流程包括：将服务器地址添加到客户端的 MCP 服务器列表，完成 OAuth 授权发现后即可与服务器进行交互，调用 capture、semantic_search、search_by_person、search_by_topic、list_recent、stats、delete_thought 等工具实现知识捕获、检索和管理。
  • 实际应用演示可参考仓库中的 README 提示，例如通过 Claude Code 将服务器作为远程 MCP 服务接入，首次连接会触发鉴权流程并完成认证。