Return [] | None on MCP resource methods when not found or no capabilities.

Author: fennb

pydantic_ai_slim/pydantic_ai/exceptions.py

@@ -24,7 +24,6 @@
     'UsageLimitExceeded',
     'ModelHTTPError',
     'MCPError',
-    'MCPServerCapabilitiesError',
     'MCPServerError',
     'IncompleteToolCall',
     'FallbackExceptionGroup',
@@ -176,10 +175,6 @@ def __str__(self) -> str:
         return self.message
 
 
-class MCPServerCapabilitiesError(MCPError):
-    """Raised when attempting to access server capabilities that aren't present."""
-
-
 class MCPServerError(MCPError):
     """Raised when an MCP server returns an error response.
 

pydantic_ai_slim/pydantic_ai/mcp.py

@@ -42,7 +42,7 @@
 
 # after mcp imports so any import error maps to this file, not _mcp.py
 from . import _mcp, _utils, exceptions, messages, models
-from .exceptions import MCPServerCapabilitiesError, MCPServerError
+from .exceptions import MCPServerError
 
 __all__ = 'MCPServer', 'MCPServerStdio', 'MCPServerHTTP', 'MCPServerSSE', 'MCPServerStreamableHTTP', 'load_mcp_servers'
 
@@ -322,12 +322,11 @@ async def list_resources(self) -> list[_mcp.Resource]:
         - We also don't subscribe to resource changes to avoid complexity.
 
         Raises:
-            MCPServerCapabilitiesError: If the server does not support resources.
             MCPServerError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
-                raise MCPServerCapabilitiesError('Server does not support resources capability')
+                return []
             try:
                 result = await self._client.list_resources()
             except mcp_exceptions.McpError as e:
@@ -338,29 +337,30 @@ async def list_resource_templates(self) -> list[_mcp.ResourceTemplate]:
         """Retrieve resource templates that are currently present on the server.
 
         Raises:
-            MCPServerCapabilitiesError: If the server does not support resources.
             MCPServerError: If the server returns an error.
         """
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
-                raise MCPServerCapabilitiesError('Server does not support resources capability')
+                return []
             try:
                 result = await self._client.list_resource_templates()
             except mcp_exceptions.McpError as e:
                 raise MCPServerError.from_mcp_sdk_error(e) from e
         return [_mcp.map_from_mcp_resource_template(t) for t in result.resourceTemplates]
 
     @overload
-    async def read_resource(self, uri: str) -> str | messages.BinaryContent | list[str | messages.BinaryContent]: ...
+    async def read_resource(
+        self, uri: str
+    ) -> str | messages.BinaryContent | list[str | messages.BinaryContent] | None: ...
 
     @overload
     async def read_resource(
         self, uri: _mcp.Resource
-    ) -> str | messages.BinaryContent | list[str | messages.BinaryContent]: ...
+    ) -> str | messages.BinaryContent | list[str | messages.BinaryContent] | None: ...
 
     async def read_resource(
         self, uri: str | _mcp.Resource
-    ) -> str | messages.BinaryContent | list[str | messages.BinaryContent]:
+    ) -> str | messages.BinaryContent | list[str | messages.BinaryContent] | None:
         """Read the contents of a specific resource by URI.
 
         Args:
