issue-scribe-mcp

v1.3.0

Published

a month ago

MCP server for GitHub Issue/PR context aggregation

Downloads

0High
0Medium
0Low

gay00ung

mcp github issue pr

issue-scribe-mcp

npm version GitHub stars

GitHub Issue와 Pull Request의 전체 컨텍스트를 수집하고 관리하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop과 같은 AI 어시스턴트에서 GitHub 저장소의 Issue와 PR을 손쉽게 조회하고 생성할 수 있습니다.

✨ 주요 기능

🔍 고급 컨텍스트 조회: Issue/PR의 본문, 댓글, 커밋, 리뷰, 리뷰 코멘트, 변경 파일, CI 상태까지 수집
🔎 검색 고도화: GitHub Search API 기반 이슈/PR 검색 + qualifier 지원 (author:, label:, is: 등)
📄 페이지네이션 지원: page, per_page, fetch_all로 대규모 저장소 데이터 안정적 조회
🛡️ 안전 실행 모드: merge/delete 계열 작업에 dry_run, expected_*, confirm_token 보호장치
📝 Issue/PR 관리: 이슈 생성/수정, PR 생성, 코멘트/리액션, 라벨/브랜치 관리
🤖 AI 통합: Claude Desktop 등 MCP를 지원하는 AI 도구와 통합
🔐 간편 인증: GitHub Personal Access Token 기반 인증

📋 사전 준비

GitHub Personal Access Token 발급

GitHub에서 Personal Access Token 생성 페이지로 이동
Token 설정:
- Note: issue-scribe-mcp (또는 원하는 이름)
- Expiration: 원하는 만료 기간 선택
- Select scopes: 다음 권한 체크
  - ✅ repo (전체 저장소 접근)
  - ✅ read:org (조직 정보 읽기, 선택사항)
Generate token 클릭
생성된 토큰을 안전하게 복사 (다시 볼 수 없습니다!)

환경 변수 설정

프로젝트 루트에 .env 파일 생성:

GITHUB_TOKEN=your_github_personal_access_token_here

서버 실행 시 dotenv로 .env를 자동 로드합니다.

🚀 설치

NPM을 통한 전역 설치

npm install -g issue-scribe-mcp

🔄 업데이트

최신 버전으로 업데이트하려면:

npm update -g issue-scribe-mcp

또는 특정 버전으로 재설치:

npm install -g issue-scribe-mcp@latest

현재 설치된 버전 확인:

npm list -g issue-scribe-mcp

로컬 개발

# 저장소 클론
git clone https://github.com/gay00ung/issue-scribe-mcp.git
cd issue-scribe-mcp

# 의존성 설치
npm install

# 빌드
npm run build

# 테스트
npm test

# 환경변수 설정
cp .env.example .env
# .env 파일에 GitHub Token 입력

# 직접 실행
node dist/index.js

MCP Inspector로 테스트

로컬에서 MCP 서버를 테스트할 수 있는 간편한 스크립트를 제공합니다:

./test-local.sh

이 스크립트가 자동으로:

✅ .env 파일 로드
✅ GITHUB_TOKEN 확인
✅ 빌드 상태 확인
✅ MCP Inspector 실행 (브라우저 자동 열림)

MCP Inspector에서 GUI로 모든 Tool을 테스트하고 API 응답을 확인할 수 있습니다!

⚙️ MCP 클라이언트 설정

Claude Desktop 설정

Claude Desktop의 설정 파일(claude_desktop_config.json)에 다음 내용 추가:

