Toast MCP Server

# トラブルシューティングガイド このドキュメントでは、Windows 10 トースト通知機能付き MCP サーバーの一般的な問題と解決策について説明します。 ## 目次 1. [サーバー起動の問題](#サーバー起動の問題) 2. [接続の問題](#接続の問題) 3. [通知の問題](#通知の問題) 4. [クライアント連携の問題](#クライアント連携の問題) 5. [ログの確認方法](#ログの確認方法) 6. [よくある質問](#よくある質問) ## サーバー起動の問題 ### サーバーが起動しない **症状**: サーバーを起動しようとすると、エラーが発生して起動しない。 **考えられる原因と解決策**: 1. **ポートが既に使用されている**: - エラーメッセージに「Address already in use」と表示される場合、指定したポートが既に他のプロセスで使用されています。 - 解決策: 別のポートを指定して起動するか、既存のプロセスを終了します。 ```bash python mcp_server.py --port 9000 ``` 2. **依存関係が不足している**: - エラーメッセージに「ModuleNotFoundError」と表示される場合、必要なライブラリがインストールされていません。 - 解決策: 依存関係をインストールします。 ```bash pip install -r requirements.txt ``` 3. **Python バージョンが古い**: - エラーメッセージに「SyntaxError」や「TypeError」が表示される場合、Python バージョンが古い可能性があります。 - 解決策: Python 3.8 以上をインストールします。 ```bash python --version # バージョンを確認 ``` ### サーバーが予期せず終了する **症状**: サーバーが起動後、予期せず終了する。 **考えられる原因と解決策**: 1. **メモリ不足**: - ログに「MemoryError」と表示される場合、メモリ不足が原因かもしれません。 - 解決策: 不要なプロセスを終了するか、メモリを増設します。 2. **例外が処理されていない**: - ログに未処理の例外が表示される場合、バグが原因かもしれません。 - 解決策: ログを確認し、問題を報告してください。デバッグモードで実行すると詳細な情報が得られます。 ```bash python mcp_server.py --debug ``` ## 接続の問題 ### クライアントがサーバーに接続できない **症状**: クライアントがサーバーに接続できない。 **考えられる原因と解決策**: 1. **サーバーが localhost でのみリッスンしている**: - サーバーがデフォルトで localhost (127.0.0.1) でのみリッスンしている場合、リモートクライアントは接続できません。 - 解決策: サーバーを 0.0.0.0 でリッスンするように設定します。 ```bash python mcp_server.py --host 0.0.0.0 ``` 2. **ファイアウォールがブロックしている**: - ファイアウォールがサーバーポートへの接続をブロックしている可能性があります。 - 解決策: ファイアウォール設定でポートを開放します。 3. **ネットワーク設定の問題**: - クライアントとサーバーが異なるネットワークにある場合、ルーティングの問題があるかもしれません。 - 解決策: ネットワーク設定を確認し、必要に応じてポート転送を設定します。 ### 接続が頻繁に切断される **症状**: クライアントとサーバーの接続が頻繁に切断される。 **考えられる原因と解決策**: 1. **ネットワークの不安定性**: - ネットワークが不安定な場合、接続が切断されることがあります。 - 解決策: より安定したネットワーク接続を使用します。 2. **タイムアウト設定が短すぎる**: - 接続タイムアウト設定が短すぎる場合、アイドル状態の接続が切断されることがあります。 - 解決策: 設定ファイルでタイムアウト値を増やします。 ```json { "server": { "timeout": 120 } } ``` ## 通知の問題 ### 通知が表示されない（Windows） **症状**: Windows 10 でトースト通知が表示されない。 **考えられる原因と解決策**: 1. **win10toast がインストールされていない**: - win10toast ライブラリがインストールされていない場合、通知は表示されません。 - 解決策: win10toast をインストールします。 ```bash pip install win10toast ``` 2. **フォーカスアシストがオン**: - Windows のフォーカスアシストがオンになっていると、通知がブロックされることがあります。 - 解決策: フォーカスアシストをオフにするか、設定を調整します。 3. **通知設定がオフ**: - Windows の通知設定でアプリからの通知が無効になっている可能性があります。 - 解決策: Windows の設定 > システム > 通知とアクション で通知を有効にします。 ### 通知が表示されない（macOS） **症状**: macOS で通知が表示されない。 **考えられる原因と解決策**: 1. **通知センターがオフ**: - macOS の通知センターがオフになっている可能性があります。 - 解決策: システム環境設定 > 通知 で通知を有効にします。 2. **おやすみモードがオン**: - macOS のおやすみモードがオンになっていると、通知がブロックされることがあります。 - 解決策: おやすみモードをオフにします。 3. **権限の問題**: - アプリに通知を表示する権限がない可能性があります。 - 解決策: システム環境設定 > セキュリティとプライバシー > プライバシー で権限を確認します。 ### 通知のカスタマイズが反映されない **症状**: 通知のカスタマイズ（アイコン、表示時間など）が反映されない。 **考えられる原因と解決策**: 1. **パラメータが正しく渡されていない**: - クライアントからのパラメータが正しく渡されていない可能性があります。 - 解決策: クライアントのコードを確認し、正しいパラメータを渡しているか確認します。 2. **プラットフォーム固有の制限**: - 一部のカスタマイズはプラットフォームによってサポートされていない場合があります。 - 解決策: プラットフォーム固有のドキュメントを参照してください。 ## クライアント連携の問題 ### VSCode Cline との連携がうまくいかない **症状**: VSCode Cline からの通知が表示されない。 **考えられる原因と解決策**: 1. **MCP プロトコルのバージョンの不一致**: - サーバーとクライアントで MCP プロトコルのバージョンが一致していない可能性があります。 - 解決策: クライアントとサーバーのバージョンを確認し、必要に応じて更新します。 2. **設定の問題**: - VSCode Cline の設定が正しくない可能性があります。 - 解決策: [クライアント設定](client_configuration.md) を参照して、VSCode Cline の設定を確認します。 3. **接続の問題**: - VSCode Cline がサーバーに接続できていない可能性があります。 - 解決策: 接続設定を確認し、サーバーが実行中であることを確認します。 ## ログの確認方法 サーバーの問題を診断するには、ログを確認することが重要です。 ### ログレベルの設定 ログレベルを変更するには、以下のコマンドを使用します： ```bash python mcp_server.py --log-level debug ``` ### ログファイルの設定 ログをファイルに出力するには、以下のコマンドを使用します： ```bash python mcp_server.py --log-file server.log ``` ### ログの解析 ログには以下の情報が含まれています： - タイムスタンプ: イベントが発生した日時 - ログレベル: DEBUG, INFO, WARNING, ERROR, CRITICAL - モジュール名: ログを出力したモジュール - メッセージ: イベントの詳細 例： ``` 2025-04-06 07:30:45,123 - INFO - server.connection - Client connected: 127.0.0.1:12345 ``` ## よくある質問 ### Q: サーバーは複数のクライアントからの同時接続をサポートしていますか？ A: はい、サーバーは複数のクライアントからの同時接続をサポートしています。デフォルトでは最大 10 の同時接続をサポートしていますが、設定ファイルで `max_connections` パラメータを変更することで調整できます。 ### Q: サーバーは Windows 以外のプラットフォームでも動作しますか？ A: はい、サーバー自体は Windows 以外のプラットフォーム（macOS、Linux など）でも動作します。ただし、通知機能は Windows 10 と macOS でのみサポートされています。Linux では通知機能は現在サポートされていません。 ### Q: サーバーのセキュリティはどうなっていますか？ A: サーバーは現在、基本的な入力検証を実装していますが、認証や暗号化は実装していません。インターネットに公開する場合は、適切な認証と暗号化を実装することを強く推奨します。 ### Q: カスタムコマンドを追加することはできますか？ A: はい、サーバーのコマンド処理システムは拡張可能です。カスタムコマンドを追加するには、`Command` クラスを継承して新しいコマンドを実装し、`CommandProcessor` に登録します。詳細は API ドキュメントを参照してください。