TheBrain MCP & API Server

将 TheBrain 知识图谱接口封装为 MCP (Model Context Protocol) 服务器和 RESTful API，支持 AI 助手集成和自定义开发。

特性

• 🧠 MCP 协议支持 - 可集成到 Claude Desktop、Cursor 等 AI 工具
• 🌐 RESTful API - 22 个完整的 HTTP 接口
• 🔍 增强搜索 - 丰富的返回字段，支持原始结果查询
• 📌 置顶管理 - 想法置顶/取消置顶
• 🔗 链接操作 - 查看和更新想法间的链接关系
• 📊 统计信息 - 获取大脑统计数据和修改日志
• 🐳 Docker 支持 - 一键部署

快速开始

使用 Docker (推荐)

# 1. 设置环境变量
cp .env.example .env
# 编辑 .env 填入：
# - THEBRAIN_API_KEY
# - THEBRAIN_BRAIN_ID

# 2. 启动服务
docker-compose up -d

# 3. 访问
# API 文档: http://localhost:8000/docs
# MCP 端点: http://localhost:8000/mcp/mcp

本地开发

# 1. 创建环境
conda create -n thebrain-mcp python=3.10 -y
conda activate thebrain-mcp

# 2. 安装依赖
pip install -r requirements.txt

# 3. 配置环境变量
cp .env.example .env
# 编辑 .env

# 4. 启动服务
python api_server.py

API 接口

🔐 认证说明

