|
| 1 | +/** |
| 2 | + * Resource collections (#3130): one `resources/read` that answers with several |
| 3 | + * contents, each under a URI of its own. The spec allows a read to return more |
| 4 | + * than one content ("a server could return the contents of several files when |
| 5 | + * a directory resource is read"), and this module shows the pattern with a |
| 6 | + * small, fixed product catalog: |
| 7 | + * |
| 8 | + * - `demo://resource/collection/summer-specials` (static, listed): every item. |
| 9 | + * - `demo://resource/collection/by-category/{category}` (template, with a |
| 10 | + * completer for `category`): the items in one category. |
| 11 | + * - `demo://resource/collection/item/{itemId}` (template, with a completer for |
| 12 | + * `itemId`): one item. |
| 13 | + * |
| 14 | + * Every content a collection returns carries its item's URI, not the |
| 15 | + * collection's, and that URI is readable on its own through the item |
| 16 | + * template, so a client can follow up on any one member. The catalog is a |
| 17 | + * constant, so the module keeps no state and serves both protocol eras alike. |
| 18 | + * Adapted from the example in olaservo's gist linked on the issue. |
| 19 | + */ |
| 20 | +import { |
| 21 | + CompleteResourceTemplateCallback, |
| 22 | + McpServer, |
| 23 | + ResourceNotFoundError, |
| 24 | + ResourceTemplate, |
| 25 | +} from "@modelcontextprotocol/server"; |
| 26 | + |
| 27 | +/** One product in the example catalog. */ |
| 28 | +export type CollectionItem = { |
| 29 | + id: number; |
| 30 | + name: string; |
| 31 | + price: number; |
| 32 | + category: string; |
| 33 | +}; |
| 34 | + |
| 35 | +/** The example catalog the collections are drawn from. */ |
| 36 | +export const COLLECTION_ITEMS: readonly CollectionItem[] = [ |
| 37 | + { id: 1, name: "Summer Hat", price: 29.99, category: "accessories" }, |
| 38 | + { id: 2, name: "Beach Towel", price: 19.99, category: "accessories" }, |
| 39 | + { id: 3, name: "Sunglasses", price: 49.99, category: "accessories" }, |
| 40 | + { id: 4, name: "Flip Flops", price: 14.99, category: "footwear" }, |
| 41 | + { id: 5, name: "Sunscreen SPF50", price: 12.99, category: "skincare" }, |
| 42 | +]; |
| 43 | + |
| 44 | +/** The distinct categories in the catalog, in first-seen order. */ |
| 45 | +export const COLLECTION_CATEGORIES: readonly string[] = [ |
| 46 | + ...new Set(COLLECTION_ITEMS.map((item) => item.category)), |
| 47 | +]; |
| 48 | + |
| 49 | +const MIME_TYPE = "application/json"; |
| 50 | +const collectionUriBase = "demo://resource/collection"; |
| 51 | +const itemUriBase = `${collectionUriBase}/item`; |
| 52 | +const categoryUriBase = `${collectionUriBase}/by-category`; |
| 53 | + |
| 54 | +/** The URI of the collection holding every item. */ |
| 55 | +export const SUMMER_SPECIALS_URI = `${collectionUriBase}/summer-specials`; |
| 56 | + |
| 57 | +/** |
| 58 | + * The URI under which one item can be read on its own. |
| 59 | + * @param id |
| 60 | + */ |
| 61 | +export const collectionItemUri = (id: number) => `${itemUriBase}/${id}`; |
| 62 | + |
| 63 | +/** |
| 64 | + * The contents of one item: JSON, under the item's own URI. |
| 65 | + * @param item |
| 66 | + */ |
| 67 | +const itemContents = (item: CollectionItem) => ({ |
| 68 | + uri: collectionItemUri(item.id), |
| 69 | + mimeType: MIME_TYPE, |
| 70 | + text: JSON.stringify(item, null, 2), |
| 71 | +}); |
| 72 | + |
| 73 | +/** Completes a category name from its prefix. */ |
| 74 | +const categoryCompleter: CompleteResourceTemplateCallback = (value) => |
| 75 | + COLLECTION_CATEGORIES.filter((category) => category.startsWith(value)); |
| 76 | + |
| 77 | +/** Completes an item id from its prefix. */ |
| 78 | +const itemIdCompleter: CompleteResourceTemplateCallback = (value) => |
| 79 | + COLLECTION_ITEMS.map((item) => String(item.id)).filter((id) => |
| 80 | + id.startsWith(value), |
| 81 | + ); |
| 82 | + |
| 83 | +/** |
| 84 | + * Register the collection resources with the MCP server. |
| 85 | + * - `summer-specials`: a static resource whose read returns every item |
| 86 | + * - `collection-by-category`: a template whose read returns one category's items |
| 87 | + * - `collection-item`: a template whose read returns one item |
| 88 | + * - A category or item id that is not in the catalog is not found (`-32602`) |
| 89 | + * |
| 90 | + * @param server |
| 91 | + */ |
| 92 | +export const registerCollectionResources = (server: McpServer) => { |
| 93 | + // The whole collection: one read, one content per item, each with its own URI |
| 94 | + server.registerResource( |
| 95 | + "summer-specials", |
| 96 | + SUMMER_SPECIALS_URI, |
| 97 | + { |
| 98 | + title: "Summer Specials Collection", |
| 99 | + mimeType: MIME_TYPE, |
| 100 | + description: |
| 101 | + "A resource collection: one read returns every item in the catalog as a separate content, each under its own demo://resource/collection/item/{itemId} URI.", |
| 102 | + }, |
| 103 | + async () => ({ contents: COLLECTION_ITEMS.map(itemContents) }), |
| 104 | + ); |
| 105 | + |
| 106 | + // A filtered collection: the items in one category |
| 107 | + server.registerResource( |
| 108 | + "collection-by-category", |
| 109 | + new ResourceTemplate(`${categoryUriBase}/{category}`, { |
| 110 | + list: undefined, |
| 111 | + complete: { category: categoryCompleter }, |
| 112 | + }), |
| 113 | + { |
| 114 | + title: "Collection by Category", |
| 115 | + mimeType: MIME_TYPE, |
| 116 | + description: `A resource collection filtered by the {category} variable (${COLLECTION_CATEGORIES.join(", ")}): one read returns each item in that category as a separate content, under its own URI.`, |
| 117 | + }, |
| 118 | + async (uri, variables) => { |
| 119 | + const category = String(variables.category); |
| 120 | + const items = COLLECTION_ITEMS.filter( |
| 121 | + (item) => item.category === category, |
| 122 | + ); |
| 123 | + if (items.length === 0) throw new ResourceNotFoundError(uri.toString()); |
| 124 | + return { contents: items.map(itemContents) }; |
| 125 | + }, |
| 126 | + ); |
| 127 | + |
| 128 | + // One member of the collections, readable on its own |
| 129 | + server.registerResource( |
| 130 | + "collection-item", |
| 131 | + new ResourceTemplate(`${itemUriBase}/{itemId}`, { |
| 132 | + list: undefined, |
| 133 | + complete: { itemId: itemIdCompleter }, |
| 134 | + }), |
| 135 | + { |
| 136 | + title: "Collection Item", |
| 137 | + mimeType: MIME_TYPE, |
| 138 | + description: |
| 139 | + "One item of the resource collections, selected by the {itemId} variable (1 to 5). The collections return their items under these URIs.", |
| 140 | + }, |
| 141 | + async (uri, variables) => { |
| 142 | + // Match the id's exact spelling, so "01" is not found rather than item 1 |
| 143 | + const itemId = String(variables.itemId); |
| 144 | + const item = COLLECTION_ITEMS.find( |
| 145 | + (candidate) => String(candidate.id) === itemId, |
| 146 | + ); |
| 147 | + if (!item) throw new ResourceNotFoundError(uri.toString()); |
| 148 | + return { contents: [itemContents(item)] }; |
| 149 | + }, |
| 150 | + ); |
| 151 | +}; |
0 commit comments