読み込み中

MCPでツールを定義する

レッスン 519 分
読み込み中

MCPサーバーを構築する作業は、公式のMCP Python SDKを使用することで大幅に簡単になります。ツール用の複雑なJSONスキーマを手動で書く代わりに、デコレーターを使ってツールを定義し、面倒な処理はSDKに任せることができます。

document.pdf、spreadsheet.xlsx、report.txt、spec.mdという4つのファイルに接続された、私たちのMCPサーバーのreadツールとupdateツール。

この例では、ドキュメント操作を管理するMCPサーバーを作成しています。このサーバーには2つの主要なツールがあります。1つはドキュメントの内容を読み取るツール、もう1つはそれを更新するツールです。すべてのドキュメントは、キーがドキュメントIDで値が内容の文字列であるシンプルな辞書として、メモリ上に存在します。

MCP Python SDKの利点

MCPプロジェクトは、複数のプログラミング言語にわたってサーバーとクライアントを構築するための公式SDKを提供しています。Python SDKを使用すると、いくつかの利点があります。

  • 最小限のボイラープレートコードでMCPサーバーを作成できる
  • Python関数のシグネチャからJSONスキーマを自動的に生成する
  • デコレーターを通じてツールの定義を簡素化する
  • 型検証とエラー処理を自動的に行う

document.pdf、spreadsheet.xlsx、report.txt、spec.mdという4つのファイルに接続された、私たちのMCPサーバーのreadツールとupdateツール。

SDKを使ってツールを定義するのがどれほど簡単か見てみましょう。@mcp.toolデコレーターは、型ヒントとフィールドの説明と組み合わさることで、Claudeが理解して使用できる適切なツールスキーマを自動的に作成します。

サーバーのセットアップ

このコースでは、MCP Python SDKのバージョン1を使用しています。以下のインポートはバージョン2では失敗します。バージョン2ではFastMCPの名前が変更されているためです。自分でプロジェクトをセットアップする場合は、SDKをバージョン2未満に保ってください。

bash
uv add "mcp[cli]<2"

pipを使う場合、同じ固定指定はpip install "mcp[cli]<2"になります。

基本的なサーバーのセットアップは、ほんの数行で済みます。

python
from mcp.server.fastmcp import FastMCP
from pydantic import Field

mcp = FastMCP("DocumentMCP", log_level="ERROR")

docs = {
    "deposition.md": "This deposition covers the testimony of Angela Smith, P.E.",
    "report.pdf": "The report details the state of a 20m condenser tower.",
    "financials.docx": "These financials outline the project's budget and expenditures",
    "outlook.pdf": "This document presents the projected future performance of the system",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

読み取りツールの実装

最初のツールは、ドキュメントIDを指定することで、Claudeがドキュメントの内容を読み取れるようにします。

python
@mcp.tool(
    name="read_doc_contents",
    description="Read the contents of a document and return it as a string."
)
def read_document(
    doc_id: str = Field(description="Id of the document to read")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    return docs[doc_id]

このツール定義には、以下が含まれます。

  • アクションを説明する明確な名前
  • ツールが何をするかを説明する記述
  • フィールドの説明が付いた型付きパラメータ
  • 無効なドキュメントIDに対するエラー処理

編集ツールの実装

2つ目のツールは、ドキュメントの内容に対してシンプルな検索・置換操作を実行します。

python
@mcp.tool(
    name="edit_document",
    description="Edit a document by replacing a string in the documents content with a new string."
)
def edit_document(
    doc_id: str = Field(description="Id of the document that will be edited"),
    old_str: str = Field(description="The text to replace. Must match exactly, including whitespace."),
    new_str: str = Field(description="The new text to insert in place of the old text.")
):
    if doc_id not in docs:
        raise ValueError(f"Doc with id {doc_id} not found")
    
    docs[doc_id] = docs[doc_id].replace(old_str, new_str)

このツールは、ドキュメントID、検索するテキスト、置換後のテキストという3つのパラメータを受け取ります。実装には、シンプルにするためPythonの組み込み文字列メソッドであるreplace()を使用しています。

実装における重要なポイント

MCP SDKでツールを定義する際は、次の重要なポイントを覚えておいてください。

  • パラメータの説明を追加するため、pydanticからFieldをインポートする
  • パラメータの型を指定するため、型ヒントを使用する
  • エッジケースに対するエラー処理を含める
  • 明確で分かりやすいツール名と説明を書く
  • MCP Python SDKは、関数のシグネチャを適切なJSONスキーマに自動的に変換する

MCP Python SDKは、JSONスキーマを手動で書く場合と比べて、ツール作成の複雑さを劇的に軽減します。かつては数十行ものスキーマ定義が必要だったものが、今ではデコレーターを付けたPython関数を数行書くだけで済みます。

@mcp.toolデコレーターと、そのシグネチャに基づくスキーマ生成は、MCP Python SDKに由来するものです。Claude Agent SDKは、カスタムツールを定義するための別の@toolデコレーターを提供しており、関数シグネチャ上のpydanticのField注釈ではなく、明示的なinput_schema引数を期待します。Pythonでは、このスキーマは{"latitude": float}のようにパラメータ名を型にマッピングする辞書であり、Agent SDKがこれを代わりにJSON Schemaに変換してくれます。あるいは、列挙型、範囲、任意フィールド、ネストされたオブジェクトが必要な場合は、完全なJSON Schema辞書を使うこともできます。どこかでツールのコードを読む際は、それがどちらのSDKをインポートしているかを確認してください。この2つのデコレーターは混同しやすいためです。