issue-scribe-mcp 1.2.0 → 1.3.0

package/.github/workflows/ci.yml

@@ -0,0 +1,29 @@
+name: CI
+
+on:
+  push:
+    branches: ["**"]
+  pull_request:
+
+jobs:
+  build-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: "20"
+          cache: npm
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Build
+        run: npm run build
+
+      - name: Run tests
+        run: npm test

package/README.md

@@ -11,11 +11,13 @@
 
 ## ✨ 주요 기능
 
-- 🔍 **컨텍스트 조회**: Issue와 PR의 상세 정보, 댓글, 커밋 내역 등 전체 컨텍스트 수집
-- 📝 **Issue 관리**: 새로운 Issue 생성 및 기존 Issue 업데이트
-- 🔀 **PR 생성**: Pull Request 자동 생성 및 Draft PR 지원
-- 🤖 **AI 통합**: Claude Desktop 등 MCP를 지원하는 AI 도구와 완벽 통합
-- 🔐 **간편 인증**: GitHub Personal Access Token을 통한 안전한 API 접근
+- 🔍 **고급 컨텍스트 조회**: 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 기반 인증
 
 ## 📋 사전 준비
 
@@ -39,6 +41,8 @@
 GITHUB_TOKEN=your_github_personal_access_token_here
 ```
 
+서버 실행 시 `dotenv`로 `.env`를 자동 로드합니다.
+
 ## 🚀 설치
 
 ### NPM을 통한 전역 설치
@@ -80,6 +84,9 @@ npm install
 # 빌드
 npm run build
 
+# 테스트
+npm test
+
 # 환경변수 설정
 cp .env.example .env
 # .env 파일에 GitHub Token 입력
@@ -131,6 +138,11 @@ Claude Desktop의 설정 파일(`claude_desktop_config.json`)에 다음 내용
 
 ## 🛠️ 제공 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의 전체 컨텍스트를 조회합니다.
 
@@ -138,6 +150,9 @@ GitHub Issue의 전체 컨텍스트를 조회합니다.
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
 - `issue_number` (number, 필수): 이슈 번호
+- `comments_page` (number, 옵션): 댓글 페이지 번호
+- `comments_per_page` (number, 옵션): 댓글 페이지당 개수 (최대 100)
+- `comments_fetch_all` (boolean, 옵션): 모든 댓글 페이지 조회 여부 (기본: `true`)
 
 **반환 정보:**
 - Issue 제목, 본문, 상태
@@ -152,6 +167,11 @@ 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 제목, 본문, 상태
@@ -225,6 +245,9 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
 - `comment_id` (number, 필수): 삭제할 댓글 ID
+- `dry_run` (boolean, 옵션): 실제 삭제 없이 미리보기
+- `confirm_token` (string, 옵션): 실제 삭제 시 `"CONFIRM"` 필요
+- `expected_body_substring` (string, 옵션): 댓글 본문 보호 조건 (부분 문자열 일치 시에만 삭제)
 
 ### github_add_reaction
 댓글 또는 Issue/PR에 이모지 반응을 추가합니다.
@@ -239,6 +262,77 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 
 **참고**: `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
 저장소에 새로운 라벨을 생성합니다.
 
@@ -271,6 +365,8 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
 - `name` (string, 필수): 삭제할 라벨 이름
+- `dry_run` (boolean, 옵션): 실제 삭제 없이 미리보기
+- `confirm_token` (string, 옵션): 실제 삭제 시 `"CONFIRM"` 필요
 
 ### github_list_labels
 저장소의 모든 라벨 목록을 조회합니다.
@@ -278,7 +374,9 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 **파라미터:**
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
+- `page` (number, 옵션): 페이지 번호
 - `per_page` (number, 옵션): 페이지당 결과 수, 최대 100 (기본값: 30)
+- `fetch_all` (boolean, 옵션): 모든 페이지 조회 여부
 
 **반환 정보:**
 - 라벨 개수
@@ -291,7 +389,9 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
 - `protected` (boolean, 옵션): 보호된 브랜치만 필터링
+- `page` (number, 옵션): 페이지 번호
 - `per_page` (number, 옵션): 페이지당 결과 수, 최대 100 (기본값: 30)
+- `fetch_all` (boolean, 옵션): 모든 페이지 조회 여부
 
 **반환 정보:**
 - 브랜치 개수
@@ -317,6 +417,9 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 - `owner` (string, 필수): 저장소 소유자
 - `repo` (string, 필수): 저장소 이름
 - `branch` (string, 필수): 삭제할 브랜치 이름
