Автоматический рендерер контекста PR-ветки (Branch Render Context MCP)

Branch Render Context — это специализированный сервер Model Context Protocol (MCP) и CLI-инструмент, предназначенный для автоматического анализа и рендеринга полного контекста Git Pull Request / целевой ветки относительно базовой или текущей ветки. Он предоставляет кэшированные инкрементальные Markdown и JSON документы напрямую AI-агентам без переключения веток, с изоляцией рабочего дерева, автоматическим управлением .gitignore и гибкими опциями очистки хранилища.

🎯 Ключевые особенности и архитектура

1. Определение целевой ветки без переключения веток:

   • Когда ваше рабочее дерево находится на main или develop, и вы указываете целевую ветку, например feature/user-auth, инструмент автоматически определяет:

     • baseBranch: main (из текущего checkout или настроенного по умолчанию)

     • 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. Встроенное редактирование секретов и оптимизация токенов:

   • Обнаруживает и маскирует учётные данные, файлы .env, сертификаты .pem и API-токены.

   • Генерирует компактные, эффективные по токенам Markdown-сводки, оптимизированные для контекстных окон LLM.

7. Детальная очистка и блокировка параллелизма:

   • Безопасная многопроцессная блокировка (.storage.lock и .branch.lock).

   • Поддерживает 3 различных области очистки: отдельная ветка, всё репозиторий и полное удаление хранилища.

Related MCP server: organisation.md

🛠️ Руководство по 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-сервером

Настройте MCP-сервер в вашем AI-редакторе или клиенте (Claude Desktop, Cursor, Cline, Roo Code):

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

Доступные MCP-инструменты

📄 Структура отрендеренного документа

Каждый отрендеренный документ ветки содержит как структурированный JSON-объект (document.json), так и дружественное для AI Markdown-представление (document.md):

• Метаданные репозитория и ветки: уникальные идентификаторы, удалённые URL, ссылки для сравнения и хэши коммитов.

• История коммитов: полный список коммитов с авторами, датами, темами и телами коммитов (с фильтрацией секретов).

• Изменения файлов и статистика diff: подробный список файлов со статусом изменения (added, modified, deleted, renamed), фрагменты патчей, вставки и удаления.

• Состояние свежести и контрольных точек: сохранённые SHA коммитов и временные метки, используемые для сверхбыстрой инкрементальной переоценки.

🧪 Разработка и тестирование

# Run Vitest test suite
npm test

# Build TypeScript output
npm run build

📜 Лицензия

Лицензия MIT. Разработано для AI-агентных рабочих процессов и автоматизированных ассистентов кодирования.