fix(core-internal): support RFC 6570 prefix modifiers in UriTemplate (#3000) by MokuLakshithReddy · Pull Request #3003 · modelcontextprotocol/typescript-sdk

MokuLakshithReddy · 2026-10-11T19:31:03Z

Motivation and Context

The SDK's UriTemplate previously treated an RFC 6570 prefix modifier (:N) as part of the variable name because getNames() stripped * but retained :N. As a result:

template.variableNames returned ["name:3"] instead of ["name"].
template.expand({ name: "abcdef" }) looked for variables["name:3"] and dropped scalar values from the expanded URI.
template.match() looked for an argument named "name:3".

Description of Changes

VarSpec parsing: Introduced parseVarSpec() in UriTemplate to separate the variable name, explode modifier (*), and prefix modifier (:N).
Clean variable names: names and variableNames now preserve the clean variable name (["name"]).
Scalar prefix truncation: Added applyPrefix() to truncate scalar values to the specified prefix length using code point spreading ([...value].slice(0, prefix).join('')), ensuring correct handling of multi-byte and supplementary Unicode characters before percent-encoding.
RFC 6570 compliance: Prefix modifiers are applied across all template operators, and per RFC 6570 §2.4.1, composite values (arrays) ignore prefix modifiers.
Regex matching: Updated partToRegExp to use clean variable names when generating matching regexes.
Unit tests: Added 17 unit tests in packages/core-internal/test/shared/uriTemplate.test.ts covering ASCII, non-ASCII Unicode, supplementary characters, prefixes longer than values, missing variables, array values, and .match().
Changeset: Added .changeset/uri-template-prefix-modifiers.md.

How Has This Been Tested?

Added unit tests in packages/core-internal/test/shared/uriTemplate.test.ts covering all prefix modifier behaviors; all 55 tests pass.
Verified type check and ESLint cleanly.

…odelcontextprotocol#3000)

changeset-bot · 2026-10-11T19:31:07Z

🦋 Changeset detected

Latest commit: 7f1ca4c

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
@modelcontextprotocol/core-internal	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

Copilot

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.

pkg-pr-new · 2026-10-11T19:32:08Z

Open in StackBlitz

@modelcontextprotocol/client

npm i https://pkg.pr.new/@modelcontextprotocol/client@3003

@modelcontextprotocol/codemod

npm i https://pkg.pr.new/@modelcontextprotocol/codemod@3003

@modelcontextprotocol/core

npm i https://pkg.pr.new/@modelcontextprotocol/core@3003

@modelcontextprotocol/server

npm i https://pkg.pr.new/@modelcontextprotocol/server@3003

@modelcontextprotocol/server-legacy

npm i https://pkg.pr.new/@modelcontextprotocol/server-legacy@3003

@modelcontextprotocol/express

npm i https://pkg.pr.new/@modelcontextprotocol/express@3003

@modelcontextprotocol/fastify

npm i https://pkg.pr.new/@modelcontextprotocol/fastify@3003

@modelcontextprotocol/hono

npm i https://pkg.pr.new/@modelcontextprotocol/hono@3003

@modelcontextprotocol/node

npm i https://pkg.pr.new/@modelcontextprotocol/node@3003

commit: 7f1ca4c

koriyoshi2041

The valid Unicode path looks good, but malformed prefix specs are now silently reinterpreted as valid variable names. RFC 6570 defines max-length as [1-9][0-9]{0,3} and makes prefix/explode mutually exclusive. At this head I get:

{name:0}     -> abcdef
{name:10000} -> abcdef
{name:abc}   -> abcdef
{name:3*}    -> abc

All four also report variableNames === ['name']. Before this change they did not resolve name, so this broadens invalid templates into successful expansions. Could parseVarSpec accept only :[1-9][0-9]{0,3} and reject (or preserve the old unresolved behavior for) malformed/combined modifiers? Focused regression cases for :0, five digits, non-digits, and :N* would pin the boundary.

…utual exclusivity

MokuLakshithReddy · 2026-10-13T06:26:53Z

@koriyoshi2041 Thank you for the detailed review! I have updated the implementation to address this:

Strict max-length validation: parseVarSpec now validates that the prefix length matches ^[1-9]\d{0,3}$ (:[1-9][0-9]{0,3}), enforcing non-zero integers under 10000 per RFC 6570 §2.4.1.
Mutual exclusivity: Enforced mutual exclusivity between prefix and explode modifiers; combined specs like :N* are not treated as valid prefix modifiers.
Preserved unresolved behavior: Malformed or combined modifiers now preserve the previous behavior — the literal unparsed text is retained (e.g. name:0, name:10000, name:abc, name:3), so variableNames does not resolve to ['name'] and scalar values are not expanded.
Regression tests: Added focused unit tests in uriTemplate.test.ts for :0, five digits (:10000), non-digits (:abc), combined (:3*), and valid upper boundary (:9999).

koriyoshi2041 · 2026-10-13T09:39:39Z

Confirmed on 2e8e0c95: the parser now accepts only :[1-9][0-9]{0,3}, keeps prefix/explode mutually exclusive, and the four malformed cases remain unresolved rather than expanding name. The added :9999 case pins the valid upper boundary. All hosted checks are green; my finding is resolved.

notlakshitha · 2026-10-14T04:07:11Z

+                .filter(v => v !== undefined);
            if (values.length === 0) return '';
-            return values.map(v => (Array.isArray(v) ? v[0] : v)).join(',');
+            return values.join(',');


Since this branch is being reworked anyway: it never goes through encodeValue and ignores the operator, so the prefix gets applied but the result goes out raw. {x,y:2} with y: 'é ü' expands to é unencoded, while {y:2} on its own gives %C3%A9%20. {/x,y} also comes out as 1024,768 instead of /1024/768. Might be out of scope here, but should multi-var expressions go through the same encode/join switch as the single-var path below?

Great catch! I have unified the multi-variable and single-variable expansion paths so all values pass through encodeValue(..., part.operator) and join according to the operator separator (e.g. / for path, . for label, , for simple/fragment/reserved). Added unit tests for multi-var encoding ({x,y:2}) and operator separators ({/x,y}, {.x,y}, {#x,y}).

notlakshitha · 2026-10-14T04:07:29Z

-        names: string[];
-        exploded: boolean;
-    }): Array<{ pattern: string; name: string }> {
+    private partToRegExp(part: TemplateExpressionPart): Array<{ pattern: string; name: string }> {


match() doesn't use the prefix at all, so /users/{id:3} matches /users/abcdef and returns id: 'abcdef', a URI this template could never expand to. Is that intended (prefix only affects expansion), or should the pattern be bounded for prefix vars? Either way a test pinning the behavior might help, since resource templates use match() to route reads.

Prefix modifiers in RFC 6570 define variable expansion truncation. Matching in this SDK extracts the segment value without lossy truncation. I have added an explicit regression test to pin this contract (/users/{id:3} extracts { id: "abc" } and { id: "abcdef" }).

…or separators

fix(core-internal): support RFC 6570 prefix modifiers in UriTemplate (m…

f30efc5

…odelcontextprotocol#3000)

Copilot AI balanced review requested due to automatic review settings October 11, 2026 19:31

MokuLakshithReddy requested a review from a team as a code owner October 11, 2026 19:31

Copilot AI reviewed Oct 11, 2026

claude Bot added the v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes label Oct 12, 2026

koriyoshi2041 reviewed Oct 13, 2026

View reviewed changes

fix(core-internal): enforce RFC 6570 prefix max-length and modifier m…

2e8e0c9

…utual exclusivity

notlakshitha reviewed Oct 14, 2026

View reviewed changes

fix(core-internal): encode multi-variable values and join with operat…

7f1ca4c

…or separators

Navigation Menu

Repository navigation

fix(core-internal): support RFC 6570 prefix modifiers in UriTemplate (#3000) - #3003

fix(core-internal): support RFC 6570 prefix modifiers in UriTemplate (#3000)#3003
MokuLakshithReddy wants to merge 3 commits into
modelcontextprotocol:mainfrom
MokuLakshithReddy:fix/uri-template-prefix-modifiers

MokuLakshithReddy commented Oct 11, 2026

Uh oh!

changeset-bot Bot commented Oct 11, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

pkg-pr-new Bot commented Oct 11, 2026 •

edited

Loading

Uh oh!

koriyoshi2041 left a comment

Uh oh!

MokuLakshithReddy commented Oct 13, 2026

Uh oh!

koriyoshi2041 commented Oct 13, 2026

Uh oh!

notlakshitha Oct 14, 2026

Uh oh!

MokuLakshithReddy Oct 14, 2026

Uh oh!

notlakshitha Oct 14, 2026

Uh oh!

MokuLakshithReddy Oct 14, 2026

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

Conversation

MokuLakshithReddy commented Oct 11, 2026

Motivation and Context

Description of Changes

How Has This Been Tested?

Uh oh!

changeset-bot Bot commented Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Uh oh!

pkg-pr-new Bot commented Oct 11, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

koriyoshi2041 left a comment

Choose a reason for hiding this comment

Uh oh!

MokuLakshithReddy commented Oct 13, 2026

Uh oh!

koriyoshi2041 commented Oct 13, 2026

Uh oh!

notlakshitha Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

MokuLakshithReddy Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

notlakshitha Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

MokuLakshithReddy Oct 14, 2026

Choose a reason for hiding this comment

Uh oh!

This branch has not been deployed

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

changeset-bot Bot commented Oct 11, 2026 •

edited

Loading

pkg-pr-new Bot commented Oct 11, 2026 •

edited

Loading