🚦 Branch-Thinking MCP Tool

🚦 Branch-Thinking MCP 工具

最新动态（2025-04）：

• 高级可视化：聚类（k-means/degree）、中心性叠加、边捆绑，以及任务和优先级的 Agentic 叠加
• Agentic 缓存与预取：为嵌入、摘要和分析提供 LRU+TTL 缓存，并主动预热 Agent 缓存
• 增强的分析功能：支持实时、多分支和 focusNode；提供针对 Agent 优化的元数据
• 改进了面向 Agent 和用户的文档与入门指引

---

功能

• 🌳 分支管理： 创建、聚焦和浏览多条思路
• 🔗 交叉引用： 跨分支关联相关思路（带类型和评分）
• 💡 AI 洞察： 自动生成洞察和摘要
• 🧠 语义搜索： 使用嵌入查找相关思路
• 📊 高级可视化：
  • 节点聚类（k-means/degree）
  • 中心性叠加（接近中心性、介数中心性）
  • 边捆绑
  • 任务叠加（状态、优先级、下一步操作）
  • 所有节点/边均提供 Agentic 叠加和元数据
  • FocusNode 和多分支可视化
• ⚡ Agentic 缓存与预取：
  • 为嵌入、摘要和分析提供 LRU+TTL 缓存
  • 主动为 Agent 工作流预热缓存
• 🗂️ 持久化存储： 可查询、可扩展，永不丢失思路
• 🔄 实时与多分支： 实时可视化和分析多个分支与节点
• 🛠️ 生产级： 稳健的错误处理、性能优化，以及便于 Agent 和人类使用的 API

---

🛠️ 技术栈

• Node.js（18+）
• TypeScript（4.x）
• @dagrejs/graphlib：图结构、算法和分析
• ml-kmeans：用于可视化的聚类
• lru-cache：为嵌入、摘要和分析提供 LRU+TTL 缓存
• @xenova/transformers：嵌入和摘要流水线
• @modelcontextprotocol/sdk：MCP 协议和 Agent 集成
• chalk：命令行输出样式
• Mermaid：甘特图/路线图可视化
• pnpm：快速依赖管理

---

路线图（甘特图）

gantt
    title Branch-Thinking MCP Roadmap (2025)
    dateFormat  YYYY-MM-DD
    section Q2 2025
    Advanced Visualization/Analytics :done,      vis1, 2025-04-01,2025-04-20
    Agentic Cache & Prefetch         :done,      cache1, 2025-04-10,2025-04-22
    Enhanced Agentic Docs            :done,      doc1, 2025-04-15,2025-04-25
    Real-time Collaboration          :active,    collab1, 2025-04-20,2025-06-01
    Web Visualization Dashboard      :active,    webviz1, 2025-04-25,2025-06-15
    section Q3 2025
    Plugin System                    :planned,   plugin1, 2025-06-15,2025-07-15
    Mobile/Tablet UI                 :planned,   mobile1, 2025-07-01,2025-08-01
    AI Branch Merging                :planned,   merge1, 2025-07-15,2025-08-15
    Knowledge Base Sync              :planned,   sync1, 2025-08-01,2025-09-01

---

目录

• 为什么选择 Branch-Thinking？
• 简介
• 功能
• 快速开始
• 入门指南
• 真实场景使用示例
• 架构与流程
• 路线图（甘特图）
• 测试与质量
• 安全
• 无障碍与国际化
• 故障排除与常见问题
• 最佳实践
• 贡献
• 更新日志
• 参考资料与相关项目
• 致谢
• 许可证

---

为什么选择 Branch-Thinking？

• Agent 优先设计： 为人类和 AI 工作流而构建，每条命令都适用于 Agent。
• 真正的分支： 并行组织、交叉链接并推理想法、代码和任务。
• 原生支持 AI： 开箱即用的语义搜索、自动摘要和洞察生成。
• 持久且直观： 再也不会丢失想法——所有内容都可查询、可视化和扩展。

简介

Branch-Thinking MCP Tool 是一个先进的 Agent 平台，用于管理、可视化和推理分支式的想法、任务、代码和知识。它通过强大的分支式范式，帮助 AI Agent 和人类整理复杂项目、交叉链接想法并自动生成洞察。它支持语义搜索、可视化以及持久化的任务和代码管理，旨在服务新一代协作式和自主式工作流。

Branch-Thinking MCP Tool 是一个先进的 Agent 平台，用于管理、可视化和推理分支式的想法、任务、代码和知识。它通过强大的分支式范式，帮助 AI Agent 和人类整理复杂项目、交叉链接想法并自动生成洞察。它支持语义搜索、可视化以及持久化的任务和代码管理，旨在服务新一代协作式和自主式工作流。

---

架构与流程

flowchart TD
    User([User/Agent 🤖])
    CLI([CLI/API])
    BM[BranchManager 🧠]
    EmbCache[[Embedding/Summary Cache]]
    Storage[(Persistent Storage 💾)]
    Viz([Visualization/Analytics])
    Tasks([Task Extraction])
    Snippets([Code Snippet Storage])

    User-->|Commands/Queries|CLI
    CLI-->|Manage/Query|BM
    BM-->|Cache|EmbCache
    BM-->|Save/Load|Storage
    BM-->|Visualize|Viz
    BM-->|Tasks|Tasks
    BM-->|Snippets|Snippets
    BM-->|Results|CLI
    CLI-->|Output|User

