feat: Implement consistent prefix-based filtering for all list operations

- Rename PaginatedRequestParams to ListRequestParams and add prefix field
- Rename PaginatedRequest to ListRequest for semantic clarity
- Rename PaginatedResult to ListResult for consistency
- Remove redundant ListResourcesRequestParams and ListResourceTemplatesRequestParams
- Add prefix filtering to tools and prompts list operations
- Ensure all prefixes are treated as path prefixes ending with /
- Update lowlevel server handlers to accept full request objects
- Update FastMCP server to extract prefix from request params

This unifies the list operation API across resources, templates, tools, and
prompts. All list methods now support optional prefix filtering using URI
path prefixes (e.g., 'tool://category/' to match only tools under that path).

Author: Tapan Chugh

src/mcp/client/session.py

@@ -348,7 +348,7 @@ async def list_prompts(self, cursor: str | None = None) -> types.ListPromptsResu
             types.ClientRequest(
                 types.ListPromptsRequest(
                     method="prompts/list",
-                    params=types.PaginatedRequestParams(cursor=cursor) if cursor is not None else None,
+                    params=types.ListRequestParams(cursor=cursor) if cursor is not None else None,
                 )
             ),
             types.ListPromptsResult,
@@ -397,7 +397,7 @@ async def list_tools(self, cursor: str | None = None) -> types.ListToolsResult:
             types.ClientRequest(
                 types.ListToolsRequest(
                     method="tools/list",
-                    params=types.PaginatedRequestParams(cursor=cursor) if cursor is not None else None,
+                    params=types.ListRequestParams(cursor=cursor) if cursor is not None else None,
                 )
             ),
             types.ListToolsResult,

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

@@ -35,6 +35,13 @@ def get_prompt(self, name: str) -> Prompt | None:
         uri = self._normalize_to_uri(name)
         return self._prompts.get(uri)
 
-    def list_prompts(self) -> list[Prompt]:
-        """List all registered prompts."""
-        return list(self._prompts.values())
+    def list_prompts(self, prefix: str | None = None) -> list[Prompt]:
+        """List all registered prompts, optionally filtered by URI prefix."""
+        prompts = list(self._prompts.values())
+        if prefix:
+            # Ensure prefix ends with / for proper path matching
+            if not prefix.endswith("/"):
+                prefix = prefix + "/"
+            prompts = [p for p in prompts if str(p.uri).startswith(prefix)]
+        logger.debug("Listing prompts", extra={"count": len(prompts), "prefix": prefix})
+        return prompts

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

@@ -90,6 +90,9 @@ def list_resources(self, prefix: str | None = None) -> list[Resource]:
         """List all registered resources, optionally filtered by URI prefix."""
         resources = list(self._resources.values())
         if prefix:
+            # Ensure prefix ends with / for proper path matching
+            if not prefix.endswith("/"):
+                prefix = prefix + "/"
             resources = [r for r in resources if str(r.uri).startswith(prefix)]
         logger.debug("Listing resources", extra={"count": len(resources), "prefix": prefix})
         return resources
@@ -98,6 +101,9 @@ def list_templates(self, prefix: str | None = None) -> list[ResourceTemplate]:
         """List all registered templates, optionally filtered by URI template prefix."""
         templates = list(self._templates.values())
         if prefix:
+            # Ensure prefix ends with / for proper path matching
+            if not prefix.endswith("/"):
+                prefix = prefix + "/"
             templates = [t for t in templates if t.matches_prefix(prefix)]
         logger.debug("Listing templates", extra={"count": len(templates), "prefix": prefix})
         return templates

src/mcp/server/fastmcp/server.py

@@ -267,9 +267,12 @@ def _setup_handlers(self) -> None:
         self._mcp_server.get_prompt()(self.get_prompt)
         self._mcp_server.list_resource_templates()(self.list_resource_templates)
 
