MCP GitHub 이슈 우선순위 서버

AI 어시스턴트가 결정론적 우선순위 점수 산정 및 동시성 안전 선택을 통해 GitHub 이슈를 관리할 수 있게 해주는 모델 컨텍스트 프로토콜(MCP) 서버입니다.

빠른 시작

# 1. Install from npm (recommended)
npm install -g mcp-git-issue-priority

# 2. Authenticate (if not already using GitHub CLI)
gh auth login

# 3. Add to Claude Code (~/.claude.json)

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

# 4. Restart Claude Code and verify
# The MCP tools should appear when you run /mcp

주요 기능

우선순위 기반 이슈 선택: 결정론적 점수 산정 알고리즘을 통해 세션 전반에 걸쳐 일관된 이슈 우선순위 지정 보장
동시성 안전 잠금: 파일 기반 원자적 잠금을 통해 여러 AI 세션이 동일한 이슈를 선택하는 것을 방지
가이드 워크플로우: 8단계 워크플로우(선택 → 조사 → 브랜치 → 구현 → 테스트 → 커밋 → PR → 검토) 및 단계 전환 검증
자동 라벨링: 우선순위(P0-P3), 유형(bug, feature, chore, docs) 및 상태 라벨 생성 및 관리
데드락 감지: 비정상 종료된 프로세스의 잠금을 자동으로 감지하고 정리
감사 로깅: 모든 작업에 대한 JSON Lines 로깅 및 30일 보관

설치

사전 요구 사항

Node.js 20+ - 다운로드
GitHub CLI (권장) - 설치 후 gh auth login 실행
- 또는: repo 범위 권한이 있는 GitHub 개인 액세스 토큰

npm을 통한 설치 (권장)

npm install -g mcp-git-issue-priority

특정 버전 설치

npm install -g mcp-git-issue-priority@1.0.0

소스에서 설치

git clone https://github.com/steiner385/mcp-git-issue-priority.git
cd mcp-git-issue-priority
npm install && npm link

문제 해결

이슈	해결 방법
`command not found: mcp-git-issue-priority`	npm 전역 bin이 PATH에 있는지 확인: `npm bin -g`
`GitHub authentication required`	`gh auth login`을 실행하거나 `GITHUB_TOKEN` 설정
설치 중 빌드 오류	Node.js 20+가 설치되어 있는지 확인: `node --version`

구성

GitHub 인증

이 서버는 두 가지 인증 방식을 지원합니다:

권장: GitHub CLI (자동)

GitHub CLI가 설치되어 있고 인증된 경우, 서버가 자동으로 토큰을 가져옵니다:

# One-time setup
gh auth login

이 방식이 권장되며, 수동으로 토큰을 관리할 필요가 없습니다.

대안: 환경 변수

repo 범위 권한이 있는 개인 액세스 토큰으로 GITHUB_TOKEN을 설정합니다:

export GITHUB_TOKEN="ghp_your_personal_access_token"

또는 MCP 설정에서 구성할 수 있습니다(아래 참조).

Claude Code 구성

~/.claude.json(전역) 또는 .claude/settings.json(프로젝트)에 추가합니다:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority"
    }
  }
}

GitHub CLI 대신 개인 액세스 토큰을 사용하시나요? 구성에 토큰을 추가하세요:

{
  "mcpServers": {
    "github-issue-priority": {
      "command": "mcp-git-issue-priority",
      "env": {
        "GITHUB_TOKEN": "ghp_your_personal_access_token"
      }
    }
  }
}

설치 확인

Claude Code를 재시작한 후:

/mcp를 실행하여 사용 가능한 MCP 서버 확인
github-issue-priority 서버가 13개의 도구와 함께 나열되어야 함
저장소에서 list_backlog를 실행하여 작동 여부 확인

사용 가능한 도구

`create_issue`

필수 우선순위 및 유형 라벨을 포함하여 새로운 GitHub 이슈를 생성합니다.

Arguments:
  - title (required): Issue title
  - body (optional): Issue description
  - priority (required): P0 (critical) | P1 (high) | P2 (medium) | P3 (low)
  - type (required): bug | feature | chore | docs
  - repository (required): "owner/repo" format

`select_next_issue`

