Fix #177: Returning multiple tool results (#222)

* feat: allow lowlevel servers to return a list of resources

The resource/read message in MCP allows of multiple resources
to be returned. However, in the SDK we do not allow this. This
change is such that we allow returning multiple resource in
the lowlevel API if needed. However in FastMCP we stick to
one, since a FastMCP resource defines the mime_type in the decorator
and hence a resource cannot dynamically return different mime_typed resources.
It also is just the better default to only return one resource.
However in the lowlevel API we will allow this.

Strictly speaking this is not a BC break since the new return value
is additive, but if people subclassed server, it will break them.

* feat: lower the type requriements for call_tool to Iterable

src/mcp/server/fastmcp/server.py

@@ -3,7 +3,7 @@
 import inspect
 import json
 import re
-from collections.abc import AsyncIterator
+from collections.abc import AsyncIterator, Iterable
 from contextlib import (
     AbstractAsyncContextManager,
     asynccontextmanager,
@@ -236,7 +236,7 @@ class FastMCP:
             for template in templates
         ]
 
-    async def read_resource(self, uri: AnyUrl | str) -> ReadResourceContents:
+    async def read_resource(self, uri: AnyUrl | str) -> Iterable[ReadResourceContents]:
         """Read a resource by URI."""
 
         resource = await self._resource_manager.get_resource(uri)
@@ -245,7 +245,7 @@ class FastMCP:
 
         try:
             content = await resource.read()
-            return ReadResourceContents(content=content, mime_type=resource.mime_type)
+            return [ReadResourceContents(content=content, mime_type=resource.mime_type)]
         except Exception as e:
             logger.error(f"Error reading resource {uri}: {e}")
             raise ResourceError(str(e))
@@ -649,7 +649,7 @@ class Context(BaseModel):
             progress_token=progress_token, progress=progress, total=total
         )
 
-    async def read_resource(self, uri: str | AnyUrl) -> ReadResourceContents:
+    async def read_resource(self, uri: str | AnyUrl) -> Iterable[ReadResourceContents]:
         """Read a resource by URI.
 
         Args:

src/mcp/server/lowlevel/server.py

@@ -67,9 +67,9 @@ messages from the client.
 import contextvars
 import logging
 import warnings
-from collections.abc import Awaitable, Callable
+from collections.abc import Awaitable, Callable, Iterable
 from contextlib import AbstractAsyncContextManager, AsyncExitStack, asynccontextmanager
-from typing import Any, AsyncIterator, Generic, Sequence, TypeVar
+from typing import Any, AsyncIterator, Generic, TypeVar
 
 import anyio
 from anyio.streams.memory import MemoryObjectReceiveStream, MemoryObjectSendStream
@@ -279,7 +279,9 @@ class Server(Generic[LifespanResultT]):
 
     def read_resource(self):
         def decorator(
-            func: Callable[[AnyUrl], Awaitable[str | bytes | ReadResourceContents]],
+            func: Callable[
+                [AnyUrl], Awaitable[str | bytes | Iterable[ReadResourceContents]]
+            ],
         ):
             logger.debug("Registering handler for ReadResourceRequest")
 
@@ -307,13 +309,22 @@ class Server(Generic[LifespanResultT]):
                     case str() | bytes() as data:
                         warnings.warn(
                             "Returning str or bytes from read_resource is deprecated. "
-                            "Use ReadResourceContents instead.",
+                            "Use Iterable[ReadResourceContents] instead.",
                             DeprecationWarning,
                             stacklevel=2,
                         )
                         content = create_content(data, None)
-                    case ReadResourceContents() as contents:
-                        content = create_content(contents.content, contents.mime_type)
+                    case Iterable() as contents:
+                        contents_list = [
+                            create_content(content_item.content, content_item.mime_type)
+                            for content_item in contents
+                            if isinstance(content_item, ReadResourceContents)
+                        ]
+                        return types.ServerResult(
+                            types.ReadResourceResult(
+                                contents=contents_list,
+                            )
+                        )
                     case _:
                         raise ValueError(
                             f"Unexpected return type from read_resource: {type(result)}"
@@ -387,7 +398,7 @@ class Server(Generic[LifespanResultT]):
             func: Callable[
                 ...,
                 Awaitable[
-                    Sequence[
+                    Iterable[
                         types.TextContent | types.ImageContent | types.EmbeddedResource
                     ]
                 ],