+- `dry_run` (boolean, 옵션): 실제 삭제 없이 미리보기
+- `expected_sha` (string, 옵션): 브랜치 HEAD SHA 보호 조건
+- `confirm_token` (string, 옵션): 실제 삭제 시 `"CONFIRM"` 필요
 
 ### github_compare_branches
 두 브랜치 간의 차이를 비교합니다.
@@ -326,6 +429,8 @@ GitHub Issue 또는 Pull Request에 댓글을 추가합니다.
 - `repo` (string, 필수): 저장소 이름
 - `base` (string, 필수): 기준 브랜치 이름
 - `head` (string, 필수): 비교할 브랜치 이름
+- `max_commits` (number, 옵션): 응답에 포함할 최대 커밋 수
+- `max_files` (number, 옵션): 응답에 포함할 최대 파일 수
 
 **반환 정보:**
 - 비교 상태 (ahead/behind)

package/README_EN.md

@@ -11,9 +11,11 @@
 
 ## ✨ Features
 
-- 🔍 **Context Retrieval**: Collect complete context including issue/PR details, comments, and commit history
-- 📝 **Issue Management**: Create new issues and update existing ones
-- 🔀 **PR Creation**: Automatically create Pull Requests with Draft PR support
+- 🔍 **Deep Context Retrieval**: Collect issue/PR body, comments, commits, reviews, review comments, changed files, and CI status
+- 🔎 **Advanced Search**: Search issues/PRs through GitHub Search API with custom qualifiers (`author:`, `label:`, `is:`, etc.)
+- 📄 **Pagination Support**: Use `page`, `per_page`, and `fetch_all` for large repositories
+- 🛡️ **Safe Execution Mode**: `dry_run`, `expected_*`, and `confirm_token` safeguards for merge/delete operations
+- 📝 **Issue/PR Management**: Create/update issues, create PRs, manage comments/reactions/labels/branches
 - 🤖 **AI Integration**: Seamless integration with MCP-compatible AI tools like Claude Desktop
 - 🔐 **Simple Authentication**: Secure API access via GitHub Personal Access Token
 
