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サーバーに関して⑥:Tools実装の実践

0
Last updated at Posted at 2026-11-18

MCPサーバーに関して⑥:Tools実装の実践

前回(⑤)は、Pythonの公式SDKでSQLiteデータベースを参照する2つのツール(get_schema と run_query)を持つ最小サーバーを作りました。今回はその続きとして、Toolsの実装を深掘りします。スキーマ定義、引数のバリデーション、エラー処理、戻り値の設計——実際に手を動かすとつまずきやすいポイントを、⑤のDBツール2つを題材に整理します。

この記事で分かること

  • ツール定義の必須の3点(名前・説明文・スキーマ)と、Pythonでは何がそれぞれに対応するか
  • 引数の必須・任意の表し方と、制約(長さ・範囲・列挙)をスキーマに載せる方法
  • 引数チェックの2段構えと、isError を使ったエラー返却
  • 戻り値の設計:テキスト中心の content と構造化出力の使い分け
  • LLMに選ばれやすいツール名・説明文の書き方と、annotations の付け方

ツール定義の必須の3点は「名前・説明文・スキーマ」

仕様上、ツール定義の必須の3点は**名前(name)・説明文(description)・入力スキーマ(inputSchema)**です。クライアントは tools/list でこの一覧を取得し、モデルがどれを呼ぶか選びます。呼び出しは tools/call で、結果は content と isError で返ります。

Python SDKでは、この3点はコードの3か所からそのまま作られます(⑤で見た通りです)。

項目 役割 誰が読むか Pythonでの出どころ
name ツールの一意な識別子 クライアント・モデル 関数名
description 何をするツールかの説明 主にモデル 関数のdocstring
inputSchema 引数の型・必須条件(JSON Schema) モデルとSDKの検証 引数の型ヒント(+ Field)
from mcp.server import MCPServer

mcp = MCPServer("sqlite-readonly-server")


@mcp.tool()
def get_schema() -> str:
    """サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す。

    クエリを書く前に、まずこのツールでDBの構造を確認すること。
    """
    ...

get_schema という関数名がそのままツール名に、docstringが説明文に、引数の型ヒントが入力スキーマになります。get_schema は引数がないので、書くべき型ヒントもありません(スキーマの引数部分は空になります)。

仕様ではツール名は1〜128文字、英数字・_・-・. のみが推奨され、スペースやカンマは避けることになっています。Pythonでは関数名のスネークケース(get_schema、run_query のような形)がそのままこの推奨に収まります。

引数の設計:必須・任意と、制約の伝え方

Python SDKでは、デフォルト値のない引数が必須、デフォルト値のある引数が任意になります。Pythonの関数定義そのままの感覚です。

制約や引数ごとの説明を足したいときは、型を Annotated で包んでPydanticの Field を付けます。⑤の run_query に「取得行数の上限を引数化する」改良を加えると、こうなります。

from typing import Annotated

from pydantic import Field

from mcp.server import MCPServer

mcp = MCPServer("sqlite-readonly-server")


@mcp.tool()
def run_query(
    sql: Annotated[
        str,
        Field(
            min_length=1,
            max_length=4000,
            description="実行するSELECT文(1文だけ)。テーブル名やカラム名が分からない場合は、先にget_schemaで確認すること",
        ),
    ],
    max_rows: Annotated[
        int, Field(ge=1, le=100, description="取得する最大行数")
    ] = 100,
) -> str:
    """読み取り専用のSELECTクエリを実行し、結果をテキストで返す。"""
    ...

この定義から、SDKは次のような入力スキーマを生成します。

{
  "type": "object",
  "properties": {
    "sql": {
      "type": "string",
      "minLength": 1,
      "maxLength": 4000,
      "description": "実行するSELECT文(1文だけ)。テーブル名やカラム名が分からない場合は、先にget_schemaで確認すること"
    },
    "max_rows": {
      "type": "integer",
      "minimum": 1,
      "maximum": 100,
      "default": 100,
      "description": "取得する最大行数"
    }
  },
  "required": ["sql"]
}

