Skip to content

πŸš€ The fast, Pythonic way to build MCP servers and clients.

11.6 KB
Raw Blame
"""Wire-schema cache behind the SDK's `get_tool_input_schema` hook (mcp>=2.3).

Every argument-bearing `tools/call` made the SDK fall back to running the
server's full `tools/list` handler β€” all `on_list_tools` middleware, provider
enumeration, and request logging β€” just to find one tool's input schema
(#5652). FastMCP now serves the sync hook from a wire-schema cache: local tool
registration seeds it, and every `tools/list` response refreshes it (which also
covers proxied and mounted tools).
"""

import json
from typing import Annotated

from pydantic import Field
from starlette.testclient import TestClient

from fastmcp import Client, FastMCP
from fastmcp.server.middleware import Middleware
from fastmcp.server.transforms.tool_transform import ToolTransform
from fastmcp.tools import Tool
from fastmcp.tools.tool_transform import (
    ArgTransform,
    ArgTransformConfig,
    ToolTransformConfig,
)

# A parameter carrying an Mcp-Param header annotation, as the SDK's
# validate_mcp_param_headers reads it out of the wire input schema.
HDR = Annotated[str, Field(json_schema_extra={"x-mcp-header": "Region"})]


def _hook(server: FastMCP):
    return server._mcp_server.get_tool_input_schema


def test_hook_installed():
    server = FastMCP("t")

    assert callable(_hook(server))
    # Unknown tools must not raise from the hook.
    assert _hook(server)("no-such-tool") is None


async def test_local_tool_available_before_any_listing():
    server = FastMCP("t")

    @server.tool
    def echo(text: str) -> str:
        return text

    schema = _hook(server)("echo")

    assert schema is not None
    assert "text" in schema["properties"]


async def test_transformed_schema_is_served():
    server = FastMCP("t")

    def add(old_x: int, old_y: int) -> int:
        return old_x + old_y

    base = Tool.from_function(add, name="add")
    renamed = Tool.from_tool(
        base,
        transform_args={
            "old_x": ArgTransform(name="x"),
            "old_y": ArgTransform(name="y"),
        },
    )
    server.add_tool(renamed)

    schema = _hook(server)("add")

    assert schema is not None
    # The renamed (wire) parameters, not the original ones.
    assert set(schema["properties"]) == {"x", "y"}


async def test_listing_covers_mounted_tools():
    nested = FastMCP("nested")

    @nested.tool
    def remote(x: int) -> int:
        return x

    server = FastMCP("main")
    server.mount(nested, namespace="nested")

    # Mounted tools resolve asynchronously, so they can only enter the cache
    # through a listing.
    assert _hook(server)("nested_remote") is None

    async with Client(server) as client:
        tools = await client.list_tools()

    assert [tool.name for tool in tools] == ["nested_remote"]
    schema = _hook(server)("nested_remote")
    assert schema is not None
    assert "x" in schema["properties"]


async def test_listing_refresh_replaces_stale_entries():
    server = FastMCP("t")

    @server.tool
    def keep(text: str) -> str:
        return text

    temp = Tool.from_function(lambda: "temp", name="temp")
    server.add_tool(temp)
    assert _hook(server)("temp") is not None

    server._local_provider.remove_tool("temp")

    # Removal evicts the cache entry immediately, not only after the next
    # listing β€” a stale schema could otherwise keep header-validating a tool
    # that no longer exists.
    assert _hook(server)("temp") is None
    assert _hook(server)("keep") is not None

    async with Client(server) as client:
        await client.list_tools()

    # The removal evicted "temp" and the listing (which cannot see it anymore)
    # merges without resurrecting it, so it stays out.
    assert _hook(server)("temp") is None
    assert _hook(server)("keep") is not None


def test_tools_call_does_not_run_list_middleware():
    listings = 0

    class CountListings(Middleware):
        async def on_list_tools(self, context, call_next):
            nonlocal listings
            listings += 1
            return await call_next(context)

    server = FastMCP("demo")
    server.add_middleware(CountListings())

    @server.tool
    def echo(text: str) -> str:
        return text

    app = server.http_app(stateless_http=True)
    with TestClient(app) as client:
        response = client.post(
            "/mcp",
            json={
                "jsonrpc": "2.0",
                "id": 1,
                "method": "tools/call",
                "params": {
                    "name": "echo",
                    "arguments": {"text": "hi"},
                    "_meta": {
                        "io.modelcontextprotocol/protocolVersion": "2026-07-28",
                        "io.modelcontextprotocol/clientCapabilities": {},
                    },
                },
            },
            headers={
                "Accept": "application/json, text/event-stream",
                "MCP-Protocol-Version": "2026-07-28",
                "Mcp-Method": "tools/call",
                "Mcp-Name": "echo",
            },
        )
        assert response.status_code == 200, response.text[:300]
        assert "hi" in response.text

    # The argument-bearing call must not have run the tools/list handler.
    assert listings == 0


async def test_auth_scoped_listing_does_not_evict_other_schemas():
    """An auth-filtered `tools/list` must not clear other principals' schemas.

    The cache is one shared server-wide dict: a listing visible to only one
    client (here: middleware filtering the catalog) merges into it instead of
    replacing it, so another client's already-cached schema keeps validating
    Mcp-Param headers instead of silently fail-opening (#5666 review).
    """

    server = FastMCP("t")

    @server.tool
    def alpha(x: int) -> int:
        return x

    @server.tool
    def beta(y: int) -> int:
        return y

    class OnlyBeta(Middleware):
        async def on_list_tools(self, context, call_next):
            return [tool for tool in await call_next(context) if tool.name == "beta"]

    server.add_middleware(OnlyBeta())

    async with Client(server) as client:
        listed = await client.list_tools()

    assert [tool.name for tool in listed] == ["beta"]
    # The scoped listing serves beta but must not evict alpha's schema.
    assert _hook(server)("beta") is not None
    assert _hook(server)("alpha") is not None
    assert "x" in _hook(server)("alpha")["properties"]


