Unordered and partial query parameter matching

[disintegrator]

Describe the bug

MCP server does not match resource requests that do no have all query parameters specified in the order they were declared in the ResourceTemplate / UriTemplate. Instead, clients receive a not found error (MCP error -32602).

To Reproduce

Run the following reproducer (e.g. npx tsx repro.ts):

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

const server = new McpServer({
  name: "test-server",
  version: "0.0.0",
});

server.resource(
  "example",
  new ResourceTemplate("acme://products{?page,limit}", { list: undefined }),
  async (uri, vars): Promise<ReadResourceResult> => {
    const page = vars.page ?? "1"
    const limit = vars.limit ?? "20"
    return {
      contents: [
        {
          text: `Listing ${vars.limit} products on page ${vars.page}`,
          mimeType: "text/plain",
          uri: "uri",
        },
      ],
    };
  }
);

const client = new Client({
  name: "test-client",
  version: "1.0.0",
});

const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
await Promise.all([
  server.connect(serverTransport),
  client.connect(clientTransport),
]);

const result = await client.readResource({
  uri: "acme://products",
});

console.log(result.contents.map((c) => c.text).join("\n"));

Expected behavior

The script above should print Listing 20 products on page 1 but instead it errors with:

McpError: MCP error -32602: MCP error -32602: Resource acme://products not found

Additional context

I think the current handling of query parameters makes resource templates a little too rigid. My current workaround is to convert certain dynamic resources to tools but I'm not sure that's a good long term solution. I propose changing the behavior of UriTemplate such that the following test cases pass:

import { UriTemplate } from "@modelcontextprotocol/sdk/shared/uriTemplate.js";
import { expect, test } from "vitest";

test("UriTemplate::match treats query parameters as optional", () => {
  const template = new UriTemplate("acme://products{?page,limit}");
  expect(template.match("acme://products")).toEqual({});
  expect(template.match("acme://products?page=2")).toEqual({ page: "2" });
});

test("UriTemplate::match accepts query parameters in arbitrary order", () => {
  const template = new UriTemplate("acme://products{?page,limit,q*}");
  expect(template.match("acme://products?q=cat,dog&limit=40&page=5")).toEqual({
    page: "5",
    limit: "40",
    q: ["cat", "dog"],
  });
});

// npx vitest uritemplate.test.ts

[EDjur]

Curious if there's any updates on this issue? Partial query matching makes a ton of sense

[bhosmer-ant]

See also #1079

[mgyarmathy]

@felixweinberger PR #1083 should resolve this one too

[mcp-claude]

bug confirmed on both main and v1.x. UriTemplate.match() generates a strict sequential regex for {?...} query parameters, so omitting any param or providing them out of order returns null instead of a partial match.

root cause: partToRegExp() emits \?page=([^&]+)&limit=([^&]+) — a fixed-order, all-required pattern. query params per RFC 6570 are optional and unordered.

workaround: register separate resource templates for each query-param combination, or convert to a tool.

repro + output + code path

repro (run from repo root: npx tsx repro.ts):

import { UriTemplate } from "./packages/core/src/shared/uriTemplate.js";

const t1 = new UriTemplate("acme://products{?page,limit}");
console.log("omit all:  ", t1.match("acme://products"));             // expected {}
console.log("one param: ", t1.match("acme://products?page=2"));      // expected { page: '2' }
console.log("all params:", t1.match("acme://products?page=2&limit=10")); // expected { page: '2', limit: '10' }
console.log("reversed:  ", t1.match("acme://products?limit=10&page=2")); // expected { page: '2', limit: '10' }

output:

omit all:   null   ← should be {}
one param:  null   ← should be { page: '2' }
all params: { page: '2', limit: '10' }   ← only case that works
reversed:   null   ← should be { page: '2', limit: '10' }

code path:

packages/core/src/shared/uriTemplate.ts lines 213-222 — partToRegExp for ?/& operators:

for (let i = 0; i < part.names.length; i++) {
    const name = part.names[i]!;
    const prefix = i === 0 ? '\\' + part.operator : '&';
    patterns.push({
        pattern: prefix + this.escapeRegExp(name) + '=([^&]+)',
        name
    });
}

For {?page,limit} this produces two required patterns: \?page=([^&]+) then &limit=([^&]+), concatenated into ^acme://products\?page=([^&]+)&limit=([^&]+)$. Each param is required and must appear in declaration order.

branch status: present on both main (b8886e7) and v1.x (bf1e022).

suggested fix

// packages/core/src/shared/uriTemplate.ts
     let pattern = '^';
     const names: Array<{ name: string; exploded: boolean }> = [];
+    const queryParts: Array<{ names: string[]; exploded: boolean }> = [];

     for (const part of this.parts) {
         if (typeof part === 'string') {
             pattern += this.escapeRegExp(part);
+        } else if (part.operator === '?' || part.operator === '&') {
+            queryParts.push({ names: part.names, exploded: part.exploded });
         } else {
             const patterns = this.partToRegExp(part);
             for (const { pattern: partPattern, name } of patterns) {
@@ ... @@
+    // Capture the entire query string as one group; individual params are
+    // extracted below so they are optional and order-independent.
+    let queryGroupIndex = -1;
+    if (queryParts.length > 0) {
+        queryGroupIndex = names.length;
+        pattern += '(?:\\?([^#]*))?';
+    }
+
     pattern += '$';
     // ... regex match ...
     const result: Variables = {};
     for (const [i, name_] of names.entries()) { /* unchanged */ }

+    if (queryGroupIndex >= 0) {
+        const queryString = match[queryGroupIndex + 1];
+        if (queryString) {
+            for (const qpart of queryParts) {
+                for (const name of qpart.names) {
+                    const escaped = this.escapeRegExp(name);
+                    const paramMatch = queryString.match(new RegExp(`(?:^|&)${escaped}=([^&]*)`));
+                    if (paramMatch) {
+                        const value = paramMatch[1]!;
+                        const cleanName = name.replace('*', '');
+                        result[cleanName] = qpart.exploded && value.includes(',') ? value.split(',') : value;
+                    }
+                }
+            }
+        }
+    }
     return result;

instead of embedding per-param capture groups in the main regex (where JS can't capture inside optional lookaheads), the fix captures the whole query string as one group then extracts each param with a separate (?:^|&)name=([^&]*) match — making every param optional and order-independent. all 490 existing tests pass.

test to verify: assert that new UriTemplate('acme://products{?page,limit}').match('acme://products?limit=10&page=2') returns { page: '2', limit: '10' } (reversed order) and .match('acme://products') returns {} (all params absent).