ポイントは3つです。

  • 必須と任意はデフォルト値で表す。 sql はデフォルト値がないので required に入り、max_rows はデフォルト値 100 があるので任意になります。曖昧なままにすると、モデルが「要るのか要らないのか」迷います。
  • 制約は Field でスキーマに載せる。 文字列の長さは min_length/max_length、数値の範囲は ge(以上)/le(以下)で書きます。候補を列挙したい場合は、型ヒントを Literal["asc", "desc"] のようにするとスキーマでは enum になります。
  • 引数ごとの説明は Field(description=...) に書く。 これがJSON Schemaの description になり、モデルが引数を決める手がかりになります。

大事なのは、制約はスキーマに載せて初めて「検証」になることです。docstringに「最大100行まで」と書くのはモデルへのお願いにすぎませんが、Field(le=100) なら、101以上が渡ってきた時点でSDKが関数の実行前に弾きます(次の節の「1段目」です)。

バリデーションは2段構えにする

引数チェックはスキーマによる検証とハンドラ内の業務チェックの2段で考えます。

  • スキーマ検証(1段目):型・長さ・範囲・必須漏れなど、形の問題はここで止まります。Python SDKでは、検証に失敗した呼び出しは関数が実行されず、「上限を超えた」といった内容のエラーがツール結果としてモデルに返ります。モデルはそれを読んで、値を直して再試行できます。
  • 業務チェック(2段目):型は正しいが意味的に使えない値のチェックです。run_query のSQLは「文字列」という形だけでは中身を縛れないため、⑤で実装した「SELECT文だけ通す」「単文のみ」「行数上限」という検証がこの段にあたります。⑤の多層防御のうち、層2〜4(文の検証・単文制限・行数上限)が業務チェック、層1(読み取り専用接続)は実行環境側の制約でした。

つまり、スキーマで表せる制約はスキーマへ、表せない意味の制約はハンドラへ、が役割分担です。

エラーは2種類に分ける

仕様はエラーを2種類に分けています。これを混同すると、モデルが自己修正できなくなります。

種類 例 返し方
プロトコルエラー 存在しないツール名、壊れたリクエスト JSON-RPCエラー
ツール実行エラー SQLの文法違い、範囲外の値、DBの失敗 isError: true の通常結果

ツール実行エラーは普通の結果として isError: true と説明文を返すのが決まりです。モデルは内容を読んで引数を直し、再試行できます。Python SDKでは、ツール関数の中で起きた例外は原則としてツール実行エラーに変換されます。ただし MCPError(from mcp import MCPError)を投げた場合だけは例外で、ラッパーに捕捉されず、プロトコルエラー(JSON-RPCエラー)としてクライアントに返ります。一方、ResourcesやPromptsのコールバックには isError の受け皿がないため、そちらで投げた例外はプロトコルエラーになります。

Pythonでのエラーの返し方は4通り

Python SDKで、ツールの中から失敗を伝える方法は次の4通りです。

1. エラー文字列を返す(⑤の run_query の方式)

@mcp.tool()
def run_query(sql: str) -> str:
    """読み取り専用のSELECTクエリを1文だけ実行し、結果をテキストで返す。"""
    statement = sql.strip().rstrip(";").strip()
    if not statement:
        return "エラー: SQLが空です。"
    ...

通常の戻り値として返すだけなので実装は簡単で、モデルは文字列を読んでSQLを直せます。ただし結果に isError は付かないため、呼び出し側のプログラムからは成功と失敗を区別できません。

2. ToolError を投げる

予期できる失敗には、公式ドキュメントで案内されている ToolError を使うのが基本です。

import re

from mcp.server import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

mcp = MCPServer("sqlite-readonly-server")


@mcp.tool()
def run_query(sql: str) -> str:
    """読み取り専用のSELECTクエリを1文だけ実行し、結果をテキストで返す。"""
    statement = sql.strip().rstrip(";").strip()
    if not statement:
        raise ToolError("SQLが空です。SELECT文を1文指定してください。")
    if ";" in statement:
        raise ToolError(
            "実行できるのは1文だけです。文を分けず、1文だけ渡してください。"
        )
    if not re.match(r"(?is)^(select|with)\b", statement):
        raise ToolError(
            "SELECT文(またはWITHで始まるSELECT)だけ実行できます。"
            f"受け取った文の先頭: {statement[:20]!r}"
        )
    ...

