星战科技xingzhan.cloud
返回市场
智慧脑-MCP

智慧脑-MCP

作者：redmorestudio3 星标更新：2025-07-22
安装使用来源：spider==github.com

项目介绍

TheBrain MCP 服务器

一个MCP（模型上下文协议）服务器，使AI助手能够与TheBrain的知识管理系统进行交互。该服务器提供了对TheBrain API的全面访问，专注于通过自然语言与TheBrain强大的知识管理功能进行交互。

🔧 什么是MCP服务器？

MCP（模型上下文协议） 是一种标准，允许像Claude这样的AI助手连接到外部工具和服务。可以将其视为自然语言和软件API之间的翻译器。

工作原理：

您 → Claude → MCP服务器 → TheBrain API → 您的大脑
  1. 您说："创建一个包含三个阶段的项目"
  2. Claude理解了您的意图
  3. MCP服务器翻译这成为特定的TheBrain API调用
  4. TheBrain API 创建了想法和关联
  5. 您的大脑 更新了新的结构

神奇之处在于您不需要了解任何技术细节——只需用简单的英语描述您想要什么！

🚀 实际工作的功能

✅ 核心功能（工作正常）

  • 内容管理：创建、更新、删除想法和笔记
  • 文件附件：上传图像、PDF文档到想法中
  • 网络引用：URL附件并自动提取标题
  • 丰富笔记：支持完整的Markdown格式，并嵌入内容
  • 关系映射：用有意义的关系连接想法
  • 搜索：全文搜索想法、笔记和附件
  • 大脑管理：无缝切换多个大脑
  • 自然语言接口：描述您想要的内容，Claude处理细节

❌ 当前问题及限制

🚨 主要视觉样式问题

最大的限制：尽管API成功响应，但视觉属性实际上并未应用。

  • ❌ 想法颜色：API接受颜色，但在TheBrain中不显示
  • ❌ 链接颜色：类似问题——被接受但未应用
  • ❌ 链接粗细：API报告成功但粗细不变
  • ❌ 视觉格式化：所有视觉样式功能目前无法使用

🐛 其他已知问题

  • 间歇性连接问题：成功操作后出现“字段必需”错误
  • 长笔记限制：非常长的Markdown内容存在问题（保持在10k字符以下）
  • 文件路径敏感性：需要绝对文件路径；相对路径可能失败
  • 连接时机：MCP初始化竞态条件导致偶发故障
  • 内存约束：大型文件附件可能导致超时
  • 搜索限制：复杂查询有时返回不完整结果

📋 API依赖及约束

  • 单用户操作：没有实时协作功能
  • 无批量操作：不能高效地导入/导出大数据集
  • API连接要求：没有离线模式可用
  • TheBrain API限制：受限于现有API能力
  • 认证要求：必须拥有有效的TheBrain API密钥

🛠 当前解决方法

直到视觉样式修复之前，请使用这些替代方案：

  • 表情符号区分：🟢🟡🔴⚪🔵代替颜色
  • 描述性名称：“🔴紧急任务”代替彩色想法
  • 丰富的Markdown笔记：在笔记中使用格式化以实现视觉组织
  • 层级结构：依靠父子关系进行组织

安装

  1. 克隆此仓库：
git clone https://github.com/redmorestudio/thebrain-mcp.git
cd thebrain-mcp
  1. 安装依赖项：
npm install
  1. 创建一个.env文件并添加您的API密钥：
THEBRAIN_API_KEY=your_api_key_here
THEBRAIN_DEFAULT_BRAIN_ID=optional_default_brain_id

配置

对于Claude桌面版

在您的Claude桌面配置中添加：

{
  "mcpServers": {
    "thebrain": {
      "command": "node",
      "args": ["/绝对路径/to/thebrain-mcp/index.js"],
      "env": {
        "THEBRAIN_API_KEY": "your_api_key_here"
      }
    }
  }
}

⚠️ 重要提示：配置和文件附件中使用绝对文件路径。

调试与故障排除

常见问题及解决方案

“字段必需”错误：

  • 重启Claude桌面
  • 验证.env文件中的API密钥是否正确
  • 总是先设置活动大脑：“将我的活动大脑设置为[name]”

