bug-triage

バグのトリアージ

apify/apify-mcp-server の未解決バグイシューをトリアージします。分析し、返信案を作成し、承認を得て投稿します。

権限

• デフォルトでは読み取り専用：イシューの一覧表示（gh issue list）、詳細とコメントの表示（gh issue view）は自動的に実行します。確認は不要です。
• 書き込みには承認が必要：コメントの投稿（gh issue comment）、クローズ（gh issue close）、編集（gh issue edit）を行う前に、必ず返信案を提示し、ユーザーから明示的な承認を得てください。

ステップ 0：引数を解析する

$ARGUMENTS によって対象範囲が決まります。

入力	動作
623 641 639	指定されたイシュー番号をトリアージします
--label bug	指定されたラベルの未解決イシューをすべてトリアージします（デフォルト：bug）
--all	bug ラベルが付いた未解決イシューをすべてトリアージします
(empty)	--all と同じです

ステップ 1：イシューを取得する

ステップ 0 で解析した引数に基づいて、取得対象を決定します。

特定のイシュー番号が指定された場合は、一覧取得のクエリを省略して、各イシューを直接取得します。

gh issue view <number> --repo apify/apify-mcp-server --comments

それ以外の場合（ラベル指定、--all、または空の場合）は、未解決のバグ報告を取得します。ステップ 0 で指定されたラベル（デフォルト：bug）を使用します。バグ報告には 2 つの形式があるため、どちらも検索します。

1. ラベルで検索：解析したラベルが付いたイシュー
2. タイトルの接頭辞で検索：タイトルに [Bug] が含まれるイシュー（バグ報告テンプレートによって追加されますが、ラベルが付いていないこともあります）

# By label (use the label from Step 0, default: bug)
gh issue list --repo apify/apify-mcp-server --label <label> --state open --json number,title,labels,createdAt,body --limit 30

# By title prefix (catches unlabeled bug reports)
gh issue list --repo apify/apify-mcp-server --state open --search "[Bug] in:title" --json number,title,labels,createdAt,body --limit 30

両方の一覧を統合し、イシュー番号で重複を除外します。

各イシューについて、コメントをすべて含む詳細情報を取得します（コメントに実際の状況が書かれていることがよくあります）。

gh issue view <number> --repo apify/apify-mcp-server --comments

返信案を作成する前に、必ずコメントを読んでください。 以前のチームメンバーがすでに返信したり、詳細を尋ねたり、回避策を提示したりしている場合があります。既存の返信と同じ内容を重ねて投稿しないでください。

ステップ 2：各イシューを分類する

次のいずれかに分類します。

カテゴリ	判断基準	一般的な対応
既知の修正方法あり	根本原因が明らかで、文書化された修正方法がある	修正方法を含む返信案を作成し、必要に応じてクローズします
こちらのバグではない	サーバーログ上は正常に動作しており、問題が MCP クライアント（Claude Desktop、Cowork など）側にある	調査結果を説明し、回避策を提案します
重複	別の未解決イシューと根本原因が同じ	リンクを記載してコメントし、重複としてクローズします
情報が必要	ログや設定がなく、説明が曖昧	詳細情報を求めます
長期間更新なし	情報を求めた後、2 週間以上返信がない	役立つ案内を添えてクローズします
対応が必要なバグ	修正が必要な、実際のサーバー側のバグ	問題を認識したことを伝え、さらに調査します

よくある根本原因（過去のトリアージより）

次のパターンは繰り返し発生します。まず確認してください。

1. SSE エンドポイントの削除（2026 年 4 月 1 日）：/sse URL を使用しているユーザーは接続に失敗します。修正方法：https://mcp.apify.com（ストリーミング可能な HTTP）に切り替えます。

2. 「ツールは接続されているが、Claude が使わない」：MCP サーバーのログには、ハンドシェイクと tools/list が正常に完了したと表示されますが、Claude が会話中にツールを使用しません。これは Claude Desktop／Cowork 側の動作であり、Apify サーバーのバグではありません。ユーザーは Claude に Apify ツールを使うよう明示的に依頼する必要があります。

3. 「拡張機能サーバーに接続できません」：Claude Desktop 拡張機能のインストールに関する問題です。多くの場合、npx キャッシュの破損、Claude が通知なく拡張機能をダウングレードすること、または Node.js が GUI アプリの PATH に含まれていないことが原因です。修正方法：リモートサーバー https://mcp.apify.com をカスタムコネクタとして使用します。

4. npx キャッシュの破損：古いキャッシュによって stdio サーバーが起動できなくなります。修正方法：macOS／Linux では rm -rf ~/.npm/_npx、Windows では rmdir /s /q %LOCALAPPDATA%\npm-cache\_npx を実行します。

5. Claude Desktop コネクタのダウングレード：Claude Desktop がコネクタを通知なく古いバージョンにダウングレードします。修正方法：コネクタを削除して、再度追加します。

ステップ 3：回答を作成する

スタイルのルール：

• 開発者向けの平易な言葉で書きます
• 簡潔にします。通常は 3～8 行で、余計な説明は省きます
• ユーザーが困っている場合は、問題を認識したうえで簡潔にお詫びします
• 修正方法やトラブルシューティングガイドがある場合は、ドキュメントを案内します
• サーバーが正しく動作している場合（ログで確認できる場合）は、そのことを明確に伝えます
• クローズする場合は、その理由と次に参照すべき場所を説明します

主なドキュメントリンク：

• セットアップガイド：https://docs.apify.com/platform/integrations/mcp
• Claude Desktop のトラブルシューティング：https://docs.apify.com/platform/integrations/claude-desktop#troubleshooting
• コンフィギュレーター：https://mcp.apify.com

Apify MCP ツール（search-apify-docs、fetch-apify-docs）を使い、上記にないトピックに関する問題では適切なドキュメントリンクを探してください。

接続の問題に対するデフォルトの推奨方法は、リモートサーバーです。

Claude Desktop でカスタムコネクターを追加し、URL に https://mcp.apify.com を指定して、OAuth フローに従ってください。

ステップ 4：提示して承認を得る

各問題について、次の内容をユーザーに提示します。

1. 問題番号＋タイトル＋リンク（https://github.com/apify/apify-mcp-server/issues/<number>）
2. カテゴリ（ステップ 2 で分類したもの）
3. 概要 — 状況を 1 行で説明します
4. 提案する返信 — 下書きコメントを引用ブロックで示します
5. 提案する対応 — コメントのみ／コメント＋クローズ／#X の重複としてクローズ／スキップ

必須：投稿する前に、必ずユーザーから明示的な承認を得てください。 ユーザーが承認するまで、問題への投稿、クローズ、変更は決して行わないでください。

ステップ 5：投稿する

承認を得た後：

# Comment only
gh issue comment <number> --repo apify/apify-mcp-server --body "<response>"

# Comment + close
gh issue comment <number> --repo apify/apify-mcp-server --body "<response>" && \
gh issue close <number> --repo apify/apify-mcp-server

# Close as duplicate
gh issue comment <number> --repo apify/apify-mcp-server --body "Closing as a duplicate of #<other> — same root cause. We'll track and update there." && \
gh issue close <number> --repo apify/apify-mcp-server

その後、次の問題に進みます。最後の問題が終わったら、次の概要表を出力します。

問題	カテゴリ	実施した対応
#623	既知の修正	コメントを投稿、SSE に移行
#639	重複	#641 の重複としてクローズ
...	...	...