ToolError のメッセージは isError: true の結果としてクライアントに届き、モデルが読める形で content に入ります。「失敗した」という事実と理由の両方を伝えられるのが、文字列返しとの違いです。

3. 予期しない例外(そのまま投げっぱなし)

想定外の例外もSDKが捕捉し、isError: true の結果に変換するため、サーバーが落ちることはありません。ただしこの場合、例外のメッセージはクライアントに届かず、結果は「Error executing tool run_query」のような名前だけの文面になります。詳しい原因はサーバー側のログにしか残りません。

4. MCPError を投げる(プロトコルエラーとして返す)

MCPError(from mcp import MCPError)は、ツール関数のラッパーが捕捉しない唯一の例外です。投げると結果そのものが返らず、tools/call のリクエスト自体がJSON-RPCエラーで失敗します。モデルには何も届かず、エラーはホストアプリケーション側に返ります(code・message・data はそのまま届きます)。

使うのは「モデルが引数を直しても解決しない」失敗のときです。例えば、参照先のDBファイルが存在しないのはサーバー側のセットアップ不備で、モデルがSQLを書き直して再試行しても無駄です。

from mcp import MCPError
from mcp.types import INTERNAL_ERROR

if not DB_PATH.exists():
    raise MCPError(
        code=INTERNAL_ERROR,
        message="参照先のDBファイルが見つかりません。サーバー側のセットアップを確認してください。",
    )

判断の目安は「もっと賢いモデルなら、この失敗を避けられたか」です。避けられたなら ToolError、避けられないなら MCPError と考えます。

この4つを踏まえた使い分けは次の通りです。

  • 予期できる失敗は ToolError で投げる。 メッセージには「何が悪くて、どう直せばいいか」を具体的に書きます。
  • 文字列返しは、モデルにだけ読ませれば十分な最小構成向け。 ⑤のように学習用のサンプルでは悪くありませんが、実務では成否を区別できる ToolError の方が扱いやすくなります。
  • リクエスト自体の不備は MCPError でプロトコルエラーにする。 前提条件の欠落やサーバー側のセットアップ不備など、モデルに直させても無駄な失敗は、モデルではなくホスト側に返します。
  • どちらでも、メッセージの書き方が肝心です。
# 悪い例:何が悪いか分からない
raise ToolError("エラー")

# 良い例:受け取った値と直し方が分かる
raise ToolError("SELECT文だけ実行できます。受け取った文の先頭: 'DELETE'")

戻り値の設計:テキスト中心、構造化出力は任意

ツールの結果は content(テキスト・画像・音声などのブロック配列)が中心です。仕様上、構造化出力は任意で、使う場合は outputSchema を宣言し、結果を structuredContent で返します。後方互換のため、構造化出力と一緒にJSONをテキストブロックにも入れることが推奨されています。

Python SDKでは、この宣言を手で書く必要はありません。戻り値の型ヒントがそのまま outputSchema になります。

  • -> str で文字列を返すと、content にテキストが入り、structuredContent には {"result": "..."} という形で同じ文字列が入ります。モデルが読むのは content の方です。run_query の結果(ヘッダー行+データ行のテキスト)はこの形で十分です。
  • Pydanticの BaseModel(や TypedDict、dataclass)を返すと、そのクラス定義が outputSchema になり、structuredContent にオブジェクトそのものが入ります。content には同じオブジェクトをJSONテキストにしたものが自動で入るため、モデルも読めます。

get_schema を構造化して返す形に変えると、こうなります。

from pydantic import BaseModel, Field

from mcp.server import MCPServer

mcp = MCPServer("sqlite-readonly-server")


class ColumnInfo(BaseModel):
    """テーブルのカラム1件分の情報。"""

    name: str = Field(description="カラム名")
    type: str = Field(description="SQLiteの型名(INTEGER、TEXTなど)")
    primary_key: bool = Field(description="主キーの一部ならtrue")


