mcp-gh-pr-mini

mcp-gh-pr-mini

一个用于通过双重身份验证与 GitHub 拉取请求交互的简易 MCP（Model Context Protocol）服务。

此工具支持通过 MCP 在 GitHub 仓库中创建、列出、查看详情和差异、请求审阅者，以及对拉取请求发表评论。它支持个人访问令牌（PAT）和 GitHub CLI 两种身份验证方式。

最新版本：1.4.0 —— 新增通过 draft 参数创建草稿 PR 的支持。

✨ 功能

🎯 可用的 MCP 工具

create_pull_request

在 GitHub 仓库中创建新的拉取请求。

• 参数：owner、repo、title、body、head（源分支）、base（目标分支）、draft（可选）
• 返回：PR 编号和 URL，可立即访问
• 功能：
  • ✅ 创建可供审阅的 PR（默认）
  • ✅ 使用 draft: true 创建草稿 PR 🆕 v1.4.0
  • ✅ 在成功消息中显示草稿状态
• 已测试：✅ PAT 和 GitHub CLI 身份验证方式均可正常使用

update_pull_request

更新 GitHub 仓库中已有的拉取请求。

• 参数：owner、repo、pr_number，以及可选的 title、body、base、state（open/closed）
• 返回：已更新的 PR 详情和确认信息
• 功能：
  • ✅ 更新标题和描述
  • ✅ 更改目标分支（base）
  • ✅ 打开或关闭拉取请求
  • ✅ 部分更新（仅修改指定字段）
• 已测试：✅ 可成功更新 PR 元数据和状态

list_open_pull_requests

列出仓库中所有未关闭的拉取请求。

• 参数：owner、repo、可选的 limit（默认值：10）
• 返回：PR 编号、标题、作者和 URL
• 已测试：✅ 能妥善处理没有未关闭 PR 的仓库

get_pull_request 🆕 v1.3.0

获取特定拉取请求的详细信息。

• 参数：owner、repo、pr_number
• 返回：PR 标题、描述、状态、作者、分支和元数据
• 功能：
  • ✅ 获取完整的 PR 详情，包括标题和正文
  • ✅ 显示 PR 状态、作者和分支信息
  • ✅ 显示创建和更新时间戳
  • ✅ 提供 PR 的直接 URL
• 使用场景：类似于 gh pr view {pr_number} --repo {owner/repository} --json title,body
• 已测试：✅ 17 项全面的单元测试覆盖所有边界情况

get_pull_request_diff

获取拉取请求的统一差异。

• 参数：owner、repo、pr_number
• 返回：以统一格式显示所有文件变更的完整差异
• 已测试：✅ 能正确格式化新增、修改和删除文件的差异

request_reviewers

为已有的拉取请求添加审阅者。

• 参数：owner、repo、pr_number、reviewers（GitHub 用户名数组）
• 返回：审阅者分配确认信息
• 已测试：✅ 可成功为拉取请求分配审阅者

add_pr_comment

在拉取请求的讨论中添加普通评论。

• 参数：owner、repo、pr_number、body（评论文本）
• 返回：评论 ID 和 URL，供后续查阅
• 特殊功能：
  • ✅ 自动为评论添加前缀「[AI] Generated using MCP」
  • ✅ 已通过两种身份验证方式测试

add_review_comment

在变更文件的特定行（或差异位置）添加代码审阅评论。

• 参数：owner、repo、pr_number、body、path（文件路径），以及以下选项之一：
  • line（首选）：文件行号；还可指定可选的 side（LEFT/RIGHT，默认值为 RIGHT），以及用于多行评论的 start_line/start_side
  • position（已弃用）：差异中的偏移量——保留以确保向后兼容
  • subject_type: "file"：当目标行位于差异代码块之外时，用于添加文件级评论（省略 line/position）
• 返回：审阅评论 ID 和 URL
• 已测试：✅ 可通过行号、差异位置和文件级评论成功添加代码行内评论

get_pr_comments

获取拉取请求中的所有评论。

• 参数：owner、repo、pr_number
• 返回：按类别整理的对话评论和审查评论列表
• 功能：
  • ✅ 将常规 PR 评论与代码审查评论分开
  • ✅ 显示评论元数据（作者、日期、URL）
  • ✅ 显示 AI 生成的评论标识符

get_pr_changes_for_commenting

获取可用于添加审查评论的文件更改及其位置。

• 参数：owner、repo、pr_number
• 返回：包含可评论位置的详细文件更改
• 功能：
  • ✅ 列出所有已更改文件及其状态（新增、修改、删除）
  • ✅ 提供行内评论的准确位置编号
  • ✅ 显示每个文件的完整补丁信息

身份验证方式 🔐

