Are you the author? Sign in to claim
GitBranchMCP
Branch Context Manager MCP 是一个轻量、本地优先的 MCP Server，用来给 Claude Code、Claude Desktop、Cursor 等 MCP 客户端提供“主线/分支”式的结构化笔记和决策记录。
当前版本是 GitBranchMCP v1.0。它保留 LiteBranchMCP / Free Mode，并新增完整的 Git Mode / API Mode 工作流。
如果你是从 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 原型收工。
已实现：
start_new_session 手动重置当前活跃分支到主线anthropic 和通用 OpenAI-compatible client）branch_chat 分支隔离模型对话未实现：
本项目做的是 结构化记录隔离，不是 模型上下文物理隔离。
如果你在同一个 Claude Code / Claude Desktop 会话里讨论主线和分支，模型仍然会看到同一聊天窗口里的全部上下文。即使 MCP 数据库没有把分支笔记合并到主线，模型回答时仍可能受到聊天历史中支线内容的影响。
Free Mode 能保证：
Free Mode 不能保证：
如果你需要更干净的隔离，推荐做法是：
适合：
不太适合：
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 branchappend_message_node：手动追加 message nodeget_branch_log：查看分支从 root 到 HEAD 的 message logget_branch_diff：查看 fork 点之后新增的 message nodesget_branch_context_preview：查看分支上下文预览save_note：保存当前分支或指定分支的结论性笔记get_branch_notes：查看某个分支的笔记merge_summary_to_main：把宿主模型生成的摘要合并到主线list_main_summaries：查看主线合并历史export_branch_markdown：导出某个分支的 Markdownexport_main_markdown：导出主线决策记录 Markdownexport_demo_markdown：导出演示数据 Markdown默认导出目录：
./exports/
导出工具会在真正写文件时自动创建 exports 目录。为了避免 Claude Desktop 自己生成文件卡片而不是调用 MCP 导出，工具说明和推荐工作流已经明确要求：导出时应调用 MCP 工具，并把工具返回的本地路径原样展示给用户。
get_context_overview：查看当前上下文总览get_workflow_prompt：获取推荐项目规则提示词suggest_branch_workflow：根据当前活跃分支给出固定建议set_model_provider：设置可选模型 provider 和 modelset_model_api_key：保存可选模型 API Keyget_model_status：查看模型配置状态，API Key 只会脱敏显示test_model_connection：显式测试当前模型配置route_user_message：根据当前 active branch 自动路由普通用户消息；主线提示宿主模型回答，普通分支自动调用 branch_chatbranch_chat：在当前 active branch 或指定分支中进行隔离模型对话summarize_branch_diff：对来源分支 fork 后的 diff 生成结构化摘要，不自动合并merge_branch_summary：将来源分支以 summary merge 方式合并到目标分支，默认合并到 mainget_merge_history：查看所有 summary merge 记录当前支持：
anthropic：Anthropic Messages API clientopenai-compatible：通用 OpenAI 兼容接口 client，可接通义千问/百炼、DeepSeek、Moonshot、OpenAI 兼容网关等预留但尚未实现：
gemini安全和费用说明：
route_user_message 会先检查当前 active branch；在主线不会调用模型 API，在普通分支会自动进入 branch_chat。branch_chat 只会把目标分支的 build_context 发给模型，不会把其他分支 fork 后的消息混入当前分支。branch_chat 只更新目标分支的 head_node_id，不会自动合并分支，也不会把分支消息写入主线。settings 表中。.env 文件中；.env 已被 .gitignore 忽略，不应提交到 GitHub。sk-ant-****abcd，不会回显完整 API Key。.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")
验证要点：
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/... 消息复制到主线。
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
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。
首次使用建议让客户端调用：
get_workflow_prompt
然后把返回内容放进 Claude Code 项目规则、Cursor Rules 或类似的长期说明里。
常见自然语言操作：
开始一个新的 Branch Context Manager 会话。
开一个分支研究 JWT 鉴权。
保存当前结论到这个分支。
查看当前上下文总览。
把这个分支的摘要合并到主线。
导出主线决策记录。
关于“新聊天”的状态：
start_new_session 回到主线；这个操作不会删除分支、笔记或摘要。导出时可以直接说：
导出快排分支。
如果宿主客户端生成了自己的文件卡片而不是本地文件，可以更明确地说：
请调用 branch-context-manager 的 export_branch_markdown，并把工具返回的本地路径原样发给我。
merge_summary_to_main 不会自动总结。
正确流程是：
get_branch_notes 读取分支笔记。merge_summary_to_main 把摘要保存为主线决策记录。也就是说，MCP 保存的是“宿主模型已经写好的摘要”，不是自己调用模型生成摘要。
固定演示场景：
主线：开发 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。
当前保存：
当前不保存：
安装开发依赖后运行：
.\.venv\Scripts\python.exe -m pytest
当前测试覆盖核心分支、笔记、摘要、导出和 demo 流程。
这个项目当前最诚实的定位是：
一个本地优先的 AI 编程支线笔记和主线决策日志 MCP。
它对长对话、复杂任务和需要沉淀决策的 AI 编程流程有价值；但它不是 Claude 上下文分叉系统，也不能提供真正的模型记忆隔离。
40+ tools for querying dashboards, alerts, datasources, and logs in Grafana
Run Claude Code as an MCP server so any agent can delegate coding tasks to it
@microsoft✓ OfficialBrowser automation using accessibility snapshots instead of screenshots
@googleapis✓ OfficialGoogle's universal MCP server supporting PostgreSQL, MySQL, MongoDB, Redis, and 10+ databases