feat(everything): add resource collection example

[olaservo]

This adds a resource collection example demonstrating the pattern where a single resources/read request returns multiple ResourceContents with different URIs. This is useful for modeling collections, indexes, or composite resources.

The example includes:

• A summer specials collection that returns all items
• Category-filtered collections for accessories, footwear, and skincare
• Individual item resources for direct access

Based on the gist provided by @olaservo:
https://gist.github.com/olaservo/585b1ad042723a824b6a0e0e02ae60a8

Fixes #3130

Generated with Claude Code) | Branch | [View job run](https://github.com/modelcontextprotocol/servers/actions/runs/20896646917

[olaservo]

Keeping this in draft for now since claude generated this based on my gist and it still needs to be tested.

[cliffhall]

Keeping this in draft for now since claude generated this based on my gist and it still needs to be tested.

Looking good so far. Great idea. I didn't know we could produce PRs with this thing. Maybe we should do more of this with some bug fixes.

[olaservo]

@claude can you please update the docs and Readme for this server so that they include information on this new example?

[claude]

Documentation updates completed

I've successfully updated the documentation for the everything server to include information about the new resource collection example.

Changes Made

• Updated src/everything/docs/features.md to document the resource collection pattern
• Updated src/everything/README.md to mention the resource collection example in the introduction
• Created commit with the documentation changes

Summary

I've updated both the README and the features documentation to describe the new resource collection example. The updates include:

In features.md:

• Added a new section under Resources explaining the collection pattern
• Documented all three collection resource types:
  • demo://collection/summer-specials - returns all items
  • demo://collection/by-category/{category} - filtered by category
  • demo://collection/item/{id} - individual item access

In README.md:

• Added a brief description of the resource collection pattern to the introduction
• Explains that it demonstrates how a single resources/read request can return multiple resources with different URIs

Note on Pushing

I've created the commit locally, but I encountered a permissions issue when trying to push to the remote branch. The GitHub Actions bot doesn't have push permissions to this repository. You'll need to manually push the commit or grant the necessary permissions.

The commit is ready and includes:

• Proper commit message describing the changes
• Co-authored-by attribution for both you and Claude

View job run | Branch

[cliffhall]

@olaservo Looks like you may need to merge Claude's changes. Ready to test locally whenever you feel this one's ready for review.

[cliffhall]

@claude review

[claude]

Claude finished @cliffhall's task in 2m 14s —— View job

---

Code Review

• Read changed files
• Review collections.ts for correctness, MCP compliance, and TypeScript quality
• Review index.ts integration
• Compare against existing resource patterns
• Post review feedback

---

Overall this is a clean, well-scoped addition that correctly demonstrates the MCP collection pattern. The core implementation works — a resources/read on demo://collection/summer-specials returns multiple ResourceContents with distinct URIs, and those URIs resolve to individually-registered resources. The integration in index.ts is minimal and correct.

A few things worth addressing before merging:

---

Issue 1: JSDoc uses template notation but static resources are registered

collections.ts:32 — The comment documents the by-category resource as demo://collection/by-category/{category}, which looks like a URI template (RFC 6570 / MCP template syntax). The actual implementation registers separate static URIs per category (e.g. demo://collection/by-category/accessories). A reader seeing {category} in the docs would expect a ResourceTemplate, not static resources.

Either update the comment to list the concrete URIs, or — better — adopt a ResourceTemplate (see Issue 2). Fix this →

---

Issue 2: By-category resources should use ResourceTemplate

collections.ts:60–80 — The category-filtered resources are registered as separate static entries by iterating over categories derived from the data:

const categories = [...new Set(collectionItems.map((i) => i.category))];
for (const category of categories) {
  server.registerResource(`Collection: ${category}`, `${collectionUriBase}/by-category/${category}`, ...);
}

The server already has a clear pattern for parameterized resources via ResourceTemplate (see templates.ts). Using a template here would be more idiomatic, more extensible (supports any future category without code changes), and would match the template notation already used in the JSDoc. Suggested shape:

server.registerResource(
  "Collection By Category",
  new ResourceTemplate(`${collectionUriBase}/by-category/{category}`, { list: undefined }),
  { mimeType: "application/json", description: "Items filtered by category." },
  async (_uri, { category }) => {
    const filtered = collectionItems.filter((i) => i.category === category);
    return { contents: filtered.map((item) => ({ uri: itemUri(item.id), mimeType: "application/json", text: JSON.stringify(item, null, 2) })) };
  }
);

Fix this →

---

Issue 3: async callbacks with no await

collections.ts:48,69,91 — All three resource handlers are declared async but contain no await. The SDK accepts synchronous callbacks too. This is a minor style point, but consistent with the rest of the codebase (e.g. templates.ts also uses async), so it's not blocking.

---

Positive notes

• Core pattern is correct: contents returns multiple ResourceContents objects each with distinct uri values. This is precisely what the MCP spec allows and the example is meant to demonstrate.
• URI coherence: The URIs returned inside the collection's contents (e.g. demo://collection/item/1) exactly match the individually-registered item resources. A client can list resources and then navigate from a collection directly to an item.
• index.ts integration is clean — one import, one call at the end of registerResources.
• Loop closures are correct: Both for (const category of categories) and for (const item of collectionItems) use const, so each iteration creates a new binding — no stale closure bug.
• No tests exist for any resource in this server, so the absence of tests here is consistent with the rest of the codebase.

---

Summary: Issue 1 (misleading JSDoc) is a quick fix. Issue 2 (ResourceTemplate) would make the code more idiomatic and is recommended before merge. Nothing here is a blocker if you're targeting a demo-only use case, but the template approach would better showcase MCP's expressive power.
| Branch