@@ -369,19 +369,26 @@ async def read_resource(
         Returns:
             The resource contents. If the resource has a single content item, returns that item directly.
             If the resource has multiple content items, returns a list of items.
+            Returns `None` if the server does not support resources or the resource is not found.
 
         Raises:
-            MCPServerCapabilitiesError: If the server does not support resources.
-            MCPServerError: If the server returns an error (e.g., resource not found).
+            MCPServerError: If the server returns an error other than resource not found.
         """
         resource_uri = uri if isinstance(uri, str) else uri.uri
         async with self:  # Ensure server is running
             if not self.capabilities.resources:
-                raise MCPServerCapabilitiesError('Server does not support resources capability')
+                return None
             try:
                 result = await self._client.read_resource(AnyUrl(resource_uri))
             except mcp_exceptions.McpError as e:
+                # As per https://modelcontextprotocol.io/specification/2025-06-18/server/resources#error-handling
+                if e.error.code == -32002:
+                    return None
                 raise MCPServerError.from_mcp_sdk_error(e) from e
+
+        if not result.contents:
+            return None
+
         return (
             self._get_content(result.contents[0])
             if len(result.contents) == 1
@@ -483,7 +490,9 @@ async def _map_tool_result_part(
             resource = part.resource
             return self._get_content(resource)
         elif isinstance(part, mcp_types.ResourceLink):
-            return await self.read_resource(str(part.uri))
+            result = await self.read_resource(str(part.uri))
+            # If resource not found, return an empty string as it's impossible to fetch anyway
+            return result if result is not None else ''
         else:
             assert_never(part)
 

tests/test_mcp.py

@@ -26,7 +26,6 @@
 from pydantic_ai._mcp import Resource, ServerCapabilities
 from pydantic_ai.agent import Agent
 from pydantic_ai.exceptions import (
-    MCPServerCapabilitiesError,
     MCPServerError,
     ModelRetry,
     UnexpectedModelBehavior,
@@ -1546,8 +1545,9 @@ async def test_read_resource_template(run_context: RunContext[int]):
 
 
 async def test_read_resource_not_found(mcp_server: MCPServerStdio) -> None:
-    """Test that read_resource raises MCPServerError for non-existent resources."""
+    """Test that read_resource raises MCPServerError for non-existent resources with non-standard error codes."""
     async with mcp_server:
+        # FastMCP uses error code 0 instead of -32002, so it should raise
         with pytest.raises(MCPServerError, match='Unknown resource: resource://does_not_exist') as exc_info:
             await mcp_server.read_resource('resource://does_not_exist')
 
@@ -1556,6 +1556,38 @@ async def test_read_resource_not_found(mcp_server: MCPServerStdio) -> None:
         assert exc_info.value.message == 'Unknown resource: resource://does_not_exist'
 
 
+async def test_read_resource_not_found_mcp_spec(mcp_server: MCPServerStdio) -> None:
+    """Test that read_resource returns None for MCP spec error code -32002 (resource not found)."""
+    # As per https://modelcontextprotocol.io/specification/2025-06-18/server/resources#error-handling
+    mcp_error = McpError(error=ErrorData(code=-32002, message='Resource not found'))
+
+    async with mcp_server:
+        with patch.object(
+            mcp_server._client,  # pyright: ignore[reportPrivateUsage]
+            'read_resource',
+            new=AsyncMock(side_effect=mcp_error),
+        ):
+            result = await mcp_server.read_resource('resource://missing')
+            assert result is None
+
+
+async def test_read_resource_empty_contents(mcp_server: MCPServerStdio) -> None:
+    """Test that read_resource returns None when server returns empty contents."""
+    from mcp.types import ReadResourceResult
+
+    # Mock a result with empty contents
+    empty_result = ReadResourceResult(contents=[])
+
+    async with mcp_server:
+        with patch.object(
+            mcp_server._client,  # pyright: ignore[reportPrivateUsage]
+            'read_resource',
+            new=AsyncMock(return_value=empty_result),
+        ):
+            result = await mcp_server.read_resource('resource://empty')
+            assert result is None
+
+
 async def test_list_resources_error(mcp_server: MCPServerStdio) -> None:
     """Test that list_resources converts McpError to MCPServerError."""
     mcp_error = McpError(
@@ -1645,16 +1677,19 @@ async def test_capabilities(mcp_server: MCPServerStdio) -> None:
 
 
 async def test_resource_methods_without_capability(mcp_server: MCPServerStdio) -> None:
-    """Test that resource methods raise MCPServerCapabilitiesError when resources capability is not available."""
+    """Test that resource methods return empty values when resources capability is not available."""
     async with mcp_server:
         # Mock the capabilities to not support resources
         mock_capabilities = ServerCapabilities(resources=False)
         with patch.object(mcp_server, '_server_capabilities', mock_capabilities):
-            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
-                await mcp_server.list_resources()
+            # list_resources should return empty list
+            result = await mcp_server.list_resources()
+            assert result == []
 
-            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
-                await mcp_server.list_resource_templates()
+            # list_resource_templates should return empty list
+            result = await mcp_server.list_resource_templates()
+            assert result == []
 
-            with pytest.raises(MCPServerCapabilitiesError, match='Server does not support resources capability'):
-                await mcp_server.read_resource('resource://test')
+            # read_resource should return None
+            result = await mcp_server.read_resource('resource://test')
+            assert result is None