Claude Code (사용자)
      │ 자연어 지시
      ▼
┌─────────────────────────────┐
│       server.js             │  ← MCP 서버 진입점
│  createServer(env)          │     도구 등록 + 의존성 주입
│  8개 Tools / 2개 Resources  │
│  1개 Prompt                 │
└──────┬──────────────────────┘
       │
  ┌────┴────────────────────┐
  │                         │
  ▼                         ▼
githubClient.js          aiClient.js
GitHub REST API v3 호출   Claude API 호출
브랜치/PR/이슈/라벨 관리   코드 생성 + 파일 쓰기
git CLI 실행              레포 컨텍스트 수집

// 실제 실행
runCreateBranchTool(args, { token, owner, repo, defaultBase })

// 테스트에서 mock 주입
runCreateBranchTool(args, {
  _getBranchSha: async () => 'sha-abc',
  _createBranch: async () => {},
})

@ repo://context
@ repo://recent-prs

/workflow task="로그인 버튼 컴포넌트 추가"

Please implement the following task using the github-workflow MCP tools:

**Task:** 로그인 버튼 컴포넌트 추가

Follow these steps in order:
1. Attach the `repo://context` resource to understand the codebase
2. Call `create_branch` with a descriptive branch name
3. Write or modify the necessary files
4. Call `run_tests` to verify correctness
5. Call `commit_and_push` with a clear commit message
6. Call `create_pr` to open a Pull Request

사용자: "feature/login-button 브랜치 만들고 테스트 통과하면 PR 열어줘"

Claude Code
  1. create_branch("feature/login-button")     → GitHub API: refs 생성
  2. (코드 작성은 Claude Code 자체가 수행)
  3. run_tests("npm test")                     → spawn("npm", ["test"], cwd)
     └ 실패 시 Claude Code가 직접 코드 수정 후 재시도
  4. commit_and_push("feat: add login button") → git add . && git commit && git push -u origin HEAD
  5. create_pr("Add login button", ...)        → GitHub API: pulls 생성

사용자: "아바타 업로드 기능 추가해줘"

run_workflow("아바타 업로드 기능 추가")
  │
  ├─ 1. 브랜치 생성
  │     generateBranchName(task) → "feature/아바타-업로드-기능-추가"
  │     getBranchSha(master) → createBranch(feature/...)
  │
  ├─ 2. 코드 생성 루프 (최대 3회 시도)
  │     │
  │     ├─ buildRepoContext(repoPath)
  │     │   └ 파일 트리 수집 (node_modules, .git 제외)
  │     │     우선순위: package.json → *.json/*.md → src/* → 나머지
  │     │     최대 20개 파일, 파일당 32,000자 제한
  │     │
  │     ├─ generateCodeChanges(client, task, context, previousError)
  │     │   └ Claude Sonnet 4.6 호출 (max_tokens: 8192)
  │     │     응답 형식: { explanation, files: [{path, content}] }
  │     │     재시도 시 이전 테스트 실패 출력을 함께 전달
  │     │
  │     ├─ applyFileChanges(repoPath, files)
  │     │   └ 생성된 파일을 디스크에 저장
  │     │
  │     └─ run_tests("npm test", repoPath)
  │         ├ PASS → 루프 종료
  │         └ FAIL → previousTestOutput 저장 후 다음 시도
  │
  ├─ 3. commitAndPush(repoPath, "feat: {task}", ["."])
  │     git add . → git commit -m ... → git push -u origin HEAD
  │
  └─ 4. createPR(task, body, branchName, master)
        → PR URL + number 반환

create_issue(title, labels=["bug", "없는라벨"])
  │
  ├─ labels가 비어있으면 → 검증 스킵, 바로 생성
  │
  ├─ listLabels(owner, repo) → 레포 라벨 전체 조회
  │
  ├─ 요청 라벨 ∩ 존재 라벨 비교
  │   ├─ 모두 존재 → createIssue() 호출
  │   └─ 없는 라벨 발견 → isError: true 반환
  │         "Label(s) not found: "없는라벨""
  │         "Available labels: bug, enhancement, ..."
  │
  └─ AI가 list_labels 재호출 후 올바른 라벨로 재시도

git clone https://github.com/GHeeJeon/github-workflow-mcp
cd github-workflow-mcp
npm install
npm link        # 전역 바이너리 등록 (github-workflow-mcp 커맨드 사용 가능)

npm install /path/to/github-workflow-mcp

claude mcp add github-workflow \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -e REPO_OWNER=yourorg \
  -e REPO_NAME=your-project \
  -e REPO_PATH=/Users/you/projects/your-project \
  -e DEFAULT_BASE_BRANCH=main \
  -- github-workflow-mcp

claude mcp add github-workflow \
  -e GITHUB_TOKEN=ghp_your_token_here \
  -e REPO_OWNER=yourorg \
  -e REPO_NAME=your-project \
  -e REPO_PATH=/Users/you/projects/your-project \
  -e ANTHROPIC_API_KEY=sk-ant-your_key_here \
  -- github-workflow-mcp

claude mcp list
# github-workflow: github-workflow-mcp - ✔ Connected

"feature/login-button 브랜치를 만들고, 로그인 버튼 컴포넌트를 작성한 뒤
테스트 통과하면 PR까지 열어줘."

"run_workflow로 '사용자 프로필 페이지에 아바타 업로드 기능 추가' 해줘"

"bug 라벨로 '로그인 버튼이 클릭되지 않음' 이슈 만들어줘"

"https://github.com/myorg/repo/pull/42 리뷰 상태 알려줘"

@ repo://context 첨부 후:
"위 구조를 보고 인증 모듈에 refresh token 기능을 추가해줘"

@ repo://recent-prs 첨부 후:
"현재 진행 중인 PR 중 리뷰어가 없는 것 있어?"

@ repo://context  @ repo://recent-prs
"현재 작업 중인 PR과 겹치지 않도록 새 브랜치 만들어서 다크모드 지원 추가해줘"

/workflow task="사용자 프로필 이미지 업로드 기능 추가"

npm test