자동 PR 브랜치 컨텍스트 렌더러 (Branch Render Context MCP)

Branch Render Context는 기본(base) 또는 체크아웃 브랜치를 기준으로 전체 Git Pull Request / 대상(Target) 브랜치 컨텍스트를 자동으로 분석하고 렌더링하도록 설계된 특수 목적의 Model Context Protocol (MCP) 서버 및 CLI 도구입니다. 브랜치 전환 없이, 작업 트리 격리, 자동 .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. 독립적인 커밋 및 Ref 해석:

   • 대상 브랜치 커밋은 현재 HEAD에 의존하지 않고 로컬 ref 또는 원격 추적 ref(origin/<branch>)에서 직접 해석됩니다.

4. 깨끗한 작업 트리 격리:

   • 현재 체크아웃 브랜치의 커밋되지 않은 더티 변경 사항은 대상 브랜치의 렌더링된 PR 컨텍스트를 절대 오염시키지 않습니다.

5. Git 유사 계층형 스토리지 및 자동 .gitignore:

   • 문서를 구조화된 경로에 저장합니다: .branch-render-context/repositories/<repo-id>/branches/<branch-path>/document.json.

   • 다른 사용자 규칙을 변경하지 않고 .branch-render-context/를 .gitignore에 자동으로 멱등적으로 추가합니다.

6. 내장 시크릿 마스킹 및 토큰 최적화:

   • 자격 증명, .env 파일, .pem 인증서 및 API 토큰을 감지하고 마스킹합니다.

   • LLM 컨텍스트 창에 최적화된 간결하고 토큰 효율적인 Markdown 요약을 생성합니다.

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 서버 통합

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 도구

📄 렌더링된 문서 구조

각 렌더링된 브랜치 문서에는 구조화된 JSON 객체(document.json)와 AI 친화적인 Markdown 표현(document.md)이 모두 포함됩니다:

• 리포지토리 및 브랜치 메타데이터: 고유 ID, 원격 URL, 비교 ref 및 커밋 해시.

• 커밋 기록: 작성자, 날짜, 제목 및 커밋 본문(시크릿 필터링 적용)이 포함된 전체 커밋 목록.

• 파일 변경 및 Diff 통계: 변경 상태(added, modified, deleted, renamed), 패치 청크, 삽입 및 삭제 수가 포함된 상세 파일 목록.

• 최신 상태 및 체크포인트 상태: 초고속 증분 재평가에 사용되는 저장된 커밋 SHA 및 타임스탬프.

🧪 개발 및 테스트

# Run Vitest test suite
npm test

# Build TypeScript output
npm run build

📜 라이선스

MIT 라이선스. AI 에이전트 워크플로우 및 자동화된 코딩 어시스턴트를 위해 설계되었습니다.