0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?

MCPサーバーに関して⑦:ResourcesとPromptsの実装

0
Last updated at Posted at 2026-11-18

MCPサーバーに関して⑦:ResourcesとPromptsの実装

前回はToolsの実装を深掘りしました。今回は残る2つの機能、ResourcesとPromptsを、Python SDKで実装します。どちらも「データを渡す」「定型の指示を渡す」ための機能で、Toolsとは役割も、誰が使うかの主導権も違います。この違いを押さえると、3つの機能の使い分けが見えてきます。

この記事で分かること

  • ResourcesとPromptsの役割と、Toolsとの違い(主導権の違い)
  • 静的なリソースと、URIテンプレートを使ったリソースの実装方法
  • プロンプトテンプレートの定義と引数、引数の検証のされ方
  • リソースをプロンプトに埋め込む方法と、3機能の組み合わせ方
  • 実装でつまずきやすい点と、よくある失敗例

まず整理:3つの機能は「誰が決めるか」が違う

連載③で触れたとおり、3つの機能は「誰が主導権を持つか」で分かれます。

機能 主導権 何をするか 呼び出し
Tools モデル 外部の操作を実行する tools/list → tools/call
Resources アプリケーション 読み取り専用のデータを渡す resources/list → resources/read
Prompts ユーザー 定型のメッセージ(指示)を渡す prompts/list → prompts/get

Toolsはモデルが「この場面で使おう」と判断して呼びます。これに対しResourcesは、読むかどうかをアプリケーション(ホスト)が決めます。たとえばエディタが開いているファイルの一覧から、ユーザーが選んだものを読ませる、という形です。Promptsはユーザーが明示的に選びます。クライアントの画面ではスラッシュコマンドやメニューの項目として出てくるのが典型です。

つまり、実装するときの問いはこうなります。

  • 状態を変える操作か? → Tools
  • ただ読ませたいデータか? → Resources
  • ユーザーが繰り返し使う定型の指示か? → Prompts

Resources:URIで識別する「読み取り専用のデータ」

Resourcesは、ファイル、データベースのスキーマ、アプリ固有の情報など、モデルへの文脈として渡すデータです。1つ1つのリソースはURIで一意に識別されます。https://やfile://のような既存のスキームも使えますし、handbook://のように独自のスキームを定義することもできます。

