fix(server): let template handlers signal not-found per SEP-2164

ResourceTemplate.create_resource() now re-raises ResourceError (and its
ResourceNotFoundError subclass) instead of wrapping them, so a template
handler can raise ResourceNotFoundError to produce -32602 INVALID_PARAMS
on the wire. Other exceptions are still wrapped as ResourceError.

Also exports ResourceError and ResourceNotFoundError from
mcp.server.mcpserver, and documents the ValueError->ResourceError change
in docs/migration.md.

Author: pja-ant

docs/migration.md

@@ -343,6 +343,10 @@ async def my_tool(x: int, ctx: Context) -> str:
 
 The internal layers (`ToolManager.call_tool`, `Tool.run`, `Prompt.render`, `ResourceTemplate.create_resource`, etc.) now require `context` as a positional argument.
 
+### `ResourceManager.get_resource()` and `ResourceTemplate.create_resource()` raise typed exceptions
+
+`ResourceManager.get_resource()` now raises `ResourceNotFoundError` (instead of `ValueError`) when no resource or template matches the URI. `ResourceTemplate.create_resource()` now raises `ResourceError` (instead of `ValueError`) when the template function fails. Neither subclasses `ValueError`, so callers catching `ValueError` should switch to `ResourceNotFoundError` / `ResourceError` (both importable from `mcp.server.mcpserver`). `MCPServer.read_resource()` continues to raise `ResourceError` and is unaffected.
+
 ### Replace `RootModel` by union types with `TypeAdapter` validation
 
 The following union types are no longer `RootModel` subclasses:

src/mcp/server/mcpserver/__init__.py

@@ -3,7 +3,8 @@
 from mcp.types import Icon
 
 from .context import Context
+from .exceptions import ResourceError, ResourceNotFoundError
 from .server import MCPServer
 from .utilities.types import Audio, Image
 
-__all__ = ["MCPServer", "Context", "Image", "Audio", "Icon"]
+__all__ = ["MCPServer", "Context", "Image", "Audio", "Icon", "ResourceError", "ResourceNotFoundError"]

src/mcp/server/mcpserver/resources/templates.py

@@ -127,5 +127,7 @@ async def create_resource(
                 meta=self.meta,
                 fn=lambda: result,  # Capture result in closure
             )
+        except ResourceError:
+            raise
         except Exception as e:
             raise ResourceError(f"Error creating resource from template: {e}")

tests/server/mcpserver/test_server.py

@@ -12,7 +12,7 @@
 from mcp.client import Client
 from mcp.server.context import ServerRequestContext
 from mcp.server.experimental.request_context import Experimental
-from mcp.server.mcpserver import Context, MCPServer
+from mcp.server.mcpserver import Context, MCPServer, ResourceNotFoundError
 from mcp.server.mcpserver.exceptions import ToolError
 from mcp.server.mcpserver.prompts.base import Message, UserMessage
 from mcp.server.mcpserver.resources import FileResource, FunctionResource
@@ -731,6 +731,21 @@ def get_item(item_id: str) -> str:
             assert exc_info.value.error.code == INTERNAL_ERROR
             assert exc_info.value.error.code != INVALID_PARAMS
 
+    async def test_read_resource_template_not_found(self):
+        """A template handler raising ResourceNotFoundError must surface as INVALID_PARAMS per SEP-2164."""
+        mcp = MCPServer()
+
+        @mcp.resource("resource://users/{user_id}")
+        def get_user(user_id: str) -> str:
+            raise ResourceNotFoundError(f"no user {user_id}")
+
+        async with Client(mcp) as client:
+            with pytest.raises(MCPError, match="no user 999") as exc_info:
+                await client.read_resource("resource://users/999")
+
+            assert exc_info.value.error.code == INVALID_PARAMS
+            assert exc_info.value.error.data == {"uri": "resource://users/999"}
+
     async def test_binary_resource(self):
         mcp = MCPServer()