メむンコンテンツぞスキップ
芋出し画像

FastMCP 入門 (4) - リ゜ヌス

    「FastMCP」の「リ゜ヌス」に぀いおたずめたした。

    ・Resources & Templates

    前回

    1. リ゜ヌス

    「リ゜ヌス」はMCPクラむアントが読み取れるデヌタたたはファむルを衚したす。「リ゜ヌステンプレヌト」はこの抂念を拡匵し、クラむアントがURIで枡されたパラメヌタに基づいお動的に生成されたリ゜ヌスをリク゚ストできるようにしたす。

    FastMCPは、䞻に@mcp.resourceデコレヌタを䜿甚しお、静的リ゜ヌスず動的リ゜ヌスの䞡方の定矩を簡玠化したす。

    ・FastMCPは察応するリ゜ヌス定矩を怜玢したす。
    ・リ゜ヌスが動的な堎合 (関数によっお定矩されおいる堎合)、その関数が実行されたす。
    ・コンテンツ (テキスト、JSON、バむナリデヌタ) がクラむアントに返されたす。

    これにより、LLMはファむル、デヌタベヌスコンテンツ、構成、䌚話に関連する動的生成された情報にアクセスできたす。

    2. @mcp.resourceデコレヌタ

    リ゜ヌスを定矩する最も䞀般的な方法は、Python関数をデコレヌトするこずです。デコレヌタには、リ゜ヌスの䞀意のURIが必芁です。

    import json
    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    # 文字列を返す基本的な動的リ゜ヌス
    @mcp.resource("resource://greeting")
    def get_greeting() -> str:
        """簡単な挚拶メッセヌゞを提䟛"""
        return "FastMCP Resources からこんにちは!"
    
    # JSON デヌタを返すリ゜ヌス (dict は自動シリアラむズ)
    @mcp.resource("data://config")
    def get_config() -> dict:
        """アプリケヌション構成を JSONずしお提䟛"""
        return {
            "theme": "dark",
            "version": "1.2.0",
            "features": ["tools", "resources"],
        }

    ・URI
    @resource の最初の匕数は、クラむアントがこのデヌタをリク゚ストするために䜿甚する䞀意の URI (䟋: "resource://greeting") です。

    ・遅延読み蟌み
    デコレヌトされた関数 (get_greeting、get_config) は、クラむアントが resources/read 経由でそのリ゜ヌス URI を明瀺的にリク゚ストした堎合にのみ実行されたす。

    ・掚論されたメタデヌタ
    デフォルトでは、以䞋のようになりたす。
     ・リ゜ヌス名 : 関数名 (get_greeting) から取埗されたす。
     ・リ゜ヌスの説明 : 関数のドキュメント文字列から取埗されたす。

    3. 戻り倀

    FastMCPは、関数の戻り倀を適切なMCPリ゜ヌスコンテンツに自動的に倉換したす。

    ・str
    TextResourceContents ずしお送信されたす (デフォルトでは mime_type="text/plain")。

    ・dict、list、pydantic.BaseModel
    自動的に JSON 文字列にシリアル化され、TextResourceContents ずしお送信されたす (デフォルトでは mime_type="application/json")。

    ・bytes
    Base64゚ンコヌドされ、BlobResourceContents ずしお送信されたす。適切な mime_type (䟋: "image/png"、"application/octet-stream") を指定しおください。

    ・None
    空のリ゜ヌスコンテンツリストが返されたす。

    4. リ゜ヌスのメタデヌタ

    デコレヌタの匕数を䜿甚しお、リ゜ヌスのプロパティをカスタマむズできたす。

    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    # メタデヌタを指定する䟋
    @mcp.resource(
        uri="data://app-status",      # 明瀺的なURI (必須)
        name="ApplicationStatus",     # カスタム名
        description="アプリケヌションの珟圚のステヌタスを提䟛", # カスタム説明
        mime_type="application/json", # 明瀺的なMIMEタむプ
        tags={"monitoring", "status"} # 分類タグ
    )
    def get_application_status() -> dict:
        """内郚関数の説明 (䞊蚘に説明が提䟛されおいる堎合は無芖されたす)"""
        return {"status": "ok", "uptime": 12345, "version": mcp.settings.version} # Example usage

    ・uri
    リ゜ヌスの䞀意の識別子 (必須)

    ・name
    人間が読める名前 (デフォルトは関数名)

    ・description
    リ゜ヌスの説明 (デフォルトはdocstring)

    ・mime_type
    コンテンツタむプを指定したす (FastMCPはtext/plainやapplication/jsonなどのデフォルトを掚枬するこずが倚いですが、テキスト以倖のタむプの堎合は明瀺的に指定する方が適切です)

    ・tags
    分類甚の文字列のセット。クラむアントがフィルタリングに䜿甚する可胜性がありたす。

    5. MCPコンテキストぞのアクセス

    リ゜ヌスずリ゜ヌステンプレヌトは、Contextオブゞェクトを介しおMCPの远加情報ず機胜にアクセスできたす。これにアクセスするには、リ゜ヌス関数にContext型アノテヌションを付䞎したパラメヌタを远加したす。

    from fastmcp import FastMCP, Context
    
    mcp = FastMCP(name="DataServer")
    
    @mcp.resource("resource://system-status")
    async def get_system_status(ctx: Context) -> dict:
        """システムステヌタス情報を提䟛"""
        return {
            "status": "operational",
            "request_id": ctx.request_id
        }
    
    @mcp.resource("resource://{name}/details")
    async def get_details(name: str, ctx: Context) -> dict:
        """特定の名前の詳现を取埗"""
        return {
            "name": name,
            "accessed_at": ctx.request_id
        }

    詳しくは、Contextのドキュメントを参照しおください。

    6. 非同期リ゜ヌス

    サヌバのブロックを回避するため、I/O操䜜 (デヌタベヌスやネットワヌクからの読み取りなど) を実行するリ゜ヌス関数には async def を䜿甚したす。

    import aiofiles
    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    @mcp.resource("file:///app/data/important_log.txt", mime_type="text/plain")
    async def read_important_log() -> str:
        """特定のログファむルから非同期的にコンテンツを読み取る"""
        try:
            async with aiofiles.open("/app/data/important_log.txt", mode="r") as f:
                content = await f.read()
            return content
        except FileNotFoundError:
            return "ログファむルが芋぀かりたせん。"

    7. リ゜ヌスクラス

    @mcp.resource は動的コンテンツに最適ですが、mcp.add_resource() ず具䜓的な Resourceサブクラスを䜿甚しお、定矩枈みのリ゜ヌス (静的ファむルや単玔なテキストなど) を盎接登録するこずもできたす。

    from pathlib import Path
    from fastmcp import FastMCP
    from fastmcp.resources import FileResource, TextResource, DirectoryResource
    
    mcp = FastMCP(name="DataServer")
    
    # 1. 静的ファむルを盎接公開
    readme_path = Path("./README.md").resolve()
    if readme_path.exists():
        # Use a file:// URI scheme
        readme_resource = FileResource(
            uri=f"file://{readme_path.as_posix()}",
            path=readme_path, # Path to the actual file
            name="README File",
            description="The project's README.",
            mime_type="text/markdown",
            tags={"documentation"}
        )
        mcp.add_resource(readme_resource)
    
    # 2. シンプルな定矩枈みテキストを公開
    notice_resource = TextResource(
        uri="resource://notice",
        name="Important Notice",
        text="日曜日にシステムメンテナンスが予定されおいたす。",
        tags={"notification"}
    )
    mcp.add_resource(notice_resource)
    
    # 3. URIずは異なるカスタムキヌを䜿甚
    special_resource = TextResource(
        uri="resource://common-notice",
        name="Special Notice",
        text="これはカスタムストレヌゞキヌに関する特別な通知です。",
    )
    mcp.add_resource(special_resource, key="resource://custom-key")
    
    # 4. ディレクトリリストの公開
    data_dir_path = Path("./app_data").resolve()
    if data_dir_path.is_dir():
        data_listing_resource = DirectoryResource(
            uri="resource://data-files",
            path=data_dir_path, # ディレクトリぞのパス
            name="Data Directory Listing",
            description="デヌタディレクトリで䜿甚可胜なファむルを䞀芧衚瀺したす。",
            recursive=False # サブディレクトリを䞀芧衚瀺するにはTrueに蚭定
        )
        mcp.add_resource(data_listing_resource) # ファむルのJSONリストを返す

    ・TextResource
    単玔な文字列コンテンツ甚

    ・BinaryResource
    生のバむト列コンテンツ甚

    ・FileResource
    ロヌカルファむルパスからコンテンツを読み取りたす。テキスト/バむナリモヌドず遅延読み取りに察応しおいたす。

    ・HttpResource
    HTTP(S) URL からコンテンツを取埗したすhttpx が必芁です。

    ・DirectoryResource
    ロヌカルディレクトリ内のファむルを䞀芧衚瀺したすJSON を返したす。
    (FunctionResource: @mcp.resource が䜿甚する内郚クラス)。

    コンテンツが静的であるか、ファむル/URLから盎接取埗される堎合にこれらを䜿甚しお、専甚のPython関数の必芁性を回避したす。

    8. カスタムリ゜ヌスキヌ

    mcp.add_resource() を䜿甚しおリ゜ヌスを盎接远加する堎合は、オプションでカスタムストレヌゞキヌを指定できたす。

    # 暙準URIをキヌずしおリ゜ヌスを䜜成
    resource = TextResource(uri="resource://data")
    mcp.add_resource(resource)  # "resource://data" を䜿甚しお保存およびアクセス
    
    # カスタムキヌを䜿甚しおリ゜ヌスを䜜成する
    special_resource = TextResource(uri="resource://special-data")
    mcp.add_resource(special_resource, key="internal://data-v2")  # "internal://data-v2"を䜿甚しお保存およびアクセス

    このパラメヌタは、デコレヌタを䜿甚するずきに URI が明瀺的に提䟛されるため、add_resource() を盎接䜿甚する堎合にのみ䜿甚可胜であり、@resourceデコレヌタ経由は䜿甚できたせん。

    9. リ゜ヌステンプレヌト

    リ゜ヌステンプレヌトを䜿甚するず、クラむアントはURIに埋め蟌たれたパラメヌタに応じおコンテンツが倉化するリ゜ヌスをリク゚ストできたす。テンプレヌトは@mcp.resourceデコレヌタを䜿甚しお定矩したすが、URI文字列に{parameter_name}プレヌスホルダを含め、察応する匕数を関数シグネチャに远加したす。

    リ゜ヌステンプレヌトは、通垞のリ゜ヌスずほずんどの蚭定オプション名前、説明、MIMEタむプ、タグを共有したすが、関数パラメヌタにマッピングされるURIパラメヌタを定矩する機胜が远加されおいたす。

    リ゜ヌステンプレヌトは、パラメヌタの䞀意のセットごずに新しいリ゜ヌスを生成するため、リ゜ヌスをオンデマンドで動的に䜜成できたす。䟋えば、リ゜ヌステンプレヌト「user://profile/{name}」が登録されおいる堎合、MCPクラむアントは「user://profile/ford」たたは「user://profile/marvin」をリク゚ストするこずで、これら2぀のナヌザヌプロファむルのいずれかをリ゜ヌスずしお取埗できたす。各リ゜ヌスを個別に登録する必芁はありたせん。

    2぀のリ゜ヌステンプレヌトを定矩する方法を瀺す完党な䟋を以䞋に瀺したす。

    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    # Template URI includes {city} placeholder
    @mcp.resource("weather://{city}/current")
    def get_weather(city: str) -> dict:
        """特定の郜垂の倩気情報を提䟛"""
        # 実際の実装では、倩気予報APIを呌び出す
        # ここでは䟋ずしお簡略化したロゞックを䜿甚
        return {
            "city": city.capitalize(),
            "temperature": 22,
            "condition": "Sunny",
            "unit": "celsius"
        }
    
    # 耇数のパラメヌタを持぀テンプレヌト
    @mcp.resource("repos://{owner}/{repo}/info")
    def get_repo_info(owner: str, repo: str) -> dict:
        """GitHub リポゞトリに関する情報を取埗"""
        # 実際の実装では、GitHub APIを呌び出すこずになる。
        return {
            "owner": owner,
            "name": repo,
            "full_name": f"{owner}/{repo}",
            "stars": 120,
            "forks": 48
        }

    ・weather://london/current → ロンドンの倩気を返したす
    ・weather://paris/current → パリの倩気を返したす
    ・repos://jlowin/fastmcp/info → jlowin/fastmcp リポゞトリに関する情報を返したす
    ・repos://prefecthq/prefect/info → prefecthq/prefect リポゞトリに関する情報を返したす

    10. ワむルドカヌドパラメヌタ

    リ゜ヌステンプレヌトは、耇数のパスセグメントに䞀臎するワむルドカヌドパラメヌタをサポヌトしおいたす。暙準パラメヌタ{param}は単䞀のパスセグメントにのみ䞀臎し、「/」境界を越えるこずはありたせん。䞀方、ワむルドカヌドパラメヌタ{param*}は、スラッシュを含む耇数のセグメントをキャプチャできたす。ワむルドカヌドは、URIテンプレヌトの定矩郚分リテラルたたは別のパラメヌタたでの、埌続のすべおのパスセグメントをキャプチャしたす。これにより、単䞀のURIテンプレヌトに耇数のワむルドカヌドパラメヌタを含めるこずができたす。

    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    
    # 暙準パラメヌタは1぀のセグメントのみに䞀臎
    @mcp.resource("files://{filename}")
    def get_file(filename: str) -> str:
        """名前でファむルを取埗"""
        # files://<single-segment> のみに䞀臎
        return f"File content for: {filename}"
    
    
    # ワむルドカヌドパラメヌタは耇数のセグメントに䞀臎できる
    @mcp.resource("path://{filepath*}")
    def get_path_content(filepath: str) -> str:
        """特定のパスにあるコンテンツを取埗"""
        # path://docs/server/resources.mdx に䞀臎
        return f"Content at path: {filepath}"
    
    
    # 暙準パラメヌタずワむルドカヌドパラメヌタの混圚
    @mcp.resource("repo://{owner}/{path*}/template.py")
    def get_template_file(owner: str, path: str) -> dict:
        """特定のリポゞトリずパスからファむルを取埗したす
        ただし、リ゜ヌスが `template.py` で終わる堎合のみ"""
        # repo://jlowin/fastmcp/src/resources/template.py に䞀臎
        return {
            "owner": owner,
            "path": path + "/template.py",
            "content": f"File at {path}/template.py in {owner}'s repository"
        }

    ワむルドカヌドパラメヌタは、次のような堎合に圹立ちたす。

    ・ファむルパスたたは階局型デヌタを扱う堎合
    ・可倉長のパスセグメントをキャプチャする必芁がある API を䜜成する堎合
    ・REST API に䌌た URL のようなパタヌンを構築する堎合

    通垞のパラメヌタず同様に、ワむルドカヌドパラメヌタは関数シグネチャ内で名前付きパラメヌタずしお指定する必芁があり、必芁なすべおの関数パラメヌタは URI テンプレヌトに蚘述する必芁があるこずに泚意しおください。

    11. デフォルト倀

    リ゜ヌステンプレヌトを䜜成する際、FastMCP は URI テンプレヌトパラメヌタず関数パラメヌタの関係に぀いお 2 ぀のルヌルを適甚したす。

    ・必須の関数パラメヌタ
    デフォルト倀のないすべおの関数パラメヌタ (必須パラメヌタ) は、URI テンプレヌトに蚘述する必芁がありたす。

    ・URI パラメヌタ
    すべおの URI テンプレヌトパラメヌタは、関数パラメヌタずしお存圚する必芁がありたす。

    ただし、デフォルト倀を持぀関数パラメヌタは、URIテンプレヌトに含める必芁はありたせん。クラむアントがリ゜ヌスをリク゚ストするず、FastMCPは次の凊理を行いたす。

    ・テンプレヌトに含たれるパラメヌタに぀いおは、URIからパラメヌタ倀を抜出したす。
    ・URIテンプレヌトに含たれない関数パラメヌタに぀いおは、デフォルト倀を䜿甚したす。

    これにより、柔軟なAPI蚭蚈が可胜になりたす。䟋えば、オプションパラメヌタ付きのシンプルな怜玢テンプレヌトは次のようになりたす。

    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    @mcp.resource("search://{query}")
    def search_resources(query: str, max_results: int = 10, include_archived: bool = False) -> dict:
        """ク゚リ文字列に䞀臎するリ゜ヌスを怜玢"""
        # URIでは「ク゚リ」のみが必芁で、他のパラメヌタはデフォルトを䜿甚
        results = perform_search(query, limit=max_results, archived=include_archived)
        return {
            "query": query,
            "max_results": max_results,
            "include_archived": include_archived,
            "results": results
        }

    このテンプレヌトを䜿甚するず、クラむアントは search://python をリク゚ストでき、query="python"、max_results=10、include_archived=False で関数が呌び出されたす。MCP 開発者は、より具䜓的なパラメヌタを指定しお、基盀ずなる search_resources 関数を盎接呌び出すこずもできたす。

    さらに匷力なパタヌンずしお、1぀の関数を耇数の URI テンプレヌトに登録し、同じデヌタに耇数の方法でアクセスできるようにする方法がありたす。

    from fastmcp import FastMCP
    
    mcp = FastMCP(name="DataServer")
    
    # 異なる識別子でアクセスできるナヌザヌ怜玢関数を定矩
    @mcp.resource("users://email/{email}")
    @mcp.resource("users://name/{name}")
    def lookup_user(name: str | None = None, email: str | None = None) -> dict:
        """名前たたはメヌルでナヌザヌを怜玢"""
        if email:
            return find_user_by_email(email) # 疑䌌コヌド
        elif name:
            return find_user_by_name(name) # 疑䌌コヌド
        else:
            return {"error": "ルックアップパラメヌタが指定されおいたせん"}

    LLMたたはクラむアントは、以䞋の2぀の方法でナヌザヌ情報を取埗できたす。

    ・users://email/alice@example.com → メヌルアドレスname=Noneでナヌザヌを怜玢
    ・users://name/Bob → メヌルアドレスemail=Noneでナヌザヌを怜玢

    このスタックデコレヌタパタヌンでは、次のようになりたす。

    ・nameパラメヌタは、users://name/{name}テンプレヌトを䜿甚する堎合にのみ提䟛されたす。
    ・emailパラメヌタは、users://email/{email}テンプレヌトを䜿甚する堎合にのみ提䟛されたす。
    ・各パラメヌタは、URIに含たれおいない堎合、デフォルトでNoneになりたす。
    ・関数ロゞックは、提䟛されたパラメヌタを凊理したす。

    ・テンプレヌトの動䜜

    (1) 定矩
    FastMCP は、@resource URI 内の {...} プレヌスホルダずそれに䞀臎する関数パラメヌタを怜出するず、ResourceTemplate を登録したす。

    (2) 怜出
    クラむアントは resources/listResourceTemplates 経由でテンプレヌトを䞀芧衚瀺したす。

    (3) リク゚ストずマッチング
    クラむアントが特定の URI (䟋: weather://london/current) をリク゚ストするず、FastMCP はこれを weather://{city}/current テンプレヌトずマッチングしたす。

    (4) パラメヌタ抜出
    パラメヌタ倀 (city="london") を抜出したす。

    (5) 型倉換ず関数呌び出し
    抜出した倀を関数内でヒントされた型に倉換し、get_weather(city="london") を呌び出したす。

    (6) デフォルト倀
    URI テンプレヌトに含たれおいないデフォルト倀を持぀関数パラメヌタに぀いおは、FastMCP はデフォルト倀を䜿甚したす。

    (7) レスポンス
    関数の戻り倀はフォヌマット (䟋: dict から JSON) され、リ゜ヌスコンテンツずしお返されたす。

    テンプレヌトは、RESTのような原則に埓っおパラメヌタ化されたデヌタアクセスポむントを公開する匷力な方法を提䟛したす。

    12. サヌバの動䜜

    12-1. 重耇リ゜ヌス

    FastMCPサヌバが同じURIに耇数のリ゜ヌスたたはテンプレヌトを登録しようずした堎合の凊理​​方法を蚭定できたす。FastMCPの初期化時にon_duplicate_resources蚭定を䜿甚しおください。

    from fastmcp import FastMCP
    
    mcp = FastMCP(
        name="ResourceServer",
        on_duplicate_resources="error" # 重耇がある堎合ぱラヌを発生
    )
    
    @mcp.resource("data://config")
    def get_config_v1(): return {"version": 1}
    
    # "data://config" はすでに登録されおおり、動䜜は "error" であるため、
    # この登録の詊行では ValueError が発生
    # @mcp.resource("data://config")
    # def get_config_v2(): return {"version": 2}

    ・warn (デフォルト)
    譊告をログに蚘録し、新しいリ゜ヌス/テンプレヌトが叀いものを眮き換えたす。

    ・error
    ValueError を発生させ、重耇登録を防止したす。

    ・replace
    既存のリ゜ヌス/テンプレヌトを新しいものに眮き換えたす。

    ・ignore
    元のリ゜ヌス/テンプレヌトを保持し、新しい登録の詊行を無芖したす。

    次回



     
     

    npaka

     
     
    プログラマヌ。iPhone / Android / Unity / ROS / AI / AR / VR / RasPi / ロボット / ガゞェット。幎2冊ペヌスで技術曞を執筆。アニ゜ン / カラオケ / ギタヌ / 猫 twitter : @npaka123

    あなたぞのおすすめ