github-issues

GitHub Issues

使用 @modelcontextprotocol/server-github MCP 伺服器管理 GitHub 議題。

可用工具

MCP 工具（讀取操作）

工具	用途
mcp__github__issue_read	讀取議題詳細資訊、子議題、留言、標籤（方法：get, get_comments, get_sub_issues, get_labels）
mcp__github__list_issues	依狀態、標籤、日期列出並篩選儲存庫議題
mcp__github__search_issues	使用 GitHub 搜尋語法跨儲存庫搜尋議題
mcp__github__projects_list	列出專案、專案欄位、專案項目、狀態更新
mcp__github__projects_get	取得專案、欄位、項目或狀態更新的詳細資訊
mcp__github__projects_write	新增/更新/刪除專案項目、建立狀態更新

CLI / REST API（寫入操作）

MCP 伺服器目前不支援建立、更新或留言議題。請使用 gh api 進行這些操作。

操作	指令
建立議題	gh api repos/{owner}/{repo}/issues -X POST -f title=... -f body=...
更新議題	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=...
關閉議題	gh api repos/{owner}/{repo}/issues/{number} -X PATCH -f state=closed
設定議題類型	在建立呼叫中加入 -f type=Bug（僅 REST API 支援，gh issue create CLI 不支援）

注意： gh issue create 可用於基本議題建立，但不支援 --type 旗標。需要設定議題類型時請使用 gh api。

工作流程

1. 判斷動作：建立、更新或查詢？
2. 收集背景資訊：取得儲存庫資訊、現有標籤、里程碑（如有需要）
3. 組織內容：使用 references/templates.md 中的適當範本
4. 執行：讀取使用 MCP 工具，寫入使用 gh api
5. 確認：將議題網址回報給使用者

建立議題

使用 gh api 建立議題。這支援所有參數，包括議題類型。

gh api repos/{owner}/{repo}/issues \
  -X POST \
  -f title="議題標題" \
  -f body="議題內容（Markdown 格式）" \
  -f type="Bug" \
  --jq '{number, html_url}'

選擇性參數

在 gh api 呼叫中加入以下任何旗標：

-f type="Bug"                    # 議題類型（Bug, Feature, Task, Epic 等）
-f labels[]="bug"                # 標籤（重複以新增多個）
-f assignees[]="username"        # 指派對象（重複以新增多個）
-f milestone=1                   # 里程碑編號

議題類型是組織層級的中繼資料。若要探索可用的類型，請使用：

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

優先使用議題類型而非標籤進行分類。 當議題類型可用時（例如 Bug、Feature、Task），請使用 type 參數，而不是套用等效的標籤如 bug 或 enhancement。議題類型是 GitHub 上分類議題的標準方式。僅在組織未設定議題類型時才退而使用標籤。

標題指南

• 具體且可操作
• 保持在 72 個字元以內
• 若已設定議題類型，請勿新增冗餘前綴如 [Bug]
• 範例：
  • Login fails with SSO enabled（類型=Bug）
  • Add dark mode support（類型=Feature）
  • Add unit tests for auth module（類型=Task）

內容結構

一律使用 references/templates.md 中的範本。根據議題類型選擇：

使用者請求	範本
錯誤、異常、損壞、無法運作	錯誤回報
功能、增強、新增、新功能	功能請求
任務、雜務、重構、更新	任務

更新議題

使用 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：錯誤回報

使用者：「建立一個錯誤議題——使用 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	緊急議題

提示

• 建立議題前務必確認儲存庫背景
• 詢問遺漏的關鍵資訊，而非猜測
• 已知相關議題時請連結：Related to #123
• 更新時，先擷取目前議題以保留未變更的欄位

延伸功能

以下功能需要 REST 或 GraphQL API，超出基本 MCP 工具範圍。每個功能都有各自的參考檔案，因此代理程式只會載入所需的知識。

功能	使用時機	參考文件
進階搜尋	複雜查詢（布林邏輯、日期範圍、跨儲存庫搜尋、議題欄位篩選 field.name:value）	references/search.md
子議題與父議題	將工作拆解為階層式任務	references/sub-issues.md
議題相依關係	追蹤 blocked-by / blocking 關係	references/dependencies.md
議題類型（進階）	超出 MCP list_issue_types / type 參數的 GraphQL 操作	references/issue-types.md
Projects V2	專案看板、進度報告、欄位管理	references/projects.md
議題欄位	自訂中繼資料：日期、優先順序、文字、數字（私人預覽）	references/issue-fields.md
議題中的圖片	透過 CLI 在議題內容和留言中嵌入圖片	references/images.md