|
| 1 | +# SEP: Resource List Prefix Filter |
| 2 | + |
| 3 | +## Preamble |
| 4 | + |
| 5 | +**Title:** Resource List Prefix Filter |
| 6 | +**Status:** Proposal |
| 7 | +**Author:** Tapan Chugh (@chughtapan) |
| 8 | +**Type:** Standards Track |
| 9 | +**Created:** 2025-07-31 |
| 10 | + |
| 11 | +## Abstract |
| 12 | + |
| 13 | +This 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). |
| 14 | + |
| 15 | +## Motivation |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +## Specification |
| 20 | + |
| 21 | +### Schema Changes |
| 22 | + |
| 23 | +Update `ListResourcesRequest` and `ListResourceTemplatesRequest` interfaces to include an optional `prefix` parameter: |
| 24 | + |
| 25 | +```typescript |
| 26 | +export interface ListResourcesRequest extends PaginatedRequest { |
| 27 | + method: "resources/list"; |
| 28 | + params?: { |
| 29 | + /** |
| 30 | + * Optional URI prefix to filter resources. |
| 31 | + * Only resources whose URI starts with this prefix will be returned. |
| 32 | + */ |
| 33 | + prefix?: string; |
| 34 | + } & PaginatedRequest["params"]; |
| 35 | +} |
| 36 | + |
| 37 | +export interface ListResourceTemplatesRequest extends PaginatedRequest { |
| 38 | + method: "resources/templates/list"; |
| 39 | + params?: { |
| 40 | + /** |
| 41 | + * Optional URI prefix to filter resource templates. |
| 42 | + * Only templates whose URI template starts with this prefix will be returned. |
| 43 | + */ |
| 44 | + prefix?: string; |
| 45 | + } & PaginatedRequest["params"]; |
| 46 | +} |
| 47 | +``` |
| 48 | + |
| 49 | +### Behavior |
| 50 | + |
| 51 | +1. **Prefix matching**: The server returns only resources whose URI (or URI template) starts with the prefix |
| 52 | +2. **Pagination compatibility**: Prefix filtering works with pagination - the cursor represents position within the filtered results |
| 53 | + |
| 54 | +### Examples |
| 55 | + |
| 56 | +Request with prefix filter: |
| 57 | + |
| 58 | +```json |
| 59 | +{ |
| 60 | + "jsonrpc": "2.0", |
| 61 | + "id": 1, |
| 62 | + "method": "resources/list", |
| 63 | + "params": { |
| 64 | + "prefix": "file:///project/src/" |
| 65 | + } |
| 66 | +} |
| 67 | +``` |
| 68 | + |
| 69 | +Response: |
| 70 | + |
| 71 | +```json |
| 72 | +{ |
| 73 | + "jsonrpc": "2.0", |
| 74 | + "id": 1, |
| 75 | + "result": { |
| 76 | + "resources": [ |
| 77 | + { |
| 78 | + "uri": "file:///project/src/main.py", |
| 79 | + "name": "main.py" |
| 80 | + }, |
| 81 | + { |
| 82 | + "uri": "file:///project/src/config.json", |
| 83 | + "name": "config.json" |
| 84 | + } |
| 85 | + ] |
| 86 | + } |
| 87 | +} |
| 88 | +``` |
| 89 | + |
| 90 | +Combining with pagination: |
| 91 | + |
| 92 | +```json |
| 93 | +{ |
| 94 | + "jsonrpc": "2.0", |
| 95 | + "id": 2, |
| 96 | + "method": "resources/list", |
| 97 | + "params": { |
| 98 | + "prefix": "https://api.example.com/users/", |
| 99 | + "cursor": "cursor-123" |
| 100 | + } |
| 101 | +} |
| 102 | +``` |
| 103 | + |
| 104 | +Resource templates with prefix filter: |
| 105 | + |
| 106 | +```json |
| 107 | +{ |
| 108 | + "jsonrpc": "2.0", |
| 109 | + "id": 3, |
| 110 | + "method": "resources/templates/list", |
| 111 | + "params": { |
| 112 | + "prefix": "https://api.example.com/" |
| 113 | + } |
| 114 | +} |
| 115 | +``` |
| 116 | + |
| 117 | +Response: |
| 118 | + |
| 119 | +```json |
| 120 | +{ |
| 121 | + "jsonrpc": "2.0", |
| 122 | + "id": 3, |
| 123 | + "result": { |
| 124 | + "resourceTemplates": [ |
| 125 | + { |
| 126 | + "uriTemplate": "https://api.example.com/users/{id}", |
| 127 | + "name": "User Details" |
| 128 | + }, |
| 129 | + { |
| 130 | + "uriTemplate": "https://api.example.com/posts/{postId}", |
| 131 | + "name": "Blog Post" |
| 132 | + } |
| 133 | + ] |
| 134 | + } |
| 135 | +} |
| 136 | +``` |
| 137 | + |
| 138 | +## Rationale |
| 139 | + |
| 140 | +Resources are a powerful abstraction in MCP that limit 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. |
| 141 | + |
| 142 | +### Alternatives Considered |
| 143 | + |
| 144 | +1. **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. |
| 145 | + |
| 146 | +2. **Client-side filtering**: Implementation complexity with pagination; inefficient for large resource sets. |
| 147 | + |
| 148 | +3. **Separate method**: Adds unnecessary protocol complexity and duplicates logic. |
| 149 | + |
| 150 | +## Backward Compatibility |
| 151 | + |
| 152 | +While 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. |
| 153 | + |
| 154 | +## Reference Implementation |
| 155 | + |
| 156 | +TBD |
| 157 | + |
| 158 | +## Security Implications |
| 159 | + |
| 160 | +Prefix 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. |
| 161 | + |
| 162 | +## Open Questions |
| 163 | + |
| 164 | +1. 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. |
| 165 | + |
| 166 | +2. 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. |
0 commit comments