async def test_version_scoped_removal_keeps_surviving_version():
    """Evicting on remove_tool must not go further than the removed version."""

    server = FastMCP("t")
    server.add_tool(Tool.from_function(lambda: "v1", name="dup", version="1.0"))
    server.add_tool(Tool.from_function(lambda: "v2", name="dup", version="2.0"))

    schema = _hook(server)("dup")
    assert schema is not None

    # Removing one version re-seeds the cache from the surviving version
    # instead of evacuating the logical name.
    server._local_provider.remove_tool("dup", version="2.0")
    schema = _hook(server)("dup")
    assert schema is not None

    # Removing the last version evicts the entry entirely.
    server._local_provider.remove_tool("dup", version="1.0")
    assert _hook(server)("dup") is None


async def test_seed_serves_highest_version_not_last_registered():
    """Regression (#5666 review repro 1): registering an older version after
    a newer one must not seed the older version's schema. Dispatch serves the
    highest version, so the cache must hold that version's schema β€” a cached
    `x-mcp-header` annotation from the wrong version fails closed (HTTP 400)
    on calls main accepts."""

    def v2(region: str) -> str:
        return f"v2:{region}"

    def v1(region: HDR) -> str:
        return f"v1:{region}"

    server = FastMCP("t")
    server.add_tool(Tool.from_function(v2, name="t", version="2.0"))
    server.add_tool(Tool.from_function(v1, name="t", version="1.0"))

    schema = _hook(server)("t")

    # v2 (the highest version, and the one dispatch runs) has no header
    # annotation; seeding v1's schema would demand Mcp-Param-Region.
    assert schema is not None
    assert "x-mcp-header" not in json.dumps(schema)


async def test_reseed_after_removal_sorts_versions_semantically():
    """Regression (#5666 review repro 2): re-seeding after a version-scoped
    removal must pick the surviving version the way dispatch does (PEP 440),
    not lexicographic string order where "9" > "10"."""

    def v9(region: HDR) -> str:
        return f"v9:{region}"

    def v10(region: str) -> str:
        return f"v10:{region}"

    def v11(region: str) -> str:
        return f"v11:{region}"

    server = FastMCP("t")
    server.add_tool(Tool.from_function(v9, name="t", version="9"))
    server.add_tool(Tool.from_function(v10, name="t", version="10"))
    server.add_tool(Tool.from_function(v11, name="t", version="11"))

    # Removing the highest version re-seeds from v10 (plain), not v9 (which
    # carries the header annotation and would fail closed).
    server._local_provider.remove_tool("t", version="11")

    schema = _hook(server)("t")

    assert schema is not None
    assert "x-mcp-header" not in json.dumps(schema)


async def test_seed_skipped_when_server_transform_rewrites_schema():
    """Regression (#5666 review repro 3): with a server-level ToolTransform
    renaming arguments, the pre-transform schema must not be seeded. The
    cache entry is dropped instead; the next tools/list (which applies the
    transform) is the only writer, and until then a miss fails open."""

    def f(region: HDR) -> str:
        return f"region:{region}"

    server = FastMCP(
        "t",
        transforms=[
            ToolTransform(
                {
                    "t": ToolTransformConfig(
                        arguments={"region": ArgTransformConfig(name="area")}
                    )
                }
            )
        ],
    )
    server.add_tool(Tool.from_function(f, name="t"))

    # No seeded entry: the transform-aware wire schema is only known after a
    # listing. A stale pre-transform entry would reject calls carrying
    # Mcp-Param-Region even though the wire argument is now "area".
    assert _hook(server)("t") is None

    async with Client(server) as client:
        tools = await client.list_tools()

    assert [tool.name for tool in tools] == ["t"]
    schema = _hook(server)("t")
    assert schema is not None
    assert set(schema["properties"]) == {"area"}


async def test_add_transform_drops_schemas_seeded_before_it():
    """A decorator tool seeds its pre-transform schema; a transform added
    afterwards renames the annotated argument. The seeded entry must be
    dropped so calls carrying the header are not rejected against a schema
    the tool no longer has."""
    server = FastMCP("t")

    @server.tool
    def t(region: HDR) -> str:
        return f"region:{region}"

    assert _hook(server)("t") is not None

    server.add_transform(
        ToolTransform(
            {
                "t": ToolTransformConfig(
                    arguments={"region": ArgTransformConfig(name="area")}
                )
            }
        )
    )

    assert _hook(server)("t") is None

    async with Client(server) as client:
        await client.list_tools()

    schema = _hook(server)("t")
    assert schema is not None
    assert set(schema["properties"]) == {"area"}


async def test_provider_add_transform_drops_seeded_schemas():
    server = FastMCP("t")

    @server.tool
    def t(region: HDR) -> str:
        return f"region:{region}"

    server._local_provider.add_transform(
        ToolTransform(
            {
                "t": ToolTransformConfig(
                    arguments={"region": ArgTransformConfig(name="area")}
                )
            }
        )
    )

    assert _hook(server)("t") is None