Commit Canvas MCP

GitHub 저장소 URL과 GitHub 사용자 ID를 받아 해당 사용자의 의미 있는 커밋을 필터링하고 Cursor Canvas용 .canvas.tsx 포함관계 트리를 생성한다.

실행

uv sync
export GITHUB_TOKEN=...
export OPENAI_API_KEY=...  # mode="llm"일 때만 필요
uv run commit-canvas-mcp

배포 전 로컬 MCP/Codex 검증 절차는 DEPLOYMENT_GUIDE.md를 따른다.

MCP endpoint:

http://localhost:8000/mcp

FastAPI endpoint:

uv run commit-canvas-api
curl -X POST http://localhost:8000/analyze \
  -H 'content-type: application/json' \
  -d '{
    "repo_url": "https://github.com/Pommit/pommit",
    "github_id": "jongphago",
    "branch": "dev",
    "commit_list_path": "docs/jongphago-분석-커밋-목록.md",
    "expected_count": 68,
    "mode": "llm",
    "output_dir": "canvases"
  }'

MCP Tool

generate_commit_canvas

입력:

• repo_url: GitHub 저장소 URL 또는 owner/repo
• github_id: GitHub author login
• branch: 기본값 dev
• commit_list_path: 선택. 필터링된 커밋 목록 Markdown. 지정하면 문서의 No/SHA를 전수 배치 대상으로 사용
• expected_count: 선택. 전수 배치 검증 기준 커밋 수
• output_dir: 기본값 canvases
• output_filename: 생략 시 <github_id>-commit-inclusion-tree-codex.canvas.tsx
• tree_json_filename: 선택. 검증된 tree JSON 파일명
• codex_html_filename: 선택. Codex에서 열 수 있는 정적 HTML 파일명
• mode: heuristic 또는 llm. 기본값 heuristic
• llm_model: 선택. 생략 시 OPENAI_MODEL 또는 gpt-5-mini
• max_repair_attempts: LLM JSON 검증 실패 시 repair 재시도 횟수. 기본값 2
• evidence_json_filename: 선택. LLM 입력 근거 bundle 저장 파일명
• max_commits: 디버그용 상한
• include_tsx: 응답에 TSX 본문 포함 여부

출력:

• 저장소, 브랜치, 작성자
• author 커밋 수
• 필터링 후 커밋 수
• 제외 사유별 카운트
• theme/node/commit 트리
• 생성된 .canvas.tsx 경로
• 생성된 tree JSON 경로
• 생성된 evidence JSON 경로
• 생성된 Codex-openable .codex.html 경로
• 전수 배치 검증 결과

필터

• GitHub author login 일치
• merge 제외
• revert 제외
• .py 변경 없음 제외
• .py 변경량 5 미만 제외
• docs only, CI only, config only, binary only 제외
• fixup, squash, wip, temp, debug 제외
• chore:, docs:, etc:, test: 제목 제외
• 분할·중복 제목 제외

그룹 기준

commit_list_path가 없는 기본 모드는 다음 필터를 먼저 적용한다.

1. 변경 파일의 주요 패키지 경로
2. associated PR title
3. commit body, PR title/body의 issue 번호
4. commit title type

commit_list_path가 있으면 성공한 Cursor 대화의 절차처럼 이미 필터링된 Markdown 목록을 권위 입력으로 사용한다.

1. Markdown의 No, 날짜, SHA, 제목을 파싱한다.
2. SHA별 commit detail과 associated PR을 조회한다.
3. commit body, PR title/body에서 issue 번호를 수집한다.
4. issue title/body를 조회해 theme/node 근거로 사용한다.
5. recursive theme/node/commit tree를 만든다.
6. 배치 수, No 중복, No 누락, SHA prefix를 검증한다.
7. .canvas.tsx와 검증용 .json을 함께 저장한다.

현재는 외부 LLM 없이 동작하는 결정적 구현이다. transcript의 수작업 수준 의미 재분류를 완전히 복제하려면 issue/body 근거를 넣은 LLM classification 단계를 build_themes 앞에 추가해야 한다. mode="llm"은 이 단계를 OpenAI Responses API structured JSON 출력으로 수행한다.

LLM 모드 처리:

1. evidence bundle 생성: commit detail, changed files, stats, PR title/body, issue title/body, issue refs graph.
2. structured JSON schema로 theme/node/children/commit No 배치 생성.
3. 원본 commit record에서 SHA/date/PR/refs 복원.
4. 배치 수, No 중복, No 누락, SHA prefix 검증.
5. 검증 실패 시 오류와 이전 tree를 넣어 repair loop 실행.
6. .canvas.tsx, .json, .evidence.json 저장.

출력 파일

MCP 마지막 단계는 같은 output_dir에 네 파일을 저장한다.

• .canvas.tsx: Cursor Canvas에서 여는 원본 Canvas 컴포넌트
• .codex.html: Codex 또는 일반 브라우저에서 여는 정적 HTML
• .json: 검증된 theme/node/commit tree
• .evidence.json: LLM과 검증에 사용한 근거 bundle