github-issues

GitHub Issues

使用 @modelcontextprotocol/server-github MCP 服务器管理 GitHub Issue。

可用工具

MCP 工具（读取操作）

工具	用途
mcp__github__issue_read	读取 Issue 详情、子 Issue、评论、标签（方法：get, get_comments, get_sub_issues, get_labels）
mcp__github__list_issues	按状态、标签、日期列出和筛选仓库 Issue
mcp__github__search_issues	使用 GitHub 搜索语法跨仓库搜索 Issue
mcp__github__projects_list	列出项目、项目字段、项目项、状态更新
mcp__github__projects_get	获取项目、字段、项或状态更新的详细信息
mcp__github__projects_write	添加/更新/删除项目项，创建状态更新

CLI / REST API（写入操作）

MCP 服务器目前不支持创建、更新或评论 Issue。请使用 gh api 进行这些操作。

操作	命令
创建 Issue	gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...
更新 Issue	gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f title=... -f state=...
添加评论	gh api repos/{owner}/{repo}/issues/{number}/comments -X POST -f body=...
关闭 Issue	gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed
设置 Issue 类型	在创建调用中包含 -f type=Bug（仅 REST API，gh issue create CLI 不支持）

注意： gh issue create 适用于基本 Issue 创建，但不支持 --type 标志。需要设置 Issue 类型时请使用 gh api。

工作流程

1. 确定操作：创建、更新还是查询？
2. 收集上下文：获取仓库信息、现有标签、里程碑（如果需要）
3. 构建内容：使用 references/templates.md 中的适当模板
4. 执行：读取使用 MCP 工具，写入使用 gh api
5. 确认：向用户报告 Issue URL

创建 Issue

使用 gh api 创建 Issue。这支持所有参数，包括 Issue 类型。

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="Issue 标题" \
  -f body="Issue 正文（Markdown 格式）" \
  -f type="Bug" \
  --jq '{number, html_url}'

可选参数

在 gh api 调用中添加以下任何标志：

-f type="Bug"                    # Issue 类型（Bug, Feature, Task, Epic 等）
-f labels[]="bug"                # 标签（重复以添加多个）
-f assignees[]="username"        # 负责人（重复以添加多个）
-f milestone=1                   # 里程碑编号

Issue 类型是组织级别的元数据。要发现可用的类型，请使用：

gh api graphql -f query='{ organization(login: "ORG") { issueTypes(first: 10) { nodes { name } } } }' --jq '.data.organization.issueTypes.nodes[].name'

优先使用 Issue 类型而非标签进行分类。 当 Issue 类型可用时（例如 Bug、Feature、Task），请使用 type 参数，而不是应用等效的标签如 bug 或 enhancement。Issue 类型是 GitHub 上对 Issue 进行分类的规范方式。仅当组织未配置 Issue 类型时才回退到标签。

标题指南

• 具体且可操作
• 保持在 72 个字符以内
• 当设置了 Issue 类型时，不要添加冗余前缀如 [Bug]
• 示例：
  • Login fails with SSO enabled（类型=Bug）
  • Add dark mode support（类型=Feature）
  • Add unit tests for auth module（类型=Task）

正文结构

始终使用 references/templates.md 中的模板。根据 Issue 类型选择：

用户请求	模板
错误、异常、损坏、不工作	Bug 报告
功能、增强、添加、新	功能请求
任务、杂务、重构、更新	任务

更新 Issue

使用 gh api 的 PATCH 方法：

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="更新后的标题" \
  --jq '{number, html_url}'

仅包含要更改的字段。可用字段：title、body、state（open/closed）、labels、assignees、milestone。

示例

示例 1：Bug 报告

用户：“创建一个 Bug Issue - 使用 SSO 时登录页面崩溃”

操作：

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Login page crashes when using SSO" \
  -f type="Bug" \
  -f body="## 描述
用户尝试使用 SSO 认证时登录页面崩溃。

## 复现步骤
1. 导航到登录页面
2. 点击“使用 SSO 登录”
3. 页面崩溃

## 预期行为
SSO 认证应完成并重定向到仪表板。

## 实际行为
页面无响应并显示错误。" \
  --jq '{number, html_url}'

示例 2：功能请求

用户：“创建一个高优先级的深色模式功能请求”

操作：

gh api repos/github/awesome-copilot/issues \
  -X POST \
  -f title="Add dark mode support" \
  -f type="Feature" \
  -f labels[]="high-priority" \
  -f body="## 摘要
添加深色模式主题选项以改善用户体验和可访问性。

## 动机
- 减少低光环境下的眼睛疲劳
- 用户越来越期望此功能

## 建议方案
实现主题切换，并检测系统偏好。

## 验收标准
- [ ] 设置中的切换开关
- [ ] 持久化用户偏好
- [ ] 默认遵循系统偏好" \
  --jq '{number, html_url}'

常用标签

在适用时使用这些标准标签：

标签	用途
bug	某些功能不正常
enhancement	新功能或改进
documentation	文档更新
good first issue	适合新手
help wanted	需要额外关注
question	需要更多信息
wontfix	将不处理
duplicate	已存在
high-priority	紧急 Issue

提示

• 创建 Issue 前始终确认仓库上下文
• 询问缺失的关键信息，不要猜测
• 关联已知的 Issue：Related to #123
• 对于更新，先获取当前 Issue 以保留未更改的字段

扩展功能

以下功能需要 REST 或 GraphQL API，超出了基本 MCP 工具的范围。每个功能都在其自己的参考文件中记录，以便代理仅加载所需的知识。

功能	何时使用	参考
高级搜索	复杂查询，包含布尔逻辑、日期范围、跨仓库搜索、Issue 字段过滤器（field.name:value）	references/search.md
子 Issue 和父 Issue	将工作分解为层次化任务	references/sub-issues.md
Issue 依赖关系	跟踪阻塞/被阻塞关系	references/dependencies.md
Issue 类型（高级）	超出 MCP list_issue_types / type 参数的 GraphQL 操作	references/issue-types.md
Projects V2	项目面板、进度报告、字段管理	references/projects.md
Issue 字段	自定义元数据：日期、优先级、文本、数字（私有预览）	references/issue-fields.md
Issue 中的图片	通过 CLI 在 Issue 正文和评论中嵌入图片	references/images.md