TheBrain MCP 服务器（FastMCP 基础实现）

关键词

知识图谱微支付机器人/AI 代理上下文云端服务脚本化查询

使用说明（Markdown 格式）

  • 项目简介

    • TheBrain MCP 服务器是一个基于 FastMCP 的参考实现，负责对接 TheBrain 云端 API，向 LLM 客户端暴露资源、工具和提示模板等能力，并通过 JSON-RPC 的 MCP 交互模式进行通信。
    • 核心能力包括：资源与知识图谱相关数据的读取/写入、工具的注册与执行、以及基于 BrainQuery 的查询模板（MCP 风格的查询语言）解析与执行。服务器还集成了 Lightning 微支付机制对工具调用进行计费，以及可选的 Secure Courier（DPYC）身份体系以实现按会话的权限控制与凭证管理。

  • 主要功能点（通俗描述）

    • MCP 服务端实现：接收客户端的 JSON-RPC 请求，解析并执行相应的资源、工具或提示相关操作，返回标准化的 JSON-RPC 响应。
    • 资源与数据访问：通过 TheBrain API 获取、查询以及修改知识图谱中的节点、链接、笔记等实体，以及执行复杂的检索和图遍历。
    • 工具注册与执行：以 Tool Catalog 的形式暴露多种可调用的外部能力，LLM 可以通过工具名调用外部功能。
    • Prompt 模板与交互模式：提供可自定义的提示模板，帮助 LLM 在对话中以一致的上下文进行交互。
    • 会话与能力声明：服务器端维护会话信息、身份授权以及能力声明，支持多种传输方式（如 Stdio、SSE、WebSocket 等）以适配不同客户端。
    • 账务与微支付：对付费工具进行 api_sats 计费，集成 BTCPay/ Authority 认证工作流，必要时可对未授权工具进行拒绝执行。
    • 本地化执行与扩展性：BrainQuery 与其执行计划器、Graph 遍历、创建/更新/删除等操作均在服务端实现，具备可测试性与可扩展性。

  • 安装与运行步骤

    • 环境准备
      • 确保系统安装了 Python 3.12（该库在代码中以 Python 为实现语言，且测试用例也依赖 Python 环境）。
    • 安装依赖
      • 通过包管理工具安装所需依赖（FastMCP、Tollbooth、http 库、OpenTS、Neon Vault 等组件，具体依赖在实际部署时按项目的 setup 配置执行）。
    • 启动服务器
      • 在部署环境中执行以下启动方式之一（客户端通过 MCP 与之连接）：
        • python -m thebrain_mcp.server
      • 服务启动后，服务器将监听 MCP 客户端的请求，并按 MCP 协议处理资源、工具和提示模板相关的操作。
    • 运行时配置（可选）
      • 服务器运行时可能需要以下环境变量与设置（示例说明，实际部署按仓库配置要求设置）：
        • TheBrain API 的访问密钥、默认脑 ID、云端 API 地址等；
        • BTCPay/微支付相关信息（host、store_id、api_key、tier 配置等）；
        • Neon Vault（Neon 数据库）地址用于资金与凭证持久化；
        • DPYC/Secure Courier 相关参数（Nostr operator NSEC、relays、on_credentials_received 回调等）；
        • 日志、并发、缓存等系统参数。
    • MCP 客户端配置（客户端无需运行代码，这里描述配置以帮助理解连接参数）
      • MCP 客户端在连接服务器时通常需要一个 JSON 配置，用于向服务器注册、识别能力、以及启动服务器进程的命令信息。一个合理的配置示例如下（以便客户端知道如何启动服务器进程，而非对客户端代码的实现要求）：
        • server_name: "thebrain-mcp"
        • command: "python"
        • args: ["-m", "thebrain_mcp.server"]
        • 说明：该配置描述了服务器进程的启动命令以及如何启动 MCP 服务端模块。实际客户端在连接时会通过 MCP 协议与服务器交换 JSON-RPC 请求与响应。并且，客户端本身通常不需要暴露服务器的环境变量，只需要知道启动命令与参数即可。
    • 基本使用方法
      • 客户端通过 MCP 协议向该服务器发送 JSON-RPC 请求，执行如下动作：读取资源、调用工具、获取 Prompt/模板等，并获取结构化的 JSON-RPC 响应。
      • 常见流程包括：解析 BrainQuery、执行引擎计划、返回结果或执行创建/更新等操作；以及在需要时进行授权、计费、以及告警/警告信息的附加（如低余额提示）。
      • 如遇到需要的配置信息（如 APi Key、默认脑 ID、Vault 配置等），请在服务器运行环境中正确设置环境变量或配置文件。

  • 使用场景与注意事项

    • 该 MCP 服务器是面向与 TheBrain 知识图谱结合的 AI 应用后端，适用于需要统一上下文信息、工具执行能力以及统一的提示模板渲染场景。
    • 在生产环境中应正确配置 Vault/Neon Vault、BTCPay、Secure Courier 以及权限/安全策略，确保对外暴露的 API、工具和数据访问符合安全要求。
    • 如需自定义工具、扩展脑查询能力或集成新的数据源，可在服务器的工具包中注册新的工具并对 BrainQuery 的 IR 与执行器进行扩展。

  • 额外信息

    • MCP 服务器是一个完整的服务端实现，代码中包含 BrainQuery 的解析、计划与执行、以及多种工具的实现与组合，具备实际运行能力与测试覆盖。

服务器信息

访问项目