Branch Context Manager MCP

Branch Context Manager MCP 是一个轻量、本地优先的 MCP Server，用来给 Claude Code、Claude Desktop、Cursor 等 MCP 客户端提供“主线/分支”式的结构化笔记和决策记录。

当前版本是 GitBranchMCP v1.0。它保留 LiteBranchMCP / Free Mode，并新增完整的 Git Mode / API Mode 工作流。

如果你是从 GitHub 下载后第一次安装使用，请先看：

• GitBranchMCP GitHub 用户快速说明书

默认情况下，LiteBranchMCP 不调用 Claude API、OpenAI API 或任何其他模型 API，不需要额外 API Key。它只做本地分支笔记、摘要管理和 Markdown 导出，不保证宿主模型在同一个聊天窗口里的物理上下文隔离。 这个项目当前包含两种模式： Free Mode 是一个本地优先的 AI 编程支线笔记和主线决策日志 MCP。它不接管宿主客户端的模型上下文，因此不能提供物理级上下文隔离。 Git Mode / API Mode 是 GitBranchMCP 的增强模式。它通过 message DAG、branch HEAD、fork point 和 branch_chat 控制每次发送给模型的上下文链，可以在 MCP 自己调用模型的范围内实现真正的 Git 式分支隔离。 需要注意的是：Git Mode 的隔离只适用于通过 branch_chat 进入的对话；如果用户仍然在 Claude Code / Claude Desktop 同一个聊天窗口中直接讨论分支内容，宿主模型仍然会看到这些内容。 未来的 Standalone App 会在此基础上提供 Web/App 形态，用更完整的界面管理 branch graph、diff、merge 和导出。

一句话说明

这是一个 AI 长对话支线笔记与主线决策日志 MCP。

它可以帮你把支线探索的结论和主线决策记录分开管理，但它不能让 Claude 在同一个聊天窗口里真正忘记已经看到过的支线内容。

当前状态

当前版本可以作为一个可用的本地 MCP 原型收工。

已实现：

• 本地 SQLite 存储

• 主线和普通分支

• 当前活跃分支切换

• 新 MCP 进程启动时默认回到主线

• start_new_session 手动重置当前活跃分支到主线

• 分支笔记保存和查询

• 分支摘要显式合并到主线

• 主线摘要历史查询

• 分支重命名和删除

• 分支 Markdown 导出

• 主线决策 Markdown 导出

• 固定 demo 数据生成和导出

• 推荐工作流提示词

• Git-like message DAG 基础结构

• 从当前 HEAD fork conversation branch

• branch log / diff / context preview

• 可选模型 API 配置层（支持 anthropic 和通用 OpenAI-compatible client）

• branch_chat 分支隔离模型对话

• branch diff summary

• summary merge

• merge history

• 增强 Markdown 导出

未实现：

• 宿主客户端同一聊天窗口里的物理上下文隔离

• 独立 Claude 会话分叉

• 自动分支检测

• Web UI

• 多用户权限管理

重要边界

本项目做的是 结构化记录隔离，不是 模型上下文物理隔离。

如果你在同一个 Claude Code / Claude Desktop 会话里讨论主线和分支，模型仍然会看到同一聊天窗口里的全部上下文。即使 MCP 数据库没有把分支笔记合并到主线，模型回答时仍可能受到聊天历史中支线内容的影响。

Free Mode 能保证：

• 分支笔记不会自动进入主线决策记录

• 分支摘要必须显式调用工具后才会合并到主线

• Markdown 导出只导出已保存的结构化记录

• MCP Server 不保存完整聊天记录

Free Mode 不能保证：

• 切换分支后 Claude 忘记刚才的内容

• 主线会话不受同一聊天窗口里的支线讨论影响

• 像 Git 分支一样拥有独立上下文历史

如果你需要更干净的隔离，推荐做法是：

1. 主线任务使用一个 Claude 会话。

2. 支线研究新开 Claude 会话。

3. 支线结束后只把摘要合并回主线。

4. 主线会话不要塞入完整支线过程。

适合场景

适合：

• 长时间 AI 编程任务

• 架构设计和技术选型

• 重构过程中的多个方案比较

• 复杂 bug 调试过程记录

• 把支线探索结论沉淀成主线决策

• 项目交接前导出 Markdown 决策记录

不太适合：

• 一两轮就结束的小问题

• 只想让 Claude 改一个小 bug

• 不需要记录决策过程的临时聊天

• 需要真正上下文隔离的研究场景

MCP 工具

分支管理

• create_branch：创建普通分支

• switch_branch：切换当前活跃分支

• start_new_session：把当前活跃分支重置回主线，不删除任何数据

• get_current_branch：查看当前分支

• list_branches：列出所有分支

• rename_branch：重命名普通分支

• delete_branch：删除普通分支

• create_branch_from_head：从当前分支 HEAD fork 出 Git-like conversation branch

• append_message_node：手动追加 message node

• get_branch_log：查看分支从 root 到 HEAD 的 message log

