π The fast, Pythonic way to build MCP servers and clients.
Fix response cache partitioning for versioned components (#4948)
CoralGarden52977ba66c8117
diff --git a/fastmcp_slim/fastmcp/server/middleware/caching.py b/fastmcp_slim/fastmcp/server/middleware/caching.pyindex a6db7eced..44d947d9f 100644--- a/fastmcp_slim/fastmcp/server/middleware/caching.py+++ b/fastmcp_slim/fastmcp/server/middleware/caching.py@@ -2,7 +2,7 @@import hashlibimport json-from collections.abc import Sequence+from collections.abc import Mapping, Sequencefrom logging import Loggerfrom typing import Any, TypedDict@@ -68,6 +68,7 @@ FIVE_MINUTES_IN_SECONDS = 300ONE_MB_IN_BYTES = 1024 * 1024ANONYMOUS_AUTH_KEY = "__anonymous__"+DEFAULT_VERSION_CACHE_KEY = "__default__"BaseModelT = TypeVar("BaseModelT", bound=FastMCPBaseModel)@@ -243,11 +244,12 @@ class ResponseCachingMiddleware(Middleware):Notes:- Caches `tools/call`, `resources/read`, `prompts/get`, `tools/list`, `resources/list`, and `prompts/list` requests.- - Cache keys are derived from the method name, arguments, and the caller's- access token. Entries are partitioned per-token so that responses filtered- by per-component authorization (e.g. `auth=require_scopes(...)`) cannot- leak across users with different permissions. Unauthenticated callers- (including STDIO) share a single anonymous partition.+ - Cache keys are derived from the method name, requested component version,+ arguments, and the caller's access token. Entries are partitioned per-token+ so that responses filtered by per-component authorization (e.g.+ `auth=require_scopes(...)`) cannot leak across users with different+ permissions. Unauthenticated callers (including STDIO) share a single+ anonymous partition."""def __init__(@@ -649,25 +651,51 @@ def _get_auth_partition_key() -> str:return _hash_cache_key(token.token)+def _get_component_version_cache_key(msg: mcp_types.RequestParams) -> str:+ """Return a cache partition for the requested component version."""+ if not msg.meta:+ return DEFAULT_VERSION_CACHE_KEY++ fastmcp_meta = msg.meta.get("fastmcp")+ if not isinstance(fastmcp_meta, Mapping):+ return DEFAULT_VERSION_CACHE_KEY++ version = fastmcp_meta.get("version")+ if version is None:+ return DEFAULT_VERSION_CACHE_KEY++ # Encode the selector as a canonical JSON value so strings and range+ # selectors cannot collide and equivalent selectors share a partition.+ return f"__version__:{_get_arguments_str({'version': version})}"++def _make_call_tool_cache_key(msg: mcp_types.CallToolRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY) -> str:- """Make a cache key for a tool call using a stable hash of name and arguments."""+ """Make a cache key for a tool call using name, version, and arguments."""- return _hash_cache_key(f"{auth_key}:{msg.name}:{_get_arguments_str(msg.arguments)}")+ return _hash_cache_key(+ f"{auth_key}:{_get_component_version_cache_key(msg)}:{msg.name}:"+ f"{_get_arguments_str(msg.arguments)}"+ )def _make_read_resource_cache_key(msg: mcp_types.ReadResourceRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY) -> str:- """Make a cache key for a resource read using a stable hash of URI."""+ """Make a cache key for a resource read using version and URI."""- return _hash_cache_key(f"{auth_key}:{msg.uri}")+ return _hash_cache_key(+ f"{auth_key}:{_get_component_version_cache_key(msg)}:{msg.uri}"+ )def _make_get_prompt_cache_key(msg: mcp_types.GetPromptRequestParams, auth_key: str = ANONYMOUS_AUTH_KEY) -> str:- """Make a cache key for a prompt get using a stable hash of name and arguments."""+ """Make a cache key for a prompt get using name, version, and arguments."""- return _hash_cache_key(f"{auth_key}:{msg.name}:{_get_arguments_str(msg.arguments)}")+ return _hash_cache_key(+ f"{auth_key}:{_get_component_version_cache_key(msg)}:{msg.name}:"+ f"{_get_arguments_str(msg.arguments)}"+ )diff --git a/tests/server/middleware/test_versioned_caching.py b/tests/server/middleware/test_versioned_caching.pynew file mode 100644index 000000000..9552123c2--- /dev/null+++ b/tests/server/middleware/test_versioned_caching.py@@ -0,0 +1,161 @@+"""Tests for response caching with versioned components."""++import mcp_types+import pytest+from mcp_types import TextContent++from fastmcp import FastMCP+from fastmcp.client.client import Client+from fastmcp.server.middleware.caching import (+ ResponseCachingMiddleware,+ _make_call_tool_cache_key,+ _make_get_prompt_cache_key,+ _make_read_resource_cache_key,+)+++def versioned_caching_server() -> tuple[FastMCP, dict[str, int]]:+ mcp_server = FastMCP("VersionedCachingTestServer")+ mcp_server.add_middleware(ResponseCachingMiddleware())+ call_counts = {+ "tool_v1": 0,+ "tool_v2": 0,+ "resource_v1": 0,+ "resource_v2": 0,+ "prompt_v1": 0,+ "prompt_v2": 0,+ }++ @mcp_server.tool(name="calculate", version="1.0")+ def calculate_v1(x: int) -> int:+ call_counts["tool_v1"] += 1+ return x + 1++ @mcp_server.tool(name="calculate", version="2.0")+ def calculate_v2(x: int) -> int:+ call_counts["tool_v2"] += 1+ return x * 2++ @mcp_server.resource("data://config", version="1.0")+ def config_v1() -> str:+ call_counts["resource_v1"] += 1+ return "resource-v1"++ @mcp_server.resource("data://config", version="2.0")+ def config_v2() -> str:+ call_counts["resource_v2"] += 1+ return "resource-v2"++ @mcp_server.prompt(name="greet", version="1.0")+ def greet_v1(name: str) -> str:+ call_counts["prompt_v1"] += 1+ return f"prompt-v1:{name}"++ @mcp_server.prompt(name="greet", version="2.0")+ def greet_v2(name: str) -> str:+ call_counts["prompt_v2"] += 1+ return f"prompt-v2:{name}"++ return mcp_server, call_counts+++class TestVersionAwareCaching:+ async def test_call_tool_cache_is_partitioned_by_component_version(+ self, versioned_caching_server: tuple[FastMCP, dict[str, int]]+ ):+ mcp_server, call_counts = versioned_caching_server++ async with Client(mcp_server) as client:+ default = await client.call_tool("calculate", {"x": 5})+ version_one = await client.call_tool("calculate", {"x": 5}, version="1.0")+ version_one_cached = await client.call_tool(+ "calculate", {"x": 5}, version="1.0"+ )++ assert default.data == 10+ assert version_one.data == 6+ assert version_one_cached.data == 6+ assert call_counts["tool_v1"] == 1+ assert call_counts["tool_v2"] == 1++ async def test_read_resource_cache_is_partitioned_by_component_version(+ self, versioned_caching_server: tuple[FastMCP, dict[str, int]]+ ):+ mcp_server, call_counts = versioned_caching_server++ async with Client(mcp_server) as client:+ default = await client.read_resource("data://config")+ version_one = await client.read_resource("data://config", version="1.0")+ version_one_cached = await client.read_resource(+ "data://config", version="1.0"+ )++ assert default[0].text == "resource-v2"+ assert version_one[0].text == "resource-v1"+ assert version_one_cached[0].text == "resource-v1"+ assert call_counts["resource_v1"] == 1+ assert call_counts["resource_v2"] == 1++ async def test_get_prompt_cache_is_partitioned_by_component_version(+ self, versioned_caching_server: tuple[FastMCP, dict[str, int]]+ ):+ mcp_server, call_counts = versioned_caching_server++ async with Client(mcp_server) as client:+ default = await client.get_prompt("greet", {"name": "Ada"})+ version_one = await client.get_prompt(+ "greet", {"name": "Ada"}, version="1.0"+ )+ version_one_cached = await client.get_prompt(+ "greet", {"name": "Ada"}, version="1.0"+ )++ default_content = default.messages[0].content+ version_one_content = version_one.messages[0].content+ version_one_cached_content = version_one_cached.messages[0].content+ assert isinstance(default_content, TextContent)+ assert isinstance(version_one_content, TextContent)+ assert isinstance(version_one_cached_content, TextContent)+ assert default_content.text == "prompt-v2:Ada"+ assert version_one_content.text == "prompt-v1:Ada"+ assert version_one_cached_content.text == "prompt-v1:Ada"+ assert call_counts["prompt_v1"] == 1+ assert call_counts["prompt_v2"] == 1+++class TestVersionCacheKeyGeneration:+ def test_call_tool_key_partitions_by_component_version(self):+ default = mcp_types.CallToolRequestParams(name="t", arguments={"a": 1})+ version_one = mcp_types.CallToolRequestParams(+ name="t",+ arguments={"a": 1},+ _meta={"fastmcp": {"version": "1.0"}},+ )++ assert _make_call_tool_cache_key(default) != _make_call_tool_cache_key(+ version_one+ )++ def test_read_resource_key_partitions_by_component_version(self):+ default = mcp_types.ReadResourceRequestParams(uri="file:///tmp/x")+ version_one = mcp_types.ReadResourceRequestParams(+ uri="file:///tmp/x",+ _meta={"fastmcp": {"version": "1.0"}},+ )++ assert _make_read_resource_cache_key(default) != _make_read_resource_cache_key(+ version_one+ )++ def test_get_prompt_key_partitions_by_component_version(self):+ default = mcp_types.GetPromptRequestParams(name="p", arguments={"a": "1"})+ version_one = mcp_types.GetPromptRequestParams(+ name="p",+ arguments={"a": "1"},+ _meta={"fastmcp": {"version": "1.0"}},+ )++ assert _make_get_prompt_cache_key(default) != _make_get_prompt_cache_key(+ version_one+ )