---

快速开始

几秒钟即可启动并运行：

pnpm install  # Recommended for speed (or npm install)
pnpm build
node dist/index.js --help  # See available commands

---

入门指南

1. 克隆并安装

git clone https://github.com/your-org/branch-thinking-mcp.git
cd branch-thinking-mcp
pnpm install  # Or npm install
pnpm build   # Or npm run build

2. 配置（可选）

如需集成 Claude Desktop，请添加到 claude_desktop_config.json：

"branch-thinking": {
  "command": "node",
  "args": [
    "/your-custom-mcp-dir-here/branch-thinking/dist/index.js"
  ]
}

3. 运行

node dist/index.js

---

真实场景使用示例

1. 知识捕获与链接

# Batch capture meeting notes
add-thought dev "Discussed semantic search improvements" note
add-thought dev "Agreed to refactor API" decision
# Link related thoughts
link-thoughts t1 t2 supports "API refactor supports search improvements"

2. Agent 任务提取

# Extract and manage tasks from a research branch
extract-tasks research
list-tasks research open
update-task-status task-1 in_progress

3. 通过可视化获取洞察

# Generate and interpret a knowledge graph
visualize dev
# Review AI-generated summary
summarize-branch dev

---

🧑‍💻 实例：Agent 工作流

# 1. Create a new branch for your project or idea
create-branch "AI Research"

# 2. Add thoughts and observations
add-thought [branchId] "Explore semantic search for agent workflows" analysis
add-thought [branchId] "Test cross-linking and summarization" observation

# 3. Link related thoughts
link-thoughts [thoughtId1] [thoughtId2] supports "Thought 2 validates Thought 1"

# 4. See your knowledge graph
visualize [branchId]

# 5. Extract tasks and get AI review
extract-tasks [branchId]
review-branch [branchId]

将 [branchId] 和 [thoughtIdX] 替换为从 list 和 history 获取的实际 ID。

---

命令参考

分支管理

命令	描述
list	显示所有分支及其状态
focus [branchId]	切换到指定分支
history [branchId?]	显示想法历史记录
summarize-branch [branchId?]	生成分支的 AI 摘要
review-branch [branchId?]	对分支进行 AI 审查
visualize [branchId?]	可视化连接关系图

想法与洞察管理

命令	描述
insights [branchId?]	获取 AI 生成的洞察
crossrefs [branchId?]	显示交叉引用
hub-thoughts [branchId?]	列出枢纽想法
semantic-search [query]	查找相似的想法
link-thoughts [from] [to] [type] [reason?]	链接两个想法
add-snippet [content] [tags]	保存代码片段
snippet-search [query]	搜索代码片段
doc-thought [thoughtId]	记录想法文档

任务管理

命令	描述
extract-tasks [branchId?]	提取可执行事项
list-tasks [branchId] [status] [assignee] [due]	列出/筛选任务
update-task-status [taskId] [status]	更新任务状态
summarize-tasks [branchId]	汇总任务

AI 与知识

命令	描述
ask [question]	从知识库获取 AI 答案

最佳实践

• 始终从 create-branch 开始，以确保上下文干净。
• 使用 list 和 focus 在项目或思路之间导航。
• 添加若干想法后，使用 summarize-branch 和 insights 获取 AI 生成的上下文。
• 使用 link-thoughts 显式关联想法、任务或代码，以构建更丰富的语义图谱。
• 更改代码后，始终运行 pnpm lint 和 pnpm build，尽早发现错误。
• 将复杂目标拆解为一系列思路／任务／洞察命令。
• 迭代并调整：利用摘要、评审和可视化提供的反馈来改进后续操作。
• 显式指定参数（branchId、status、assignee 等），以获得精确结果。
• 使用交叉引用和多跳链接，激发创造力并连接不同想法。
• 提示 Agent（Claude、GPT-4 等）“逐步思考”或“使用思维链”，以获得最佳结果。

安全

• 所有持久化数据都存储在本地（默认位置：项目目录或 MCP_STORAGE_PATH）
• 除非经过配置，否则不会调用外部 API
• Agent／用户需自行负责存储的想法和任务的隐私
• 如需报告安全问题，请提交 issue 或给维护者发送电子邮件。

故障排除与常见问题

问：工具没有响应！ 答：检查 MCP 服务日志，并确认配置正确。

问：如何重置存储？ 答：删除或移动持久化存储目录（参见配置）。

问：如何添加新命令？ 答：在 src/index.ts 中扩展 handleCommand，并在 README 中记录。

无障碍与国际化

• 所有徽章／图片都有描述性替代文本。
• 英语为默认语言；欢迎提交翻译。
• 如果你想帮助本地化此工具，请提交 PR 或 issue。

贡献

欢迎贡献、反馈问题和提出功能请求！请在 GitHub 上提交 PR 或 issue。

1. Fork 此仓库
2. 创建新分支（git checkout -b feature/your-feature）
3. 提交更改
4. 推送到该分支
5. 发起 Pull Request

参考资料与相关项目

• Model Context Protocol（MCP）
• Sequential Thinking Tool
• Obsidian
• Logseq

---

致谢

• 概念与测试： @ssdeanx
• 核心代码生成： Claude、GPT-4 和 Cascade
• 实现、修复与文档： @ssdeanx

---

许可证

MIT