fix(resources)!: match RFC 6570 operators and prefer specific templates

[mcollina]

Problem

resources/read routes a concrete URI to a registered template (#245), but compileUriTemplate only handled level-1 {name} placeholders. Any template that used an operator ({+path}, {?q}, {/seg}, ...) compiled to null. It was still registered and listed in resources/templates/list, but reads always returned "Resource not found". Matching was also first-registered-wins, so x://{a}/{b} shadowed a later x://files/{name} for x://files/a.

Fix

Template compiling and matching now live in src/uri-template.ts.

Supported expressions

• {name}: unchanged. One non-empty segment without /, percent-decoded the same way as before (decodeURIComponent, falling back to the raw value).
• {+name}: a non-empty value that may contain / but not ? or #.
• {/a,b}: optional /value segments. Each segment is non-empty and contains no /.
• {?a,b}{&c}: optional query parameters, accepted in any order. These expressions must come last in the template. A query that has an undeclared or repeated parameter does not match, because it is not an expansion of the template. A template without query expressions keeps its old behaviour for URIs that contain ?.

Everything else throws at registration. That covers the #, ., ; and reserved operators, multi-variable {a,b} / {+a,b}, the * and :n modifiers, query expressions that are not at the end, and {&x} with no {?...} before it. The error message includes the template. I chose to reject these instead of matching them loosely or warning:

• a resource that is listed but can never be read is worse than a clear startup error;
• #, . and ; are rarely used in MCP resource URIs, and matching them correctly (fragment handling, ;name=value pairs, . suffix ambiguity) would add a lot of code for little benefit;
• multi-variable simple expressions and modifiers are ambiguous to invert. For example, {a,b} joins values with ,, which a value can also contain.

Specificity: when several templates match, the one with the most literal characters wins, and ties go to registration order. An exact uri registration still takes precedence over any template.

README: the resource-template section now documents the supported expressions, rejection at registration, the precedence rules, and a note that {+path} values are not sanitized.

Breaking change

Registering a template with an unsupported expression (for example x://doc{#section}, x://{a,b} or x://{list*}) now throws from mcpAddResource. Before, these registered without any error but could never be read.

Fixes #303

🤖 Generated with Claude Code

https://claude.ai/code/session_01UF4S3w7iA83V9DVsasLJzM