Skip to content

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

Preserve binary resource contents in response cache (#5181)

Brennan Butlerc6e09d5360b4
diff --git a/fastmcp_slim/fastmcp/server/middleware/caching.py b/fastmcp_slim/fastmcp/server/middleware/caching.py
index 44d947d9f..a0258cdea 100644
--- a/fastmcp_slim/fastmcp/server/middleware/caching.py
+++ b/fastmcp_slim/fastmcp/server/middleware/caching.py
@@ -1,5 +1,6 @@
"""A middleware for response caching."""
+import base64
import hashlib
import json
from collections.abc import Mapping, Sequence
@@ -89,6 +90,7 @@ class CacheableResourceContent(FastMCPBaseModel):
content: str | bytes
mime_type: str | None = None
meta: dict[str, Any] | None = None
+ is_binary: bool = False
class CacheableResourceResult(FastMCPBaseModel):
@@ -105,7 +107,14 @@ class CacheableResourceResult(FastMCPBaseModel):
return cls(
contents=[
CacheableResourceContent(
- content=item.content, mime_type=item.mime_type, meta=item.meta
+ # JSON cannot distinguish bytes from text. Encode binary
+ # content and retain its type independently of the MIME type.
+ content=base64.b64encode(item.content).decode("ascii")
+ if isinstance(item.content, bytes)
+ else item.content,
+ mime_type=item.mime_type,
+ meta=item.meta,
+ is_binary=isinstance(item.content, bytes),
)
for item in value.contents
],
@@ -116,7 +125,11 @@ class CacheableResourceResult(FastMCPBaseModel):
return ResourceResult(
contents=[
ResourceContent(
- content=item.content, mime_type=item.mime_type, meta=item.meta
+ content=base64.b64decode(item.content)
+ if item.is_binary
+ else item.content,
+ mime_type=item.mime_type,
+ meta=item.meta,
)
for item in self.contents
],
diff --git a/tests/server/middleware/test_caching.py b/tests/server/middleware/test_caching.py
index fec5424c1..7ded3c81d 100644
--- a/tests/server/middleware/test_caching.py
+++ b/tests/server/middleware/test_caching.py
@@ -31,9 +31,10 @@ from fastmcp.client.client import CallToolResult, Client
from fastmcp.client.transports import FastMCPTransport
from fastmcp.prompts.base import Message, Prompt
from fastmcp.prompts.function_prompt import FunctionPrompt
-from fastmcp.resources.base import Resource
+from fastmcp.resources.base import Resource, ResourceContent, ResourceResult
from fastmcp.server.middleware.caching import (
ANONYMOUS_AUTH_KEY,
+ CacheableResourceResult,
CacheableToolResult,
CallToolSettings,
ResponseCachingMiddleware,
@@ -49,6 +50,7 @@ from fastmcp.server.middleware.middleware import (
)
from fastmcp.tools.base import Tool, ToolResult
from fastmcp.utilities.tasks import TaskConfig
+from tests.conftest import user_meta
TEST_URI = AnyUrl("https://test_uri")
@@ -395,6 +397,71 @@ class TestResponseCachingMiddlewareIntegration:
assert pre_tool_list == post_tool_list
+ @pytest.mark.parametrize(
+ "contents",
+ [
+ b"",
+ b"hello",
+ b"\x89PNG\r\n\x1a\n",
+ bytes(range(256)),
+ "",
+ "hello",
+ "coffee \u2615",
+ "aGVsbG8=",
+ [
+ ResourceContent("text", meta={"item": "text"}),
+ ResourceContent(b"\xff\x00", meta={"item": "binary"}),
+ ResourceContent(b"hello", mime_type="text/plain"),
+ ],
+ ],
+ ids=[
+ "empty-bytes",
+ "ascii-bytes",
+ "png-header",
+ "all-bytes",
+ "empty-text",
+ "ascii-text",
+ "unicode-text",
+ "base64-like-text",
+ "mixed",
+ ],
+ )
+ async def test_resource_contents_survive_cache(
+ self,
+ caching_server: FastMCP,
+ contents: str | bytes | list[ResourceContent],
+ ) -> None:
+ expected = ResourceResult(
+ contents
+ if isinstance(contents, list)
+ else [
+ ResourceContent(
+ contents,
+ mime_type="application/octet-stream",
+ meta={"item": "sample"},
+ )
+ ],
+ meta={"result": "sample"},
+ )
+ calls = 0
+
+ @caching_server.resource("data://cached-content")
+ def sample() -> ResourceResult:
+ nonlocal calls
+ calls += 1
+ return expected
+
+ async with Client(caching_server) as client:
+ for _ in range(2):
+ result = await client.read_resource_mcp("data://cached-content")
+ assert (
+ result.contents
+ == expected.to_mcp_result("data://cached-content").contents
+ )
+ assert user_meta(result.meta) == expected.meta
+
+ assert calls == 1
+
async def test_list_operations_preserve_component_metadata(self):
"""Base component fields should survive conversion through the cache."""
from fastmcp.server.extensions import ServerExtension
@@ -799,6 +866,31 @@ class TestCachingWithImportedServerPrefixes:
assert tracking_calculator.add_calls == 1
+def test_resource_cache_accepts_existing_text_entries() -> None:
+ cached = CacheableResourceResult.model_validate(
+ {
+ "contents": [
+ {
+ "content": "aGVsbG8=",
+ "mime_type": "application/octet-stream",
+ "meta": {"item": "sample"},
+ }
+ ],
+ "meta": {"result": "sample"},
+ }
+ )
+ assert cached.unwrap() == ResourceResult(
+ [
+ ResourceContent(
+ "aGVsbG8=",
+ mime_type="application/octet-stream",
+ meta={"item": "sample"},
+ )
+ ],
+ meta={"result": "sample"},
+ )
+
+
class TestCacheKeyGeneration:
def test_call_tool_key_is_hashed_and_does_not_include_raw_input(self):
msg = mcp_types.CallToolRequestParams(