Skip to content

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

6.3 KB
Raw Blame
"""Result validation for tool calls that pin a version.

`Client.call_tool(name, version=...)` executes that exact version on the
server. The session's output-schema cache is keyed by tool name and holds only
the highest version's schema (`list_tools` deduplicates by identifier), so the
pinned result cannot be checked against it: the client has no schema for the
version that actually ran.
"""

from __future__ import annotations

import asyncio
import datetime
from dataclasses import dataclass

import pytest

from fastmcp import Client, FastMCP


@pytest.fixture
def versioned_server() -> FastMCP:
    server = FastMCP("versioned")

    @server.tool(name="same", version="1.0")
    def same_v1() -> int:
        return 7

    @server.tool(name="same", version="2.0")
    def same_v2() -> int:
        return 8

    @server.tool(name="value", version="1.0")
    def value_v1() -> int:
        return 7

    @server.tool(name="value", version="2.0")
    def value_v2() -> str:
        return "hello"

    @server.tool(name="shape", version="1.0")
    def shape_v1() -> int:
        return 7

    @server.tool(name="shape", version="2.0")
    def shape_v2() -> dict:
        return {"a": 1}

    return server


async def test_pinned_call_returns_its_own_version_result(
    versioned_server: FastMCP,
) -> None:
    """A pinned call is not validated against the highest version's schema."""
    async with Client(versioned_server) as client:
        result = await client.call_tool("value", version="1.0")

    assert result.data == 7


async def test_pinned_call_hydrates_when_versions_differ_in_shape(
    versioned_server: FastMCP,
) -> None:
    """The highest version's schema does not accept this version's content."""
    async with Client(versioned_server) as client:
        result = await client.call_tool("shape", version="1.0")

    assert result.data == 7


async def test_pinned_call_with_matching_schemas_is_unchanged(
    versioned_server: FastMCP,
) -> None:
    async with Client(versioned_server) as client:
        pinned = await client.call_tool("same", version="1.0")
        highest = await client.call_tool("same")

    assert pinned.data == 7
    assert highest.data == 8


@dataclass
class Point:
    x: int
    y: int


async def test_pinned_call_to_the_listed_version_still_hydrates() -> None:
    """Pinning the version the cached schema describes keeps type coercion."""
    server = FastMCP("single")

    @server.tool(name="when", version="1.0")
    def when() -> datetime.datetime:
        return datetime.datetime(2024, 1, 2, 3, 4, 5)

    @server.tool(name="point", version="1.0")
    def point() -> Point:
        return Point(x=1, y=2)

    async with Client(server) as client:
        pinned_when = await client.call_tool("when", version="1.0")
        pinned_point = await client.call_tool("point", version="1.0")

    assert pinned_when.data == datetime.datetime(2024, 1, 2, 3, 4, 5)
    assert pinned_point.data.x == 1
    assert pinned_point.data.y == 2
    assert not isinstance(pinned_point.data, dict)


async def test_pinned_call_to_the_listed_version_still_validates() -> None:
    """Pinning the listed version keeps the SDK's result revalidation."""
    server = FastMCP("liar")

    @server.tool(name="liar", version="1.0")
    def liar() -> int:
        """Declares int, returns a string."""
        return "oops"  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

    async with Client(server) as client:
        with pytest.raises(RuntimeError, match="Invalid structured content"):
            await client.call_tool("liar", version="1.0")


async def test_unpinned_call_still_validates_a_non_conforming_result() -> None:
    """Pinning a version must not turn result validation off in general."""
    server = FastMCP("liar")

    @server.tool
    def liar() -> int:
        """Declares int, returns a string."""
        return "oops"  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

    async with Client(server) as client:
        with pytest.raises(RuntimeError, match="Invalid structured content"):
            await client.call_tool("liar")


async def test_concurrent_pinned_calls_leave_the_schema_cache_intact(
    versioned_server: FastMCP,
) -> None:
    """Pinning is per call: concurrent calls must not disturb the shared cache.

    A pinned call is a property of one request, so it must not be expressed by
    clearing the session-wide schema entry: two pinned calls in flight would
    then restore each other's placeholder, and every later unpinned call would
    skip validation for the rest of the session.
    """
    async with Client(versioned_server) as client:
        await client.list_tools()
        before = client.session._tool_output_schemas.get("value")
        assert before is not None

        await asyncio.gather(
            client.call_tool("value", version="1.0"),
            client.call_tool("value", version="1.0"),
        )

        assert client.session._tool_output_schemas.get("value") == before

        # And the cache is still consulted for an ordinary call.
        result = await client.call_tool("value")
        assert result.data == "hello"


async def test_pinned_call_does_not_exempt_a_nested_client_call() -> None:
    """The marker is scoped to the session that made the pinned call.

    With the in-memory transport the server handler runs in the caller's
    context, so a process-wide flag would also exempt an unrelated ``Client``
    call made from inside that handler. Those still validate.
    """
    inner = FastMCP("inner")

    @inner.tool
    def liar() -> int:
        """Declares int, returns a string."""
        return "oops"  # type: ignore[return-value]  # ty:ignore[invalid-return-type]

    validated: list[bool] = []

    outer = FastMCP("outer")

    @outer.tool(name="probe", version="1.0")
    async def probe_v1() -> int:
        async with Client(inner) as nested:
            try:
                await nested.call_tool("liar")
            except RuntimeError:
                validated.append(True)
            else:
                validated.append(False)
        return 1

    @outer.tool(name="probe", version="2.0")
    def probe_v2() -> int:
        return 2

    async with Client(outer) as client:
        result = await client.call_tool("probe", version="1.0")

    assert result.data == 1
    assert validated == [True]