17. トラブルシューティング

MCPサーバーの開発や実行中には、様々な問題が発生する可能性があります。このセクションでは、よく遭遇する可能性のある問題とその原因、対処法、デバッグのヒントについて説明します。

1. MCPサーバーが起動しない / すぐに終了する

• 原因の特定:

  • コンソールログの確認: サーバーを起動したターミナルにエラーメッセージが出力されていないか確認します。これが最も重要な情報源です。
  • 構文エラー: TypeScriptのコンパイルは通っていても、JavaScriptの実行時エラー（例: undefined のプロパティにアクセスしようとしたなど）が発生している可能性があります。
  • 必須ファイルの欠落: サーバーが必要とするファイル（設定ファイルなど）が見つからない場合。
  • ポートの競合 (HTTPサーバーの場合): もしHTTPトランスポートを使用している場合、指定したポートが他のアプリケーションによって既に使用されている可能性があります。
  • APIキーの未設定: 「09-MCPサーバーの実装-MCPツール定義」で実装したように、OPENWEATHER_API_KEY が環境変数に設定されていない場合、サーバーは起動時にエラー終了します。

• 対処法:

  • コンソールに出力されたエラーメッセージをよく読み、原因を特定します。
  • APIキーが正しく設定されているか（mcp_settings.json や実行時の環境変数）を確認します。
  • コード内のパス指定などが正しいか確認します。

2. MCPクライアントからツールを呼び出しても反応がない / エラーになる

• 原因の特定:

  • サーバーが正しく起動していない: 上記「1.」を確認してください。
  • mcp_settings.json の記述ミス:
    • サーバーの識別名、command、args（特に実行ファイルへの絶対パス）、env（APIキー）などが正しく記述されているか確認します。
    • "disabled": true になっていないか確認します。
  • ツール名の不一致: クライアントが呼び出そうとしているツール名と、サーバー側で server.tool() で定義したツール名が完全に一致しているか確認します（大文字・小文字も区別されます）。
  • 入力パラメータの不一致・バリデーションエラー:
    • クライアントが渡したパラメータが、サーバー側で定義した zod スキーマによるバリデーションを通過できない場合、ツールは実行されません（MCP SDKがエラーを返すか、何も起こらない可能性があります）。
    • サーバー側のログに zod のバリデーションエラーに関する情報が出力されていないか確認します。
  • サーバー側のツール実装内のエラー:
    • APIクライアント関数でエラーが発生している（例: OpenWeatherMap APIからのエラーレスポンス）。
    • ツール内のロジックで予期せぬエラーが発生している。
    • サーバー側のコンソールログを確認します。
  • ファイアウォール (リモートHTTPサーバーの場合): サーバーがリモートにあり、HTTPで通信している場合、ファイアウォールによって通信がブロックされている可能性があります。

• 対処法:

  • mcp_settings.json の内容を徹底的に確認します。特にパスの記述ミスはよくあります。
  • サーバー側のコンソールログで、ツール呼び出し時のログやエラーメッセージを確認します。
  • クライアント側から渡されるパラメータの型や構造が、サーバー側のスキーマ定義と一致しているか確認します。
  • 簡単な console.log をツール定義の最初やAPI呼び出し前後に追加して、処理がどこまで進んでいるかを確認する（デバッグプリント）。

3. 天気情報が取得できない / APIエラーが発生する

• 原因の特定:

  • OpenWeatherMap APIキーの誤り: mcp_settings.json や環境変数で設定したAPIキーが正しいか、OpenWeatherMapのダッシュボードで確認します。
  • APIキーが有効化されていない: 新しく取得したAPIキーは、有効になるまで時間がかかることがあります。
  • APIリクエスト制限超過: OpenWeatherMapの無料プランでは、API呼び出し回数に制限があります。短時間に多くのリクエストを送ると制限に達する可能性があります。
  • 都市名が無効: 存在しない都市名や、OpenWeatherMapが認識できない都市名を指定した場合。
  • ネットワーク接続の問題: サーバーが動作しているマシンがインターネットに接続できない場合。
  • OpenWeatherMap API側の障害: まれにAPIサービス自体に問題が発生していることもあります。

• 対処法:

  • APIキーを再確認します。
  • ブラウザや curl コマンドなどで、同じAPIキーと都市名を使って直接OpenWeatherMap APIを叩いてみて、レスポンスが返ってくるか確認します。

    # YOUR_API_KEY と CITY_NAME を置き換えてください
    curl "https://api.openweathermap.org/data/2.5/weather?q=CITY_NAME&appid=YOUR_API_KEY&units=metric"
    

  • サーバーのコンソールログで、axios から返されたエラーメッセージを確認します。

4. TypeScriptのコンパイルエラー (npm run build が失敗する)

• 原因の特定:

  • TypeScriptの文法エラー、型エラー。
  • tsconfig.json の設定不備。
  • 必要な型定義ファイル (*.d.ts) が不足している（通常はライブラリインストール時に自動で入ります）。

• 対処法:

  • ターミナルに出力される tsc のエラーメッセージをよく読み、該当箇所のコードを修正します。
  • VSCodeなどのエディタがリアルタイムで表示する型エラーも参考にします。

5. デバッグのヒント

• console.log を活用する: 変数の値、処理の通過点、エラーオブジェクトの内容などを積極的にコンソールに出力して確認します。
• Node.jsデバッガー: VSCodeなどのIDEには強力なNode.jsデバッガーが統合されています。ブレークポイントを設定し、ステップ実行しながら変数の状態を確認できます。
  • VSCodeでデバッガーを起動するには、Run and Debug ビューから設定を作成します（Node.js を選択）。program に "${workspaceFolder}/weather-server/build/index.js" などを指定し、環境変数 OPENWEATHER_API_KEY も設定します。
• ツールの入出力を単純化する: 問題を切り分けるために、一時的にツールの入力や処理内容を非常に単純なものにして動作確認します。
• MCPプロトコルのメッセージを確認する (高度): Stdioでやり取りされる実際のJSONメッセージを確認できれば、問題解決の手がかりになることがありますが、通常はSDKが隠蔽しています。

---

トラブルシューティングは試行錯誤の連続です。エラーメッセージを注意深く読み、一つずつ原因を潰していくことが大切です。