René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"SEP: Prefix Filtering for Listing Resource / Templates","articleBody":"## Preamble\n\n**Title:** Prefix Filtering for Listing Resource / Templates\n**Status:** Proposal\n**Author:** Tapan Chugh (@chughtapan)\n**Type:** Standards Track\n**Created:** 2025-07-31\n\n## Abstract\n\nThis SEP proposes adding an optional `prefix` parameter to the `resources/list` and `resources/templates/list` requests to enable servers to efficiently filter resources and resource templates by URI prefix, to improve discoverability of resources for clients when servers expose thousands of resources (or more).\n\n## Motivation\n\nResources are a powerful abstraction in MCP to define the scope of information available to LLMs. While the protocol already supports pagination for handling large resource lists, this alone is insufficient when servers expose thousands of resources. Clients must retrieve multiple pages and implement local filtering to find specific resources, which becomes complex when combined with pagination as they must track filtered results across page boundaries. This leads to inefficiency as the same filtering logic is reimplemented in every client, with redundant data transfer for resources that will be discarded. Since resources already use URI format, prefix-based filtering is a natural solution that offloads this common operation to the server. \n\n## Specification\n\n### Schema Changes\n\nUpdate `ListResourcesRequest` and `ListResourceTemplatesRequest` interfaces to include an optional `prefix` parameter:\n\n```typescript\nexport interface ListResourcesRequest extends PaginatedRequest {\n  method: \"resources/list\";\n  params?: {\n    /**\n     * Optional URI prefix to filter resources.\n     * Only resources whose URI starts with this prefix will be returned.\n     */\n    prefix?: string;\n  } \u0026 PaginatedRequest[\"params\"];\n}\n\nexport interface ListResourceTemplatesRequest extends PaginatedRequest {\n  method: \"resources/templates/list\";\n  params?: {\n    /**\n     * Optional URI prefix to filter resource templates.\n     * Only templates whose URI template starts with this prefix will be returned.\n     */\n    prefix?: string;\n  } \u0026 PaginatedRequest[\"params\"];\n}\n```\n\n### Behavior\n\n1. **Prefix matching**: The server returns only resources whose URI (or URI template) starts with the prefix\n2. **Pagination compatibility**: Prefix filtering works with pagination - the cursor represents position within the filtered results\n\n### Examples\n\nRequest with prefix filter:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"method\": \"resources/list\",\n  \"params\": {\n    \"prefix\": \"file:///project/src/\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 1,\n  \"result\": {\n    \"resources\": [\n      {\n        \"uri\": \"file:///project/src/main.py\",\n        \"name\": \"main.py\"\n      },\n      {\n        \"uri\": \"file:///project/src/config.json\",\n        \"name\": \"config.json\"\n      }\n    ]\n  }\n}\n```\n\nCombining with pagination:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 2,\n  \"method\": \"resources/list\",\n  \"params\": {\n    \"prefix\": \"https://api.example.com/users/\",\n    \"cursor\": \"cursor-123\"\n  }\n}\n```\n\nResource templates with prefix filter:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"method\": \"resources/templates/list\",\n  \"params\": {\n    \"prefix\": \"https://api.example.com/\"\n  }\n}\n```\n\nResponse:\n\n```json\n{\n  \"jsonrpc\": \"2.0\",\n  \"id\": 3,\n  \"result\": {\n    \"resourceTemplates\": [\n      {\n        \"uriTemplate\": \"https://api.example.com/users/{id}\",\n        \"name\": \"User Details\"\n      },\n      {\n        \"uriTemplate\": \"https://api.example.com/posts/{postId}\",\n        \"name\": \"Blog Post\"\n      }\n    ]\n  }\n}\n```\n\n## Rationale\n\nResources are a powerful abstraction in MCP to define the scope of information available to LLMs. Efficient discoverability of these resources is crucial for effective context management. As the number of resources exposed by servers increases into thousands or millions, naively returning all resources becomes inefficient and convoluted for clients to handle. Given the hierarchical structure inherent in URIs, prefix-based filtering provides the simplest approach to improve resource discoverability.\n\n### Alternatives Considered\n\n1. **Glob patterns**: Although more flexible than simple prefixes, the value from the additional implementation complexity does not seem clear given the hierarchical nature of URIs.\n\n2. **Namespaces**: (#993) I believe this was already rejected in #1061. The hierarchical nature of URIs lends itself to simple path based name-spacing automatically.\n\n3. **New search method**: (#322, #204) Creating a new search method only for resources seems like an overkill. Creating a unified search method across components / tools might not work since the search requirements are likely different.\n\n## Backward Compatibility\n\nWhile the `prefix` parameter is optional in the schema, this feature requires updates to SDKs to expose the prefix parameter. Existing clients continue to work as it is since the parameter is optional.\n\n## Reference Implementation\nSpecification Updates PR: #1279 \nPython SDK Implementation: https://github.com/modelcontextprotocol/python-sdk/pull/1225\n\n\n## Security Implications\n\nPrefix filtering doesn't grant access to resources that wouldn't already be accessible through pagination. It only provides a more efficient way to retrieve subsets of already-accessible resources.\n\n## Open Questions\n\n1. Should we consider path-based prefix matching versus string-based prefix matching? For example, should the prefix `uri://a` match `uri://abc/def` or not? Assuming the prefix to be path prefix seems like the easiest to implement especially with templates in mix.\n\n2. For resource templates with embedded variables (e.g., `https://api.example.com/users/{id}/operations/{action}`), should we resolve partial parameters and try to match them against templates? This seems a little tricky to get right: While resolving template parameters makes sense from an improving discoverability perspective, it's unclear if returning something like: `https://api.example.com/users/123/operations/{action}` is in line with semantics that we want list_templates to offer.\n","author":{"url":"https://github.com/chughtapan","@type":"Person","name":"chughtapan"},"datePublished":"2025-07-31T07:11:37.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":3},"url":"https://github.com/1269/modelcontextprotocol/issues/1269"}