ContextBridge

在多个 AI 编程 IDE 之间传递会话上下文的轻量 MCP 工具。 把当前对话 + git diff 打包成快照,切换工具时一键 import,接手的 AI 立刻懂"前因后果"。

ContextBridge 解决一个非常具体的问题:你在 Cursor / Claude Code / Codex / Gemini CLI 之间切来切去时,每次都要跟新工具重新解释"我刚改了什么、现在在做什么"。它把当前会话导出成一份可移植的快照,在另一边 import 进来,接着干。

• 双入口:既能作为 MCP server 被 AI IDE 直接调用,也能作为命令行工具独立使用
• 全本地:sqlite + JSON 文件存储,不联网,不上传,隐私完全可控
• 零常驻:CLI 用完即走,MCP server 仅在 host 进程内运行,没有后台服务
• 自动采集:在 Claude Code 下自动读取 ~/.claude/projects/ 会话,无需手动粘贴

---

目录

• 安装
• 快速开始
• 接入 MCP host
• CLI 用法
• MCP 工具
• 数据存储
• 项目结构
• 测试
• 设计文档
• License

---

安装

需要 Python 3.10+。

git clone https://github.com/luanyanchengdeqiong/contextbridge.git
cd contextbridge

# 推荐:用 uv
uv venv && uv pip install -e ".[dev]"

# 或者纯 pip
python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate
pip install -e ".[dev]"

验证安装:

cb --help          # 应列出 export / list / show / import / clear

---

快速开始

场景:你在 Claude Code 里干了一阵,想切到 Cursor 接着做。

# 1. 在 Claude Code 侧,导出当前会话(自动读取本地 session)
cb export -t "把登录改成 OAuth"

# 2. 切到 Cursor 后,打印 handoff 块粘贴进新对话
cb import          # 默认取最新一条

粘贴进去的内容长这样(节选):

# Context Handoff — 把登录改成 OAuth
source IDE: claude_code  cwd: /path/to/repo  created: 2026-07-29T...

## user
需要把登录改成 OAuth...

## assistant
我已经把 session.py 改好了,接下来要...

## Current git diff
```diff
diff --git a/src/session.py b/src/session.py
...

接手的 AI 一眼看到完整上下文 + 当前代码改动。

---

## 接入 MCP host

接入后,AI 能在自己会话里直接调用 `cb_export` / `cb_import`,无需切到终端。

### Claude Code

编辑 `~/.claude.json`(或项目根 `.mcp.json`):

```json
{
  "mcpServers": {
    "contextbridge": {
      "command": "cb",
      "args": ["serve"]
    }
  }
}

Cursor / Claude Desktop / 其他 MCP host

Settings → MCP → Add Server,填入同样 JSON。Windows 上若 cb 不在 PATH,改用绝对路径:

{
  "mcpServers": {
    "contextbridge": {
      "command": "C:\\path\\to\\contextbridge\\.venv\\Scripts\\cb.exe",
      "args": ["serve"]
    }
  }
}

Windows 注意:cb serve 启动的 git 子进程已做 handle 隔离处理,不会因继承 stdio 管道而挂起。

---

CLI 用法

cb export [-t TITLE] [-c CONVERSATION_JSON] [--no-diff]   # 导出快照
cb list   [-n LIMIT]                                       # 列出快照
cb show   <ID>                                             # 打印某条快照 JSON
cb import [<ID>]                                           # 打印 handoff 块(默认最新)
cb clear  [DAYS]                                           # 清理 N 天前的(默认 30)

显式传入对话(非 Claude Code 环境,如从 GUI host 拷贝):

cb export -t "修复登录 bug" -c '[{"role":"user","content":"登录总报 500"}]'

ID 支持前缀:cb_list 显示的是 8 位短 id,import / show 既接受完整 UUID 也接受短前缀。

---

MCP 工具

工具	作用
cb_export	导出当前上下文为快照;在 Claude Code 下自动采集,其他 host 可传 conversation 参数
cb_list	列出快照(显示短 id、IDE、时间、标题)
cb_import	按 id/前缀导入,返回 Markdown handoff 块;省略 id 取最新
cb_clear	按天数清理旧快照

---

数据存储

~/.contextbridge/
├── index.db               # sqlite 索引 + FTS5 全文检索(按标题)
└── snapshots/             # JSON 快照文件,可直接查看/分享/删除
    └── 2026-07-29T080000Z_feature-x_<id8>.json

• 用 CONTEXTBRIDGE_HOME 环境变量覆盖存储目录
• 快照单文件上限 1MB(超长对话会被截断)
• 存储采用进程级单例连接,长生命周期下不会泄漏 sqlite 连接

---

项目结构

contextbridge/
├── src/contextbridge/
│   ├── server.py            # FastMCP server + 4 个 cb_* 工具
│   ├── cli.py               # Typer CLI
│   ├── store.py             # sqlite 存储 + FTS5 + 前缀查找
│   ├── render.py            # 共享的 handoff 渲染(CLI/MCP 复用)
│   ├── gitutils.py          # Windows 安全的 git diff
│   ├── truncation.py        # 对话/diff 截断
│   ├── schema.py            # pydantic 模型
│   └── adapters/            # IDE 适配器(Claude Code / Generic)
├── tests/                   # 38 条测试
├── docs/
│   ├── install.md
│   └── architecture.md
└── pyproject.toml

---

测试

pytest

覆盖:存储 CRUD、前缀查找、孤儿行兜底、FTS 检索、CLI 各命令、MCP server 工具、Claude Code 适配器、渲染格式。

---

设计文档

• docs/install.md — 详细安装说明
• docs/architecture.md — 架构与设计决策

---

License

MIT