Which URI Templates Work in MCP Resources

{
  "name": "mcp-template-check",
  "private": true,
  "type": "module",
  "dependencies": {
    "@modelcontextprotocol/sdk": "1.30.0"
  }
}

import { UriTemplate } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";

// Every pattern a server might register, with a known set of values.
// expand() builds the URI. match() is the direction the server needs to
// route an incoming resources/read back to your callback.
const patterns = [
  ["{id}",        "note://{id}",            { id: "glossary" }],
  ["{owner}/{name}", "repo://{owner}/{name}", { owner: "acme", name: "web" }],
  ["{+path}",     "file://{+path}",         { path: "a/b/c.txt" }],
  ["{.ext}",      "file://name{.ext}",      { ext: "json" }],
  ["{/seg}",      "api://v1{/seg}",         { seg: "users" }],
  ["{?q}",        "search://x{?q}",         { q: "mcp" }],
  ["{?a,b}",      "search://x{?a,b}",       { a: "1", b: "2" }],
  ["{&page}",     "search://x?q=1{&page}",  { page: "2" }],
  ["{#frag}",     "doc://x{#frag}",         { frag: "intro" }],
  ["{/segs*}",    "api://v1{/segs*}",       { segs: ["a", "b", "c"] }],
];

for (const [label, template, vars] of patterns) {
  const t = new UriTemplate(template);
  const uri = t.expand(vars);
  const back = t.match(uri);

  let verdict;
  if (back === null) {
    verdict = "BROKEN   template does not match its own output";
  } else {
    const roundTripped = Object.keys(vars).every(
      (k) => JSON.stringify(back[k]) === JSON.stringify(vars[k])
    );
    verdict = roundTripped ? "ok" : `LOSSY    got ${JSON.stringify(back)}`;
  }
  console.log(label.padEnd(16), uri.padEnd(22), verdict);
}

{id}             note://glossary        ok
{owner}/{name}   repo://acme/web        ok
{+path}          file://a/b/c.txt       ok
{.ext}           file://name.json       ok
{/seg}           api://v1/users         ok
{?q}             search://x?q=mcp       ok
{?a,b}           search://x?a=1&b=2     ok
{&page}          search://x?q=1&page=2  ok
{#frag}          doc://x#intro          LOSSY    got {"frag":"#intro"}
{/segs*}         api://v1/a/b/c         BROKEN   template does not match its own output

import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";

const server = new McpServer({ name: "template-probe", version: "1.0.0" });

// Register one resource per pattern. Each read callback just echoes the
// variables it was handed, so we can see exactly what the router parsed.
const echo = (name) => async (uri, vars) => ({
  contents: [
    { uri: uri.href, mimeType: "text/plain", text: `${name} -> ${JSON.stringify(vars)}` },
  ],
});

for (const [name, template] of [
  ["note", "note://{id}"],
  ["repo", "repo://{owner}/{name}"],
  ["tree", "api://v1{/segs*}"],
  ["doc", "doc://x{#frag}"],
]) {
  server.registerResource(
    name,
    new ResourceTemplate(template, { list: undefined }),
    { title: name, mimeType: "text/plain" },
    echo(name)
  );
}

const client = new Client({ name: "probe", version: "1.0.0" });
const [clientSide, serverSide] = InMemoryTransport.createLinkedPair();
await Promise.all([client.connect(clientSide), server.connect(serverSide)]);

const listed = await client.listResourceTemplates();
console.log("advertised by resources/templates/list:");
for (const t of listed.resourceTemplates) console.log("  ", t.uriTemplate);

console.log("\nresources/read:");
for (const uri of ["note://glossary", "repo://acme/web", "api://v1/a/b/c", "doc://x#intro"]) {
  try {
    const result = await client.readResource({ uri });
    console.log("  ok    ", uri.padEnd(18), result.contents[0].text);
  } catch (error) {
    console.log("  error ", uri.padEnd(18), error.message);
  }
}

await client.close();

advertised by resources/templates/list:
   note://{id}
   repo://{owner}/{name}
   api://v1{/segs*}
   doc://x{#frag}

resources/read:
  ok     note://glossary    note -> {"id":"glossary"}
  ok     repo://acme/web    repo -> {"owner":"acme","name":"web"}
  error  api://v1/a/b/c     MCP error -32602: MCP error -32602: Resource api://v1/a/b/c not found
  ok     doc://x#intro      doc -> {"frag":"#intro"}

server.registerResource(
  "tree",
  new ResourceTemplate("api://v1/{+segs}", { list: undefined }),
  { title: "tree", mimeType: "text/plain" },
  async (uri, vars) => {
    const segments = String(vars.segs).split("/");
    return {
      contents: [
        { uri: uri.href, mimeType: "text/plain", text: JSON.stringify(segments) },
      ],
    };
  }
);

ok   api://v1/a/b/c   ["a","b","c"]
ok   api://v1/a       ["a"]