• get_branch_diff：查看 fork 点之后新增的 message nodes

• get_branch_context_preview：查看分支上下文预览

笔记和摘要

• save_note：保存当前分支或指定分支的结论性笔记

• get_branch_notes：查看某个分支的笔记

• merge_summary_to_main：把宿主模型生成的摘要合并到主线

• list_main_summaries：查看主线合并历史

导出

• export_branch_markdown：导出某个分支的 Markdown

• export_main_markdown：导出主线决策记录 Markdown

• export_demo_markdown：导出演示数据 Markdown

默认导出目录：

./exports/

导出工具会在真正写文件时自动创建 exports 目录。为了避免 Claude Desktop 自己生成文件卡片而不是调用 MCP 导出，工具说明和推荐工作流已经明确要求：导出时应调用 MCP 工具，并把工具返回的本地路径原样展示给用户。

工作流辅助

• get_context_overview：查看当前上下文总览

• get_workflow_prompt：获取推荐项目规则提示词

• suggest_branch_workflow：根据当前活跃分支给出固定建议

可选模型 API 配置

• set_model_provider：设置可选模型 provider 和 model

• set_model_api_key：保存可选模型 API Key

• get_model_status：查看模型配置状态，API Key 只会脱敏显示

• test_model_connection：显式测试当前模型配置

• route_user_message：根据当前 active branch 自动路由普通用户消息；主线提示宿主模型回答，普通分支自动调用 branch_chat

• branch_chat：在当前 active branch 或指定分支中进行隔离模型对话

• summarize_branch_diff：对来源分支 fork 后的 diff 生成结构化摘要，不自动合并

• merge_branch_summary：将来源分支以 summary merge 方式合并到目标分支，默认合并到 main

• get_merge_history：查看所有 summary merge 记录

当前支持：

• anthropic：Anthropic Messages API client

• openai-compatible：通用 OpenAI 兼容接口 client，可接通义千问/百炼、DeepSeek、Moonshot、OpenAI 兼容网关等

预留但尚未实现：

• gemini

安全和费用说明：

• Lite Mode / Free Mode 不需要 API Key。

• 普通分支、笔记、摘要、导出、message DAG 功能不会默认调用模型 API。

• route_user_message 会先检查当前 active branch；在主线不会调用模型 API，在普通分支会自动进入 branch_chat。

• branch_chat 只会把目标分支的 build_context 发给模型，不会把其他分支 fork 后的消息混入当前分支。

• branch_chat 只更新目标分支的 head_node_id，不会自动合并分支，也不会把分支消息写入主线。

• API Key 保存在本地 SQLite settings 表中。

• 也可以把 API Key 放在项目根目录 .env 文件中；.env 已被 .gitignore 忽略，不应提交到 GitHub。

• 工具返回和状态查询只显示脱敏 Key，例如 sk-ant-****abcd，不会回显完整 API Key。

• API Mode 会产生额外模型费用，费用由 Anthropic、OpenAI、Google 等模型服务商按你的账号计费。

.env 示例：

GITBRANCHMCP_MODEL_PROVIDER=openai-compatible
GITBRANCHMCP_MODEL_NAME=qwen-plus
GITBRANCHMCP_MODEL_BASE_URL=https://dashscope.aliyuncs.com/compatible-mode/v1
GITBRANCHMCP_API_KEY=your-api-key-here

发布版用户可以直接复制 .env.example 为 .env，然后只替换模型名、base_url 和真实 API Key。

通义千问/阿里云百炼可以直接用上面这组配置。其他 OpenAI 兼容模型通常只需要换：

GITBRANCHMCP_MODEL_NAME=你的模型名
GITBRANCHMCP_MODEL_BASE_URL=服务商的兼容接口地址，不含 /chat/completions
GITBRANCHMCP_API_KEY=你的 key

配置优先级：

系统环境变量 > .env > SQLite settings

真实 API Mode 本地验证：

branch_chat(message="A")
branch_chat(message="B")
create_branch_from_head(name="jwt", title="JWT 分支")
branch_chat(message="D")
switch_branch(branch_id=1)
branch_chat(message="C")

验证要点：

• 主线 context 包含 A/B/C，不包含 D。

• JWT 分支 context 包含 fork 前的 A/B，以及 fork 后自己的 D。

• 切换分支不会改变其他分支的 HEAD。

• 这些命令会真实调用已配置的模型 API，并可能产生服务商费用。

CLI 验证 branch_chat：

$env:PYTHONPATH="src"
$env:PYTHONIOENCODING="utf-8"
branch-context chat "hello from current branch"
branch-context chat "hello from branch 2" --branch-id 2

Git-like summary merge 工作流：

branch -> chat -> diff -> summarize -> merge summary -> export

对应工具：

create_branch_from_head
branch_chat
get_branch_diff
summarize_branch_diff
merge_branch_summary
get_merge_history
export_main_markdown