所有 /api/* 接口都需要 Bearer Token 认证，使用您的 THEBRAIN_API_KEY 作为 token：

curl -H "Authorization: Bearer YOUR_THEBRAIN_API_KEY" \
  http://localhost:8000/api/pins

📋 完整接口列表

搜索相关

接口	方法	说明	主要参数
/api/search	POST	搜索想法（增强字段）	query, max_results
/api/search/raw	POST	原始搜索结果（含匹配上下文）	query, max_results, only_names
/api/search/by-type	POST	按类型/标签过滤搜索 🆕	query, type_id, tag_id, max_results
/api/search/related	POST	多关键词相关性搜索 🆕	keywords (List), max_results

想法操作

接口	方法	说明	主要参数
/api/thoughts/{id}	GET	获取想法详情	id (路径参数)
/api/thoughts/by-name	GET	按名称精确查找想法	name (查询参数)
/api/thoughts/{id}/graph	GET	获取想法关联图谱	id, siblings (可选)
/api/thoughts/{id}/children	GET	获取子想法列表	id
/api/thoughts/{id}/parents	GET	获取父想法列表	id
/api/thoughts/{id}/jumps	GET	获取跳转链接	id
/api/thoughts	POST	创建新想法	name, parent_id/jump_id, kind
/api/thoughts/{id}	PATCH	更新想法属性	id, name/label/color/type_id
/api/thoughts/{id}	DELETE	删除想法	id
/api/thoughts/{id}/pin	POST	置顶想法	id
/api/thoughts/{id}/pin	DELETE	取消置顶	id
/api/thoughts/{id}/context	GET	获取完整上下文 🆕	id
/api/thoughts/{id}/neighbors	GET	多层级邻居探索 🆕	id, depth, include_notes
/api/thoughts/recent	GET	获取最近修改的想法 🆕	days, max_results

链接操作

接口	方法	说明	主要参数
/api/links	POST	创建链接	thought_id_a, thought_id_b, relation
/api/links/{id}	GET	获取链接详情	id
/api/links/between/{a}/{b}	GET	获取两想法间的链接	a, b (想法ID)
/api/links/{id}	PATCH	更新链接属性	id, color/thickness/name
/api/links/{id}	DELETE	删除链接	id

笔记操作

接口	方法	说明	主要参数
/api/thoughts/{id}/note	GET	获取笔记	id, format (markdown/html/text)
/api/thoughts/{id}/note	POST	更新/追加笔记	id, content, append, position
/api/thoughts/{id}/note/batch-replace	POST	批量替换笔记 🆕	id, replacements (List)

元数据

接口	方法	说明	主要参数
/api/types	GET	获取所有类型	无
/api/tags	GET	获取所有标签	无
/api/pins	GET	获取置顶想法列表	无

附件操作

接口	方法	说明	主要参数
/api/thoughts/{id}/attachments	GET	获取附件列表	id
/api/thoughts/{id}/attachments/url	POST	添加 URL 附件	id, url, name (可选)

大脑统计

接口	方法	说明	主要参数
/api/brain/stats	GET	获取大脑统计信息	无
/api/brain/modifications	GET	获取修改日志	max_logs, start_time, end_time

总计: 28 个 RESTful API 接口

查看完整文档和在线测试: http://localhost:8000/docs

MCP 集成

MCP 工具列表

工具名	说明	必需参数	可选参数
search_thoughts	搜索想法	query	n (默认30)
get_thought	获取想法详情	thought_id	-
get_graph	获取想法的关联图谱	thought_id	siblings (默认false)
create_thought	创建新想法	name	parent_id, jump_id, kind
update_thought	更新想法属性	thought_id	name, label, color, type_id
delete_thought	删除想法	thought_id	-
create_link	创建链接	thought_id_a, thought_id_b	relation (默认3=跳转), name
delete_link	删除链接	link_id	-
get_link_between	获取两想法间的链接详情 🆕	thought_id_a, thought_id_b	-
get_note	获取笔记	thought_id	format (默认markdown)
update_note	覆盖笔记 ⚠️	thought_id, content	-
append_note	追加笔记 ✅	thought_id, content	position (end/start, 默认end)
batch_replace_note	批量替换笔记 🆕	thought_id, replacements (JSON)	-
list_metadata	列出元数据	category (types/tags/pins)	-
import_structure	导入结构化数据	parent_id, data (JSON字符串)	-
search_by_type	按类型/标签过滤搜索	-	query, type_id, tag_id, max_results
explore_neighbors	多层级探索邻居节点	thought_id	depth (1-3,默认2), include_notes
get_context	获取完整上下文	thought_id	-
recent_thoughts	获取最近修改的想法	-	days (默认7), max_results (默认20)
find_related	按关键词查找相关想法	keywords (逗号分隔)	max_results (默认10)

🌟 高级工具使用指南

以下工具专为知识发现和智能分析设计,推荐 AI 优先使用:

1. get_graph - 查看知识关系网络 ⭐

适用场景: 了解一个想法的完整关联关系

返回内容:

• ✅ 自动包含 typeName - 想法会显示类型名称(如"项目"、"任务")
• 想法的所有关联: parents(父节点)、children(子节点)、jumps(跳转链接)、siblings(兄弟节点)
• links 数组: 包含链接的基本信息(简化版)
  • relation - 关系类型(1=Child, 2=Parent, 3=Jump, 4=Sibling) ⭐
  • meaning - 链接语义(1=Normal, 2=InstanceOf, 5=HasTag 等) ⭐
  • thickness - 链接粗细(-1=默认, 1-5=用户设置) ⭐
  • typeId - 链接类型ID(⚠️ 无法获取类型名称)
  • ❌ 不包含: name(标签)、color(颜色)
• attachments(附件列表)

最佳实践:

用户: "帮我分析一下 '项目A' 的知识结构"
AI: 使用 get_graph 获取完整图谱
    - 查看 activeThought.typeName 了解想法类型(如"项目")
    - 查看 links[].relation 了解关系方向(1=子,2=父,3=跳转,4=兄弟)
    - 查看 links[].meaning 了解语义(1=普通,5=标签等)
    - 查看 links[].thickness 识别重要链接(数值越大越重要)
    - 如需查看链接的 name 和 color,使用 get_link_between

2. get_link_between - 查看两节点间的链接详情 🆕

适用场景: 需要查看链接的完整信息(name、color等)时使用

核心参数:

• detailed: 是否返回详细信息,默认 False(简化版,更快速)

返回内容:

• 简化版(默认): relation, meaning, thickness, name, color, typeId
• 详细版(detailed=True): 所有字段(包括 direction、创建时间等)

最佳实践:

用户: "这两个想法之间是什么关系?"
AI: 使用 get_link_between(thought_id_a, thought_id_b)  # 默认简化版,快速
    - 查看 name 了解用户定义的关系标签
    - 查看 color 了解可视化标记
    - 查看 thickness 了解重要程度
    
用户: "给我这个链接的所有详细信息"
AI: 使用 get_link_between(thought_id_a, thought_id_b, detailed=True)
    - 返回包含创建时间、修改时间、direction 等所有字段

3. get_context - 一站式获取完整信息 🎯

适用场景: 需要全面了解一个想法时使用,比 get_graph 更高层

返回内容:

• 想法详情(包含 typeName)
• 完整笔记内容(markdown 格式)
• 所有关联节点分类汇总(每个节点都包含 typeName)
• 统计信息(关联数量)

最佳实践:

用户: "总结一下这个想法的所有内容"
AI: 用 get_context 一次获取所有信息,无需多次调用

4. explore_neighbors - 多层知识探索 🔍

适用场景: 发现深层次的知识关联,适合"扩散式"思维导图

核心参数:

• depth: 探索深度 1-3 层(默认 2 层)
• include_notes: 是否显示第一层的笔记预览

返回内容:

• 递归的层级结构
• 每层节点都包含 typeName
• 可选的笔记摘要

最佳实践:

用户: "帮我找找这个想法相关的所有概念"
AI: 使用 explore_neighbors(depth=3) 深入探索,发现间接关联

5. recent_thoughts - 发现最新变化 ⏰

适用场景: 了解用户最近在思考什么

核心参数:

• days: 最近几天(默认 7 天)
• max_results: 返回数量(默认 20)

最佳实践:

用户: "最近我都在研究什么?"
AI: 用 recent_thoughts(days=7) 快速找到最近活跃的想法

6. find_related - 多关键词智能匹配 🧠

适用场景: 根据多个关键词找相关内容,自动按匹配度排序

特点:

• 匹配多个关键词的想法会排在前面
• 返回匹配分数和匹配的关键词列表

最佳实践:

用户: "找一下关于 'Python' 和 'API' 的内容"
AI: 用 find_related(keywords="Python,API") 找到同时相关的想法

7. search_by_type - 按类型精准过滤 🎨

适用场景: 只想查看某种类型的想法

核心参数:

• type_id: 类型 ID(可选)
• tag_id: 标签 ID(可选)
• query: 搜索关键词(可选)

最佳实践:

用户: "列出所有项目类型的想法"
AI: 先用 list_metadata(category="types") 找到 "项目" 的 type_id
    再用 search_by_type(type_id=xxx) 精准过滤

8. batch_replace_note - 批量更新笔记 ✏️

适用场景: 需要在笔记中批量替换文本

参数格式:

replacements: '[["旧文本1","新文本1"],["旧文本2","新文本2"]]'

最佳实践:

用户: "把所有笔记中的 'TODO' 改成 'DONE'"
AI: 用 batch_replace_note 一次完成,返回替换统计

💡 组合使用技巧

场景1: 深入分析某个主题

1. search_thoughts 找到目标想法
2. get_context 获取完整信息
3. explore_neighbors 发现相关概念

场景2: 发现知识关联

1. find_related 根据多关键词找相关内容
2. get_graph 查看每个想法的 links(包含 typeName)
3. 分析 link 的 relation 和 typeName 理解关系类型

场景3: 类型化知识管理

1. list_metadata(category="types") 查看所有类型
2. search_by_type 按类型筛选
3. get_graph 查看想法时,links 和 thoughts 都会显示 typeName

MCP 认证

⚠️ 新增: MCP 服务器现在也支持 Bearer Token 认证，使用与 RESTful API 相同的 THEBRAIN_API_KEY。

Claude Desktop

编辑 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "thebrain": {
      "url": "http://localhost:8000/mcp/mcp",
      "headers": {
        "Authorization": "Bearer YOUR_THEBRAIN_API_KEY"
      }
    }
  }
}

n8n 集成

在 n8n 中添加 MCP Client 节点，配置如下：

• Connection Type: Streamable HTTP
• URL: http://localhost:8000/mcp/mcp
• Authentication: 在 Headers 中添加 Authorization: Bearer YOUR_THEBRAIN_API_KEY

注意: 确保所有工具参数都有明确的类型定义。如果遇到 Cannot read properties of undefined (reading 'inputType') 错误，请检查 MCP 服务器版本是否最新。

传输协议: 使用 HTTP Streamable 协议（推荐），支持高效双向通信

技术栈

• FastMCP - MCP 协议实现 (锁定 <3 版本)
• FastAPI - RESTful API 框架
• Requests - TheBrain API 客户端

项目结构

.
├── scripts/
│   ├── client.py          # TheBrain API 客户端
│   └── thebrain.py        # CLI 工具
├── mcp_server.py          # MCP 服务器
├── api_server.py          # FastAPI 服务器
├── Dockerfile             # Docker 镜像
├── docker-compose.yml     # Docker Compose 配置
└── requirements.txt       # Python 依赖

环境变量

THEBRAIN_API_KEY=your-api-key-here  # 用于访问 TheBrain API 和保护本服务的 RESTful API
THEBRAIN_BRAIN_ID=your-brain-id-here

⚠️ 注意: THEBRAIN_API_KEY 同时用于：

1. 访问 TheBrain 官方 API
2. 保护本服务的 RESTful API（作为 Bearer Token）

许可证

MIT License

贡献

欢迎提交 Issue 和 Pull Request！