Skip to content

mcp_client.md

Latest commit

 

History

History
222 lines (139 loc) · 7.42 KB

mcp_client.md

File metadata and controls

222 lines (139 loc) · 7.42 KB

MCP クライアント仕様

本ドキュメントは、Model Context Protocol（MCP）クライアントの概要と使用方法を日本語でまとめたものです。

1. 概要

1.1 MCPとは

Model Context Protocol（MCP）は、LLMアプリケーションと外部ツール・サービスを接続するための標準プロトコルです。MCPクライアントはMCPサーバーに接続し、ツールの呼び出しやリソースへのアクセスを行います。

1.2 主な機能

  • ツール呼び出し: MCPサーバーが提供するツールを実行
  • リソースアクセス: 外部リソースへのアクセス
  • プロンプト管理: サーバー提供のプロンプトテンプレート
  • 複数サーバー接続: 複数のMCPサーバーとの同時接続

2. システム要件

2.1 必要なソフトウェア

  • Python 3.8以上: Python版クライアントの場合
  • Node.js 17以上: TypeScript版クライアントの場合

2.2 必要なライブラリ

Python版の場合、以下のパッケージが必要です：

  • mcp: MCPプロトコルライブラリ
  • anthropic: Anthropic SDK（Claude使用時）
  • python-dotenv: 環境変数管理

3. 環境のセットアップ

3.1 プロジェクトの初期化

新しいプロジェクトディレクトリを作成し、仮想環境をセットアップします。必要なパッケージをインストールします。

3.2 APIキーの設定

使用するLLMプロバイダーのAPIキーを環境変数として設定します。.envファイルを作成して管理することを推奨します。セキュリティのため、.envファイルは.gitignoreに追加してください。

4. クライアントの実装

4.1 基本構造

MCPクライアントの基本構造は以下のコンポーネントで構成されます：

  • セッション管理: サーバーとの接続セッションを管理
  • ツール管理: 利用可能なツールの一覧と実行
  • メッセージ処理: LLMとの対話とツール呼び出しの処理
  • クリーンアップ: リソースの適切な解放

4.2 サーバー接続管理

MCPサーバーへの接続は以下の手順で行います：

  1. サーバースクリプトのパスを指定
  2. スクリプトの種類（Python/Node.js）を判定
  3. 適切なコマンドでサーバーを起動
  4. Stdioトランスポートで通信チャネルを確立
  5. セッションを初期化
  6. 利用可能なツールを取得

4.3 クエリ処理

ユーザークエリの処理は以下の流れで行われます：

  1. サーバーから利用可能なツールのリストを取得
  2. クエリとツール情報をLLMに送信
  3. LLMがツール使用を決定した場合、MCPサーバーを通じてツールを実行
  4. 実行結果をLLMに返送
  5. 最終的な応答を取得

5. インタラクティブチャット

5.1 チャットループ

インタラクティブなチャットセッションでは、ユーザー入力を受け取り、クエリを処理し、応答を表示するループを実行します。

5.2 セッション終了

チャットセッション終了時には、MCPクライアントのリソースを適切に解放します。

6. 主要コンポーネント

6.1 クライアント初期化

  • セッション管理とAPIクライアントの初期化
  • 適切なリソース管理のためのAsyncExitStackの使用
  • LLMクライアントの設定

6.2 サーバー接続

  • PythonとNode.jsサーバーの両方をサポート
  • サーバースクリプトの種類を検証
  • 適切な通信チャネルの設定
  • セッションの初期化と利用可能なツールの一覧取得

6.3 クエリ処理

  • 会話コンテキストの維持
  • LLMの応答とツール呼び出しの処理
  • LLMとツール間のメッセージフローの管理
  • 結果を一貫した応答に統合

6.4 インタラクティブインターフェース

  • シンプルなコマンドラインインターフェースの提供
  • ユーザー入力の処理と応答の表示
  • 基本的なエラーハンドリング
  • 優雅な終了処理

6.5 リソース管理

  • リソースの適切なクリーンアップ
  • 接続問題のエラーハンドリング
  • 優雅なシャットダウン手順

7. カスタマイズポイント

7.1 ツール処理

  • 特定のツールタイプに対応するためのクエリ処理のカスタマイズ
  • ツール呼び出しのカスタムエラーハンドリング
  • ツール固有のレスポンスフォーマット

7.2 応答処理

  • ツール結果のフォーマットカスタマイズ
  • レスポンスフィルタリングや変換
  • カスタムロギング

7.3 ユーザーインターフェース

  • GUIやWebインターフェースの追加
  • リッチなコンソール出力
  • コマンド履歴や自動補完

8. ベストプラクティス

8.1 エラーハンドリング

  • ツール呼び出しはtry-catchブロックでラップ
  • 意味のあるエラーメッセージを提供
  • 接続問題を優雅に処理

8.2 リソース管理

  • 適切なクリーンアップのためAsyncExitStackを使用
  • 完了時に接続をクローズ
  • サーバー切断を処理

8.3 セキュリティ

  • APIキーは.envファイルで安全に保管
  • サーバーレスポンスを検証
  • ツール権限に注意

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

9.1 サーバーパスの問題

  • サーバースクリプトへのパスが正しいことを確認
  • 相対パスが機能しない場合は絶対パスを使用
  • Windowsではスラッシュ（/）またはエスケープされたバックスラッシュ（\）を使用
  • サーバーファイルに正しい拡張子があることを確認

9.2 応答タイミング

  • 最初の応答は最大30秒かかる場合がある
  • これはサーバー初期化、クエリ処理、ツール実行中に発生する正常な動作
  • 後続の応答は通常より高速
  • 初期待機期間中はプロセスを中断しない

9.3 よくあるエラーメッセージ

  • FileNotFoundError: サーバーパスを確認
  • Connection refused: サーバーが実行中でパスが正しいことを確認
  • Tool execution failed: ツールに必要な環境変数が設定されているか確認
  • Timeout error: クライアント設定でタイムアウトを増やすことを検討

10. 本プロジェクトでの使用

10.1 MCPToolClientクラス

本プロジェクトでは、MCPToolClientクラスがMCPサーバーとの通信を担当します。config.yamlのmcp_serversセクションで設定されたサーバーに接続し、LLMからのツール呼び出しリクエストを処理します。

10.2 設定方法

config.yamlのmcp_serversセクションで以下を設定します：

  • mcp_server_name: サーバーの識別名
  • command: サーバー起動コマンド（配列形式）
  • system_prompt: サーバー提供ツールの説明（LLMへの説明用）

10.3 ツール呼び出しの形式

LLMからのツール呼び出しは「サーバー名/ツール名」の形式で指定します。MCPToolClientが適切なサーバーにリクエストをルーティングします。

参照元: Model Context Protocol公式ドキュメント（https://modelcontextprotocol.io）