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	プロジェクトアイテムの追加／更新／削除、ステータス更新の作成を行います

MCP ツール（書き込み操作）

ツール	目的
mcp__github__issue_write	issue を作成または更新します（メソッド: create、update）。タイトル、本文、タイプ、ラベル、担当者、マイルストーン、および issue フィールドをサポートします
mcp__github__add_issue_comment	issue にコメントまたはリアクションを追加します
mcp__github__sub_issue_write	サブ issue を追加、削除、または優先順位を変更します

CLI / 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 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 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 のペア全体を引用符で囲んでください。 [] は、macOS のデフォルトシェルである zsh では glob パターンであるため、引用符で囲まれていない -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）、bug や enhancement のような同等のラベルを適用する代わりに type パラメータを使用してください。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、error、broken、not working	Bug Report
Feature、enhancement、add、new	Feature Request
Task、chore、refactor、update	Task

Issue の更新

PATCH を指定して gh api を使用します。

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: バグレポート

ユーザー:「バグ 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 が必要です。それぞれが独自のリファレンスファイルに記載されているため、エージェントは必要な知識のみを読み込みます。

機能	使用する場面	リファレンス
高度な検索	ブール論理、日付範囲、リポジトリ横断検索、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