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 分支一样拥有独立上下文历史

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

主线任务使用一个 Claude 会话。
支线研究新开 Claude 会话。
支线结束后只把摘要合并回主线。
主线会话不要塞入完整支线过程。

适合场景

适合：

长时间 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 不会自动总结。

正确流程是：

调用 get_branch_notes 读取分支笔记。
由 Claude Code / Claude Desktop / Cursor 自己生成摘要。
调用 merge_summary_to_main 把摘要保存为主线决策记录。
合并完成后，当前活跃分支会自动切回主线。

也就是说，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 流程。

文档

结论

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

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

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

MCP Servers

Branch Context Manager MCP

一句话说明

当前状态

重要边界

适合场景

MCP 工具

分支管理

笔记和摘要

导出

工作流辅助

可选模型 API 配置

Demo

安装和本地运行

Claude Desktop 配置

Claude Code / Cursor 使用建议

合并逻辑

Demo 流程

数据存储

开发和测试

文档

结论

安装包（如果需要）

Cursor 配置 (mcp.json)

Branch Context Manager MCP

一句话说明

当前状态

重要边界

适合场景

MCP 工具

分支管理

笔记和摘要

导出

工作流辅助

可选模型 API 配置

Demo

安装和本地运行

Claude Desktop 配置

Claude Code / Cursor 使用建议

合并逻辑

Demo 流程

数据存储

开发和测试

文档

结论

安装包 （如果需要）

Cursor 配置 (mcp.json)

安装包（如果需要）