• 个人访问令牌（PAT）：传统的基于令牌的身份验证
• GitHub CLI：使用现有的 gh CLI 身份验证
• 自动检测：自动选择最佳的可用身份验证方式
• 智能回退：一种身份验证方式失败时，无缝切换到另一种方式
  • 首选：PAT 身份验证（如果已配置）
  • 回退：GitHub CLI 身份验证（如果可用）
  • 身份验证失败时无需用户干预
  • 在不同身份验证方式下保持 API 响应一致

🛠️ 设置

此工具在本地环境中以 MCP 服务的形式运行。 你可以将它与 Copilot Agent 等工具或任何兼容 MCP 的客户端搭配使用。

要求

• 已安装 Node.js
• 安装了兼容 MCP 扩展的 VSCode（例如 Copilot Agent）

🔐 身份验证系统

推荐：GitHub CLI 身份验证

gh auth login  # One-time setup
npx mcp-gh-pr-mini  # Works immediately

替代方式：个人访问令牌

如果你更倾向于使用 PAT 身份验证，请设置环境变量 GITHUB_PERSONAL_ACCESS_TOKEN。

所需的 PAT 权限：

权限	访问级别
拉取请求	读取和写入
问题	读取和写入
元数据	读取（自动）

在 settings.json 中配置

使用 GitHub CLI 身份验证

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"]
    }
  }
}

使用个人访问令牌

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "{Your Fine-Grained GitHub Token}"
      }
    }
  }
}

🔐 身份验证详情

双重身份验证系统

此 MCP 服务采用智能双重身份验证系统，可自动检测并使用最佳的可用身份验证方式：

GitHub CLI（推荐）⭐

• 无缝集成：使用现有的 GitHub CLI 身份验证
• 全面支持：适用于所有 GitHub CLI 身份验证方式（OAuth、PAT、SSH）
• 零配置：在执行 gh auth login 后无需额外配置令牌
• 适用于企业：全面支持组织 SSO 和 SAML
• 自动检测：服务会检测 GitHub CLI 是否可用以及其身份验证状态

个人访问令牌（替代方式）

• 直接访问 API：使用 GitHub 的 REST API 和个人访问令牌
• 精细控制：支持精细粒度的个人访问令牌，以精确设置权限
• 所需权限：
  • 拉取请求：读取和写入
  • 问题：读取和写入
  • 内容：读取和写入
• 可用作回退：GitHub CLI 不可用时自动使用

身份验证流程 🔄

1. 检测阶段：服务启动时检查可用的身份验证方式
2. 优先级选择：为保持一致性，优先使用个人访问令牌（如果已配置）
3. 自动回退：如果 PAT 失败或无效，则自动切换到 GitHub CLI
4. 透明运行：用户不会看到身份验证错误；回退过程会无缝完成
5. 一致的体验：无论使用哪种身份验证方式，所有 MCP 工具的工作方式都相同

已测试场景 ✅

• ✅ 仅使用 PAT：使用有效的个人访问令牌时可正常工作
• ✅ 仅使用 GitHub CLI：仅使用 GitHub CLI 身份验证时可正常工作
• ✅ 自动回退：从无效 PAT 无缝切换到 GitHub CLI
• ✅ 混合环境：可处理其中一种方式不可用的场景
• ✅ 错误恢复：身份验证失败时可平稳处理，不会干扰用户

🚀 使用示例

基本工作流示例

// 1. Create a pull request
create_pull_request({
  owner: "username",
  repo: "repository",
  title: "Add new feature",
  body: "Description of the changes",
  head: "feature-branch",
  base: "main"
})

// 1a. Create a draft pull request (NEW in v1.4.0)
create_pull_request({
  owner: "username",
  repo: "repository",
  title: "WIP: Add new feature",
  body: "Work in progress - not ready for review yet",
  head: "feature-branch",
  base: "main",
  draft: true  // Creates as draft PR
})

// 1.5. Get PR details to review information
get_pull_request({
  owner: "username",
  repo: "repository",
  pr_number: 1
})

// 1.6. Update the pull request if needed
update_pull_request({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  title: "Add new feature (updated)",
  body: "Updated description with more details"
})

// 2. Get the diff to review changes
get_pull_request_diff({
  owner: "username",
  repo: "repository", 
  pr_number: 1
})

// 3. Add a general comment
add_pr_comment({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  body: "This looks great! Just a few small suggestions."
})

// 4. Add a specific code review comment (line is preferred over position)
add_review_comment({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  body: "Consider using const instead of let here for immutability.",
  path: "src/index.ts",
  line: 42
})

// 5. Request reviewers
request_reviewers({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  reviewers: ["reviewer1", "reviewer2"]
})

处理评论

// Get all comments to review feedback
get_pr_comments({
  owner: "username",
  repo: "repository",
  pr_number: 1
})

// Get file changes to find reviewable positions
get_pr_changes_for_commenting({
  owner: "username", 
  repo: "repository",
  pr_number: 1
})
// Returns positions where you can add review comments

