π The fast, Pythonic way to build MCP servers and clients.
Improve client return types
Jeremiah Lowinea13dc114fcd
diff --git a/src/fastmcp/client/client.py b/src/fastmcp/client/client.pyindex ea4f81cd4..dbae1b965 100644--- a/src/fastmcp/client/client.py+++ b/src/fastmcp/client/client.py@@ -1,7 +1,7 @@import datetimefrom contextlib import AbstractAsyncContextManagerfrom pathlib import Path-from typing import Any+from typing import Any, Literal, cast, overloadimport mcp.typesfrom mcp import ClientSession@@ -24,6 +24,10 @@ from .transports import ClientTransport, SessionKwargs, infer_transport__all__ = ["Client", "RootsHandler", "RootsList"]+class ClientError(ValueError):+ """Base class for errors raised by the client."""++class Client:"""MCP client that delegates connection management to a Transport instance.@@ -122,60 +126,101 @@ class Client:"""Send a logging/setLevel request."""await self.session.set_logging_level(level)- async def list_resources(self) -> mcp.types.ListResourcesResult:+ async def send_roots_list_changed(self) -> None:+ """Send a roots/list_changed notification."""+ await self.session.send_roots_list_changed()++ async def list_resources(self) -> list[mcp.types.Resource]:"""Send a resources/list request."""- return await self.session.list_resources()+ result = await self.session.list_resources()+ return result.resources- async def list_resource_templates(self) -> mcp.types.ListResourceTemplatesResult:+ async def list_resource_templates(self) -> list[mcp.types.ResourceTemplate]:"""Send a resources/listResourceTemplates request."""- return await self.session.list_resource_templates()+ result = await self.session.list_resource_templates()+ return result.resourceTemplates- async def read_resource(self, uri: AnyUrl | str) -> mcp.types.ReadResourceResult:+ async def read_resource(+ self, uri: AnyUrl | str+ ) -> list[mcp.types.TextResourceContents | mcp.types.BlobResourceContents]:"""Send a resources/read request."""if isinstance(uri, str):uri = AnyUrl(uri) # Ensure AnyUrl- return await self.session.read_resource(uri)-- async def subscribe_resource(self, uri: AnyUrl | str) -> None:- """Send a resources/subscribe request."""- if isinstance(uri, str):- uri = AnyUrl(uri)- await self.session.subscribe_resource(uri)-- async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:- """Send a resources/unsubscribe request."""- if isinstance(uri, str):- uri = AnyUrl(uri)- await self.session.unsubscribe_resource(uri)-- async def list_prompts(self) -> mcp.types.ListPromptsResult:+ result = await self.session.read_resource(uri)+ return result.contents++ # async def subscribe_resource(self, uri: AnyUrl | str) -> None:+ # """Send a resources/subscribe request."""+ # if isinstance(uri, str):+ # uri = AnyUrl(uri)+ # await self.session.subscribe_resource(uri)++ # async def unsubscribe_resource(self, uri: AnyUrl | str) -> None:+ # """Send a resources/unsubscribe request."""+ # if isinstance(uri, str):+ # uri = AnyUrl(uri)+ # await self.session.unsubscribe_resource(uri)++ async def list_prompts(self) -> list[mcp.types.Prompt]:"""Send a prompts/list request."""- return await self.session.list_prompts()+ result = await self.session.list_prompts()+ return result.promptsasync def get_prompt(self, name: str, arguments: dict[str, str] | None = None) -> mcp.types.GetPromptResult:"""Send a prompts/get request."""- return await self.session.get_prompt(name, arguments)+ result = await self.session.get_prompt(name, arguments)+ return resultasync def complete(self,ref: mcp.types.ResourceReference | mcp.types.PromptReference,argument: dict[str, str],- ) -> mcp.types.CompleteResult:- """Send a completion/complete request."""- return await self.session.complete(ref, argument)+ ) -> mcp.types.Completion:+ """Send a completion request."""+ result = await self.session.complete(ref, argument)+ return result.completion- async def list_tools(self) -> mcp.types.ListToolsResult:+ async def list_tools(self) -> list[mcp.types.Tool]:"""Send a tools/list request."""- return await self.session.list_tools()+ result = await self.session.list_tools()+ return result.tools+ @overloadasync def call_tool(- self, name: str, arguments: dict[str, Any] | None = None- ) -> mcp.types.CallToolResult:- """Send a tools/call request."""- return await self.session.call_tool(name, arguments)+ self,+ name: str,+ arguments: dict[str, Any] | None = None,+ _return_raw_result: Literal[False] = False,+ ) -> list[+ mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource+ ]: ...++ @overload+ async def call_tool(+ self,+ name: str,+ arguments: dict[str, Any] | None = None,+ _return_raw_result: Literal[True] = True,+ ) -> mcp.types.CallToolResult: ...- async def send_roots_list_changed(self) -> None:- """Send a roots/list_changed notification."""- await self.session.send_roots_list_changed()+ async def call_tool(+ self,+ name: str,+ arguments: dict[str, Any] | None = None,+ _return_raw_result: bool = False,+ ) -> (+ list[+ mcp.types.TextContent | mcp.types.ImageContent | mcp.types.EmbeddedResource+ ]+ | mcp.types.CallToolResult+ ):+ """Send a tools/call request."""+ result = await self.session.call_tool(name, arguments)+ if _return_raw_result:+ return result+ elif result.isError:+ msg = cast(mcp.types.TextContent, result.content[0]).text+ raise ClientError(msg)+ return result.contentdiff --git a/src/fastmcp/server/proxy.py b/src/fastmcp/server/proxy.pyindex 048d1d1e0..6a129bc2e 100644--- a/src/fastmcp/server/proxy.py+++ b/src/fastmcp/server/proxy.py@@ -40,11 +40,15 @@ class ProxyTool(Tool):async def run(self, arguments: dict[str, Any], context: Context | None = None) -> Any:+ # the client context manager will swallow any exceptions inside a TaskGroup+ # so we return the raw result and raise an exception ourselvesasync with self._client:- result = await self._client.call_tool(self.name, arguments)+ result = await self._client.call_tool(+ self.name, arguments, _return_raw_result=True+ )if result.isError:raise ValueError(cast(mcp.types.TextContent, result.content[0]).text)- return result.content[0]+ return result.contentclass ProxyResource(Resource):@@ -73,12 +77,12 @@ class ProxyResource(Resource):async with self._client:result = await self._client.read_resource(self.uri)- if isinstance(result.contents[0], TextResourceContents):- return result.contents[0].text- elif isinstance(result.contents[0], BlobResourceContents):- return result.contents[0].blob+ if isinstance(result[0], TextResourceContents):+ return result[0].text+ elif isinstance(result[0], BlobResourceContents):+ return result[0].blobelse:- raise ValueError(f"Unsupported content type: {type(result.contents[0])}")+ raise ValueError(f"Unsupported content type: {type(result[0])}")class ProxyTemplate(ResourceTemplate):@@ -103,20 +107,20 @@ class ProxyTemplate(ResourceTemplate):async with self._client:result = await self._client.read_resource(uri)- if isinstance(result.contents[0], TextResourceContents):- value = result.contents[0].text- elif isinstance(result.contents[0], BlobResourceContents):- value = result.contents[0].blob+ if isinstance(result[0], TextResourceContents):+ value = result[0].text+ elif isinstance(result[0], BlobResourceContents):+ value = result[0].blobelse:- raise ValueError(f"Unsupported content type: {type(result.contents[0])}")+ raise ValueError(f"Unsupported content type: {type(result[0])}")return ProxyResource(client=self._client,uri=uri,name=self.name,description=self.description,- mime_type=result.contents[0].mimeType,- contents=result.contents,+ mime_type=result[0].mimeType,+ contents=result,_value=value,)@@ -177,15 +181,15 @@ class FastMCPProxy(FastMCP):async with client:# Register proxies for client tools- tools_result = await client.list_tools()- for tool in tools_result.tools:+ tools = await client.list_tools()+ for tool in tools:tool_proxy = await ProxyTool.from_client(client, tool)server._tool_manager._tools[tool_proxy.name] = tool_proxylogger.debug(f"Created proxy for tool: {tool_proxy.name}")# Register proxies for client resources- resources_result = await client.list_resources()- for resource in resources_result.resources:+ resources = await client.list_resources()+ for resource in resources:resource_proxy = await ProxyResource.from_client(client, resource)server._resource_manager._resources[str(resource_proxy.uri)] = (resource_proxy@@ -193,8 +197,8 @@ class FastMCPProxy(FastMCP):logger.debug(f"Created proxy for resource: {resource_proxy.uri}")# Register proxies for client resource templates- templates_result = await client.list_resource_templates()- for template in templates_result.resourceTemplates:+ templates = await client.list_resource_templates()+ for template in templates:template_proxy = await ProxyTemplate.from_client(client, template)server._resource_manager._templates[template_proxy.uri_template] = (template_proxy@@ -204,8 +208,8 @@ class FastMCPProxy(FastMCP):)# Register proxies for client prompts- prompts_result = await client.list_prompts()- for prompt in prompts_result.prompts:+ prompts = await client.list_prompts()+ for prompt in prompts:prompt_proxy = await ProxyPrompt.from_client(client, prompt)server._prompt_manager._prompts[prompt_proxy.name] = prompt_proxylogger.debug(f"Created proxy for prompt: {prompt_proxy.name}")diff --git a/tests/client/test_fastmcp_transport.py b/tests/client/test_client.pysimilarity index 88%rename from tests/client/test_fastmcp_transport.pyrename to tests/client/test_client.pyindex bf097cc2b..4d933a185 100644--- a/tests/client/test_fastmcp_transport.py+++ b/tests/client/test_client.py@@ -51,8 +51,8 @@ async def test_list_tools(fastmcp_server):result = await client.list_tools()# Check that our tools are available- assert len(result.tools) == 2- assert set(tool.name for tool in result.tools) == {"greet", "add"}+ assert len(result) == 2+ assert set(tool.name for tool in result) == {"greet", "add"}async def test_call_tool(fastmcp_server):@@ -63,7 +63,7 @@ async def test_call_tool(fastmcp_server):result = await client.call_tool("greet", {"name": "World"})# The result content should contain our greeting- content_str = str(result.content[0])+ content_str = str(result[0])assert "Hello, World!" in content_str@@ -75,8 +75,8 @@ async def test_list_resources(fastmcp_server):result = await client.list_resources()# Check that our resource is available- assert len(result.resources) == 1- assert str(result.resources[0].uri) == "data://users"+ assert len(result) == 1+ assert str(result[0].uri) == "data://users"async def test_list_prompts(fastmcp_server):@@ -87,8 +87,8 @@ async def test_list_prompts(fastmcp_server):result = await client.list_prompts()# Check that our prompt is available- assert len(result.prompts) == 1- assert result.prompts[0].name == "welcome"+ assert len(result) == 1+ assert result[0].name == "welcome"async def test_get_prompt(fastmcp_server):@@ -115,7 +115,7 @@ async def test_read_resource(fastmcp_server):result = await client.read_resource(uri)# The contents should include our user list- contents_str = str(result.contents[0])+ contents_str = str(result[0])assert "Alice" in contents_strassert "Bob" in contents_strassert "Charlie" in contents_str@@ -145,15 +145,15 @@ async def test_resource_template(fastmcp_server):result = await client.list_resource_templates()# Check that our template is available- assert len(result.resourceTemplates) == 1- assert "data://user/{user_id}" in result.resourceTemplates[0].uriTemplate+ assert len(result) == 1+ assert "data://user/{user_id}" in result[0].uriTemplate# Now use the template with a specific user_iduri = cast(AnyUrl, "data://user/123")result = await client.read_resource(uri)# Check the content matches what we expect for the provided user_id- content_str = str(result.contents[0])+ content_str = str(result[0])assert '"id": "123"' in content_strassert '"name": "User 123"' in content_strassert '"active": true' in content_strdiff --git a/tests/client/test_roots.py b/tests/client/test_roots.pyindex 0ede20f01..74b478a6d 100644--- a/tests/client/test_roots.py+++ b/tests/client/test_roots.py@@ -41,8 +41,8 @@ class TestClientRoots:async def test_valid_roots(self, fastmcp_server: FastMCP, roots: list[str]):async with Client(fastmcp_server, roots=roots) as client:result = await client.call_tool("list_roots", {})- assert isinstance(result.content[0], TextContent)- assert json.loads(result.content[0].text) == [+ assert isinstance(result[0], TextContent)+ assert json.loads(result[0].text) == ["file://x/y/z","file://x/y/z",]diff --git a/tests/client/test_sampling.py b/tests/client/test_sampling.pyindex 0707f3a44..15c2a2ff1 100644--- a/tests/client/test_sampling.py+++ b/tests/client/test_sampling.py@@ -47,7 +47,7 @@ async def test_simple_sampling(fastmcp_server: FastMCP):async with Client(fastmcp_server, sampling_handler=sampling_handler) as client:result = await client.call_tool("simple_sample", {"message": "Hello, world!"})- reply = cast(TextContent, result.content[0])+ reply = cast(TextContent, result[0])assert reply.text == "This is the sample message!"@@ -62,7 +62,7 @@ async def test_sampling_with_system_prompt(fastmcp_server: FastMCP):result = await client.call_tool("sample_with_system_prompt", {"message": "Hello, world!"})- reply = cast(TextContent, result.content[0])+ reply = cast(TextContent, result[0])assert reply.text == "You love FastMCP"@@ -81,5 +81,5 @@ async def test_sampling_with_messages(fastmcp_server: FastMCP):result = await client.call_tool("sample_with_messages", {"message": "Hello, world!"})- reply = cast(TextContent, result.content[0])+ reply = cast(TextContent, result[0])assert reply.text == "I need to think."