MCP Gh Pr Mini

mcp gh pr mini

一个最小的MCP（模型上下文协议）服务器，用于与具有双重身份验证支持的GitHub拉取请求进行交互。

此工具允许您通过MCP在GitHub存储库中创建、列出、查看详细信息和差异、请求审阅者以及对拉取请求进行评论。它支持个人访问令牌（PAT）和GitHub CLI身份验证方法。

最新版本：1.4.0 -添加了PR创建支持草稿 draft 参数。

✨ 特性

🎯 MCP工具可用

create_pull_request

在GitHub存储库中创建新的pull请求。

• 参数：所有者、仓库、标题、正文、头部（源分支）、基础（目标分支）、草稿（可选）
• 退货：PR编号和URL可立即访问
• 特性:

- ✅ 创建可供审查的PR（默认） - ✅ 使用创建PR草案 draft: true 🆕 v1.4.0版本 - ✅ 成功消息中显示草稿状态

• 已测试: ✅ 适用于PAT和GitHub CLI身份验证

update_pull_request

更新GitHub存储库中现有的pull请求。

• 参数：所有者、仓库、pr_number、可选标题、正文、基础、状态（打开/关闭）
• 退货：更新PR详细信息并确认
• 特性:

- ✅ 更新标题和描述 - ✅ 更改目标分支（基） - ✅ 打开或关闭拉取请求 - ✅ 部分更新（仅修改指定字段）

• 已测试: ✅ 已成功更新PR元数据和状态

list_open_pull_requests

列出存储库中所有打开的拉取请求。

• 参数：所有者、回购、可选限额（默认值：10）
• 退货：PR编号、标题、作者和URL
• 已测试: ✅ 优雅地处理没有打开PR的存储库

get_pull_request 🆕 v1.3.0版本

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

• 参数：所有者、回购、产品编号
• 退货：PR标题、描述、状态、作者、分支机构和元数据
• 特性:

- ✅ 检索完整的PR详细信息，包括标题和正文 - ✅ 显示PR状态、作者和分支机构信息 - ✅ 显示创建和更新时间戳 - ✅ 提供PR的直接URL

• 用例：类似于 gh pr view {pr_number} --repo {owner/repository} --json title,body
• 已测试: ✅ 17个全面的单元测试，涵盖所有边缘情况

get_pull_request_diff

检索拉取请求的统一差异。

• 参数：所有者、回购、产品编号
• 退货：以统一格式显示所有文件更改的完整差异
• 已测试: ✅ 正确格式化新文件、修改文件和删除文件的差异

request_reviewers

将审阅者添加到现有的拉取请求中。

• 参数：所有者、仓库、pr_number、审阅者（GitHub用户名数组）
• 退货：审核员分配确认
• 已测试: ✅ 已成功为审阅者分配拉取请求

add_pr_comment

在拉取请求对话中添加一般注释。

• 参数：所有者、仓库、pr_number、正文（注释文本）
• 退货：评论ID和URL供参考
• 特别功能:

- ✅ 自动在注释前添加“\[AI\]使用MCP生成” - ✅ 用两种身份验证方法进行了测试

add_review_comment

在更改的行中添加特定位置的代码审查注释。

• 参数：所有者、仓库、pr_number、正文、路径（文件路径）、位置
• 退货：查看评论ID和URL
• 已测试: ✅ 在特定位置成功添加内联代码注释

get_pr_comments

从拉取请求中检索所有注释。

• 参数：所有者、回购、产品编号
• 退货：分类的对话和评论列表
• 特性:

- ✅ 将一般PR注释与代码审查注释分开 - ✅ 显示评论元数据（作者、日期、URL） - ✅ 显示AI生成的评论标识符

get_pr_changes_for_commenting

获取文件更改，其中包含可用于添加审阅注释的位置。

• 参数：所有者、回购、产品编号
• 退货：具有可评论位置的详细文件更改
• 特性:

- ✅ 列出所有更改的文件及其状态（添加、修改、删除） - ✅ 为内联注释提供精确的位置编号 - ✅ 显示每个文件的完整补丁信息

身份验证方法🔐

• 个人访问令牌（PAT）：传统的基于令牌的身份验证
• GitHub命令行界面：利用现有资源 gh CLI身份验证
• 自动检测：自动选择最佳可用身份验证方法
• 智能回退：当一种身份验证方法失败时，可以在身份验证方法之间无缝切换

- 主：PAT身份验证（如果已配置） - 回退：GitHub CLI身份验证（如果可用） - 身份验证失败时无需用户干预 - 跨身份验证方法保持API响应的一致性

🛠️ 设置

此工具在您的本地环境中作为MCP服务器运行。 您可以将其与Copilot Agent或任何兼容MCP的客户端等工具一起使用。

需求

• 已安装Node.js
• 具有MCP兼容扩展的VSCode（例如，Copilot代理）

🔐 验证系统

推荐：GitHub CLI身份验证

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

替代方案：个人访问令牌

设置环境变量 GITHUB_PERSONAL_ACCESS_TOKEN 如果您更喜欢PAT身份验证。

所需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
add_review_comment({
  owner: "username",
  repo: "repository",
  pr_number: 1,
  body: "Consider using const instead of let here for immutability.",
  path: "src/index.ts",
  position: 15
})

// 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\]使用MCP生成”
• 职位具体评论：使用 get_pr_changes_for_commenting 首先找到有效的职位
• 审查工作流程：获取差异→ 识别问题→ 添加有针对性的评论

错误处理

• 身份验证失败：系统会自动在方法之间回退
• 无效的PR：工具可以优雅地处理不存在的PR或存储库
• 网络问题：针对瞬态故障的内置重试逻辑

🤔 为什么？

该项目通过MCP为基本的拉取请求任务提供了一个最小的、有重点的实现。 它的设计简单易懂，是构建MCP服务器的良好参考。

🔧 故障排除

身份验证问题

“身份验证失败”或“未经授权”

1. 检查GitHub CLI状态：运行 gh auth status 验证身份验证
2. 重新验证GitHub CLI：运行 gh auth login 刷新凭据
3. 验证PAT权限：确保您的个人访问令牌具有所需的权限：

- 拉取请求：读和写 - 问题：读写 - 内容：读写

1. 使用简单命令进行测试：试试 gh pr list 在GitHub存储库中验证CLI访问权限

“未找到存储库”

• 验证存储库访问权限：确保您的身份验证方法可以访问目标存储库
• 检查存储库名称：确认所有者和存储库名称拼写正确
• 私有存储库访问：对于私有存储库，请确保您的令牌/CLI具有适当的权限

身份验证方法优先级

服务器使用此回退顺序：

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

常见问题

“审阅评论的位置无效”

• 使用 get_pr_changes_for_commenting 首先找到有效的职位
• 位置编号对应于diff中的行，而不是原始文件
• 只有修改或添加的行才能收到审核意见

“未找到拉取请求”

• 验证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 检索详细公关信息（标题、正文、州、作者、分支机构）的工具
• 📚 类似功能 gh pr view --json title,body

版本1.2.0

• 添加 update_pull_request 用于修改现有PR的工具
• 支持部分PR更新（标题、正文、州、基地）

版本1.1.0

• 首次发布，具有核心公关管理功能

🙏 备注

我还是构建MCP服务器的新手，所以可能有一些地方可以改进。 随时欢迎反馈、建议和贡献！