Anthropic の MCP の仕様 (5) - クライアント機能
以下の記事が面白かったので、簡単にまとめました。
前回
1. クライアント機能
「クライアント」は接続されたMCPサーバを強化するために、追加機能を実装できます。
2. ルート
2-1. ルート
「MCP」は、クライアントがファイルシステムの「ルート」をサーバに公開するための標準化された方法を提供します。「ルート」は、ファイルシステム内でサーバが操作できる範囲の境界を定義し、サーバがアクセスできるディレクトリとファイルを把握できるようにします。サーバは、サポートクライアントから「ルート」のリストを要求し、そのリストが変更されたときに通知を受け取ることができます。
2-2. ユーザーインタラクションモデル
「MCP」のルートは通常、ワークスペースまたはプロジェクト構成インターフェースを通じて公開されます。
たとえば実装では、ユーザーがサーバがアクセスできるディレクトリとファイルを選択できるワークスペース/プロジェクトピッカーを提供できます。これは、バージョンコントロールシステムまたはプロジェクトファイルからの自動ワークスペース検出と組み合わせることができます。
ただし実装では、ニーズに合った任意のインターフェースパターンを通じてルートを自由に公開できます。プロトコル自体は、特定のユーザーインタラクションモデルを必須としていません。
2-3. ケイパビリティ
プロンプトをサポートするクライアントは、初期化中にルートケイパビリティを宣言する必要があります。
{
"capabilities": {
"roots": {
"listChanged": true
}
}
}listChanged は、ルートのリストが変更されたときにクライアントが通知を発行するかどうかを示します。
2-4. プロトコルメッセージ
(1) ルートの一覧表示
ルートを取得するには、サーバは roots/list リクエストを送信します。
・Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "roots/list"
}・Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"roots": [
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}
]
}
}(2) ルートリストの変更
ルートが変更された場合、listChanged をサポートするクライアントは通知を送信する必要があります。
{
"jsonrpc": "2.0",
"method": "notifications/roots/list_changed"
}2-5. メッセージフロー
2-6. データ型
(1) ルート
ルート定義には次のものが含まれます。
・uri : ルートの一意の識別子。現在の仕様では、これは file:// URI である必要がある。
・name : 表示目的の、人間が読めるオプションの名前。
・プロジェクトディレクトリ
{
"uri": "file:///home/user/projects/myproject",
"name": "My Project"
}・複数のリポジトリ
[
{
"uri": "file:///home/user/repos/frontend",
"name": "Frontend Repository"
},
{
"uri": "file:///home/user/repos/backend",
"name": "Backend Repository"
}
]2-7. エラー処理
クライアントは、一般的な失敗ケースに対して標準の JSON-RPC エラーを返す必要があります。
・クライアントはルートをサポートしていません : -32601 (メソッドが見つかりません)
・内部エラー : -32603
・エラーの例
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Roots not supported",
"data": {
"reason": "Client does not have roots capability"
}
}
}2-8. セキュリティに関する考慮事項
クライアントは以下を行う必要があります。
・適切な権限を持つルートのみを公開する。
- パストラバーサルを防ぐためにすべてのルートURIを検証
- 適切なアクセス制御を実装する
- ルートのアクセス可能性を監視する
・サーバは以下を行う必要があります。
- ルートが利用できなくなった場合に対処
- 操作中にルートの境界を尊重
- 提供されたルートに対してすべてのパスを検証
2-9. 実装ガイドライン
クライアントは以下を行う必要があります。
・ルートをサーバーに公開する前に、ユーザーに同意を求めます。
- ルート管理用の明確なユーザー インターフェースを提供
- 公開する前にルートのアクセス可能性を検証
- ルートの変更を監視
・サーバは以下を行う必要があります。
- 使用前にルートの機能を確認
- ルートリストの変更を適切に処理
- 操作でルートの境界を尊重
- ルート情報を適切にキャッシュ
3. サンプリング
3-1. サンプリング
「MCP」は、サーバがクライアントを介して言語モデルからLLMサンプリング (「completion」または「generation」) を要求するための標準化された方法を提供します。このフローにより、クライアントはモデルのアクセス、選択、および権限を制御しながら、サーバがAI機能を活用できるようになります。サーバAPIキーは必要ありません。サーバはテキストまたは画像ベースのインタラクションを要求し、オプションでMCPサーバからのコンテキストをプロンプトに含めることができます。
3-2. ユーザーインタラクションモデル
「MCP」のサンプリングにより、LLM呼び出しを他のMCPサーバ機能内にネストして実行できるようにすることで、サーバはエージェント動作を実装できます。
実装では、ニーズに合った任意のインターフェイスパターンを通じてサンプリングを自由に公開できます。プロトコル自体は、特定のユーザーインタラクションモデルを義務付けていません。
【注意】 信頼性と安全性、セキュリティを確保するため、サンプリング リクエストを拒否できる人間が常に関与している必要があります。
アプリケーションは次のことを行う必要があります。
・サンプリングリクエストを簡単かつ直感的に確認できる UI を提供
・送信前にユーザーがプロンプトを表示および編集できるようにする
・生成された応答を配信前に確認用に提示
3-3. ケイパビリティ
サンプリングをサポートするクライアントは、初期化中にサンプリングケイパビリティを宣言する必要があります。
{
"capabilities": {
"sampling": {}
}
}3-4. プロトコルメッセージ
(1) メッセージの作成
言語モデルの生成を要求するために、サーバはサンプリング/createMessage 要求を送信します。
・Request
{
"jsonrpc": "2.0",
"id": 1,
"method": "sampling/createMessage",
"params": {
"messages": [
{
"role": "user",
"content": {
"type": "text",
"text": "What is the capital of France?"
}
}
],
"modelPreferences": {
"hints": [
{
"name": "claude-3-sonnet"
}
],
"intelligencePriority": 0.8,
"speedPriority": 0.5
},
"systemPrompt": "You are a helpful assistant.",
"maxTokens": 100
}
}・Response
{
"jsonrpc": "2.0",
"id": 1,
"result": {
"role": "assistant",
"content": {
"type": "text",
"text": "The capital of France is Paris."
},
"model": "claude-3-sonnet-20240307",
"stopReason": "endTurn"
}
}3-5. メッセージフロー
3-6. データ型
(1) メッセージ
サンプリングメッセージには次のものが含まれます。
・テキストコンテンツ
{
"type": "text",
"text": "The message content"
}・画像コンテンツ
{
"type": "image",
"data": "base64-encoded-image-data",
"mimeType": "image/jpeg"
}3-7. モデル設定
「MCP」でのモデル選択では、サーバとクライアントが異なるモデルを提供する異なるAIプロバイダーを使用する可能性があるため、慎重な抽象化が必要です。クライアントがそのモデルにアクセスできない場合や、別のプロバイダーの同等のモデルを使用することを好む場合があるため、サーバは単に名前で特定のモデルを要求することはできません。
これを解決するため、「MCP」は抽象的な能力の優先順位とオプションのモデルヒントを組み合わせたプリファレンスシステムを実装しています。
(1) ケイパビリティの優先順位
サーバは、3つの正規化された優先順位値 (0 ～ 1) でニーズを表します。
・costPriority : コストの最小化はどの程度重要か。値が高いほど、安価なモデルが優先される。
・speedPriority : 低レイテンシはどの程度重要か。値が高いほど、高速なモデルが優先される。
・intelligencePriority : 高度な機能はどの程度重要か。値が高いほど、より高性能なモデルが優先される。
(2) モデルのヒント
優先順位は特性に基づいてモデルを選択するのに役立ちますが、ヒントを使用すると、サーバは特定のモデルまたはモデルファミリを提案できます。
・ヒントはモデル名に柔軟に一致できる部分文字列として扱われる。
・複数のヒントは優先順位に従って評価。
・クライアントは、ヒントを異なるプロバイダーの同等のモデルにマッピングできる。
・ヒントはアドバイスであり、クライアントが最終的なモデルを選択。
{
"hints": [
{"name": "claude-3-sonnet"}, // Prefer Sonnet-class models
{"name": "claude"} // Fall back to any Claude model
],
"costPriority": 0.3, // Cost is less important
"speedPriority": 0.8, // Speed is very important
"intelligencePriority": 0.5 // Moderate capability needs
}クライアントはこれらの設定を処理して、利用可能なオプションから適切なモデルを選択します。たとえば、クライアントが Claude モデルにアクセスできないが Gemini を持っている場合、同様の機能に基づいて sonnet ヒントを gemini-1.5-pro にマップする可能性があります。
3-8. エラー処理
クライアントは、一般的な失敗のケースではエラーを返す必要があります。
・エラーの例
{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -1,
"message": "User rejected sampling request"
}
}3-9. セキュリティに関する考慮事項
・クライアントはユーザー承認コントロールを実装する必要がある。
・双方はメッセージ コンテンツを検証する必要がある。
・クライアントはモデル設定のヒントを尊重する必要がある。
・クライアントはレート制限を実装する必要がある。
・双方は機密データを適切に処理する必要がある。