백로그에서 가장 우선순위가 높은 이슈를 선택하고 잠급니다. 결정론적 점수 산정을 사용하여 일관된 선택을 보장합니다.

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - maxPriority (optional): Only consider issues at or above this priority

`list_backlog`

잠금을 획득하지 않고 우선순위 순으로 모든 열린 이슈를 나열합니다(읽기 전용).

Arguments:
  - repository (required): "owner/repo" format
  - type (optional): Filter by issue type
  - limit (optional): Maximum issues to return (default: 20)

`advance_workflow`

잠긴 이슈의 워크플로우를 다음 단계로 진행합니다.

Arguments:
  - issueNumber (required): Issue number to advance
  - targetPhase (required): research | branch | implementation | testing | commit | pr | review
  - repository (required): "owner/repo" format
  - testsPassed (optional): Required when advancing to 'commit' phase
  - prTitle (optional): Required for 'pr' phase
  - prBody (optional): Required for 'pr' phase
  - skipJustification (optional): Required if skipping phases

`get_workflow_status`

잠긴 이슈의 현재 워크플로우 상태를 가져옵니다.

Arguments:
  - issueNumber (optional): Specific issue number
  - repository (optional): "owner/repo" format

`release_lock`

이슈에 대한 잠금을 해제합니다(완료, 중단 또는 병합 시).

Arguments:
  - issueNumber (required): Issue number
  - reason (required): completed | abandoned | merged
  - repository (required): "owner/repo" format

`force_claim`

다른 세션에 의해 잠긴 이슈를 강제로 가져옵니다(확인 필요).

Arguments:
  - issueNumber (required): Issue number to claim
  - confirmation (required): Must be exactly "I understand this may cause conflicts"
  - repository (required): "owner/repo" format

`sync_backlog_labels`

필수 우선순위/유형/상태 라벨이 누락된 이슈를 감지하고 선택적으로 수정합니다.

Arguments:
  - repository (required): "owner/repo" format
  - mode (optional): "report" (default) to list issues, "update" to apply labels
  - defaultPriority (optional): P0 | P1 | P2 | P3 (defaults to P2)
  - defaultType (optional): bug | feature | chore | docs (defaults to feature)

보고 모드에서는 누락된 라벨에 대한 세부 정보와 함께 누락된 모든 이슈 목록을 반환합니다.

업데이트 모드에서는 이슈에 기본 라벨을 적용합니다:

우선순위 누락 → priority:P2 (또는 지정된 기본값)
유형 누락 → type:feature (또는 지정된 기본값)
상태 누락 → status:backlog

`get_pr_status`

풀 리퀘스트의 CI 상태, 승인 상태 및 병합 상태를 확인합니다.

Arguments:
  - repository (required): "owner/repo" format
  - prNumber (required): Pull request number to check

`bulk_update_issues`

여러 이슈의 라벨을 한 번에 추가/제거하고 닫거나 다시 엽니다.

Arguments:
  - repository (required): "owner/repo" format
  - issues (required): Array of issue numbers (1-50)
  - addLabels (optional): Labels to add
  - removeLabels (optional): Labels to remove
  - state (optional): "open" | "closed"

`implement_batch`

우선순위 순으로 N개의 이슈 배치를 구현하기 시작합니다. 구현할 첫 번째 이슈를 반환합니다.

Arguments:
  - repository (required): "owner/repo" format
  - count (required): Number of issues to implement (1-10)
  - includeTypes (optional): Only include these issue types
  - excludeTypes (optional): Exclude these issue types
  - maxPriority (optional): Only P0, P1, etc.

`batch_continue`

배치 구현을 계속합니다. PR 병합을 폴링한 후 다음 이슈를 반환하거나 완료합니다.

Arguments:
  - batchId (required): Batch ID from implement_batch
  - prNumber (optional): PR number for current issue

`get_workflow_analytics`

시간 기반 워크플로우 분석(주기 시간, 단계별 분석, 노후화 보고서)을 가져옵니다.

Arguments:
  - repository (required): "owner/repo" format
  - period (optional): "7d" | "30d" | "90d" | "all" (default: 30d)

우선순위 점수 산정 알고리즘

이슈는 결정론적 공식에 따라 점수가 매겨집니다:

