Skip to content

[v2] UriTemplate: {;...} path-style expressions are not recognized, and empty lists expand as if defined #3182

Open

Description

@trackoor

What happened?

UriTemplate has two RFC 6570 gaps that the open URI template issues and PRs (prefix modifiers, explode, multi-variable, encoding, match decoding) do not cover:

  1. getOperator() only recognizes +, #, ., /, ?, and &. In a path-style expression like {;lang,version}, the leading ; is kept as part of the first variable name (;lang), expand() drops the operator and any variable named lang, and match() captures the entire tail under ;lang.
  2. In expandPart(), an empty array [] is treated as a defined value instead of undefined, so {/segments}, {?tags}, and {.list} still emit their operator prefix (and name= for ?/&) when given [].

What did you expect?

Per RFC 6570 §3.2.7 (path-style parameter expansion) and §2.3 ("A variable defined as a list value is considered undefined if the list contains zero members"):

[ 'lang', 'version' ]
file:///docs;lang=en;version=2
{ lang: 'en', version: '2' }
""
"/search"
"X"

Code to reproduce

Run npm i @modelcontextprotocol/server@2.4.0 && node repro.mjs:

import { UriTemplate } from '@modelcontextprotocol/server';

// 1. Path-style `;` operator
const t = new UriTemplate('file:///docs{;lang,version}');
console.log(t.variableNames);
console.log(t.expand({ lang: 'en', version: '2' }));
console.log(t.match('file:///docs;lang=en;version=2'));

// 2. Empty list variables
console.log(JSON.stringify(new UriTemplate('{/segments}').expand({ segments: [] })));
console.log(JSON.stringify(new UriTemplate('/search{?tags}').expand({ tags: [] })));
console.log(JSON.stringify(new UriTemplate('X{.list}').expand({ list: [] })));

Actual output:

[ ';lang', 'version' ]
file:///docs2
{ ';lang': ';lang=en;version=2' }
"/"
"/search?tags="
"X."

SDK version

@modelcontextprotocol/server@2.4.0, @modelcontextprotocol/sdk@1.32.2, and main at 919bb8e (Node.js v26.13.0)

Area

Other

Credit: https://ucsbplse.github.io/

Activity

  1. shhhhhhjokerist commented on Nov 14, 2026

    @shhhhhhjokerist

    I'd like to work on this. I've traced the issue to packages/core-internal/src/shared/uriTemplate.ts (missing ; operator and empty-list expansion). Could you assign this issue to me? I'll open a PR with tests against RFC 6570 examples.

  2. added
    v1Issues / PRs related to v1.x
    v2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes
    on Nov 14, 2026
  3. media-ctrl commented on Nov 14, 2026

    @media-ctrl
  4. shhhhhhjokerist commented on Nov 15, 2026

    @shhhhhhjokerist

    Thanks @media-ctrl — the variable-name reading matches what I hit while implementing this: because getOperator did not accept ;, {;lang,version} was parsed as two names with ;lang, which is exactly the expand/match divergence you describe.

    I have #3183 open against main with a patch for that: ; is now an operator (;name=value, ;name when the value is empty, and exploded lists repeating the name as ;name=v;name=v), plus one shared isUndefinedValue predicate (undefined or a zero-member array) applied at both the expansion and the match sites so the two directions cannot disagree about empty lists.

    Tests are built from the RFC 6570 §3.2.7 example table ({;x,y}, {;x,y,empty}, {;x,y,undef}, {;list}, {;list*}, {;keys}, {;keys*}) plus the empty-array cases that used to expand to /, ?tags=, X. or X#.

    If the fixture set you mentioned has cases mine miss, I'm glad to fold them in — a comment on #3183 (or a PR that extends the test table) works. I'm not assigned to #3182 yet; if a maintainer assigns it to someone else first I'll defer to them.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    v1Issues / PRs related to v1.xv2Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions