issue-scribe-mcp 1.0.0 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 gay00ung
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,16 +1,59 @@
 # issue-scribe-mcp
 
-GitHub Issue/PR 컨텍스트를 수집하는 MCP 서버
+[![한국어](https://img.shields.io/badge/lang-한국어-blue.svg)](README.md)
+[![English](https://img.shields.io/badge/lang-English-red.svg)](README_EN.md)
 
-## 설치
+![npm version](https://img.shields.io/npm/v/issue-scribe-mcp.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![GitHub stars](https://img.shields.io/github/stars/gay00ung/issue-scribe-mcp.svg)
+
+> GitHub Issue와 Pull Request의 전체 컨텍스트를 수집하고 관리하는 MCP(Model Context Protocol) 서버입니다. Claude Desktop과 같은 AI 어시스턴트에서 GitHub 저장소의 Issue와 PR을 손쉽게 조회하고 생성할 수 있습니다.
+
+## ✨ 주요 기능
+
+- 🔍 **컨텍스트 조회**: Issue와 PR의 상세 정보, 댓글, 커밋 내역 등 전체 컨텍스트 수집
+- 📝 **Issue 관리**: 새로운 Issue 생성 및 기존 Issue 업데이트
+- 🔀 **PR 생성**: Pull Request 자동 생성 및 Draft PR 지원
+- 🤖 **AI 통합**: Claude Desktop 등 MCP를 지원하는 AI 도구와 완벽 통합
+- 🔐 **간편 인증**: GitHub Personal Access Token을 통한 안전한 API 접근
+
+## 📋 사전 준비
+
+### GitHub Personal Access Token 발급
+
+1. GitHub에서 [Personal Access Token 생성 페이지](https://github.com/settings/tokens/new)로 이동
+2. Token 설정:
+   - **Note**: `issue-scribe-mcp` (또는 원하는 이름)
+   - **Expiration**: 원하는 만료 기간 선택
+   - **Select scopes**: 다음 권한 체크
+     - ✅ `repo` (전체 저장소 접근)
+     - ✅ `read:org` (조직 정보 읽기, 선택사항)
+3. `Generate token` 클릭
+4. **생성된 토큰을 안전하게 복사** (다시 볼 수 없습니다!)
+
+### 환경 변수 설정
+
+프로젝트 루트에 `.env` 파일 생성:
+
+```bash
+GITHUB_TOKEN=your_github_personal_access_token_here
+```
+
+## 🚀 설치
+
+### NPM을 통한 전역 설치
 
 ```bash
 npm install -g issue-scribe-mcp
 ```
 
-## 로컬 개발
+### 로컬 개발
 
 ```bash
+# 저장소 클론
+git clone https://github.com/gay00ung/issue-scribe-mcp.git
+cd issue-scribe-mcp
+
 # 의존성 설치
 npm install
 
@@ -18,15 +61,37 @@ npm install
 npm run build
 
 # 환경변수 설정
-export GITHUB_TOKEN=your_github_token_here
+cp .env.example .env
+# .env 파일에 GitHub Token 입력
 
 # 직접 실행
 node dist/index.js
 ```
 
-## MCP 클라이언트 설정
+### MCP Inspector로 테스트
+
+로컬에서 MCP 서버를 테스트할 수 있는 간편한 스크립트를 제공합니다:
+
+```bash
+./test-local.sh
+```
+
+이 스크립트가 자동으로:
+- ✅ `.env` 파일 로드
+- ✅ `GITHUB_TOKEN` 확인
+- ✅ 빌드 상태 확인
+- ✅ **MCP Inspector 실행** (브라우저 자동 열림)
+
+MCP Inspector에서 GUI로 모든 Tool을 테스트하고 API 응답을 확인할 수 있습니다!
+
+## ⚙️ MCP 클라이언트 설정
+
+### Claude Desktop 설정
 
-Claude Desktop 등의 MCP 클라이언트에서 사용:
+Claude Desktop의 설정 파일(`claude_desktop_config.json`)에 다음 내용 추가:
+
+**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
 ```json
 {
@@ -42,56 +107,189 @@ Claude Desktop 등의 MCP 클라이언트에서 사용:
 }
 ```
 
-## 제공 Tools
+설정 후 Claude Desktop을 재시작하세요.
+
+## 🛠️ 제공 Tools
 
 ### github_get_issue_context
-GitHub Issue의 전체 컨텍스트 조회
+GitHub Issue의 전체 컨텍스트를 조회합니다.
 
-- owner: 저장소 소유자
-- repo: 저장소 이름
-- issue_number: 이슈 번호
+**파라미터:**
+- `owner` (string, 필수): 저장소 소유자
+- `repo` (string, 필수): 저장소 이름
+- `issue_number` (number, 필수): 이슈 번호
+
+**반환 정보:**
+- Issue 제목, 본문, 상태
+- 작성자 및 담당자 정보
+- 라벨, 마일스톤
+- 모든 댓글 및 반응
 
 ### github_get_pr_context
-GitHub Pull Request의 전체 컨텍스트 조회 (커밋 포함)
+GitHub Pull Request의 전체 컨텍스트를 조회합니다 (커밋 포함).
+
+**파라미터:**
+- `owner` (string, 필수): 저장소 소유자
+- `repo` (string, 필수): 저장소 이름
+- `pull_number` (number, 필수): PR 번호
 
-- owner: 저장소 소유자
-- repo: 저장소 이름
-- pull_number: PR 번호
+**반환 정보:**
+- PR 제목, 본문, 상태
+- 소스/타겟 브랜치
+- 커밋 목록 및 변경 파일
+- 리뷰 댓글 및 승인 상태
 
 ### github_create_issue
-새로운 GitHub Issue 생성
+새로운 GitHub Issue를 생성합니다.
 
-- owner: 저장소 소유자
-- repo: 저장소 이름
-- title: 이슈 제목 (필수)
-- body: 이슈 본문 (옵션)
-- labels: 라벨 배열 (옵션)
-- assignees: 담당자 배열 (옵션)
+**파라미터:**
+- `owner` (string, 필수): 저장소 소유자
+- `repo` (string, 필수): 저장소 이름
+- `title` (string, 필수): 이슈 제목
+- `body` (string, 옵션): 이슈 본문
+- `labels` (string[], 옵션): 라벨 배열
+- `assignees` (string[], 옵션): 담당자 배열
 
 ### github_update_issue
-기존 GitHub Issue 수정
+기존 GitHub Issue를 수정합니다.
 
-- owner: 저장소 소유자
-- repo: 저장소 이름
-- issue_number: 이슈 번호
-- title: 새 제목 (옵션)
-- body: 새 본문 (옵션)
-- state: "open" 또는 "closed" (옵션)
-- labels: 새 라벨 배열 (옵션)
-- assignees: 새 담당자 배열 (옵션)
+**파라미터:**
+- `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 생성
+새로운 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
+
+### 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` 중 하나를 반드시 제공해야 합니다.
+
+## 💡 사용 예시
+
+### 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이 환경 변수로 설정되지 않았습니다.
+
+**해결**:
+1. `.env` 파일이 프로젝트 루트에 있는지 확인
+2. `.env` 파일에 `GITHUB_TOKEN=your_token` 형식으로 작성되어 있는지 확인
+3. Token이 유효한지 [GitHub Settings](https://github.com/settings/tokens)에서 확인
+
+### "Bad credentials" 오류
+
+**원인**: GitHub Token이 만료되었거나 잘못되었습니다.
+
+**해결**:
+1. GitHub에서 새 Personal Access Token 발급
+2. `.env` 파일의 토큰을 업데이트
+3. 필요한 권한(`repo` scope)이 부여되었는지 확인
+
+### MCP 서버가 Claude Desktop에서 인식되지 않음
+
+**원인**: 설정 파일 경로가 잘못되었거나 JSON 형식 오류가 있습니다.
+
+**해결**:
+1. `claude_desktop_config.json` 파일 위치 확인
+2. JSON 형식이 올바른지 검증 ([JSONLint](https://jsonlint.com/) 사용)
+3. 파일 경로가 절대 경로로 정확히 입력되었는지 확인
+4. Claude Desktop 재시작
+
+### "Cannot find module" 오류
+
+**원인**: 의존성이 설치되지 않았거나 빌드가 되지 않았습니다.
+
+**해결**:
+```bash
+npm install
+npm run build
+```
+
+## 📝 라이선스
+
+MIT License
+
+## 🤝 기여
+
+이슈 리포트와 Pull Request를 환영합니다!
 
-- owner: 저장소 소유자
-- repo: 저장소 이름
-- title: PR 제목 (필수)
-- body: PR 설명 (옵션)
-- head: 병합할 브랜치 (필수, 예: "feature-branch")
-- base: 병합 대상 브랜치 (필수, 예: "main")
-- draft: Draft PR로 생성 (옵션)
-- maintainer_can_modify: 메인테이너 수정 허용 (옵션)
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
 
-## 라이선스
+## 📮 문의
 
-ISC
+프로젝트 링크: [https://github.com/gay00ung/issue-scribe-mcp](https://github.com/gay00ung/issue-scribe-mcp)

package/README_EN.md

@@ -0,0 +1,297 @@
+# issue-scribe-mcp
+
+[![한국어](https://img.shields.io/badge/lang-한국어-blue.svg)](README.md)
+[![English](https://img.shields.io/badge/lang-English-red.svg)](README_EN.md)
+
+![npm version](https://img.shields.io/npm/v/issue-scribe-mcp.svg)
+![License](https://img.shields.io/badge/license-MIT-green.svg)
+![GitHub stars](https://img.shields.io/github/stars/gay00ung/issue-scribe-mcp.svg)
+
+> An MCP (Model Context Protocol) server for collecting and managing GitHub Issue and Pull Request contexts. Easily query and create Issues and PRs from AI assistants like Claude Desktop.
+
+## ✨ 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
+- 🤖 **AI Integration**: Seamless integration with MCP-compatible AI tools like Claude Desktop
+- 🔐 **Simple Authentication**: Secure API access via GitHub Personal Access Token
+
+## 📋 Prerequisites
+
+### GitHub Personal Access Token Setup
+
+1. Navigate to [GitHub Personal Access Token creation page](https://github.com/settings/tokens/new)
+2. Configure token settings:
+   - **Note**: `issue-scribe-mcp` (or your preferred name)
+   - **Expiration**: Select desired expiration period
+   - **Select scopes**: Check the following permissions
+     - ✅ `repo` (Full repository access)
+     - ✅ `read:org` (Read organization info, optional)
+3. Click `Generate token`
+4. **Safely copy the generated token** (you won't be able to see it again!)
+
+### Environment Variable Setup
+
+Create a `.env` file in the project root:
+
+```bash
+GITHUB_TOKEN=your_github_personal_access_token_here
+```
+
+## 🚀 Installation
+
+### Global Installation via NPM
+
+```bash
+npm install -g issue-scribe-mcp
+```
+
+### Local Development
+
+```bash
+# Clone repository
+git clone https://github.com/gay00ung/issue-scribe-mcp.git
+cd issue-scribe-mcp
+
+# Install dependencies
+npm install
+
+# Build
+npm run build
+
+# Set up environment variables
+cp .env.example .env
+# Add your GitHub Token to .env file
+
+# Run directly
+node dist/index.js
+```
+
+### Test with MCP Inspector
+
+We provide a convenient script to test the MCP server locally:
+
+```bash
+./test-local.sh
+```
+
+This script automatically:
+- ✅ Loads `.env` file
+- ✅ Verifies `GITHUB_TOKEN`
+- ✅ Checks build status
+- ✅ **Launches MCP Inspector** (opens browser automatically)
+
+You can test all Tools with a GUI and inspect API responses in MCP Inspector!
+
+## ⚙️ MCP Client Configuration
+
+### Claude Desktop Setup
+
+Add the following to Claude Desktop's configuration file (`claude_desktop_config.json`):
+
+**Mac**: `~/Library/Application Support/Claude/claude_desktop_config.json`  
+**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "issue-scribe": {
+      "command": "node",
+      "args": ["/path/to/issue-scribe-mcp/dist/index.js"],
+      "env": {
+        "GITHUB_TOKEN": "your_github_token_here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop after configuration.
+
+## 🛠️ Available Tools
+
+### github_get_issue_context
+Retrieve full context of a GitHub Issue.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `issue_number` (number, required): Issue number
+
+**Returns:**
+- Issue title, body, state
+- Author and assignee information
+- Labels, milestones
+- All comments and reactions
+
+### github_get_pr_context
+Retrieve full context of a GitHub Pull Request (including commits).
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `pull_number` (number, required): PR number
+
+**Returns:**
+- PR title, body, state
+- Source/target branches
+- Commit list and changed files
+- Review comments and approval status
+
+### github_create_issue
+Create a new GitHub Issue.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `title` (string, required): Issue title
+- `body` (string, optional): Issue body
+- `labels` (string[], optional): Array of labels
+- `assignees` (string[], optional): Array of assignees
+
+### github_update_issue
+Update an existing GitHub Issue.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `issue_number` (number, required): Issue number
+- `title` (string, optional): New title
+- `body` (string, optional): New body
+- `state` (string, optional): `"open"` or `"closed"`
+- `labels` (string[], optional): New labels array
+- `assignees` (string[], optional): New assignees array
+
+### github_create_pr
+Create a new GitHub Pull Request.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `title` (string, required): PR title
+- `body` (string, optional): PR description
+- `head` (string, required): Branch to merge from (e.g., `"feature-branch"`)
+- `base` (string, required): Branch to merge into (e.g., `"main"`)
+- `draft` (boolean, optional): Create as draft PR
+- `maintainer_can_modify` (boolean, optional): Allow maintainer modifications
+
+---
+
+### github_add_comment
+Add a comment to a GitHub Issue or Pull Request.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `issue_number` (number, required): Issue or PR number
+- `body` (string, required): Comment body text
+
+**Returns:**
+- Comment ID, body, author
+- Comment URL and creation time
+
+### github_update_comment
+Update an existing comment.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `comment_id` (number, required): Comment ID to update
+- `body` (string, required): New comment body text
+
+### github_delete_comment
+Delete a comment.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `comment_id` (number, required): Comment ID to delete
+
+### github_add_reaction
+Add an emoji reaction to a comment or directly to an issue/PR.
+
+**Parameters:**
+- `owner` (string, required): Repository owner
+- `repo` (string, required): Repository name
+- `comment_id` (number, optional): Comment ID to react to
+- `issue_number` (number, optional): Issue/PR number to react to
+- `reaction` (string, required): Reaction type
+  - `thumbs_up` 👍, `thumbs_down` 👎, `laugh` 😄, `confused` 😕, `heart` ❤️, `hooray` 🎉, `rocket` 🚀, `eyes` 👀
+
+**Note**: Either `comment_id` OR `issue_number` must be provided.
+
+## 💡 Usage Examples
+
+### Using with Claude Desktop
+
+Once configured, you can use it in Claude Desktop like this:
+
+```
+"Check issue #5 in the gay00ung/issue-scribe-mcp repository"
+
+"Create a new issue in issue-scribe-mcp. 
+Title is 'Improve README' and body is 'Need to add Features section'"
+
+"Show me the commit history of PR #3"
+```
+
+Claude will automatically call the appropriate MCP tools to fetch the information!
+
+## 🔧 Troubleshooting
+
+### "GITHUB_TOKEN is not set" Error
+
+**Cause**: GitHub Personal Access Token is not set as an environment variable.
+
+**Solution**:
+1. Check if `.env` file exists in project root
+2. Verify `.env` file is formatted as `GITHUB_TOKEN=your_token`
+3. Confirm token is valid in [GitHub Settings](https://github.com/settings/tokens)
+
+### "Bad credentials" Error
+
+**Cause**: GitHub Token is expired or invalid.
+
+**Solution**:
+1. Generate a new Personal Access Token from GitHub
+2. Update the token in `.env` file
+3. Verify required permissions (`repo` scope) are granted
+
+### MCP Server Not Recognized in Claude Desktop
+
+**Cause**: Configuration file path is incorrect or JSON format error.
+
+**Solution**:
+1. Verify `claude_desktop_config.json` file location
+2. Validate JSON format using [JSONLint](https://jsonlint.com/)
+3. Ensure file paths are absolute and correct
+4. Restart Claude Desktop
+
+### "Cannot find module" Error
+
+**Cause**: Dependencies are not installed or build has not been run.
+
+**Solution**:
+```bash
+npm install
+npm run build
+```
+
+## 📝 License
+
+MIT License
+
+## 🤝 Contributing
+
+Issue reports and Pull Requests are welcome!
+
+1. Fork the Project
+2. Create your Feature Branch (`git checkout -b feature/AmazingFeature`)
+3. Commit your Changes (`git commit -m 'Add some AmazingFeature'`)
+4. Push to the Branch (`git push origin feature/AmazingFeature`)
+5. Open a Pull Request
+
+## 📮 Contact
+
+Project Link: [https://github.com/gay00ung/issue-scribe-mcp](https://github.com/gay00ung/issue-scribe-mcp)