class TableInfo(BaseModel):
    """テーブル1件分の情報。"""

    name: str = Field(description="テーブル名")
    columns: list[ColumnInfo]


class DatabaseSchema(BaseModel):
    """DB全体のスキーマ情報。"""

    tables: list[TableInfo]


@mcp.tool()
def get_schema() -> DatabaseSchema:
    """サンプルDBのテーブル一覧と、各テーブルのカラム名・型を構造化して返す。"""
    conn = _connect_readonly()  # ⑤で定義した読み取り専用接続のヘルパー
    try:
        tables: list[TableInfo] = []
        for (table,) in conn.execute(
            "SELECT name FROM sqlite_master "
            "WHERE type = 'table' AND name NOT LIKE 'sqlite_%' "
            "ORDER BY name"
        ):
            columns = [
                ColumnInfo(
                    name=info[1], type=info[2], primary_key=bool(info[5])
                )
                for info in conn.execute(f"PRAGMA table_info({table})")
            ]
            tables.append(TableInfo(name=table, columns=columns))
        return DatabaseSchema(tables=tables)
    finally:
        conn.close()

戻した値は outputSchema で検証されてからクライアントに届きます。スキーマに合わない値を返すと、その呼び出し自体がツールエラーになります。

設計の目安は次のとおりです。

  • モデルに読ませる結果はテキストで十分です。まずは -> str の1本で始めましょう。
  • プログラムで後処理する結果(スキーマ情報、件数、ID、状態など)は、モデルクラスを返すと structuredContent で受け取れます。
  • 構造化出力が要らないツールは @mcp.tool(structured_output=False) でテキストだけにできます。
  • 返すクラスには型ヒントを必ず付けること。注釈のないクラスを返すとスキーマを作れず、オブジェクトの repr(<... object at 0x...> のような文字列)がモデルに届く事故になります。

名前と説明文は「LLMへの説明書」

モデルはツール一覧の description を主に見て、どのツールを呼ぶか決めます(name や inputSchema も判断材料になります)。つまり説明文=docstringは人間向けのドキュメントではなく、モデルへの指示文です。

  • 動詞から始めて、何をするか・何が返るかを1〜2文で書く。 例:「サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す」
  • 似たツールの違いを書き分ける。 get_schema と run_query が両方あるなら、「カラム名が分からない場合は、先にget_schemaで確認すること」のように、使い分けの条件を互いのdocstringに入れます(⑤で実践した形です)。
  • 制約も説明に含める。 「使えるのはSELECT文のみ」「最大100行まで」まで書いておくと、モデルが無効な呼び出しをする確率が下がります。ただし検証そのものはスキーマと業務チェックの仕事で、説明は補助だという役割分担は崩さないこと。
  • ツール名は動詞+対象の形にする。 get_schema、run_query のように、読んだだけで動作が想像できる名前にします。

annotationsでクライアントに性質を伝える

ツールの性質(読み取り専用か、破壊的かなど)は annotations でクライアントに伝えられます。Python SDKでは、デコレータに ToolAnnotations を渡します。あわせて title でUI表示用の名前も付けられます。

from mcp.server import MCPServer
from mcp.types import ToolAnnotations

mcp = MCPServer("sqlite-readonly-server")


@mcp.tool(
    title="DBスキーマ取得",
    annotations=ToolAnnotations(read_only_hint=True, open_world_hint=False),
)
def get_schema() -> str:
    """サンプルDBのテーブル一覧と、各テーブルのカラム名・型を返す。"""
    ...

ヒントは4種類あります。

ヒント 意味
read_only_hint 環境を変更しない(読み取り専用)
destructive_hint 破壊的な更新を行いうる(書き込み系のツール向け)
idempotent_hint 同じ引数で繰り返し呼んでも追加の効果がない
open_world_hint Webなど開かれた外部とやり取りする

get_schema と run_query はどちらも読み取り専用で、対象もローカルのDBだけなので、read_only_hint=True、open_world_hint=False が実態に合います。クライアントはこれを見て「実行前にユーザーの確認を求めるか」などの判断材料にします。

