Skip to main content
Glama
Sign In
deenesjakoruzh
MCP Branch Render Document

MCP Branch Render Document

by Ninh-Duong
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Local

自动 PR 分支上下文渲染器（Branch Render Context MCP）

Node.js TypeScript MCP Protocol

Branch Render Context 是一个专门的模型上下文协议（MCP）服务器和 CLI 工具，旨在自动分析和渲染相对于基础分支或检出分支的完整 Git 拉取请求 / 目标分支上下文。它通过零分支切换、工作树隔离、自动 .gitignore 管理和灵活的存储清理选项，将缓存的增量 Markdown 和 JSON 文档直接提供给 AI 代理。

🎯 核心亮点与架构

  1. 无需切换分支的目标分支解析：

    • 当您的工作树当前位于 main 或 develop 上，并且您指定了类似 feature/user-auth 的目标分支时，该工具会自动确定：

      • baseBranch：main（来自当前检出或配置的默认值）

      • targetBranch：feature/user-auth

      • 比较：main..feature/user-auth

  2. 零工作树干扰：

    • 开发人员的工作树保持完全不受影响。像 git checkout 或 git switch 这样的命令永远不会被执行。

  3. 独立的提交与引用解析：

    • 目标分支提交直接从本地引用或远程跟踪引用（origin/<branch>）解析，而不依赖当前的 HEAD。

  4. 干净的工作树隔离：

    • 当前检出分支上未提交的脏更改永远不会污染目标分支的渲染 PR 上下文。

  5. 类 Git 的分层存储与自动 .gitignore：

    • 将文档持久化到结构化路径中：.branch-render-context/repositories/<repo-id>/branches/<branch-path>/document.json。

    • 自动且幂等地将 .branch-render-context/ 添加到 .gitignore，而不会更改其他用户规则。

  6. 内置机密脱敏与 token 优化：

    • 检测并屏蔽凭据、.env 文件、.pem 证书和 API 令牌。

    • 生成紧凑、token 高效的 Markdown 摘要，针对 LLM 上下文窗口进行了优化。

  7. 细粒度清理与并发锁定：

    • 安全的多进程锁定（.storage.lock 和 .branch.lock）。

    • 支持 3 种不同的清理范围：单个分支、整个仓库和完全存储清除。

Related MCP server: Branchpoint

🛠️ CLI 指南

1. 渲染 / 刷新目标分支上下文

# Analyze target branch relative to the currently checked-out base branch
npm run branch-render:refresh -- --branch feature/user-auth

# Specify explicit base branch and force a full rebuild
npm run branch-render:refresh -- --branch feature/user-auth --base develop --force

示例输出：

=================================================================
Target branch:   feature/user-auth
Checkout branch: main
Base branch:     main
Comparison:      main..feature/user-auth
Target commit:   8f3b2a1c
Base commit:     1e4d9c7b
Strategy:        full
─────────────────────────────────────────────────────────────────
Metrics:
- Commits:        3
- Changed files:  4
- Insertions:     +142
- Deletions:      -18
- Worktree dirty: ignored (clean isolation)
─────────────────────────────────────────────────────────────────
Document path:
.branch-render-context/repositories/r_9a2b4c1d/branches/feature/user-auth/document.json
=================================================================

2. 交互式终端向导

npm run branch-render:start

该向导会检测您当前的检出分支，显示现有的渲染上下文，并引导您完成渲染或清除选项。

3. 检查新鲜度状态

npm run branch-render:status -- --branch feature/user-auth

4. 列出已注册的上下文

npm run branch-render:list

5. 上下文与存储清理

# Scope 1: Clear context for a specific branch
npm run branch-render:clear -- --branch feature/user-auth

# Scope 2: Clear all branch contexts in the current repository
npm run branch-render:clear -- --all

# Scope 3: Completely clear ENTIRE storage (all repositories, catalog, config, indexes)
npm run branch-render:clear -- --all-storage --yes

🤖 MCP 服务器集成

在您的 AI 编辑器或客户端（Claude Desktop、Cursor、Cline、Roo Code）中配置 MCP 服务器：

{
  "mcpServers": {
    "branch-render-context": {
      "command": "node",
      "args": ["<path-to-mcp-branch-render-document>/dist/index.js"]
    }
  }
}

可用的 MCP 工具

工具名称

参数

描述

branch_context_start

repo_path?, target_branch?, base_ref?, storage_path?

初始化会话，发现仓库，并检查分支状态。

branch_context_list

repo_path?, storage_path?

列出所有已注册的仓库和缓存的分支文档。

branch_context_status

repo_path?, branch?, base_ref?, storage_path?

在不渲染的情况下评估目标引用与基础引用之间的 Git 新鲜度。

branch_context_get

repo_path?, branch?, freshness_mode?, storage_path?

使用指定的新鲜度策略（required、auto、check_only、allow_stale）检索 document.json。

branch_context_refresh

repo_path?, branch?, base_ref?, force?, storage_path?

触发确定性的增量更新或完全重建。

branch_context_clear

repo_path?, branch?, all?, storage_path?

清除仓库中单个分支或所有分支的渲染上下文。

branch_context_clear_storage

confirm: boolean, storage_path?

清除所有仓库中的整个存储（需要 confirm: true）。

📄 渲染文档结构

每个渲染的分支文档都包含一个结构化的 JSON 对象（document.json）和一个 AI 友好的 Markdown 表示（document.md）：

  • 仓库与分支元数据：唯一 ID、远程 URL、比较引用和提交哈希。

  • 提交历史：完整的提交列表，包含作者、日期、主题和提交正文（带有机密过滤）。

  • 文件更改与差异统计：详细的文件列表，包含更改状态（added、modified、deleted、renamed）、补丁块、插入和删除。

  • 新鲜度与检查点状态：保存的提交 SHA 和时间戳，用于超快速的增量重新评估。

🧪 开发与测试

# Run Vitest test suite
npm test

# Build TypeScript output
npm run build

📜 许可证

MIT 许可证。专为 AI 代理工作流和自动化编码助手而设计。

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Resources

Related MCP Connectors

Related MCP Servers