troubleshoot-binlog-mcp

Binlog MCP の起動に関するトラブルシューティング

プラグインの Binlog MCP サーバーに接続できない理由を説明し、証拠に基づくポリシー準拠の復旧方法を示します。これはサーバーの起動を診断するものであり、ビルド中に記録されたエラーを対象とするものではありません。 Binlog ファイルもプロジェクトのビルドも必要ありません。

このスキルは必要に応じて実行されます。エージェントに公開されていないホストエラーを確認したり、セッション開始時のコンテキストを注入したり、プラグインをインストールしただけで確実に有効化されたりすることはできません。

1. 何が失敗したのかを確認する

ユーザーのエラーと、すでに利用可能なホストの MCP ステータスまたは起動ログを使用します。 CONNECTION_CLOSED だけでは、トランスポートが切断されたことを示すにすぎず、その理由はわかりません。これをそのまま「パッケージが見つからない」と解釈しないでください。

• Binlog サーバーに接続できていて、そのツールを検出できる場合は、起動のトラブルシューティングを中止します。 元の Binlog 分析を続け、正常に動作している設定は変更しないでください。
• プラグインのスキルは読み込まれているものの、Binlog サーバーが起動していない場合は、以下を続けてください。
• プラグイン自体がインストールまたは有効化されていない場合、あるいはサーバーが登録されていない場合は、まずそのホスト設定に対処してください。起動を試みていない段階で、NuGet パッケージの解決を診断しないでください。
• 実行環境またはホストのログを確認できない場合は、その制約を説明し、ユーザーが次に実行するコマンドを示してください。ログを確認した、または接続を修復したと決して主張しないでください。

2. ホストのワークスペースと SDK を一致させる

影響を受けているワークスペースのディレクトリと、利用可能な設定からホストの実際の MCP コマンド、引数、環境を特定します。配布されているコマンドは次のとおりです。

dotnet dnx Microsoft.AITools.BinlogMcp --yes --prerelease

プラグインのディレクトリや、NuGet の設定が異なる一時ディレクトリではなく、そのワークスペースでホストの環境を使って診断を実行します。次を確認してください。

dotnet --info
dotnet --version
dotnet nuget list source

適用される global.json と、親またはユーザーの設定を含む継承された NuGet 設定を確認します。clear、無効化されたソース、packageSourceMapping も対象です。ワークスペースの clear によって、既定の nuget.org ソースがこのパッケージを含まないプライベートミラーに置き換わる場合があります。SDK がインストールされていても、このディレクトリで選択される SDK とは限りません。配布されている dotnet dnx コマンドには、.NET 10 以降の SDK が必要です。

認証情報の設定、プライベートフィードの URL、トークン、認証情報プロバイダーの出力を回答に含めないでください。必要に応じてローカルで確認し、ソース名を伏せて、関連するエラーを報告してください。

3. 実際の起動エラーを取得する

失敗しているホストに既存の起動ログがあれば、そちらを優先してください。ない場合は、影響を受けているワークスペースから、変更していない起動コマンドを一度だけ再実行し、標準出力と標準エラーの両方、および終了コードを記録してください。最初から --source を追加したり、設定を置き換えたり、global.json を削除したり、キャッシュを消去したり、別のコピーをインストールしたりしないでください。これらを行うと、診断対象の条件が変わってしまいます。

stdio MCP サーバーは、プロトコル入力を待って実行を続ける場合があります。起動を観察している間は stdin を開いたままにし、実行時間に上限を設けて（たとえば30秒）、認証情報プロバイダーの子プロセスも含む診断プロセスツリーだけを終了させてください。ホストがサポートするタイムアウト／キャンセル機能を使用してください。安全に終了させられない場合は、ユーザーにローカルでコマンドを実行するよう依頼してください。バックグラウンドでサーバーを実行したままにしたり、無関係な dotnet プロセスを終了させたりしないでください。タイムアウト、応答がないこと、プロセスが開いたままであることは、MCP の初期化が成功した証拠にはなりません。

パッケージの入手可否が不明なままの場合に限り、同じワークスペース設定で、実行時間に上限を設けて次の補助プローブを実行してください。

dotnet package search Microsoft.AITools.BinlogMcp --exact-match --prerelease --format json

