π The fast, Pythonic way to build MCP servers and clients.
Add meta support to ToolResult (#2283)
Brandon Sharc18782f02b1a
diff --git a/docs/servers/tools.mdx b/docs/servers/tools.mdxindex 8b2279ccf..c7adc16d6 100644--- a/docs/servers/tools.mdx+++ b/docs/servers/tools.mdx@@ -616,7 +616,7 @@ Schema generation works for most common types including basic types, collections### Full Control with ToolResult-For complete control over both traditional content and structured output, return a `ToolResult` object:+For complete control over traditional content, structured output, and metadata, return a `ToolResult` object:```pythonfrom fastmcp.tools.tool import ToolResult@@ -626,14 +626,15 @@ def advanced_tool() -> ToolResult:"""Tool with full control over output."""return ToolResult(content=[TextContent(type="text", text="Human-readable summary")],- structured_content={"data": "value", "count": 42}+ structured_content={"data": "value", "count": 42},+ meta={"some": "metadata"})```When returning `ToolResult`:-- You control exactly what content and structured data is sent+- You control exactly what content, structured data, and metadata is sent- Output schemas are optional - structured content can be provided without a schema-- Clients receive both traditional content blocks and structured data+- Clients receive traditional content blocks, structured data, and metadata<Note>If your return type annotation cannot be converted to a JSON schema (e.g., complex custom classes without Pydantic support), the output schema will be omitted but the tool will still function normally with traditional content.diff --git a/examples/tool_result_echo.py b/examples/tool_result_echo.pynew file mode 100644index 000000000..5e542b4e2--- /dev/null+++ b/examples/tool_result_echo.py@@ -0,0 +1,22 @@+"""+FastMCP Echo Server+"""++from dataclasses import dataclass++from fastmcp import FastMCP+from fastmcp.tools.tool import ToolResult++mcp = FastMCP("Echo Server")+++@dataclass+class EchoData:+ data: str+++def echo(text: str) -> ToolResult:+ return ToolResult(+ content=text, structured_content=EchoData(data=text), meta={"some": "metadata"}+ )diff --git a/pyproject.toml b/pyproject.tomlindex ac89b01a4..d461186fb 100644--- a/pyproject.toml+++ b/pyproject.toml@@ -7,7 +7,7 @@ dependencies = ["python-dotenv>=1.1.0","exceptiongroup>=1.2.2","httpx>=0.28.1",- "mcp>=1.17.0,<2.0.0",+ "mcp>=1.19.0,<2.0.0","openapi-pydantic>=0.5.1","platformdirs>=4.0.0","rich>=13.9.4",diff --git a/src/fastmcp/client/client.py b/src/fastmcp/client/client.pyindex d24350d38..aa6fb30c2 100644--- a/src/fastmcp/client/client.py+++ b/src/fastmcp/client/client.py@@ -928,6 +928,7 @@ class Client(Generic[ClientTransportT]):return CallToolResult(content=result.content,structured_content=result.structuredContent,+ meta=result.meta,data=data,is_error=result.isError,)@@ -945,5 +946,6 @@ class Client(Generic[ClientTransportT]):class CallToolResult:content: list[mcp.types.ContentBlock]structured_content: dict[str, Any] | None+ meta: dict[str, Any] | Nonedata: Any = Noneis_error: bool = Falsediff --git a/src/fastmcp/server/middleware/caching.py b/src/fastmcp/server/middleware/caching.pyindex 52540248e..1ae232ec4 100644--- a/src/fastmcp/server/middleware/caching.py+++ b/src/fastmcp/server/middleware/caching.py@@ -63,14 +63,21 @@ class CachableReadResourceContents(BaseModel):class CachableToolResult(BaseModel):content: list[mcp.types.ContentBlock]structured_content: dict[str, Any] | None+ meta: dict[str, Any] | None@classmethoddef wrap(cls, value: ToolResult) -> Self:- return cls(content=value.content, structured_content=value.structured_content)+ return cls(+ content=value.content,+ structured_content=value.structured_content,+ meta=value.meta,+ )def unwrap(self) -> ToolResult:return ToolResult(- content=self.content, structured_content=self.structured_content+ content=self.content,+ structured_content=self.structured_content,+ meta=self.meta,)diff --git a/src/fastmcp/tools/tool.py b/src/fastmcp/tools/tool.pyindex b58645579..4517f9486 100644--- a/src/fastmcp/tools/tool.py+++ b/src/fastmcp/tools/tool.py@@ -16,7 +16,7 @@ from typing import (import mcp.typesimport pydantic_core-from mcp.types import ContentBlock, Icon, TextContent, ToolAnnotations+from mcp.types import CallToolResult, ContentBlock, Icon, TextContent, ToolAnnotationsfrom mcp.types import Tool as MCPToolfrom pydantic import Field, PydanticSchemaGenerationErrorfrom typing_extensions import TypeVar@@ -68,6 +68,7 @@ class ToolResult:self,content: list[ContentBlock] | Any | None = None,structured_content: dict[str, Any] | Any | None = None,+ meta: dict[str, Any] | None = None,):if content is None and structured_content is None:raise ValueError("Either content or structured_content must be provided")@@ -75,6 +76,7 @@ class ToolResult:content = structured_contentself.content: list[ContentBlock] = _convert_to_content(result=content)+ self.meta: dict[str, Any] | None = metaif structured_content is not None:try:@@ -96,7 +98,15 @@ class ToolResult:def to_mcp_result(self,- ) -> list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]]:+ ) -> (+ list[ContentBlock] | tuple[list[ContentBlock], dict[str, Any]] | CallToolResult+ ):+ if self.meta is not None:+ return CallToolResult(+ structuredContent=self.structured_content,+ content=self.content,+ _meta=self.meta,+ )if self.structured_content is None:return self.contentreturn self.content, self.structured_contentdiff --git a/tests/server/middleware/test_caching.py b/tests/server/middleware/test_caching.pyindex 696933530..01dadafde 100644--- a/tests/server/middleware/test_caching.py+++ b/tests/server/middleware/test_caching.py@@ -23,6 +23,7 @@ from fastmcp.client.transports import FastMCPTransportfrom fastmcp.prompts.prompt import FunctionPrompt, Promptfrom fastmcp.resources.resource import Resourcefrom fastmcp.server.middleware.caching import (+ CachableToolResult,CallToolSettings,ResponseCachingMiddleware,ResponseCachingStatistics,@@ -505,3 +506,18 @@ class TestResponseCachingMiddlewareIntegration:),))+++class TestCachableToolResult:+ def test_wrap_and_unwrap(self):+ tool_result = ToolResult(+ "unstructured content",+ structured_content={"structured": "content"},+ meta={"meta": "data"},+ )++ cached_tool_result = CachableToolResult.wrap(tool_result).unwrap()++ assert cached_tool_result.content == tool_result.content+ assert cached_tool_result.structured_content == tool_result.structured_content+ assert cached_tool_result.meta == tool_result.metadiff --git a/tests/server/test_server_interactions.py b/tests/server/test_server_interactions.pyindex 76f1dffb2..238893151 100644--- a/tests/server/test_server_interactions.py+++ b/tests/server/test_server_interactions.py@@ -1179,6 +1179,7 @@ class TestToolOutputSchema:"_meta": None,},],+ meta=None,))diff --git a/tests/tools/test_tool.py b/tests/tools/test_tool.pyindex dc815b5bf..c779d0942 100644--- a/tests/tools/test_tool.py+++ b/tests/tools/test_tool.py@@ -1405,6 +1405,70 @@ class TestAutomaticStructuredContent:assert result.data.verified is True+class TestToolResultCasting:+ @pytest.fixture+ async def client(self):+ from fastmcp import FastMCP+ from fastmcp.client import Client++ mcp = FastMCP()++ @mcp.tool+ def test_tool(+ unstructured: str | None = None,+ structured: dict[str, Any] | None = None,+ meta: dict[str, Any] | None = None,+ ):+ return ToolResult(+ content=unstructured,+ structured_content=structured,+ meta=meta,+ )++ async with Client(mcp) as client:+ yield client++ async def test_only_unstructured_content(self, client):+ result = await client.call_tool("test_tool", {"unstructured": "test data"})++ assert result.content[0].type == "text"+ assert result.content[0].text == "test data"+ assert result.structured_content is None+ assert result.meta is None++ async def test_neither_unstructured_or_structured_content(self, client):+ from fastmcp.exceptions import ToolError++ with pytest.raises(ToolError):+ await client.call_tool("test_tool", {})++ async def test_structured_and_unstructured_content(self, client):+ result = await client.call_tool(+ "test_tool",+ {"unstructured": "test data", "structured": {"data_type": "test"}},+ )++ assert result.content[0].type == "text"+ assert result.content[0].text == "test data"+ assert result.structured_content == {"data_type": "test"}+ assert result.meta is None++ async def test_structured_unstructured_and_meta_content(self, client):+ result = await client.call_tool(+ "test_tool",+ {+ "unstructured": "test data",+ "structured": {"data_type": "test"},+ "meta": {"some": "metadata"},+ },+ )++ assert result.content[0].type == "text"+ assert result.content[0].text == "test data"+ assert result.structured_content == {"data_type": "test"}+ assert result.meta == {"some": "metadata"}++class TestUnionReturnTypes:"""Tests for tools with union return types."""diff --git a/uv.lock b/uv.lockindex 2d6c95d23..b06bb819b 100644--- a/uv.lock+++ b/uv.lock@@ -1,5 +1,5 @@version = 1-revision = 3+revision = 2requires-python = ">=3.10"resolution-markers = ["python_full_version >= '3.11'",@@ -636,7 +636,7 @@ requires-dist = [{ name = "exceptiongroup", specifier = ">=1.2.2" },{ name = "httpx", specifier = ">=0.28.1" },{ name = "jsonschema-path", specifier = ">=0.3.4" },- { name = "mcp", specifier = ">=1.17.0,<2.0.0" },+ { name = "mcp", specifier = ">=1.19.0,<2.0.0" },{ name = "openai", marker = "extra == 'openai'", specifier = ">=1.102.0" },{ name = "openapi-pydantic", specifier = ">=0.5.1" },{ name = "platformdirs", specifier = ">=4.0.0" },@@ -1068,7 +1068,7 @@ wheels = [[[package]]name = "mcp"-version = "1.18.0"+version = "1.19.0"source = { registry = "https://pypi.org/simple" }dependencies = [{ name = "anyio" },@@ -1083,9 +1083,9 @@ dependencies = [{ name = "starlette" },{ name = "uvicorn", marker = "sys_platform != 'emscripten'" },]-sdist = { url = "https://files.pythonhosted.org/packages/1a/e0/fe34ce16ea2bacce489ab859abd1b47ae28b438c3ef60b9c5eee6c02592f/mcp-1.18.0.tar.gz", hash = "sha256:aa278c44b1efc0a297f53b68df865b988e52dd08182d702019edcf33a8e109f6", size = 482926, upload-time = "2025-10-16T19:19:55.125Z" }+sdist = { url = "https://files.pythonhosted.org/packages/69/2b/916852a5668f45d8787378461eaa1244876d77575ffef024483c94c0649c/mcp-1.19.0.tar.gz", hash = "sha256:213de0d3cd63f71bc08ffe9cc8d4409cc87acffd383f6195d2ce0457c021b5c1", size = 444163, upload-time = "2025-10-24T01:11:15.839Z" }wheels = [- { url = "https://files.pythonhosted.org/packages/1b/44/f5970e3e899803823826283a70b6003afd46f28e082544407e24575eccd3/mcp-1.18.0-py3-none-any.whl", hash = "sha256:42f10c270de18e7892fdf9da259029120b1ea23964ff688248c69db9d72b1d0a", size = 168762, upload-time = "2025-10-16T19:19:53.2Z" },+ { url = "https://files.pythonhosted.org/packages/ce/a3/3e71a875a08b6a830b88c40bc413bff01f1650f1efe8a054b5e90a9d4f56/mcp-1.19.0-py3-none-any.whl", hash = "sha256:f5907fe1c0167255f916718f376d05f09a830a215327a3ccdd5ec8a519f2e572", size = 170105, upload-time = "2025-10-24T01:11:14.151Z" },][[package]]