merge_branch_summary 默认只做 summary merge：它会在目标分支当前 HEAD 后追加一个 node_type="merge_summary" 的 summary node，更新目标分支 HEAD，并写入 merges 和旧版 summaries 表。它不会把来源分支 fork 后的完整 D/E/... 消息复制到主线。

Demo

• create_demo_data：创建固定 FastAPI 登录系统演示数据

• reset_demo_data：重置演示数据

• export_demo_markdown：导出演示 Markdown

安装和本地运行

建议使用 Python 3.11 或更高版本。

cd D:\path\to\GitBranchMCP
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e ".[dev]"

如果 PowerShell 禁止运行 Activate.ps1，不用激活虚拟环境，直接调用 .venv 里的 Python 即可。

手动启动：

.\.venv\Scripts\python.exe -m branch_context_manager.server

或者安装后使用脚本入口：

.\.venv\Scripts\branch-context-manager-mcp.exe

默认数据库路径：

./data/branch-context.db

可以通过环境变量指定数据库位置：

$env:BRANCH_CONTEXT_DB_PATH="D:\path\to\GitBranchMCP\data\branch-context.db"
.\.venv\Scripts\python.exe -m branch_context_manager.server

Claude Desktop 配置

Windows 下 Claude Desktop 配置文件通常在：

%APPDATA%\Claude\claude_desktop_config.json

Microsoft Store 版本可能在类似路径：

C:\Users\<用户名>\AppData\Local\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json

配置示例：

{
  "mcpServers": {
    "branch-context-manager": {
      "command": "D:\\path\\to\\GitBranchMCP\\.venv\\Scripts\\python.exe",
      "args": [
        "-m",
        "branch_context_manager.server"
      ],
      "cwd": "D:\\path\\to\\GitBranchMCP",
      "env": {
        "PYTHONPATH": "D:\\path\\to\\GitBranchMCP\\src",
        "BRANCH_CONTEXT_DB_PATH": "D:\\path\\to\\GitBranchMCP\\data\\branch-context.db"
      }
    }
  }
}

修改配置后需要完全重启 Claude Desktop。

Claude Code / Cursor 使用建议

首次使用建议让客户端调用：

get_workflow_prompt

然后把返回内容放进 Claude Code 项目规则、Cursor Rules 或类似的长期说明里。

常见自然语言操作：

开始一个新的 Branch Context Manager 会话。
开一个分支研究 JWT 鉴权。
保存当前结论到这个分支。
查看当前上下文总览。
把这个分支的摘要合并到主线。
导出主线决策记录。

关于“新聊天”的状态：

• MCP server 每次重新启动时会把当前活跃分支重置为主线。

• Claude Desktop 不一定每开一个新聊天就重启 MCP 进程。

• 如果新聊天里发现仍停在上一次的分支，可以调用 start_new_session 回到主线；这个操作不会删除分支、笔记或摘要。

导出时可以直接说：

导出快排分支。

如果宿主客户端生成了自己的文件卡片而不是本地文件，可以更明确地说：

请调用 branch-context-manager 的 export_branch_markdown，并把工具返回的本地路径原样发给我。

合并逻辑

merge_summary_to_main 不会自动总结。

正确流程是：

1. 调用 get_branch_notes 读取分支笔记。

2. 由 Claude Code / Claude Desktop / Cursor 自己生成摘要。

3. 调用 merge_summary_to_main 把摘要保存为主线决策记录。

4. 合并完成后，当前活跃分支会自动切回主线。

也就是说，MCP 保存的是“宿主模型已经写好的摘要”，不是自己调用模型生成摘要。

Demo 流程

固定演示场景：

主线：开发 FastAPI 登录系统
分支 1：JWT 算法选择
分支 2：Refresh Token 设计
分支 3：密码哈希方案
最终主线结论：认证系统采用 RS256 + refresh token 数据库存储 + bcrypt。

快速生成 demo：

create_demo_data

查看上下文：

get_context_overview

查看主线摘要：

list_main_summaries

导出演示 Markdown：

export_demo_markdown

完整演示脚本见 docs/demo-script.md。

数据存储

数据保存在本地 SQLite。

当前保存：

• 分支

• 分支笔记

• 主线摘要合并记录

• message_nodes

• 分支 fork/head 指针

• summary merge history

• 本地设置

• 可选模型 provider、model、API Key

当前不保存：

• 模型推理过程

• Claude 会话历史

• 用户文件内容

开发和测试

安装开发依赖后运行：

.\.venv\Scripts\python.exe -m pytest

当前测试覆盖核心分支、笔记、摘要、导出和 demo 流程。

文档

• Free Mode 说明

• Git Mode 说明

• 演示脚本

• 用户指南

• 路线图

• 设计文档

• 说明书

结论

这个项目当前最诚实的定位是：

一个本地优先的 AI 编程支线笔记和主线决策日志 MCP。

它对长对话、复杂任务和需要沉淀决策的 AI 编程流程有价值；但它不是 Claude 上下文分叉系统，也不能提供真正的模型记忆隔离。