@@ -39,6 +41,8 @@ Create a `.env` file in the project root:
 GITHUB_TOKEN=your_github_personal_access_token_here
 ```
 
+The server automatically loads `.env` via `dotenv` at startup.
+
 ## 🚀 Installation
 
 ### Global Installation via NPM
@@ -80,6 +84,9 @@ npm install
 # Build
 npm run build
 
+# Test
+npm test
+
 # Set up environment variables
 cp .env.example .env
 # Add your GitHub Token to .env file
@@ -131,6 +138,11 @@ Restart Claude Desktop after configuration.
 
 ## 🛠️ Available Tools
 
+### Shared Options
+- Most list/search tools support `page`, `per_page`, and `fetch_all`.
+- Risky operations (`github_merge_pr`, `github_delete_comment`, `github_delete_branch`, `github_delete_label`) support `dry_run`; live execution requires `confirm_token: "CONFIRM"`.
+- Search tools (`github_search_issues`, `github_search_prs`) support `qualifiers` (for example `author:octocat`, `label:bug`, `is:draft`).
+
 ### github_get_issue_context
 Retrieve full context of a GitHub Issue.
 
@@ -138,6 +150,9 @@ Retrieve full context of a GitHub Issue.
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `issue_number` (number, required): Issue number
+- `comments_page` (number, optional): Comment page number
+- `comments_per_page` (number, optional): Comments per page (max 100)
+- `comments_fetch_all` (boolean, optional): Fetch all comment pages (default: `true`)
 
 **Returns:**
 - Issue title, body, state
@@ -152,6 +167,11 @@ Retrieve full context of a GitHub Pull Request (including commits).
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `pull_number` (number, required): PR number
+- `include_reviews` (boolean, optional): Include reviews + approval summary (default: `true`)
+- `include_review_comments` (boolean, optional): Include line-level review comments (default: `true`)
+- `include_files` (boolean, optional): Include changed files (default: `true`)
+- `include_ci` (boolean, optional): Include CI/check status (default: `true`)
+- `page` / `per_page` / `fetch_all` (optional): Pagination for PR context collections
 
 **Returns:**
 - PR title, body, state
@@ -227,6 +247,9 @@ Delete a comment.
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `comment_id` (number, required): Comment ID to delete
+- `dry_run` (boolean, optional): Preview deletion without executing
+- `confirm_token` (string, optional): Required as `"CONFIRM"` for live deletion
+- `expected_body_substring` (string, optional): Guard condition; delete only if body contains this substring
 
 ### github_add_reaction
 Add an emoji reaction to a comment or directly to an issue/PR.
@@ -241,6 +264,77 @@ Add an emoji reaction to a comment or directly to an issue/PR.
 
 **Note**: Either `comment_id` OR `issue_number` must be provided.
 
+### github_search_issues
+Search repository issues using GitHub Search API.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `query` (string, optional): Search text
+- `state` (string, optional): `"open"`, `"closed"`, `"all"`
+- `labels` (string[], optional): Label filters
+- `qualifiers` (string[], optional): Extra qualifiers (for example `author:octocat`)
+- `sort` (string, optional): `"created"`, `"updated"`, `"comments"`, `"best-match"`
+- `direction` (string, optional): `"asc"`, `"desc"`
+- `page` / `per_page` / `fetch_all` (optional): Pagination controls
+
+### github_search_prs
+Search repository pull requests using GitHub Search API.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `query` (string, optional): Search text
+- `state` (string, optional): `"open"`, `"closed"`, `"all"`
+- `qualifiers` (string[], optional): Extra qualifiers (for example `author:octocat`, `is:draft`)
+- `sort` (string, optional): `"created"`, `"updated"`, `"comments"`, `"best-match"`
+- `direction` (string, optional): `"asc"`, `"desc"`
+- `page` / `per_page` / `fetch_all` (optional): Pagination controls
+
+### github_list_recent_issues
+List recent issues in a repository.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `state` (string, optional): `"open"`, `"closed"`, `"all"`
+- `sort` (string, optional): `"created"`, `"updated"`, `"comments"`
+- `direction` (string, optional): `"asc"`, `"desc"`
+- `page` / `per_page` / `fetch_all` (optional): Pagination controls
+
+### github_merge_pr
+Merge a pull request.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `pull_number` (number, required): PR number
+- `merge_method` (string, optional): `"merge"`, `"squash"`, `"rebase"`
+- `commit_title` (string, optional): Merge commit title
+- `commit_message` (string, optional): Merge commit message
+- `dry_run` (boolean, optional): Preview merge without executing
+- `expected_head_sha` (string, optional): Guard condition for PR head SHA
+- `confirm_token` (string, optional): Required as `"CONFIRM"` for live merge
+
+### github_get_pr_diff
+Get the PR diff.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `pull_number` (number, required): PR number
+- `max_chars` (number, optional): Maximum diff length in characters
+
+### github_get_pr_files
+List PR changed files.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `pull_number` (number, required): PR number
+- `include_patch` (boolean, optional): Include patch text per file
+- `page` / `per_page` / `fetch_all` (optional): Pagination controls
+
 ### github_create_label
 Create a new label in the repository.
 
@@ -273,6 +367,8 @@ Delete a label from the repository.
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `name` (string, required): Label name to delete
+- `dry_run` (boolean, optional): Preview deletion without executing
+- `confirm_token` (string, optional): Required as `"CONFIRM"` for live deletion
 
 ### github_list_labels
 List all labels in the repository.
@@ -280,7 +376,9 @@ List all labels in the repository.
 **Parameters:**
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
+- `page` (number, optional): Page number
 - `per_page` (number, optional): Results per page, max 100 (default: 30)
+- `fetch_all` (boolean, optional): Fetch all pages
 
 **Returns:**
 - Label count
@@ -293,7 +391,9 @@ List all branches in the repository.
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `protected` (boolean, optional): Filter by protected status
+- `page` (number, optional): Page number
 - `per_page` (number, optional): Results per page, max 100 (default: 30)
+- `fetch_all` (boolean, optional): Fetch all pages
 
 **Returns:**
 - Branch count
@@ -319,6 +419,9 @@ Delete a branch from the repository.
 - `owner` (string, required): Repository owner
 - `repo` (string, required): Repository name
 - `branch` (string, required): Branch name to delete
+- `dry_run` (boolean, optional): Preview deletion without executing
+- `expected_sha` (string, optional): Guard condition for branch HEAD SHA
+- `confirm_token` (string, optional): Required as `"CONFIRM"` for live deletion
 
 ### github_compare_branches
 Compare two branches and show the differences.
@@ -328,6 +431,8 @@ Compare two branches and show the differences.
 - `repo` (string, required): Repository name
 - `base` (string, required): Base branch name
 - `head` (string, required): Head branch name to compare
+- `max_commits` (number, optional): Maximum commits returned in response
+- `max_files` (number, optional): Maximum files returned in response
 
 **Returns:**
 - Comparison status (ahead/behind)