URIスキーム 用途の目安
https:// Web上にあり、クライアントが直接取得できるもの
file:// ファイルシステムのように振る舞うもの(実在のファイルでなくてもよい)
git:// Gitのバージョン管理と連携するもの
独自スキーム(例:handbook://) アプリ固有のデータを表すもの

リソースを出すサーバーは、初期化時にresourcesケイパビリティを宣言しなければなりません。クライアントはresources/listで一覧を取り、resources/readで中身を読みます。resources/listにはページネーションがあり、読み取りはテキストかバイナリ(Base64)のどちらかで返ります。存在しないURIを読むと、JSON-RPCエラー-32602(Invalid Params)が返ります。空のcontentsを返してごまかすのは仕様で禁じられています。

リソース定義には、uri・nameのほかに任意でtitle・description・mimeType・sizeを付けられます。さらに、クライアントへのヒントとしてアノテーションを付けられます。

アノテーション 意味
audience 想定する読み手。"user"と"assistant"の配列
priority 重要度。0.0〜1.0で、1が最も重要
lastModified 最終更新日時(ISO 8601形式)

静的なリソースを登録する

Python SDKでは、関数に@mcp.resource()を付けてURIを指定するだけです。関数名がリソースの名前、docstringが説明文になり、戻り値がそのまま中身になります。

from mcp.server import MCPServer

mcp = MCPServer("handbook")

@mcp.resource("handbook://release-checklist", mime_type="text/markdown")
def release_checklist() -> str:
    """リリース前に確認する項目の一覧。"""
    return "- テストがすべて通っている\n- 変更内容を共有済み\n- ロールバック手順を確認済み"

ポイントは3つです。

  • resources/listに載るのは、URI・名前・説明・mimeTypeです。 関数が実行されるのはresources/readで読まれたときだけです。一覧を返すために中身を全部読み込む必要はない、という設計になっています。
  • mime_type=でデータの種類を宣言します。 既定はtext/plainで、SDKが戻り値を見て推測することはありません。Markdownならtext/markdownと明示します。
  • 戻り値の型で返し方が変わります。 strはテキストのまま、bytesはBase64のblobとして、dictなどJSONに変換できるものはJSONテキストとして返ります。

リソーステンプレート:URIのパターンでまとめて公開する

ファイル名やIDごとにリソースが増える場合、1つずつ登録するのは現実的ではありません。そこでリソーステンプレートを使います。URIに{name}のようなプレースホルダ(変数)を含め、関数の引数で受け取ります。

RUNBOOKS: dict[str, str] = {
    "release-rollback": "# リリースのロールバック手順\n\n1. 直前の版に戻す\n2. 動作を確認する",
    "backup-restore": "# バックアップからの復旧手順\n\n1. 最新のバックアップを確認する\n2. 復旧して動作を確認する",
}

@mcp.resource("runbook://{name}", mime_type="text/markdown")
def read_runbook(name: str) -> str:
    """名前で指定した運用手順書を返す。"""
    text = RUNBOOKS.get(name)
    if text is None:
        raise ValueError(f"運用手順書が見つかりません: {name}")
    return text

ポイントは3つです。

  • プレースホルダの名前と、関数の引数名を一致させます。 runbook://release-rollbackを読むと、nameに'release-rollback'が入ります。名前が食い違うと、クライアントが接続する前、importした時点でValueErrorになってサーバーが起動できません。実行時ではなく起動前に気づける、親切な失敗の仕方です。
  • テンプレートはresources/listではなく、resources/templates/listに載ります。 静的リソースの一覧とは別枠で、uriTemplateというパターンとして公開されます。クライアントはパターンを見て、具体的なURIを組み立てて読みに来ます。戻り値に付くURIはテンプレートではなく、実際に読まれた具体URI(runbook://release-rollback)です。
  • 存在しない名前はエラーを投げます。 空のcontentsを返すのではなく、例外にして「ない」ことをはっきり伝えます。

プレースホルダの構文はRFC 6570(URI Template)の決まりに従い、SDKは取り出した値にパス安全性のチェックを既定で適用します。とはいえ、テンプレートの変数をそのままファイルパスに使うのは危険です。..のような値で、想定外のファイルが読めてしまう恐れがあるからです。上の例では、読み取り対象をRUNBOOKSという一覧に限定することで、この問題を避けています。どうしてもファイルから読む場合は、パスを実在のパスに解決してから、決めたディレクトリの内側かどうかを確認してから読むのが決まりです。

変更があったらクライアントに知らせる

リソースの一覧が変わったときは、サーバーからnotifications/resources/list_changedを送ります。1つのリソースの「中身」が変わったときは別の通知(notifications/resources/updated)を使います。一覧の変化と中身の変化は、通知も別物だと覚えておきましょう。

なお、プロンプトについては、Python SDKに実行時の追加・削除(mcp.add_prompt()、mcp.remove_prompt())と、一覧変更の通知を送る仕組みが用意されています。動的に出し入れしたいものがある場合は、まずこの仕組みで足りるかを確認するのが順序です。

Prompts:ユーザーが選ぶ「メッセージのテンプレート」

Promptsは、サーバーが用意するメッセージのテンプレートです。クライアントはprompts/listで一覧を取り、ユーザーが選んだものをprompts/getで取得します。引数を渡すと、テンプレートに引数が埋め込まれたメッセージが返ります。クライアントではスラッシュコマンドやメニューとして表示されるのが典型です。

Python SDKでは、関数に@mcp.prompt()を付けます。関数名がプロンプト名、docstringが説明文、引数がそのままプロンプトの引数になります。

@mcp.prompt()
def review_runbook(name: str) -> str:
    """運用手順書を読み、抜け漏れを指摘する。"""
    return f"手順書「{name}」をレビューしてください。抜け漏れを指摘してください。"

プロンプトの引数は、名前付きの文字列のフラットなリストです。Toolsと違ってJSON Schemaはなく、人がフォームに入力する前提の形になっています。既定値のない引数は必須です。strを返すと、それが1件のユーザーメッセージになります。

表示を整えたい場合は、title=で人間向けの表示名を付け、引数の説明はAnnotatedとField(description=...)で付けます。複数メッセージを返したい場合は、UserMessageとAssistantMessageのリストを返します。

from typing import Annotated

from pydantic import Field
from mcp.server.mcpserver.prompts.base import AssistantMessage, Message, UserMessage

@mcp.prompt(title="手順書レビュー")
def review_runbook(
    name: Annotated[str, Field(description="レビューする手順書の名前")],
    focus: Annotated[str, Field(description="指摘の観点。safetyは安全性、clarityは分かりやすさ")] = "clarity",
) -> list[Message]:
    """運用手順書を読み、抜け漏れを指摘する。"""
    return [
        UserMessage(f"手順書「{name}」をレビューしてください。観点は{focus}です。"),
        AssistantMessage("指摘は次の形式で出します:"),
    ]

focusのように既定値を付けた引数は任意になります。末尾にassistantのメッセージを置くと、それがモデルの返信の出だしになります。メッセージの内容はテキストのほか、画像・音声、リソースの埋め込みも使えます(埋め込みは後述)。

引数の検証:Toolsとは失敗の返り方が違う

プロンプトの引数は、関数が走る前に検証されます。必須の引数が欠けていると、プロトコルエラー(JSON-RPCエラー-32602)でリクエスト全体が失敗し、関数は実行されません。

機能 引数が不正なとき
Tools isError: trueの通常結果が返る(連載⑥)
Prompts プロトコルエラー-32602で失敗する

この違いは、失敗の「持ち主」が違うからです。ツールはモデルが呼ぶものなので、失敗も結果としてモデルに返して修正させます。プロンプトはユーザーが選ぶものなので、引数の不備はリクエスト自体の失敗として扱われます。

入力候補を出す:補完ハンドラ

引数の候補を入力中に提示したい場合は、**補完(Completions)**を使います。Python SDKでは引数ごとに指定するのではなく、サーバーに1つだけ@mcp.completion()のハンドラを登録し、対象(プロンプトかリソーステンプレートか)と引数名で分岐します。プロンプトの引数にも、リソーステンプレートの変数にも使えます。

from mcp.types import (
    Completion,
    CompletionArgument,
    CompletionContext,
    PromptReference,
    ResourceTemplateReference,
)

@mcp.completion()
async def handle_completion(
    ref: PromptReference | ResourceTemplateReference,
    argument: CompletionArgument,
    context: CompletionContext | None,
) -> Completion | None:
    if isinstance(ref, PromptReference) and ref.name == "review_runbook" and argument.name == "name":
        return Completion(values=[n for n in RUNBOOKS if n.startswith(argument.value)])
    if isinstance(ref, ResourceTemplateReference) and argument.name == "name":
        return Completion(values=[n for n in RUNBOOKS if n.startswith(argument.value)])
    return None
  • argument.valueが、ユーザーが入力途中の文字列です。絞り込みはハンドラ側の仕事で、上の例ではstartswithで前方一致に絞っています。
  • 候補がなければNoneを返します。これは空の候補リストとして扱われ、エラーにはなりません。
  • ハンドラを登録すると、completionsケイパビリティはSDKが自動で宣言します。

リソースをプロンプトに埋め込む

プロンプトのメッセージには、リソースの中身を直接埋め込めます。TextResourceContentsに登録済みのリソースと同じURI・MIMEタイプ・テキストを指定し、EmbeddedResourceで包んでUserMessageに入れます。クライアントはresources/readをもう一度呼ぶ必要がなく、埋め込まれた資料を添付のように表示できます。

from mcp.server.mcpserver import Message, UserMessage
from mcp.types import EmbeddedResource, TextResourceContents

@mcp.prompt()
def fix_with_runbook(name: str) -> list[Message]:
    """手順書に沿って障害対応の手順を立てる。"""
    text = RUNBOOKS.get(name)
    if text is None:
        raise ValueError(f"運用手順書が見つかりません: {name}")
    guide = TextResourceContents(
        uri=f"runbook://{name}",
        mime_type="text/markdown",
        text=text,
    )
    return [
        UserMessage(EmbeddedResource(resource=guide)),
        UserMessage("上の手順書に沿って、対応の手順を立ててください。"),
    ]

バイナリの中身を埋め込む場合は、TextResourceContentsの代わりにBlobResourceContentsを使い、Base64のblobで渡します。

これが、3つの機能を組み合わせる基本形です。プロンプトが入口になり、リソースが資料になり、必要ならツールが実行を担う、という流れです。

よくある失敗例

失敗 どうなるか 対策
リソースに副作用を持たせる 「読むだけ」の約束が崩れ、クライアントが安心して読めなくなる 状態を変える処理はToolsに分ける
何でもツールで実装する モデルが毎回判断しなければならず、定型の指示までモデル任せになる 定型の指示はPrompts、資料はResourcesにする
テンプレートがresources/listに出ないと慌てる テンプレートはresources/templates/listに載る仕様で、一覧の場所が違うだけ 静的リソースとテンプレートで一覧が別だと理解する。実例の候補は補完で出す
変数をそのままファイルパスに使う ..で想定外のファイルが読める 一覧で限定するか、解決済みパスが決めた内側か確認する
プロンプトに秘密情報を直書きする 選んだ誰にでも見える形で漏れる 秘密はプロンプトに入れず、引数も検証する

まとめ

  • Resourcesはアプリケーションが選んで読む、読み取り専用のデータ。URIで識別し、resources/listとresources/readで使う。
  • テンプレートを使うと、URIパターン1つで多数のリソースを公開できる。テンプレートはresources/templates/listに載る。
  • Promptsはユーザーが選ぶメッセージのテンプレート。引数は検証され、不備があると-32602のプロトコルエラーになる。
  • リソースをプロンプトに埋め込むと、資料付きの指示を1回で渡せる。
  • 判断基準はシンプルで、状態を変えるならTools、読ませるだけならResources、定型の指示ならPrompts。

次回はリモートMCPサーバーとデプロイを取り上げ、Streamable HTTPでの公開とAWSでのホスティングを解説します。

関連記事

参考リンク

用語集

  • Resources:サーバーが公開する読み取り専用のデータ。ファイルやスキーマなど、モデルへの文脈として使う。アプリケーションが読むかどうかを決める。
  • Prompts:サーバーが用意するメッセージのテンプレート。ユーザーが選んで引数を渡すと、メッセージが会話に入る。
  • URI:リソースを一意に識別する文字列。handbook://release-checklistのように、スキームと名前で表す。
  • リソーステンプレート:runbook://{name}のように変数を含むURIパターン。1つの登録で多数のリソースを公開できる。
  • mimeType:データの種類を表す文字列。text/markdownやapplication/jsonなど。クライアントが扱い方を決める手がかりになる。
  • アノテーション:リソースやプロンプトに付ける任意のヒント。読み手(audience)、重要度(priority)、最終更新日時(lastModified)などがある。
  • ケイパビリティ:サーバーが対応している機能の宣言。ResourcesやPromptsを使うサーバーは、初期化時に宣言しなければならない。
  • listChanged:リソースやプロンプトの一覧が変わったことをクライアントに知らせる通知の仕組み。宣言するとサーバーは変更時に通知を送る。
  • 補完(Completions):プロンプトの引数やリソーステンプレートの変数について、入力途中の文字列に合う候補をサーバーが返す仕組み。Python SDKでは@mcp.completion()のハンドラが担う。
  • EmbeddedResource:プロンプトのメッセージにリソースを埋め込むための表現。URIとMIMEタイプと中身を一緒に運ぶ。
  • docstring:Pythonの関数やクラスの先頭に書く説明文。MCPのPython SDKでは、リソースやプロンプトの説明文として使われる。
  • JSON-RPC 2.0:JSONでリクエストとレスポンスをやり取りする遠隔呼び出しの仕組み。MCPのメッセージ交換の土台。
  • Base64:バイナリデータをテキストとして表すための符号化方式。画像などのバイナリをリソースやメッセージで運ぶときに使う。
0
0
0

Register as a new user and use Qiita more conveniently

  1. You get articles that match your needs
  2. You can efficiently read back useful information
  3. You can use dark theme
What you can do with signing up
0
0

Delete article

Deleted articles cannot be recovered.

Draft of this article would be also deleted.

Are you sure you want to delete this article?