Skip to content

fix(uri-template): align value encoding with RFC 6570 section 3.2.1 - #3215

Open
rockcli wants to merge 1 commit into
modelcontextprotocol:mainfrom
rockcli:fix/uri-template-rfc6570-encoding
Open

rockcli wants to merge 1 commit into
modelcontextprotocol:mainfrom
rockcli:fix/uri-template-rfc6570-encoding

Conversation

@rockcli

@rockcli rockcli commented Nov 20, 2026

Copy link
Copy Markdown

Fixes #2919
Fixes #2920

Symptom & Repro

UriTemplate.encodeValue() diverged from RFC 6570 section 3.2.1 in two ways:

  1. Strict variable expansions ({var}, {?q}, {&q}, {.var}, {/var}) called encodeURIComponent(value) directly, leaving sub-delimiters !'()* unencoded (e.g. search{?q} with hello! produced search?q=hello! instead of search?q=hello%21).
  2. Reserved (+) and fragment (#) expansions called encodeURI(value) directly, double-encoding valid existing %HH pct-encoded triplets (e.g. file:///docs/{+path} with My%20File.txt became file:///docs/My%2520File.txt).

Root Cause

JavaScript's encodeURIComponent() follows HTML/ECMA-262 rules rather than RFC 3986 unreserved characters (!'()* remain raw), while encodeURI() always escapes % as %25 even when followed by two hexadecimal digits forming a valid pct-encoded triplet.

Fix

  • Updated UriTemplate.encodeValue() in packages/core-internal/src/shared/uriTemplate.ts:
    • For + and #, unescape %25([0-9A-Fa-f]{2}) back to %$1 after encodeURI(value), preserving existing %HH triplets while still percent-encoding lone or malformed % sequences (100%, %2G, %2, %%20).
    • For strict operators, percent-encode [!'()*] after encodeURIComponent(value).
  • Added unit tests in packages/core-internal/test/shared/uriTemplate.test.ts and a patch changeset in .changeset/uri-template-rfc6570-encoding.md.

Verification

  • Pre-fix TDD: all 3 new RFC 6570 test blocks failed on origin/main (5ee54ee).
  • Post-fix:
    • pnpm --filter @modelcontextprotocol/core-internal check (tsgo, eslint, prettier): passed
    • pnpm --filter @modelcontextprotocol/core-internal test: 79 files, 1864 tests passed
    • pnpm --filter @modelcontextprotocol/server test: 57 files, 725 tests passed

@rockcli
rockcli requested a review from a team as a code owner November 20, 2026 03:48
@changeset-bot

changeset-bot Bot commented Nov 20, 2026

Copy link
Copy Markdown

🦋 Changeset detected

Latest commit: 83547e8

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

This PR includes changesets to release 6 packages
Name Type
@modelcontextprotocol/core-internal Patch
@modelcontextprotocol/server Patch
@modelcontextprotocol/client Patch
@modelcontextprotocol/codemod Patch
@modelcontextprotocol/core Patch
@modelcontextprotocol/server-legacy 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

@pkg-pr-new

pkg-pr-new Bot commented Nov 20, 2026

Copy link
Copy Markdown

Open in StackBlitz

@modelcontextprotocol/client

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

@modelcontextprotocol/codemod

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

@modelcontextprotocol/core

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

@modelcontextprotocol/server

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

@modelcontextprotocol/server-legacy

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

@modelcontextprotocol/express

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

@modelcontextprotocol/fastify

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

@modelcontextprotocol/hono

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

@modelcontextprotocol/node

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

commit: 83547e8

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

This branch has not been deployed

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

Labels

v2 Ideas, requests and plans for v2 of the SDK which will incorporate major changes and fixes

Projects

None yet

Development

Successfully merging this pull request may close these issues.

[v2] URI template reserved expansions encode existing %HH sequences again [v2] URI template strict expansions leave !'()* unencoded

1 participant