github-issues

GitHub Issues

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

可用工具

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	添加/更新/删除项目条目，创建状态更新

MCP 工具（写入操作）

工具	用途
mcp__github__issue_write	创建或更新 issue（方法：create、update）。支持 title、body、type、labels、assignees、milestone 和 issue 字段
mcp__github__add_issue_comment	为 issue 添加评论或回应
mcp__github__sub_issue_write	添加、移除子 issue 或调整其优先级

命令行 / REST API（写入操作）

gh api 执行相同的写入操作，也是下面示例中使用的形式。当 MCP 服务未连接，或你需要 MCP 工具未暴露的 REST 字段时，可以使用它。

操作	命令
创建 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 命令行不支持）

注意： 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 title" \
  -f body="Issue body in markdown" \
  -f type="Bug" \
  --jq '{number, html_url}'

可选参数

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

-f type="Bug"                    # Issue type (Bug, Feature, Task, Epic, etc.)
-f 'labels[]=bug'                # Labels (repeat for multiple)
-f 'assignees[]=username'        # Assignees (repeat for multiple)
-f milestone=1                   # Milestone number

为整个 name[]=value 对加引号。 [] 在 zsh（macOS 上的默认 shell）中是通配模式，因此未加引号的 -f labels[]=bug 永远不会传递给 gh：

zsh: no matches found: labels[]=bug

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（配合 type=Bug）
  • Add dark mode support（配合 type=Feature）
  • Add unit tests for auth module（配合 type=Task）

正文结构

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

用户请求	模板
Bug、错误、损坏、无法工作	Bug Report
Feature、增强、添加、新增	Feature Request
Task、杂项、重构、更新	Task

更新 Issue

使用 gh api 配合 PATCH：

gh api repos/{owner}/{repo}/issues/{number} \
  -X PATCH \
  -f state=closed \
  -f title="Updated 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="## Description
The login page crashes when users attempt to authenticate using SSO.

## Steps to Reproduce
1. Navigate to login page
2. Click 'Sign in with SSO'
3. Page crashes

## Expected Behavior
SSO authentication should complete and redirect to dashboard.

## Actual Behavior
Page becomes unresponsive and displays error." \
  --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="## Summary
Add dark mode theme option for improved user experience and accessibility.

## Motivation
- Reduces eye strain in low-light environments
- Increasingly expected by users

## Proposed Solution
Implement theme toggle with system preference detection.

## Acceptance Criteria
- [ ] Toggle switch in settings
- [ ] Persists user preference
- [ ] Respects system preference by default" \
  --jq '{number, html_url}'

常用标签

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

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

提示

• 创建 issue 前始终确认仓库上下文
• 对于缺失的关键信息，主动询问而不是猜测
• 在已知时链接相关 issue：Related to #123
• 更新时，先获取当前 issue 以保留未更改的字段

扩展能力

以下功能需要基础 MCP 工具之外的 REST 或 GraphQL API。每项功能都在各自的参考文件中有详细说明，以便 Agent 只加载所需的知识。

能力	何时使用	参考
高级搜索	使用布尔逻辑、日期范围、跨仓库搜索、issue 字段过滤（field.name:value）的复杂查询	references/search.md
子 issue 与父 issue	将工作拆分为层级任务	references/sub-issues.md
里程碑	创建、读取、更新、关闭、重新打开、删除里程碑并管理里程碑 issue	references/milestones.md
标签	发现、创建、重命名、重新着色和删除仓库标签；在 issue 上添加或替换标签	references/labels.md
Issue 依赖	跟踪 blocked-by / blocking 关系	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 中的图片	通过命令行在 issue 正文和评论中嵌入图片	references/images.md