refactor: Update URI schemes and improve filter_by_prefix signature

- Change URI schemes from tool:// and prompt:// to mcp://tools and mcp://prompts
- Add MCP_SCHEME constant and use it for URL validation
- Add model validators to ensure URIs start with correct prefixes
- Improve filter_by_prefix to accept AnyUrl | str, removing need for str() casts
- Make Prompt description field optional (matching main branch)
- Update all tests to use scheme constants instead of hardcoded values

This provides a more standard URI format where 'mcp' is the scheme and
'tools'/'prompts' are path segments, while also simplifying the API.

🤖 Generated with [Claude Code](https://claude.ai/code)

Co-Authored-By: Claude <noreply@anthropic.com>

Author: Tapan Chugh

README.md

@@ -1125,7 +1125,7 @@ server = Server("example-server", lifespan=server_lifespan)
 
 
 @server.list_tools()
-async def handle_list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
+async def handle_list_tools(_) -> list[types.Tool]:
     """List available tools."""
     return [
         types.Tool(
@@ -1207,7 +1207,7 @@ server = Server("example-server")
 
 
 @server.list_prompts()
-async def handle_list_prompts(request: types.ListPromptsRequest) -> list[types.Prompt]:
+async def handle_list_prompts(_) -> list[types.Prompt]:
     """List available prompts."""
     return [
         types.Prompt(
@@ -1286,7 +1286,7 @@ server = Server("example-server")
 
 
 @server.list_tools()
-async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
+async def list_tools(_) -> list[types.Tool]:
     """List available tools with structured output schemas."""
     return [
         types.Tool(

src/mcp/server/fastmcp/prompts/base.py

@@ -60,7 +60,7 @@ class Prompt(BaseModel):
     name: str = Field(description="Name of the prompt")
     uri: str = Field(description="URI of the prompt")
     title: str | None = Field(None, description="Human-readable title of the prompt")
-    description: str = Field(description="Description of what the prompt does")
+    description: str | None = Field(None, description="Description of what the prompt does")
     arguments: list[PromptArgument] | None = Field(None, description="Arguments that can be passed to the prompt")
     fn: Callable[..., PromptResult | Awaitable[PromptResult]] = Field(exclude=True)
 

src/mcp/server/fastmcp/prompts/manager.py

@@ -28,7 +28,7 @@ def get_prompt(self, name: str) -> Prompt | None:
     def list_prompts(self, prefix: str | None = None) -> list[Prompt]:
         """List all registered prompts, optionally filtered by URI prefix."""
         prompts = list(self._prompts.values())
-        prompts = filter_by_prefix(prompts, prefix, lambda p: str(p.uri))
+        prompts = filter_by_prefix(prompts, prefix, lambda p: p.uri)
         logger.debug("Listing prompts", extra={"count": len(prompts), "prefix": prefix})
         return prompts
 

src/mcp/server/fastmcp/prompts/prompt_manager.py

@@ -37,6 +37,6 @@ def get_prompt(self, name: str) -> Prompt | None:
     def list_prompts(self, prefix: str | None = None) -> list[Prompt]:
         """List all registered prompts, optionally filtered by URI prefix."""
         prompts = list(self._prompts.values())
-        prompts = filter_by_prefix(prompts, prefix, lambda p: str(p.uri))
+        prompts = filter_by_prefix(prompts, prefix, lambda p: p.uri)
         logger.debug("Listing prompts", extra={"count": len(prompts), "prefix": prefix})
         return prompts

src/mcp/server/fastmcp/resources/resource_manager.py

@@ -90,7 +90,7 @@ async def get_resource(self, uri: AnyUrl | str) -> Resource | None:
     def list_resources(self, prefix: str | None = None) -> list[Resource]:
         """List all registered resources, optionally filtered by URI prefix."""
         resources = list(self._resources.values())
-        resources = filter_by_prefix(resources, prefix, lambda r: str(r.uri))
+        resources = filter_by_prefix(resources, prefix, lambda r: r.uri)
         logger.debug("Listing resources", extra={"count": len(resources), "prefix": prefix})
         return resources
 

src/mcp/server/fastmcp/tools/tool_manager.py

@@ -47,7 +47,7 @@ def get_tool(self, name: str) -> Tool | None:
     def list_tools(self, prefix: str | None = None) -> list[Tool]:
         """List all registered tools, optionally filtered by URI prefix."""
         tools = list(self._tools.values())
-        tools = filter_by_prefix(tools, prefix, lambda t: str(t.uri))
+        tools = filter_by_prefix(tools, prefix, lambda t: t.uri)
         logger.debug("Listing tools", extra={"count": len(tools), "prefix": prefix})
         return tools
 

src/mcp/server/fastmcp/uri_utils.py

@@ -3,6 +3,8 @@
 from collections.abc import Callable
 from typing import TypeVar
 
+from pydantic import AnyUrl
+
 from mcp.types import PROMPT_SCHEME, TOOL_SCHEME
 
 T = TypeVar("T")
@@ -33,7 +35,7 @@ def normalize_to_prompt_uri(name_or_uri: str) -> str:
     return normalize_to_uri(name_or_uri, PROMPT_SCHEME)
 
 
-def filter_by_prefix(items: list[T], prefix: str | None, uri_getter: Callable[[T], str]) -> list[T]:
+def filter_by_prefix(items: list[T], prefix: str | None, uri_getter: Callable[[T], AnyUrl | str]) -> list[T]:
     """Filter items by URI prefix.
 
     Args:
@@ -50,7 +52,7 @@ def filter_by_prefix(items: list[T], prefix: str | None, uri_getter: Callable[[T
     # Filter items where the URI starts with the prefix
     filtered: list[T] = []
     for item in items:
-        uri = uri_getter(item)
+        uri = str(uri_getter(item))
         if uri.startswith(prefix):
             # If prefix ends with a separator, we already have a proper boundary
             if prefix.endswith(("/", "?", "#")):

src/mcp/types.py

@@ -6,8 +6,9 @@
 from typing_extensions import deprecated
 
 # URI scheme constants
-TOOL_SCHEME = "tool:/"
-PROMPT_SCHEME = "prompt:/"
+MCP_SCHEME = "mcp"
+TOOL_SCHEME = f"{MCP_SCHEME}://tools"
+PROMPT_SCHEME = f"{MCP_SCHEME}://prompts"
 
 """
 Model Context Protocol bindings for Python
@@ -641,9 +642,7 @@ class PromptArgument(BaseModel):
 class Prompt(BaseMetadata):
     """A prompt or prompt template that the server offers."""
 
-    uri: (
-        Annotated[AnyUrl, UrlConstraints(allowed_schemes=[PROMPT_SCHEME.rstrip(":/ ")], host_required=False)] | None
-    ) = None
+    uri: Annotated[AnyUrl, UrlConstraints(allowed_schemes=[MCP_SCHEME], host_required=False)] | None = None
     """URI for the prompt. Auto-generated if not provided."""
     description: str | None = None
     """An optional description of what this prompt provides."""
@@ -662,6 +661,15 @@ def __init__(self, **data: Any) -> None:
             data["uri"] = AnyUrl(f"{PROMPT_SCHEME}/{data['name']}")
         super().__init__(**data)
 
+    @model_validator(mode="after")
+    def validate_prompt_uri(self) -> "Prompt":
+        """Validate that prompt URI starts with the correct prefix."""
+        if self.uri is not None:
+            uri_str = str(self.uri)
+            if not uri_str.startswith(f"{PROMPT_SCHEME}/"):
+                raise ValueError(f"Prompt URI must start with {PROMPT_SCHEME}/")
+        return self
+
 
 class ListPromptsResult(ListResult):
     """The server's response to a prompts/list request from the client."""
@@ -870,9 +878,7 @@ class ToolAnnotations(BaseModel):
 class Tool(BaseMetadata):
     """Definition for a tool the client can call."""
 
-    uri: Annotated[AnyUrl, UrlConstraints(allowed_schemes=[TOOL_SCHEME.rstrip(":/ ")], host_required=False)] | None = (
-        None
-    )
+    uri: Annotated[AnyUrl, UrlConstraints(allowed_schemes=[MCP_SCHEME], host_required=False)] | None = None
     """URI for the tool. Auto-generated if not provided."""
     description: str | None = None
     """A human-readable description of the tool."""
@@ -898,6 +904,15 @@ def __init__(self, **data: Any) -> None:
             data["uri"] = AnyUrl(f"{TOOL_SCHEME}/{data['name']}")
         super().__init__(**data)
 
+    @model_validator(mode="after")
+    def validate_tool_uri(self) -> "Tool":
+        """Validate that tool URI starts with the correct prefix."""
+        if self.uri is not None:
+            uri_str = str(self.uri)
+            if not uri_str.startswith(f"{TOOL_SCHEME}/"):
+                raise ValueError(f"Tool URI must start with {TOOL_SCHEME}/")
+        return self
+
 
 class ListToolsResult(ListResult):
     """The server's response to a tools/list request from the client."""

tests/server/fastmcp/test_tool_manager.py

@@ -62,7 +62,7 @@ class AddArguments(ArgModelBase):
         # warn on duplicate tools
         with caplog.at_level(logging.WARNING):
             manager = ToolManager(True, tools=[original_tool, original_tool])
-            assert "Tool already exists: tool://sum" in caplog.text
+            assert f"Tool already exists: {TOOL_SCHEME}/sum" in caplog.text
 
     @pytest.mark.anyio
     async def test_async_function(self):
@@ -163,7 +163,7 @@ def f(x: int) -> int:
         manager.add_tool(f)
         with caplog.at_level(logging.WARNING):
             manager.add_tool(f)
-            assert "Tool already exists: tool://f" in caplog.text
+            assert f"Tool already exists: {TOOL_SCHEME}/f" in caplog.text
 
     def test_disable_warn_on_duplicate_tools(self, caplog):
         """Test disabling warning on duplicate tools."""
@@ -351,7 +351,7 @@ def math_multiply(a: int, b: int) -> int:
         multiply_tool.uri = f"{TOOL_SCHEME}/custom/math/multiply"
         manager._tools[str(multiply_tool.uri)] = multiply_tool
 
-        # Call by default URI (tool://function_name)
+        # Call by default URI (TOOL_SCHEME/function_name)
         result = await manager.call_tool(f"{TOOL_SCHEME}/math_add", {"a": 5, "b": 3})
         assert result == 8
 

tests/test_types.py

@@ -58,7 +58,7 @@ def test_resource_uri():
     assert resource.name == "test"
     assert str(resource.uri) == "file://test.txt/"  # AnyUrl adds trailing slash
 
-    # Should reject tool:// and prompt:// schemes
+    # Should reject TOOL_SCHEME and PROMPT_SCHEME schemes
     with pytest.raises(ValueError, match="reserved schemes"):
         Resource(name="test", uri=AnyUrl(f"{TOOL_SCHEME}/test"))
 
@@ -68,7 +68,7 @@ def test_resource_uri():
 
 def test_tool_uri_validation():
     """Test that Tool requires URI with tool scheme."""
-    # Tool requires URI with tool:// scheme
+    # Tool requires URI with TOOL_SCHEME
     tool = Tool(name="calculator", inputSchema={"type": "object"}, uri=f"{TOOL_SCHEME}/calculator")
     assert tool.name == "calculator"
     assert str(tool.uri) == f"{TOOL_SCHEME}/calculator"
@@ -80,7 +80,7 @@ def test_tool_uri_validation():
 
 def test_prompt_uri_validation():
     """Test that Prompt requires URI with prompt scheme."""
-    # Prompt requires URI with prompt:// scheme
+    # Prompt requires URI with PROMPT_SCHEME
     prompt = Prompt(name="greeting", uri=f"{PROMPT_SCHEME}/greeting")
     assert prompt.name == "greeting"
     assert str(prompt.uri) == f"{PROMPT_SCHEME}/greeting"