# 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 用户快速说明书](docs/github-user-quickstart.md)

默认情况下，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

默认导出目录：

```text
./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` 示例：

```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 兼容模型通常只需要换：

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

配置优先级：

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

真实 API Mode 本地验证：

```text
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`：

```powershell
$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 工作流：

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

对应工具：

```text
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 或更高版本。

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

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

手动启动：

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

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

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

默认数据库路径：

```text
./data/branch-context.db
```

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

```powershell
$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 配置文件通常在：

```text
%APPDATA%\Claude\claude_desktop_config.json
```

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

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

配置示例：

```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 使用建议

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

```text
get_workflow_prompt
```

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

常见自然语言操作：

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

关于“新聊天”的状态：

- MCP server 每次重新启动时会把当前活跃分支重置为主线。
- Claude Desktop 不一定每开一个新聊天就重启 MCP 进程。
- 如果新聊天里发现仍停在上一次的分支，可以调用 `start_new_session` 回到主线；这个操作不会删除分支、笔记或摘要。

导出时可以直接说：

```text
导出快排分支。
```

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

```text
请调用 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 流程

固定演示场景：

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

快速生成 demo：

```text
create_demo_data
```

查看上下文：

```text
get_context_overview
```

查看主线摘要：

```text
list_main_summaries
```

导出演示 Markdown：

```text
export_demo_markdown
```

完整演示脚本见 [docs/demo-script.md](docs/demo-script.md)。

## 数据存储

数据保存在本地 SQLite。

当前保存：

- 分支
- 分支笔记
- 主线摘要合并记录
- message_nodes
- 分支 fork/head 指针
- summary merge history
- 本地设置
- 可选模型 provider、model、API Key

当前不保存：

- 模型推理过程
- Claude 会话历史
- 用户文件内容

## 开发和测试

安装开发依赖后运行：

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

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

## 文档

- [Free Mode 说明](docs/free-mode.md)
- [Git Mode 说明](docs/git-mode.md)
- [演示脚本](docs/demo-script.md)
- [用户指南](docs/user-guide.md)
- [路线图](docs/roadmap.md)
- [设计文档](docs/design.md)
- [说明书](docs/github-user-quickstart.md)

## 结论

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

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

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