resourceの代わりにtextで prompt message を渡す #25

[solavrc]

Cursor や GitHub Copilot Agent などContent type "resource" not supported な client 向けに、
prompt message をtextで渡すように変更。

refs: https://modelcontextprotocol.io/specification/2025-03-26/server/prompts#embedded-resources

[eiel]

Cursorで動作することを確認

設定例

{
  "mcpServers": {
    "chatwork": {
      "command": "/opt/homebrew/bin/node",
      "args": [
        "/Users/cw-himura/ghq/github.com/chatwork/chatwork-mcp-server/dist/index.js"
      ],
      "env": {
        "CHATWORK_API_TOKEN": "XXXXXXXXXXXXXXX"
      }
    }
  }
}

[eiel]

type: resourceのコンテンツに関してはGET APIに関してはあっても良い可能性はあるが、POST APIのレスポンスの場合は対応するGET APIのURIにしたりすべきだったり、MCP Serverとして、resourceの実装をしていない状態のため、消してしまっても良さそうである。
しかし、Cursorで動作するようにすることのほうが重要度が高いとかんがえられ、情報として入っていても動作に支障がなさそうであるため、別途議論する。

[solavrc]

@eiel 以下の理解で良さそうですかね...？

MCPプロトコルの理解と実装に関するサマリー

1. MCP 基本概念・仕様の理解について

Q. サーバー設定の capabilities: { resources: {} } と、ツール実行結果 CallToolResult 内の EmbeddedResource はどう違うのですか？また、EmbeddedResource と TextContent の具体的な意味と違いはなんですか？

A. capabilities: { resources: {} } は、サーバーがMCPのトップレベル機能である Resources（リソースの一覧取得 resources/list や内容取得 resources/read など）を提供するかどうかを示す宣言です。
一方、CallToolResult 内の EmbeddedResource は、Tools 機能（tools/call）の実行結果として返却されうるデータ形式の一つです。これは特定のURIに関連付けられた、構造化されたデータ片やバイナリデータを含むリソース表現を指します。
これらはMCPプロトコルの異なる側面を指しており、直接的な包含関係はありません。

TextContent は単純なテキスト情報を示すための形式です。
EmbeddedResource は以下の特徴を持ちます。

• URIが必須: リソースの本体がどこにあるかを示すURI (resource.uri) を必ず含みます。
• データ本体はURIの先に: 長大なJSONやバイナリデータなどの実体は、このURIが指し示す場所（Webサーバー、ファイルシステム、MCPサーバー内部など）に保存されています。EmbeddedResource 自体はデータへの参照（ポインタ）です。
• 補助的なメタデータ: mimeType, name に加え、text フィールドを持つことができます。text フィールドは 必須ではなく、リソースの内容に関する 短い説明や要約 を提供し、クライアント（やLLM）がURIを辿る前に内容を推測するヒントを与える目的で使われます。（例: "全1234件の製品情報を含むJSONデータ。詳細はURIを参照。"）
• コンテキスト節約: 完全なデータを直接LLMのコンテキストに入れずに済む可能性があります（詳細は後述）。

2. クライアント互換性と実装上の課題について

Q. クライアントが CallToolResult の EmbeddedResource を解釈できない可能性がある場合、サーバー側で特別な対応は必要ですか？また、EmbeddedResource のユースケースにはどのようなものがありますか？

A. MCP標準では、サーバーがクライアントの応答解釈能力を事前に知る方法は定義されていません。そのため、サーバー側で 必須 とされる特別な対応はありません。
互換性を考慮する実用的な回避策として、TextContent（要約やプレビュー）と EmbeddedResource（完全なデータへの参照）の両方を返すことも考えられますが、これは冗長であり、コンテキストウィンドウを余分に消費する可能性があるため、EmbeddedResource の利点を損なう可能性があります。原則として、EmbeddedResource を使う場合は、別途 type: "text" で完全なデータを返す必要はありません。

EmbeddedResource は以下のような状況で特に有用です。

• 大規模データ: LLMのコンテキストウィンドウを圧迫せずに大量データ（DBクエリ結果、長大なJSON等）へのアクセスを提供。
• 動的データ: 内容が変化するリソース（チャット、市場価格等）への参照を提供。クライアントは 利用時にURIを参照し、その時点でのデータを取得 します（リアルタイム性はURIによります）。
• バイナリ/マルチメディア: 画像、音声、PDF等の非テキストコンテンツを提供。
• 多段階処理: 中間結果を保持し、後続処理で再利用。
• 永続的アクセス: 会話コンテキスト外でも参照可能な情報を提供。

特定のクライアント（例：Cursor）が EmbeddedResource を現状で解釈できない問題と、そのクライアントがMCPの Resources 機能（resources/list など）をサポートしていない問題は、それぞれ独立した別の事柄です。

3. 機能の使い分け (Resources vs Tools) について

Q. MCPの Resources と Tools はどのように使い分けるべきですか？

A. Resources と Tools は、その特性と主な用途に基づいて使い分けるのが効果的です。

• Resources:

  • application-driven（クライアント主導）。
  • 主に静的なデータや基本的なコンテキスト情報（組織知識、ファイル構造等）の提供に適しています (resources/list, resources/read 等）。

• Tools:

  • model-controlled（モデル主導）。
  • 能動的なアクション実行や動的情報の取得（API呼び出し、DB検索、計算等）に適しています (tools/call）。

実践的な活用方法:

1. 基本的なコンテキストや静的データは Resources として提供。
2. 動的な処理や外部連携は Tools として実装。
3. Tools の実行結果が複雑、大規模、または再利用価値がある場合は EmbeddedResource として返す:
   • コンテキスト節約: LLMは uri や text フィールドを見てデータの内容や存在を認識しますが、必ずしも全データを読み込む必要はありません。「要約して」「特定の部分だけ抽出して」といった指示を出すことで、クライアント側がURIにアクセスして処理を行い、結果の短い部分だけをLLMに返すことができます。これにより、長大な元データをLLMのコンテキストに入れずに済みます。ただし、LLMが結局「全データを見せて」と指示し、クライアントがそのまま渡した場合は節約になりません。節約効果はLLMとクライアントの挙動に依存します。
   • 遅延読み込みと最新性: データの実体は uri の先にあり、クライアントはデータが必要になった時点で uri を参照して取得します。これにより、常に（あるいはキャッシュが許す範囲で）元の情報源からデータを取得できます。

この組み合わせにより、モデルは基本的な文脈を理解しつつ、必要に応じて Tools を使って能動的に情報を取得・操作し、その結果（特に大規模な場合）を EmbeddedResource を介して効率的に扱えるようになります。

4. Tools, Resources 以外の機能について

Q. MCPでは Tools や Resources 以外にどのような機能カテゴリが存在しますか？

A. MCPでは、サーバーがクライアントに提供できる主要な機能カテゴリとして、他に以下のようなものがあります。

• Prompts: サーバー定義のテンプレート化されたメッセージやワークフローを提示する機能。
• Sampling: サーバーがクライアント（LLM）に推論を要求できるようにする機能（サーバー主導のLLM利用）。

さらに、プロトコル全体を支える補助的な機能として、設定管理 (Configuration)、進捗状況の通知 (Progress tracking)、操作のキャンセル (Cancellation)、エラー報告 (Error reporting)、ログ記録 (Logging) などが定義されています。

これらの機能のサポート状況は、MCPサーバーやクライアントの実装によって異なり、各実装のドキュメントや通信開始時の機能ネゴシエーションによって確認する必要があります。

[eiel]

斜め読みですがよさそうです。