Mac: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "issue-scribe": {
      "command": "node",
      "args": ["/path/to/issue-scribe-mcp/dist/index.js"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}

설정 후 Claude Desktop을 재시작하세요.

🛠️ 제공 Tools

공통 옵션

대부분의 목록/검색 Tool은 page, per_page, fetch_all을 지원합니다.
위험 작업(github_merge_pr, github_delete_comment, github_delete_branch, github_delete_label)은 dry_run을 지원하며, 실제 실행 시 confirm_token: "CONFIRM"이 필요합니다.
검색 Tool(github_search_issues, github_search_prs)은 qualifiers를 지원합니다 (예: author:octocat, label:bug, is:draft).

github_get_issue_context

GitHub Issue의 전체 컨텍스트를 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
issue_number (number, 필수): 이슈 번호
comments_page (number, 옵션): 댓글 페이지 번호
comments_per_page (number, 옵션): 댓글 페이지당 개수 (최대 100)
comments_fetch_all (boolean, 옵션): 모든 댓글 페이지 조회 여부 (기본: true)

반환 정보:

Issue 제목, 본문, 상태
작성자 및 담당자 정보
라벨, 마일스톤
모든 댓글 및 반응

github_get_pr_context

GitHub Pull Request의 전체 컨텍스트를 조회합니다 (커밋 포함).

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
pull_number (number, 필수): PR 번호
include_reviews (boolean, 옵션): 리뷰 정보 포함 여부 (기본: true)
include_review_comments (boolean, 옵션): 라인 리뷰 코멘트 포함 여부 (기본: true)
include_files (boolean, 옵션): 변경 파일 정보 포함 여부 (기본: true)
include_ci (boolean, 옵션): CI/check status 포함 여부 (기본: true)
page / per_page / fetch_all (옵션): PR 컨텍스트 내부 목록 페이지네이션

반환 정보:

PR 제목, 본문, 상태
소스/타겟 브랜치
커밋 목록 및 변경 파일
리뷰 댓글 및 승인 상태

github_create_issue

새로운 GitHub Issue를 생성합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
title (string, 필수): 이슈 제목
body (string, 옵션): 이슈 본문
labels (string[], 옵션): 라벨 배열
assignees (string[], 옵션): 담당자 배열

github_update_issue

기존 GitHub Issue를 수정합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
issue_number (number, 필수): 이슈 번호
title (string, 옵션): 새 제목
body (string, 옵션): 새 본문
state (string, 옵션): "open" 또는 "closed"
labels (string[], 옵션): 새 라벨 배열
assignees (string[], 옵션): 새 담당자 배열

github_create_pr

새로운 GitHub Pull Request를 생성합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
title (string, 필수): PR 제목
body (string, 옵션): PR 설명
head (string, 필수): 병합할 브랜치 (예: "feature-branch")
base (string, 필수): 병합 대상 브랜치 (예: "main")
draft (boolean, 옵션): Draft PR로 생성 여부
maintainer_can_modify (boolean, 옵션): 메인테이너 수정 허용 여부

github_add_comment

GitHub Issue 또는 Pull Request에 댓글을 추가합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
issue_number (number, 필수): Issue 또는 PR 번호
body (string, 필수): 댓글 내용

반환 정보:

댓글 ID, 내용, 작성자
댓글 URL 및 생성 시간

github_update_comment

기존 댓글을 수정합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
comment_id (number, 필수): 수정할 댓글 ID
body (string, 필수): 새로운 댓글 내용

github_delete_comment

댓글을 삭제합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
comment_id (number, 필수): 삭제할 댓글 ID
dry_run (boolean, 옵션): 실제 삭제 없이 미리보기
confirm_token (string, 옵션): 실제 삭제 시 "CONFIRM" 필요
expected_body_substring (string, 옵션): 댓글 본문 보호 조건 (부분 문자열 일치 시에만 삭제)

github_add_reaction

댓글 또는 Issue/PR에 이모지 반응을 추가합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
comment_id (number, 옵션): 반응을 추가할 댓글 ID
issue_number (number, 옵션): 반응을 추가할 Issue/PR 번호
reaction (string, 필수): 반응 종류
- thumbs_up 👍, thumbs_down 👎, laugh 😄, confused 😕, heart ❤️, hooray 🎉, rocket 🚀, eyes 👀

참고: comment_id 또는 issue_number 중 하나를 반드시 제공해야 합니다.

github_search_issues

GitHub Search API 기반으로 이슈를 검색합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
query (string, 옵션): 검색어
state (string, 옵션): "open", "closed", "all"
labels (string[], 옵션): 라벨 필터
qualifiers (string[], 옵션): 추가 검색 qualifier (예: author:octocat)
sort (string, 옵션): "created", "updated", "comments", "best-match"
direction (string, 옵션): "asc", "desc"
page / per_page / fetch_all (옵션): 페이지네이션

github_search_prs

GitHub Search API 기반으로 PR을 검색합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
query (string, 옵션): 검색어
state (string, 옵션): "open", "closed", "all"
qualifiers (string[], 옵션): 추가 검색 qualifier (예: author:octocat, is:draft)
sort (string, 옵션): "created", "updated", "comments", "best-match"
direction (string, 옵션): "asc", "desc"
page / per_page / fetch_all (옵션): 페이지네이션

github_list_recent_issues

최근 이슈 목록을 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
state (string, 옵션): "open", "closed", "all"
sort (string, 옵션): "created", "updated", "comments"
direction (string, 옵션): "asc", "desc"
page / per_page / fetch_all (옵션): 페이지네이션

github_merge_pr

PR을 머지합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
pull_number (number, 필수): PR 번호
merge_method (string, 옵션): "merge", "squash", "rebase"
commit_title (string, 옵션): 머지 커밋 제목
commit_message (string, 옵션): 머지 커밋 메시지
dry_run (boolean, 옵션): 실제 머지 없이 미리보기
expected_head_sha (string, 옵션): PR HEAD SHA 보호 조건
confirm_token (string, 옵션): 실제 머지 시 "CONFIRM" 필요

github_get_pr_diff

PR의 diff를 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
pull_number (number, 필수): PR 번호
max_chars (number, 옵션): diff 최대 출력 길이

github_get_pr_files

PR 변경 파일 목록을 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
pull_number (number, 필수): PR 번호
include_patch (boolean, 옵션): 파일별 patch 포함 여부
page / per_page / fetch_all (옵션): 페이지네이션

github_create_label

저장소에 새로운 라벨을 생성합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
name (string, 필수): 라벨 이름
color (string, 필수): 16진수 색상 코드 ('#' 제외, 예: 'FF0000')
description (string, 옵션): 라벨 설명

반환 정보:

라벨 이름, 색상, 설명
라벨 URL

github_update_label

기존 라벨의 이름, 색상, 설명을 수정합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
name (string, 필수): 수정할 라벨의 현재 이름
new_name (string, 옵션): 새로운 라벨 이름
color (string, 옵션): 새로운 16진수 색상 코드 ('#' 제외)
description (string, 옵션): 새로운 설명

github_delete_label

저장소에서 라벨을 삭제합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
name (string, 필수): 삭제할 라벨 이름
dry_run (boolean, 옵션): 실제 삭제 없이 미리보기
confirm_token (string, 옵션): 실제 삭제 시 "CONFIRM" 필요

github_list_labels

저장소의 모든 라벨 목록을 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
page (number, 옵션): 페이지 번호
per_page (number, 옵션): 페이지당 결과 수, 최대 100 (기본값: 30)
fetch_all (boolean, 옵션): 모든 페이지 조회 여부

반환 정보:

라벨 개수
각 라벨의 이름, 색상, 설명, URL

github_list_branches

저장소의 모든 브랜치 목록을 조회합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
protected (boolean, 옵션): 보호된 브랜치만 필터링
page (number, 옵션): 페이지 번호
per_page (number, 옵션): 페이지당 결과 수, 최대 100 (기본값: 30)
fetch_all (boolean, 옵션): 모든 페이지 조회 여부

반환 정보:

브랜치 개수
각 브랜치의 이름, 커밋 SHA, 보호 상태

github_create_branch

기존 브랜치 또는 커밋에서 새로운 브랜치를 생성합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
branch (string, 필수): 새 브랜치 이름
ref (string, 필수): 소스 브랜치 이름 또는 커밋 SHA (예: 'main' 또는 'abc123')

반환 정보:

브랜치 이름, ref, SHA
브랜치 URL

github_delete_branch

저장소에서 브랜치를 삭제합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
branch (string, 필수): 삭제할 브랜치 이름
dry_run (boolean, 옵션): 실제 삭제 없이 미리보기
expected_sha (string, 옵션): 브랜치 HEAD SHA 보호 조건
confirm_token (string, 옵션): 실제 삭제 시 "CONFIRM" 필요

github_compare_branches

두 브랜치 간의 차이를 비교합니다.

파라미터:

owner (string, 필수): 저장소 소유자
repo (string, 필수): 저장소 이름
base (string, 필수): 기준 브랜치 이름
head (string, 필수): 비교할 브랜치 이름
max_commits (number, 옵션): 응답에 포함할 최대 커밋 수
max_files (number, 옵션): 응답에 포함할 최대 파일 수

반환 정보:

비교 상태 (ahead/behind)
커밋 차이 개수
변경된 파일 목록 (추가/삭제/변경 라인 수)
커밋 목록

💡 사용 예시

Claude Desktop에서 사용하기

설정이 완료되면 Claude Desktop에서 다음과 같이 사용할 수 있습니다:

"gay00ung/issue-scribe-mcp 저장소의 5번 Issue를 확인해줘"

"issue-scribe-mcp에 새로운 Issue를 만들어줘. 
제목은 'README 개선' 이고 본문은 'Features 섹션 추가 필요'"

"PR #3의 커밋 내역을 보여줘"

Claude가 자동으로 적절한 MCP Tool을 호출하여 정보를 가져옵니다!

🔧 문제 해결

"GITHUB_TOKEN is not set" 오류

원인: GitHub Personal Access Token이 환경 변수로 설정되지 않았습니다.

해결:

.env 파일이 프로젝트 루트에 있는지 확인
.env 파일에 GITHUB_TOKEN=your_token 형식으로 작성되어 있는지 확인
Token이 유효한지 GitHub Settings에서 확인

"Bad credentials" 오류

원인: GitHub Token이 만료되었거나 잘못되었습니다.

해결:

GitHub에서 새 Personal Access Token 발급
.env 파일의 토큰을 업데이트
필요한 권한(repo scope)이 부여되었는지 확인

MCP 서버가 Claude Desktop에서 인식되지 않음

원인: 설정 파일 경로가 잘못되었거나 JSON 형식 오류가 있습니다.

해결:

claude_desktop_config.json 파일 위치 확인
JSON 형식이 올바른지 검증 (JSONLint 사용)
파일 경로가 절대 경로로 정확히 입력되었는지 확인
Claude Desktop 재시작

"Cannot find module" 오류

원인: 의존성이 설치되지 않았거나 빌드가 되지 않았습니다.

해결:

npm install
npm run build

📝 라이선스

MIT License

🤝 기여

이슈 리포트와 Pull Request를 환영합니다!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

📮 문의

프로젝트 링크: https://github.com/gay00ung/issue-scribe-mcp

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

issue-scribe-mcp

✨ 주요 기능

📋 사전 준비

GitHub Personal Access Token 발급

환경 변수 설정

🚀 설치

NPM을 통한 전역 설치

🔄 업데이트

로컬 개발

MCP Inspector로 테스트

⚙️ MCP 클라이언트 설정

Claude Desktop 설정

🛠️ 제공 Tools

공통 옵션

github_get_issue_context

github_get_pr_context

github_create_issue

github_update_issue

github_create_pr

github_add_comment

github_update_comment

github_delete_comment

github_add_reaction

github_search_issues

github_search_prs

github_list_recent_issues

github_merge_pr

github_get_pr_diff

github_get_pr_files

github_create_label

github_update_label

github_delete_label

github_list_labels

github_list_branches

github_create_branch

github_delete_branch

github_compare_branches

💡 사용 예시

Claude Desktop에서 사용하기

🔧 문제 해결

"GITHUB_TOKEN is not set" 오류

"Bad credentials" 오류

MCP 서버가 Claude Desktop에서 인식되지 않음

"Cannot find module" 오류

📝 라이선스

🤝 기여

📮 문의