Skip to main content
Glama
Sign In
conversation-branch

conversation-branch

by qddfxp
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

conversation-branch-mcp（E 盘独立副本）

Conversation Branch 的 MCP 适配层独立副本，零第三方依赖，只用 Python 3.8+ 标准库。

完整规则与工作流说明见 SKILL.md；MCP 专用说明见 MCP.md。

目录

E:/conversation-branch-mcp/
├── README.md                 本文件
├── MCP.md                    MCP 配置与工具清单
├── SKILL.md                  技能完整说明（工作流 + 隔离铁律）
├── references/
│   └── evaluation.md         A/B 对比评估方法
├── scripts/
│   ├── cb_mcp.py             MCP stdio 服务入口
│   └── cb.py                 核心管理器（MCP 与 CLI 共用）
├── hooks/
│   ├── guard.py              可选 PreToolUse 硬守卫
│   └── README.md             守卫安装与局限说明
└── tests/
    └── test_cb.py            标准库回归测试

cb_mcp.py 与 cb.py 必须在同一目录：适配器按自身路径定位 cb.py。

Related MCP server: strand-router

MCP 客户端配置

{
  "mcpServers": {
    "conversation-branch": {
      "command": "python",
      "args": [
        "E:/conversation-branch-mcp/scripts/cb_mcp.py"
      ]
    }
  }
}

python 不在 PATH 时换成解释器绝对路径。

命令行直接使用

# 初始化一个长期任务工作区
python "E:/conversation-branch-mcp/scripts/cb.py" init "D:/long-task"

# 开实验分支（默认复制同源 inputs/）
python "E:/conversation-branch-mcp/scripts/cb.py" branch "D:/long-task" my-experiment --purpose "一句话目的"

# 查看状态 / 自检
python "E:/conversation-branch-mcp/scripts/cb.py" status "D:/long-task"
python "E:/conversation-branch-mcp/scripts/cb.py" check  "D:/long-task"

自检与测试

python "E:/conversation-branch-mcp/hooks/guard.py" --selftest        # 期望 29/29 passed
python -m unittest discover -s "E:/conversation-branch-mcp/tests" -v # 期望 4/4 OK

边界

  • MCP 只暴露白名单工具，不执行任意 shell 命令。

  • MCP 不是文件系统沙箱；hook 也拦不住 Bash 里的重定向、mv、cp、rm。

  • promote / discard / rollback 属于正式主线变更，始终需要用户明确决定。

安装

两种用法都长期有效，按需选一种即可。

A. 克隆即用（零安装，推荐先试）

git clone https://github.com/qddfxp/conversation-branch-mcp
python scripts/cb.py demo /tmp/cb-demo    # 生成带主线与两个分支的示例工作区
python scripts/cb.py --help

B. 装成命令行工具（pip / pipx）

pipx install .        # 或：pip install .
cb --help
cb demo /tmp/cb-demo
cb-mcp                # MCP stdio 服务器，供客户端以 stdio 方式拉起

装出来两个入口：cb 是 CLI，cb-mcp 是 MCP 服务器；零运行时依赖，requires-python >= 3.8。 安装不移动仓库里的任何文件，所以 A 里的 scripts/cb.py 路径永远可用，两种用法的文档与配置可以混着写。

MCP 客户端两种写法都行（详见 MCP.md）：

{"command": "cb-mcp", "args": []}
{"command": "python", "args": ["/绝对路径/scripts/cb_mcp.py"]}

授权

Apache License 2.0，见 LICENSE。商用、修改、再分发都允许，需保留版权与许可声明； 本项目按 Apache-2.0 的默认条款提供，不含额外附加条款。

Available Tools

15 tools
cb_branchA

创建实验分支，默认复制同源 inputs

Inputs: name (required), root (required), from, purpose, +1 more.

cb_checkA
Read-onlyIdempotent

体检工作区结构（只读）：报告孤儿分支目录、缺失 PROMPT.md、归档缺失等问题

Inputs: root (required). Returns: ok, info, root, problems, +1 more

cb_checkoutA
Idempotent

切换 HEAD 到指定分支（实验期间主线只读，HEAD 决定谁可以被改动）

