refactor: consolidate URI handling and implement DRY principles

- Add TOOL_SCHEME and PROMPT_SCHEME constants in mcp/types.py
- Create common URI utilities in uri_utils.py for normalization and prefix filtering
- Update Tool and Prompt classes to auto-generate URIs when not provided
- Replace hardcoded URI schemes throughout codebase with constants
- Fix prefix filtering to handle partial matches correctly
- Update example files to match expected function signatures

Author: Tapan Chugh

README.md

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

examples/servers/simple-prompt/mcp_simple_prompt/server.py

@@ -49,7 +49,7 @@ def main(port: int, transport: str) -> int:
     app = Server("mcp-simple-prompt")
 
     @app.list_prompts()
-    async def list_prompts() -> list[types.Prompt]:
+    async def list_prompts(request: types.ListPromptsRequest) -> list[types.Prompt]:
         return [
             types.Prompt(
                 name="simple",

examples/servers/simple-streamablehttp-stateless/mcp_simple_streamablehttp_stateless/server.py

@@ -69,7 +69,7 @@ async def call_tool(name: str, arguments: dict) -> list[types.ContentBlock]:
         ]
 
     @app.list_tools()
-    async def list_tools() -> list[types.Tool]:
+    async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
         return [
             types.Tool(
                 name="start-notification-stream",

examples/servers/simple-streamablehttp/mcp_simple_streamablehttp/server.py

@@ -87,7 +87,7 @@ async def call_tool(name: str, arguments: dict) -> list[types.ContentBlock]:
         ]
 
     @app.list_tools()
-    async def list_tools() -> list[types.Tool]:
+    async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
         return [
             types.Tool(
                 name="start-notification-stream",

examples/servers/simple-tool/mcp_simple_tool/server.py

@@ -37,7 +37,7 @@ async def fetch_tool(name: str, arguments: dict) -> list[types.ContentBlock]:
         return await fetch_website(arguments["url"])
 
     @app.list_tools()
-    async def list_tools() -> list[types.Tool]:
+    async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
         return [
             types.Tool(
                 name="fetch",

examples/servers/structured_output_lowlevel.py

@@ -21,7 +21,7 @@
 
 
 @server.list_tools()
-async def list_tools() -> list[types.Tool]:
+async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
     """List available tools with their schemas."""
     return [
         types.Tool(

examples/snippets/servers/lowlevel/basic.py

@@ -15,7 +15,7 @@
 
 
 @server.list_prompts()
-async def handle_list_prompts() -> list[types.Prompt]:
+async def handle_list_prompts(request: types.ListPromptsRequest) -> list[types.Prompt]:
     """List available prompts."""
     return [
         types.Prompt(

examples/snippets/servers/lowlevel/lifespan.py

@@ -49,7 +49,7 @@ async def server_lifespan(_server: Server) -> AsyncIterator[dict]:
 
 
 @server.list_tools()
-async def handle_list_tools() -> list[types.Tool]:
+async def handle_list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
     """List available tools."""
     return [
         types.Tool(

examples/snippets/servers/lowlevel/structured_output.py

@@ -15,7 +15,7 @@
 
 
 @server.list_tools()
-async def list_tools() -> list[types.Tool]:
+async def list_tools(request: types.ListToolsRequest) -> list[types.Tool]:
     """List available tools with structured output schemas."""
     return [
         types.Tool(

src/mcp/client/session.py

@@ -342,13 +342,16 @@ async def _validate_tool_result(self, name: str, result: types.CallToolResult) -
             except SchemaError as e:
                 raise RuntimeError(f"Invalid schema for tool {name}: {e}")
 
-    async def list_prompts(self, cursor: str | None = None) -> types.ListPromptsResult:
+    async def list_prompts(self, prefix: str | None = None, cursor: str | None = None) -> types.ListPromptsResult:
         """Send a prompts/list request."""
+        params = None
+        if cursor is not None or prefix is not None:
+            params = types.ListRequestParams(prefix=prefix, cursor=cursor)
         return await self.send_request(
             types.ClientRequest(
                 types.ListPromptsRequest(
                     method="prompts/list",
-                    params=types.ListRequestParams(cursor=cursor) if cursor is not None else None,
+                    params=params,
                 )
             ),
             types.ListPromptsResult,
@@ -391,13 +394,16 @@ async def complete(
             types.CompleteResult,
         )
 
-    async def list_tools(self, cursor: str | None = None) -> types.ListToolsResult:
+    async def list_tools(self, prefix: str | None = None, cursor: str | None = None) -> types.ListToolsResult:
         """Send a tools/list request."""
+        params = None
+        if cursor is not None or prefix is not None:
+            params = types.ListRequestParams(prefix=prefix, cursor=cursor)
         result = await self.send_request(
             types.ClientRequest(
                 types.ListToolsRequest(
                     method="tools/list",
-                    params=types.ListRequestParams(cursor=cursor) if cursor is not None else None,
+                    params=params,
                 )
             ),
             types.ListToolsResult,