Reserved URI-template expansion throws for supplementary Unicode characters

Open Beginner friendly
#1,913 1 comment 0 reactions 1 assignee View on GitHub

Maintainers usually reply within 1 day

@tarekgh is already working on this.

Since Nov 18, 2026.

  • #1931 by @pournasserian — open

Assessment

Difficulty
2/5
Estimated time
1-3 hours
Newbie friendliness
74/100
Issue type
Bug
Clarity
Clearly specified
Activity status
Active
Tech stack
csharp
Domain
api

Research direction

Start with the reserved-expansion encoder in src/ModelContextProtocol.Core/UriTemplate.cs, around the Encode and AppendHex functions (about line 467-487), where the new Rune(char) call fails on surrogate pairs. Trace how ReadResourceAsync in McpClient.Methods.cs reaches FormatUri. Done when {+name} and {#name} with a supplementary character such as U+1F600 produce UTF-8 percent-encoded output and the read succeeds, with a regression test added to McpClientResourceTemplateTests.

Written by the indexing model from the issue text.

Description

P3

Description

McpClient.ReadResourceAsync(uriTemplate, arguments) throws ArgumentOutOfRangeException when a reserved ({+var}) or fragment ({#var}) URI-template expansion contains a supplementary Unicode character, such as an emoji. This prevents a client from reading resources whose template arguments include those characters, before a resources/read request is sent.

Reproduction

On main at 3338e88e15c42cfc27465143c140d7d10f1a2707, with a connected client and a resource handler that echoes the requested URI:

var result = await client.ReadResourceAsync(
    "test://resource/{+name}",
    new Dictionary<string, object?> { ["name"] = "hello\U0001F600" });

Expected: The request URI is test://resource/hello%F0%9F%98%80, with U+1F600 percent-encoded as UTF-8, and the resource can be read.

Actual: System.ArgumentOutOfRangeException: Specified argument was out of the range of valid values. (Parameter 'ch'). The focused regression test fails on net10.0 with this stack:

at System.Text.Rune..ctor(Char ch)
at ModelContextProtocol.UriTemplate.<Encode>g__AppendHex|6_0(...) in UriTemplate.cs:487
at ModelContextProtocol.UriTemplate.Encode(String value, Boolean allowReserved) in UriTemplate.cs:467
at ModelContextProtocol.UriTemplate.FormatUri(...) in UriTemplate.cs:392
at ModelContextProtocol.Client.McpClient.ReadResourceAsync(...) in McpClient.Methods.cs:596

I reproduced this by adding a [Fact] to McpClientResourceTemplateTests using its in-memory client/server fixture, then running:

dotnet test tests/ModelContextProtocol.Tests/ModelContextProtocol.Tests.csproj -f net10.0 --filter "FullyQualifiedName~ReservedExpansion_EncodesSupplementaryUnicodeScalar"

Result: 1 failed, 0 passed. The client/server connection completed; expansion failed before the read request.

Cause and possible fix

The reserved-expansion encoder loops over UTF-16 char values and calls new Rune(c) for each non-ASCII character. A supplementary Unicode scalar is a surrogate pair, so constructing a Rune from its first char throws. Decode the scalar from the input span (and advance past both UTF-16 code units) before writing its UTF-8 percent-encoded bytes. A regression test could cover {+name} and {#name} with supplementary Unicode characters.

Relevant code: UriTemplate.cs:487, McpClient.Methods.cs:596. RFC 6570 specifies UTF-8 percent encoding for characters outside the allowed URI set.

Dominant language
C#
Stars
4.6k
Forks
849
Avg merge
1d 16h
Merged PRs (30d)
24

Getting set up

Open in Codespaces

Starts the project's dev container in your browser, under your own GitHub account.

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

More from modelcontextprotocol/csharp-sdk

All issues in modelcontextprotocol/csharp-sdk

Similar issues

More C# issues

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.