Inputs: name (required), root (required).

cb_compareA
Idempotent

生成多分支横向对比（写入 COMPARE.md，不改主线）

Inputs: root (required).

cb_diffA
Idempotent

生成分支 PROMPT 与父版本（或主线）的规则差异（写入分支 DIFF.md，不改主线）

Inputs: root (required), name, against, against_main.

cb_discardA
Destructive

舍弃实验分支：names 指定要舍弃的分支，keep 指定保留的赢家（其余全舍弃）；names 与 keep 互斥，必须给其一。默认归档到 archive/，加 purge 则真删目录（不可恢复）。舍弃 HEAD 所在分支时 HEAD 自动回 main

Inputs: root (required), keep, names, purge.

cb_exportA

导出分支交接包（不改工作区状态）：生成自带上下文的目录，可交给全新对话测试

Inputs: to (required), name (required), root (required).

cb_initA

初始化工作区（在 root 下建立 .branches/ 与主线）

Inputs: root (required), prompt.

cb_logA
Read-onlyIdempotent

查看工作区事件时间线（只读）

Inputs: root (required), limit. Returns: root, total, events, inferred, +1 more

cb_noteB
Idempotent

更新分支 NOTES.md 的备注

Inputs: name (required), root (required), text (required).

cb_promoteA
Destructive

把实验分支提升为新主线：旧主线归档、版本号 +1（必须由用户明确批准）。note 为必填的提升理由，写入主线 CHANGELOG.md 供事后审计

Inputs: name (required), note (required), root (required).

cb_renameC

重命名实验分支

Inputs: new (required), old (required), root (required).

cb_rollbackA
Destructive

把主线回滚到某个归档版本：ref 可以是版本号或 archive/ 下的目录名（必须由用户明确批准）

Inputs: ref (required), root (required), note.

cb_statusA

查看工作区状态（会就地重建 STATE.md 视图与 updated 时间戳，不改分支数据、版本号与 HEAD）

Inputs: root (required). Returns: head, root, updated, branches, +2 more

cb_verdictA

把外部测试结论回流到分支 VERDICT.md（只记录，不执行 promote/discard）

Inputs: name (required), root (required), from_file (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    Claude Code, inside the Godot 4 editorFlockbay puts an AI agent in the real Godot 4 editor: it writes GDScript, runs your game and fixes what breaks. Free, or bring your own Claude Code or Codex.flockbay.comAd

    TDQS

    A3.7/5.0

    Scored across 15 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes: status/check/log all inspect but target different aspects (state, health, timeline). diff/compare are separable as single-branch vs multi-branch analysis. Only minor boundary overlap exists between status and check, but descriptions clarify the distinction.

    Naming Consistency5/5

    All tools use the unified cb_ prefix followed by a short imperative verb (rename, status, check, log, diff, compare, init, branch, checkout, note, discard, promote, rollback, export, verdict). The pattern is completely consistent and predictable.

    Tool Count5/5

    15 tools is at the upper boundary of the ideal range, but each tool maps to a distinct operation in the branch lifecycle: init, create, inspect, modify, archive, promote, rollback, export, and verdict review. No tool feels redundant or unnecessary for the stated domain.

    Completeness4/5

    The surface covers the full branch workflow: creation, checkout, status, health checks, timeline, diffs, comparisons, naming, notes, discard, promotion, rollback, export, and external verdict ingestion. The only notable gap is the lack of a dedicated tool to update or edit the branch PROMPT itself, though that may be intentionally left to direct file editing.

    Maintenance

    ActivitySlowing
    ResponsivenessNo recent community issues

    Resources

    Related MCP Connectors

    Related MCP Servers

    • strand-router

      SanjoyDat1
      -
      license
      Not graded
      quality
      Not graded
      maintenance
      Enables AI agents to branch, score, prune, and merge conversation strands with provenance and timeline export. Provides MCP tools and resources for managing parallel exploratory strands.
      -

    • TinyAssets

      TinyAssets
      A
      license
      A
      quality
      B
      maintenance
      Enables chatbots to interact with a global goals engine, allowing them to declare goals, manage branches, and evaluate outcomes through MCP tools.
      12
      1
      MIT