searchResult[].packages にある正確なパッケージ ID とバージョンを確認し、トップレベルとソースごとの両方の problems を調べてください。終了コードがゼロでも、検索の成功が確定するわけではありません。

観測された証拠	診断と次の対応
dnx が、設定済みのフィードに一致するバージョンがないと報告する	その設定ではパッケージを解決できませんでした。承認済みミラーに、このパッケージの正確な ID に対応するプレリリース版があるか確認してください。
検索でパッケージが見つからず、ソースの問題もない	検索対象のフィードに、該当する登録情報がないだけです。これだけでは dnx が必ず失敗する証拠にはなりません。キャッシュ済みのツールや未登録のバージョンが動作する可能性があります。
検索にトップレベル／ソースごとの問題、HTTP 401/403、TLS、ネットワーク、または認証情報プロバイダーのエラーがある	入手可否は未確認です。「パッケージがない」と判断せず、まず具体的なフィード／アクセスの問題に対処してください。検索の終了コードがゼロでも同様です。
検索でパッケージが見つかるが、dnx が失敗する	起動エラーに従ってください。検索はパッケージソースのマッピングを適用しません。マッピング、復元／ダウンロードへのアクセス、ランタイム要件を確認してください。接続が正常だと判断しないでください。
dotnet が見つからない、dnx が認識されない、または SDK の選択エラーが発生する	ホストの PATH／SDK 選択を修正してください。global.json を考慮し、リポジトリを暗黙にアップグレードしたり、SDK の固定指定を削除したりしないでください。
タイムアウト、未対応の検索コマンド、不正な形式／非 JSON の出力	プローブでは結論が出なかったと報告してください。起動ログまたはユーザーが実行する診断を利用し、パッケージがないとも、成功したとも推測しないでください。
起動は成功するが、ホスト接続は失敗する	ホストで実際に使われているコマンド／環境と、MCP の初期化ログを調査してください。パッケージの検出が原因の障害であるとは、もはや示されていません。

証拠から次の対応が確定した後は、時間のかかるプローブを繰り返さないでください。

4. ポリシーに準拠した復旧方法を選択する

確認された失敗の状況に応じて、必要最小限の変更を提案します。

• フィードの管理者に、Microsoft.AITools.BinlogMcp とその必須バージョン／依存関係を承認済みフィードにミラーリングするか、除外している承認済みマッピングを修正するよう依頼します。
• 確認された問題が承認済みフィードの認証、接続、または証明書の設定にある場合は、それを修正します。証明書の検証を無効にする提案は決してしないでください。
• 組織のポリシーで許可され、ユーザーが変更を承認した場合に限り、nuget.org を追加します。エンタープライズポリシーを回避するために clear を削除したり、ソースマッピングを無効にしたり、ソースを上書きしたりしないでください。
• 適切で承認されている場合は、承認済みフィードからツールをインストールし、その binlog-mcp 実行ファイルを代替の MCP サーバーとしてホストに登録します。実行ファイルのパスを確認し、サーバーを重複登録しないようにします。インストールしただけでは接続は復旧しません。
• SDK／PATH の問題については、必要な SDK をホストから利用できるようにするか、意図的に設定した別の起動方法を使用します。リポジトリの SDK 選択を変更する前に確認してください。

ユーザーの承認なしに、NuGet の設定、ホストへの登録、SDK の固定設定を編集しないでください。 ポリシー上復旧できない場合は、その旨を伝えてください。既存の binlog がある場合は、MCP の修復をビルド診断の妨げにせず、binlog-failure-analysis のテキストログ再生による代替手段を案内してください。

5. 検証して報告する

承認された変更を行った後、ホストでサポートされている操作を使ってサーバーに再接続するか、再起動します。 MCP の初期化と、binlog_overview などの binlog ツールを含むツール一覧を確認します。binlog を利用できる場合は、元の分析を再開します。

確認された原因（または不明な点）、関連する機密情報を伏せた証拠、必要最小限の復旧策、実際に検証できた内容を報告します。最後にステータスを1行で記載します。

MCP status: connected

ホストがサーバーのツールを検出した場合に限り connected を使用し、起動／接続の失敗が確認された場合は failed を使用します。プローブまたは助言しか得られていない場合は unverified を使用します。 「パッケージが見つかった」または「ツールがインストールされた」というだけで、MCP 接続が検証済みであるかのように扱わないでください。