score = (basePoints + ageBonus) * blockingMultiplier * blockedPenalty

기본 점수: P0=1000, P1=100, P2=10, P3=1
생성 보너스: 생성 후 경과일당 +1점 (최대 365)
차단 승수: "blocking" 라벨이 있는 이슈에 대해 1.5배
차단 페널티: 열린 상위 이슈에 의해 차단된 이슈에 대해 0.1배 (GitHub 하위 이슈를 통해)
동점 처리: 생성 날짜가 빠른 순 (FIFO)

의존성 감지

(GitHub의 하위 이슈 기능을 사용하는) 열린 상위 이슈가 있는 이슈는 0.1배 페널티와 함께 자동으로 우선순위가 낮아집니다. 이는 차단된 작업이 의존성이 해결될 때까지 백로그 하단으로 내려가도록 보장합니다. 상위 이슈가 닫히면 하위 이슈의 우선순위는 정상으로 돌아옵니다.

워크플로우 단계

selection: 이슈 선택 및 잠금
research: 문제 파악
branch: 기능 브랜치 생성
implementation: 코드 변경 진행 중
testing: 테스트 및 검증 실행
commit: 변경 사항 커밋
pr: 풀 리퀘스트 생성
review: 검토/병합 대기 중

데이터 저장소

모든 데이터는 로컬 ~/.mcp-git-issue-priority/에 저장됩니다:

~/.mcp-git-issue-priority/
├── locks/          # Active lock files (.lockdata)
├── workflow/       # Workflow state files (.json)
└── logs/           # Audit logs (JSON Lines format)

개발

빌드

npm run build

테스트

npm test

린트

npm run lint

타입 체크

npm run typecheck

릴리스 (관리자용)

1회성 설정

https://www.npmjs.com/ 에서 npm 계정 생성
https://www.npmjs.com/settings/tokens 로 이동
"Publish" 권한이 있는 "Automation" 토큰 생성
GitHub에 추가: Settings → Secrets → Actions → NPM_TOKEN이라는 이름의 새 시크릿 생성

릴리스 생성

# Patch release (bug fixes): 1.0.0 → 1.0.1
npm version patch -m "Release v%s"
git push && git push --tags

# Minor release (new features): 1.0.0 → 1.1.0
npm version minor -m "Release v%s"
git push && git push --tags

# Major release (breaking changes): 1.0.0 → 2.0.0
npm version major -m "Release v%s"
git push && git push --tags

태그를 푸시하면 다음을 수행하는 릴리스 워크플로우가 트리거됩니다:

린트, 빌드 및 테스트 실행
tarball이 첨부된 GitHub 릴리스 생성
npm 레지스트리에 게시

다운로드 추적

GitHub: 릴리스 페이지에서 .tgz 자산별 다운로드 수 확인 가능
npm: https://www.npmjs.com/package/mcp-git-issue-priority 에서 주간 다운로드 수 확인 가능

라이선스

MIT 라이선스 - 자세한 내용은 LICENSE를 참조하세요.

기여

기여를 환영합니다! 가이드라인은 CONTRIBUTING.md를 참조하세요.

피드백 및 지원

여러분의 의견을 기다립니다! 여러분의 피드백은 이 도구를 모두를 위해 개선하는 데 도움이 됩니다.

질문이나 아이디어가 있으신가요? 토론을 시작하세요
버그를 발견하셨나요? 이슈를 열어주세요
기능 요청? 제목에 [Feature]를 포함하여 이슈를 열어주세요
빠른 피드백? mcp-git-issue-priority --feedback을 실행하여 피드백 페이지를 여세요

새로운 이슈를 만들기 전에 기존 이슈를 먼저 확인해 주세요.

MCP GitHub 이슈 우선순위 서버

빠른 시작

주요 기능

설치

사전 요구 사항

npm을 통한 설치 (권장)

특정 버전 설치

소스에서 설치

문제 해결

구성

GitHub 인증

권장: GitHub CLI (자동)

대안: 환경 변수

Claude Code 구성

설치 확인

사용 가능한 도구

create_issue

select_next_issue

list_backlog

advance_workflow

get_workflow_status

release_lock

force_claim

sync_backlog_labels

get_pr_status

bulk_update_issues

implement_batch

batch_continue

get_workflow_analytics