読み込み中

MCPでツールを定義する

レッスン 5010 分
読み込み中

公式のPython SDKを使用すると、MCPサーバーの構築がはるかに簡単になります。ツール用の複雑なJSONスキーマを手作業で書く代わりに、SDKがデコレータと型ヒントを使ってその複雑さをすべて処理してくれます。

ドキュメントの読み取りと更新を行うツールを備えた、document.pdf、spreadsheet.xlsx、report.txt、spec.mdに接続された当社のMCPサーバー。

この例では、メモリ内に保存されたドキュメントを管理するMCPサーバーを作成します。このサーバーは2つの重要なツールを提供します。1つはドキュメントの内容を読み取るためのもの、もう1つは検索・置換操作によってそれらを更新するためのものです。

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

このプロジェクトではMCP Python SDKのバージョン1を使用しており、そのセットアップによってそのバージョンがインストールされます。自分でプロジェクトをセットアップする場合は、"mcp[cli]<2" をインストールしてください。バージョン2では FastMCP が MCPServer に名称変更されたため、以下のインポートはバージョン2では失敗します。

Python MCP SDKを使うと、サーバーの作成が驚くほど簡単になります。わずか1行で完全なMCPサーバーを初期化できます。

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

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

この実装では、ドキュメントはシンプルなPythonの辞書に保存され、キーがドキュメントID、値がドキュメントの内容を含みます。

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 expenditure",
    "outlook.pdf": "This document presents the projected future performance of the",
    "plan.md": "The plan outlines the steps for the project's implementation.",
    "spec.txt": "These specifications define the technical requirements for the equipment"
}

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

ドキュメントの読み取りと更新を行うツールを備えた、document.pdf、spreadsheet.xlsx、report.txt、spec.mdに接続された当社のMCPサーバー。

SDKは、ツール作成を冗長なプロセスから、すっきりと読みやすいものに変えてくれます。長いJSONスキーマを書く代わりに、Pythonのデコレータと型ヒントを使用します。

ドキュメント読み取りツールの作成

最初のツールは、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]

@mcp.tool デコレータは、Claudeが必要とするJSONスキーマを自動的に生成します。PydanticからきたFieldクラス、すなわち 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つのパラメータを受け取ります。この実装では、シンプルさのためにPythonの組み込み文字列メソッドである replace() を使用しています。

エラー処理

両方のツールには、Claudeが存在しないドキュメントを要求した場合に対応するための基本的なエラー処理が含まれています。無効なドキュメントIDが指定された場合、ツールはClaudeが理解し、必要に応じて対処できるような説明的なメッセージとともに ValueError を送出します。

SDKアプローチの主な利点

  • Pythonの型ヒントからのJSONスキーマの自動生成
  • 保守しやすい、すっきりとした読みやすいコード
  • Pydanticによる組み込みのパラメータ検証
  • 手動でのスキーマ記述に比べてボイラープレートが削減される
  • 開発時の型安全性とIDEサポート

MCP Python SDKは、かつてはツール定義を書くための複雑なプロセスだったものを、Python開発者にとって自然に感じられるものへと変えてくれます。プロトコルの詳細はSDKが処理してくれるため、あなたはビジネスロジックに集中できます。