文件上传失败：

  • 使用绝对文件路径：/Users/username/Documents/file.pdf
  • 检查文件权限和存在性
  • 保持文件大小合理（< 50MB）

长笔记问题：

  • 将笔记保持在10,000个字符以内
  • 将大量内容拆分为多个想法
  • 使用附件处理长文档

调试模式：

VERBOSE=true node index.js

可用工具（25+功能）

大脑管理

  • list_brains - 列出所有可用的大脑
  • get_brain - 获取大脑详情
  • set_active_brain - 设置用于操作的活动大脑
  • get_brain_stats - 获取综合大脑统计信息

想法操作

  • create_thought - 创建想法（视觉属性不起作用）
  • get_thought - 获取想法详情
  • update_thought - 更新想法属性
  • delete_thought - 删除想法
  • search_thoughts - 在大脑中搜索
  • get_thought_graph - 获取带有所有连接的想法
  • get_types - 列出所有想法类型
  • get_tags - 列出所有标签

链接操作

  • create_link - 在想法之间创建链接（样式不起作用）
  • update_link - 修改链接属性
  • get_link - 获取链接详情
  • delete_link - 删除链接

附件操作

  • add_file_attachment - 将文件/图像附加到想法中 ✅
  • add_url_attachment - 附加网络URL ✅
  • get_attachment - 获取附件元数据
  • get_attachment_content - 下载附件内容
  • delete_attachment - 删除附件
  • list_attachments - 列出想法附件

笔记操作

  • get_note - 以markdown/html/text形式检索笔记 ✅
  • create_or_update_note - 创建或更新笔记 ✅
  • append_to_note - 追加内容到现有笔记 ✅

高级功能

  • get_modifications - 查看大脑修改历史

使用示例（实际工作的功能）

项目组织

您："创建一个名为'厨房翻新'的项目"
Claude：创建中央项目想法

您："添加规划、拆除和安装阶段"
Claude：为每个阶段创建连接的子想法

您："将我的承包商报价附加到规划阶段"
Claude：将文件上传到规划想法

您："在项目中添加关于时间表的详细说明"
Claude：创建包含您时间表的丰富Markdown笔记

研究与知识管理

您："创建一个关于可持续能源的研究主题"
Claude：设置主要研究想法

您："添加太阳能、风能和水力发电的子主题"
Claude：创建组织良好的想法层次结构

您："附加相关论文和网络文章"
Claude：添加文件和URL附件

您："搜索所有与效率相关的内容"
Claude：找到所有相关的想法和内容

🔮 发展路线图及未来开发

立即优先事项（v1.2.0）

  • 🚨 修复视觉样式：调查为什么颜色/粗细不适用
  • 🔧 连接稳定性：解决MCP定时/竞态条件问题
  • 📝 长笔记支持：更好地处理大量的Markdown内容
  • 🛡️ 错误处理：更优雅的失败和恢复

未来增强

  • 批量操作：大规模组织
  • 增强模板：常见工作流程
  • 性能优化：复杂大脑
  • 离线能力和缓存

技术架构

什么让这个服务器特别

  • 自然语言接口：无需技术知识
  • 完整的API覆盖：涵盖所有TheBrain操作的25+工具
  • 强大的错误处理：优雅的失败和清晰的错误消息
  • 模块化设计：干净、易于维护的代码架构
  • 生产就绪：适当的日志记录、测试和文档

当前状态

  • 版本：1.1.0（2025年6月）
  • 核心功能：✅ 完整且工作正常
  • 视觉属性：❌ 存在重大问题需调查
  • 稳定性：🟡 一般稳定，但有间歇性连接问题

贡献

欢迎贡献！特别需要帮助的地方：

  • 视觉样式调查：为什么颜色/粗细不适用？
  • 连接稳定性：调试MCP竞态条件
  • 性能优化：大型大脑处理
  • 文档：更多的使用示例和教程

请随时提交问题或拉取请求。

许可

MIT许可 - 详情见LICENSE文件。

支持

⚠️ 当前建议：使用此服务器进行内容管理和组织，并通过自然语言交互。不要依赖视觉样式功能，直到它们被修复。核心功能坚实且非常有用，可以通过对话管理TheBrain内容！