仓库管理

// List all open PRs to get an overview
list_open_pull_requests({
  owner: "username",
  repo: "repository",
  limit: 5
})

💡 最佳实践

身份验证设置

1. 使用 GitHub CLI 以图方便：运行一次 gh auth login，之后就无需再操心令牌
2. 在 CI/CD 中使用 PAT：在自动化环境中使用个人访问令牌
3. 测试身份验证：使用工具前，通过 gh auth status 验证

评论管理

• AI 标识：所有 AI 生成的评论都会自动添加前缀「[AI] Generated using MCP」
• 针对特定行的评论：优先使用 line（文件中的实际行号），而不是已弃用的 position（差异偏移量）——这样就无需重新统计差异块
• 差异块外行的回退方式：如果某行位于差异块之外，请使用 subject_type: "file" 添加文件级评论
• 评审工作流：获取差异 → 找出问题 → 添加有针对性的评审评论

错误处理

• 身份验证失败：系统会自动在不同方式之间回退
• 无效的 PR：工具会平稳处理不存在的 PR 或仓库
• 网络问题：内置重试逻辑，可应对暂时性故障

🤔 为什么？

此项目通过 MCP 提供精简、专注的实现，以处理基本的拉取请求任务。 该项目设计简单易懂，可作为构建 MCP 服务的良好参考。

🔧 故障排除

身份验证问题

“Authentication failed” 或 “Unauthorized”

1. 检查 GitHub CLI 状态：运行 gh auth status 验证身份验证
2. 重新验证 GitHub CLI：运行 gh auth login 刷新凭据
3. 检查 PAT 权限：确保个人访问令牌具有所需权限：
   • 拉取请求：读取和写入
   • 问题：读取和写入
   • 内容：读取和写入
4. 使用简单命令测试：在 GitHub 仓库中尝试运行 gh pr list，验证 CLI 访问权限

“Repository not found”

• 验证仓库访问权限：确保所用身份验证方式有权访问目标仓库
• 检查仓库名称：确认所有者和仓库名称拼写正确
• 访问私有仓库：对于私有仓库，请确保令牌/CLI 具有相应权限

身份验证方式优先级

服务按以下顺序回退：

1. 个人访问令牌（如果已设置 GITHUB_PERSONAL_ACCESS_TOKEN）
2. GitHub CLI（如果 gh auth status 成功）
3. 错误（如果两种方式都不可用）

常见问题

“Invalid position/line for review comment”（HTTP 422）

• 指定的 line（或 position）可能位于差异块范围之外——只有修改或新增的行（以及少量相邻上下文行）才能接收行级评审评论
• 请改用 subject_type: "file" 添加文件级评论
• 如果需要使用已弃用的 position 参数，仍可通过 get_pr_changes_for_commenting 检查补丁并查找有效的差异位置

“Pull request not found”

• 确认 PR 编号存在且可访问
• 检查你是否具有仓库的读取权限
• 确认 PR 未被删除或移动

MCP 服务连接问题

1. 重启 VSCode：有时需要刷新 MCP 连接
2. 检查 settings.json 语法：确保 MCP 配置是有效的 JSON
3. 验证 npx 安装：运行 npx mcp-gh-pr-mini --version 进行测试
4. 启用调试日志：在环境变量中添加 "DEBUG": "true"

调试模式

添加调试环境变量以启用详细日志：

"mcp": {
  "servers": {
    "mcp-gh-pr-mini": {
      "command": "npx",
      "args": ["mcp-gh-pr-mini"],
      "env": {}
    }
  }
}

这会在 MCP 服务日志中显示详细的身份验证流程和 API 调用。

获取帮助

如果遇到问题：

1. 检查身份验证：验证 gh auth status 和令牌权限
2. 使用最小示例进行测试：先尝试列出公共仓库中的 PR
3. 查看调试日志：启用调试模式以查看详细的错误信息
4. 提交问题：附上调试日志和具体的错误消息

📝 更新日志

版本 1.4.0（2025-12-01）

• ✨ 新增创建草稿 PR 的支持，可选使用 draft 参数
• 🎯 在实现完成前将 PR 创建为草稿
• 📊 在成功消息中显示草稿状态
• ✅ 为草稿 PR 功能提供全面的测试覆盖

版本 1.3.0（2025-11-07）

• ✨ 新增 get_pull_request 工具，用于获取详细的 PR 信息（标题、正文、状态、作者、分支）
• 📚 功能类似于 gh pr view --json title,body

版本 1.2.0

• 新增 update_pull_request 工具，用于修改现有 PR
• 支持部分更新 PR（标题、正文、状态、基础分支）

版本 1.1.0

• 首次发布，包含核心 PR 管理功能

🙏 说明

我还不太熟悉构建 MCP 服务，因此可能还有可以改进的地方。 欢迎提出反馈、建议和贡献！