読み込み中

MCPでツールを定義する

レッスン 310 分

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

私たちのMCPサーバーの読み取りツールと更新ツールが、document.pdf、spreadsheet.xlsx、report.txt、spec.mdという4つのファイルに接続されている様子。

この例では、2つの中核ツールを備えたドキュメント管理サーバーを作成します。1つはドキュメントを読み取るツール、もう1つはドキュメントを更新するツールです。すべてのドキュメントは、キーがドキュメントID、値がコンテンツとなるシンプルな辞書としてメモリ上に存在します。

プロジェクトの取得

このコースのレッスンは、MCPクライアントとMCPサーバーを備えたコマンドラインチャットボットという小さなスターター プロジェクトを基に構築されています。このレッスンの最後にあるダウンロードセクションからcli_project.zipをダウンロードし、お好みの開発用ディレクトリに展開してください。プロジェクトフォルダでコードエディタを開きます。

プロジェクトにはセットアップ手順が記載されたREADMEファイルが含まれています。.envファイルにAnthropicのAPIキーを追加してください。その後、uv(推奨)またはpipのいずれかを使って依存関係をインストールします。このプロジェクトはMCP Python SDKのバージョン1を使用しており、セットアップ時にそのバージョンがインストールされます。

MCPサーバーのセットアップ

MCP Python SDKを使うと、サーバーの作成が簡単になります。mcp_server.pyを開いてください。すでにたった1行でサーバーが初期化されています。以下のツールにはFieldのインポートも必要です。

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

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

ドキュメントはシンプルな辞書構造で保存できます。

python
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"
}

デコレータによるツール定義

SDKはデコレータを使ってツールを定義します。JSONスキーマを手作業で書く代わりに、Pythonの型ヒントとフィールドの説明を使用できます。SDKはClaudeが理解できる適切なスキーマを自動的に生成します。

ドキュメントリーダーツールの作成

最初のツールは、IDによってドキュメントの内容を読み取ります。完全な実装は以下の通りです。

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]

デコレータはツール名と説明を指定し、関数のパラメータは必須の引数を定義します。PydanticのFieldクラスは引数の説明を提供し、Claudeが各パラメータに何が期待されているかを理解するのに役立ちます。

ドキュメントエディタツールの構築

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つのパラメータを受け取ります。実装には、ドキュメントが見つからない場合のエラー処理が含まれており、単純な文字列置換を行います。

SDKアプローチの主な利点

  • JSONスキーマを手作業で書く必要がない
  • 型ヒントによって自動的な検証が行われる
  • 明確なパラメータの説明がClaudeのツール使用の理解を助ける
  • エラー処理がPythonの例外と自然に統合される
  • デコレータを通じてツールの登録が自動的に行われる

MCP Python SDKは、ツール作成を複雑なスキーマ記述作業から、シンプルなPython関数定義へと変えてくれます。このアプローチにより、Claudeが適切にフォーマットされたツール仕様を確実に受け取れるようにしながら、MCPサーバーの構築と保守がはるかに容易になります。

ダウンロード

  • Starter project (cli_project.zip)

    The chatbot project you build on for the rest of this course.

    ダウンロード
  • Completed project (cli_project_COMPLETE.zip)

    The finished version, for checking your work.

    ダウンロード