-    async def list_tools(self) -> list[MCPTool]:
-        """List all available tools."""
-        tools = self._tool_manager.list_tools()
+    async def list_tools(self, request: types.ListToolsRequest) -> list[MCPTool]:
+        """List all available tools, optionally filtered by prefix."""
+        prefix = None
+        if request.params:
+            prefix = request.params.prefix
+        tools = self._tool_manager.list_tools(prefix=prefix)
         return [
             MCPTool(
                 name=info.name,
@@ -966,9 +969,12 @@ def streamable_http_app(self) -> Starlette:
             lifespan=lambda app: self.session_manager.run(),
         )
 
-    async def list_prompts(self) -> list[MCPPrompt]:
-        """List all available prompts."""
-        prompts = self._prompt_manager.list_prompts()
+    async def list_prompts(self, request: types.ListPromptsRequest) -> list[MCPPrompt]:
+        """List all available prompts, optionally filtered by prefix."""
+        prefix = None
+        if request.params:
+            prefix = request.params.prefix
+        prompts = self._prompt_manager.list_prompts(prefix=prefix)
         return [
             MCPPrompt(
                 name=prompt.name,

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

@@ -45,9 +45,16 @@ def get_tool(self, name: str) -> Tool | None:
         uri = self._normalize_to_uri(name)
         return self._tools.get(uri)
 
-    def list_tools(self) -> list[Tool]:
-        """List all registered tools."""
-        return list(self._tools.values())
+    def list_tools(self, prefix: str | None = None) -> list[Tool]:
+        """List all registered tools, optionally filtered by URI prefix."""
+        tools = list(self._tools.values())
+        if prefix:
+            # Ensure prefix ends with / for proper path matching
+            if not prefix.endswith("/"):
+                prefix = prefix + "/"
+            tools = [t for t in tools if str(t.uri).startswith(prefix)]
+        logger.debug("Listing tools", extra={"count": len(tools), "prefix": prefix})
+        return tools
 
     def add_tool(
         self,

src/mcp/server/lowlevel/server.py

@@ -231,11 +231,11 @@ def request_context(
         return request_ctx.get()
 
     def list_prompts(self):
-        def decorator(func: Callable[[], Awaitable[list[types.Prompt]]]):
+        def decorator(func: Callable[[types.ListPromptsRequest], Awaitable[list[types.Prompt]]]):
             logger.debug("Registering handler for PromptListRequest")
 
-            async def handler(_: Any):
-                prompts = await func()
+            async def handler(request: types.ListPromptsRequest):
+                prompts = await func(request)
                 return types.ServerResult(types.ListPromptsResult(prompts=prompts))
 
             self.request_handlers[types.ListPromptsRequest] = handler
@@ -382,11 +382,11 @@ async def handler(req: types.UnsubscribeRequest):
         return decorator
 
     def list_tools(self):
-        def decorator(func: Callable[[], Awaitable[list[types.Tool]]]):
+        def decorator(func: Callable[[types.ListToolsRequest], Awaitable[list[types.Tool]]]):
             logger.debug("Registering handler for ListToolsRequest")
 
-            async def handler(_: Any):
-                tools = await func()
+            async def handler(request: types.ListToolsRequest):
+                tools = await func(request)
                 # Refresh the tool cache
                 self._tool_cache.clear()
                 for tool in tools:

src/mcp/types.py

@@ -55,28 +55,17 @@ class Meta(BaseModel):
     meta: Meta | None = Field(alias="_meta", default=None)
 
 
-class PaginatedRequestParams(RequestParams):
+class ListRequestParams(RequestParams):
+    prefix: str | None = None
+    """Optional prefix to filter results by URI."""
+
     cursor: Cursor | None = None
     """
     An opaque token representing the current pagination position.
     If provided, the server should return results starting after this cursor.
     """
 
 
-class ListResourcesRequestParams(PaginatedRequestParams):
-    """Parameters for listing resources with optional prefix filtering."""
-
-    prefix: str | None = None
-    """Optional prefix to filter resources by URI."""
-
-
-class ListResourceTemplatesRequestParams(PaginatedRequestParams):
-    """Parameters for listing resource templates with optional prefix filtering."""
-
-    prefix: str | None = None
-    """Optional prefix to filter resource templates by URI template."""
-
-
 class NotificationParams(BaseModel):
     class Meta(BaseModel):
         model_config = ConfigDict(extra="allow")
@@ -101,11 +90,11 @@ class Request(BaseModel, Generic[RequestParamsT, MethodT]):
     model_config = ConfigDict(extra="allow")
 
 
-class PaginatedRequest(Request[PaginatedRequestParams | None, MethodT], Generic[MethodT]):
-    """Base class for paginated requests,
-    matching the schema's PaginatedRequest interface."""
+class ListRequest(Request[ListRequestParams | None, MethodT], Generic[MethodT]):
+    """Base class for list requests,
+    matching the schema's ListRequest interface."""
 
-    params: PaginatedRequestParams | None = None
+    params: ListRequestParams | None = None
 
 
 class Notification(BaseModel, Generic[NotificationParamsT, MethodT]):
@@ -127,7 +116,7 @@ class Result(BaseModel):
     model_config = ConfigDict(extra="allow")
 
 
-class PaginatedResult(Result):
+class ListResult(Result):
     nextCursor: Cursor | None = None
     """
     An opaque token representing the pagination position after the last returned result.
@@ -408,11 +397,10 @@ class ProgressNotification(Notification[ProgressNotificationParams, Literal["not
     params: ProgressNotificationParams
 
 
-class ListResourcesRequest(Request[ListResourcesRequestParams | None, Literal["resources/list"]]):
+class ListResourcesRequest(ListRequest[Literal["resources/list"]]):
     """Sent from the client to request a list of resources the server has."""
 
     method: Literal["resources/list"]
-    params: ListResourcesRequestParams | None = None
 
 
 class Annotations(BaseModel):
@@ -478,22 +466,19 @@ class ResourceTemplate(BaseMetadata):
     model_config = ConfigDict(extra="allow")
 
 
-class ListResourcesResult(PaginatedResult):
+class ListResourcesResult(ListResult):
     """The server's response to a resources/list request from the client."""
 
     resources: list[Resource]
 
 
-class ListResourceTemplatesRequest(
-    Request[ListResourceTemplatesRequestParams | None, Literal["resources/templates/list"]]
-):
+class ListResourceTemplatesRequest(ListRequest[Literal["resources/templates/list"]]):
     """Sent from the client to request a list of resource templates the server has."""
 
     method: Literal["resources/templates/list"]
-    params: ListResourceTemplatesRequestParams | None = None
 
 
-class ListResourceTemplatesResult(PaginatedResult):
+class ListResourceTemplatesResult(ListResult):
     """The server's response to a resources/templates/list request from the client."""
 
     resourceTemplates: list[ResourceTemplate]
@@ -629,7 +614,7 @@ class ResourceUpdatedNotification(
     params: ResourceUpdatedNotificationParams
 
 
-class ListPromptsRequest(PaginatedRequest[Literal["prompts/list"]]):
+class ListPromptsRequest(ListRequest[Literal["prompts/list"]]):
     """Sent from the client to request a list of prompts and prompt templates."""
 
     method: Literal["prompts/list"]
@@ -664,7 +649,7 @@ class Prompt(BaseMetadata):
     model_config = ConfigDict(extra="allow")
 
 
-class ListPromptsResult(PaginatedResult):
+class ListPromptsResult(ListResult):
     """The server's response to a prompts/list request from the client."""
 
     prompts: list[Prompt]
@@ -814,7 +799,7 @@ class PromptListChangedNotification(
     params: NotificationParams | None = None
 
 
-class ListToolsRequest(PaginatedRequest[Literal["tools/list"]]):
+class ListToolsRequest(ListRequest[Literal["tools/list"]]):
     """Sent from the client to request a list of tools the server has."""
 
     method: Literal["tools/list"]
@@ -892,7 +877,7 @@ class Tool(BaseMetadata):
     model_config = ConfigDict(extra="allow")
 
 
-class ListToolsResult(PaginatedResult):
+class ListToolsResult(ListResult):
     """The server's response to a tools/list request from the client."""
 
     tools: list[Tool]