ただし、annotationsはヒントであって保証ではありません。読み取り専用の担保は、あくまで⑤で実装した読み取り専用接続や文の検証といった実装側の仕組みです。annotationsは実態に正直に付け、過信しないことが大切です。

よくある失敗例

失敗 どうなるか 対策
docstringが「便利なツール」だけ モデルがいつ使うか判断できない 何をするか・何が返るかを具体的に書く
任意にしたい引数にデフォルト値を付け忘れる 必須扱いになり、モデルが値をでっち上げて渡す デフォルト値で任意を明示する
制約をdocstringにしか書かない 検証されず、そのまま関数に渡ってしまう Field や Literal でスキーマに載せる
予期できる失敗を素の例外で投げる isError にはなるがメッセージが届かず、直し方を伝えられない ToolError で理由と直し方を書いて投げる
型ヒントのないクラスを返す スキーマが作れず、repr の文字列がモデルに届く BaseModel や TypedDict で型を注釈して返す
ツール名にスペースや日本語を使う 仕様の推奨から外れ、互換性が落ちる 英数字・_・-・. だけにする

まとめ

  • ツール定義の必須の3点は名前・説明文・スキーマ。Pythonでは関数名・docstring・型ヒントがそれぞれに対応し、説明文はモデルへの指示文として書く。
  • 必須・任意はデフォルト値で表し、制約と引数の説明は Field や Literal でスキーマに集約する。
  • バリデーションはスキーマ検証+ハンドラ内の業務チェックの2段構え。スキーマで表せない意味の制約(SQLの文種別など)は業務チェックで見る。
  • 実行時の失敗は isError: true の通常結果で返す。予期できる失敗は ToolError で直し方まで書くのが基本で、モデルに直させても無駄なリクエスト自体の不備は MCPError でプロトコルエラーとして返す。
  • 戻り値はテキスト中心。構造化出力は戻り値の型ヒントから自動で作られ、必要なときだけモデルクラスを返す。
  • annotations はクライアントへのヒント。正直に付けるが、担保は実装側の仕組みで取る。

次回はResourcesとPromptsの実装を取り上げ、Toolsとの組み合わせ方を解説します。

関連記事

参考リンク

用語集

  • JSON Schema:JSONデータの形(型・必須項目・値の範囲など)を宣言する仕様。MCPではツールの入力・出力の形を表すのに使う。
  • inputSchema:ツールが受け取る引数の形を定義したJSON Schema。モデルはこれを見て引数を作る。Python SDKでは型ヒントから自動生成される。
  • outputSchema:ツールが返す構造化データの形を定義したJSON Schema。Python SDKでは戻り値の型ヒントから自動生成される。
  • structuredContent:outputSchema に沿った機械可読な結果。テキストの content と併用する。
  • isError:ツールの実行結果が失敗であることを示すフラグ。true ならツール側の失敗で、モデルは内容を読んで再試行できる。
  • Pydantic:Pythonでデータの形(スキーマ)を宣言し、検証するためのライブラリ。MCPのPython SDKは、型ヒントからのスキーマ生成や引数・戻り値の検証に使っている。
  • Field:Pydanticで、引数やフィールドに説明や制約(長さ・範囲など)を付ける仕組み。Annotated[型, Field(...)] の形で書く。
  • ToolError:Python SDKで、ツールの失敗をモデルに伝えるときに投げる例外。isError: true の結果に変換され、メッセージがモデルに届く。
  • MCPError:Python SDKのプロトコルエラーを表す例外(from mcp import MCPError)。ツール関数の中で投げるとラッパーに捕捉されず、JSON-RPCエラーとしてクライアントに返る。モデルでは直せない、リクエスト自体の不備に使う。
  • annotations:ツールの性質(読み取り専用か、破壊的かなど)をクライアントに伝える任意のヒント。実行内容は変えず、保証にもならない。
  • JSON-RPC 2.0:JSONでリクエストとレスポンスをやり取りする遠隔呼び出しの仕組み。MCPのメッセージ交換の土台。
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?