fix: preserve pct-triplets in reserved expansion; allow empty match captures

Two RFC-conformance fixes:

Reserved expansion ({+var}, {#var}) now passes through existing %XX
pct-triplets unchanged per RFC 6570 section 3.2.3, while still
encoding bare %. Previously quote() double-encoded path%2Fto into
path%252Fto. Simple expansion is unchanged (still encodes %
unconditionally).

Match patterns now use * instead of + quantifiers so defined-but-empty
values round-trip. RFC says empty variables still emit the operator
prefix: {#section} with section='' expands to '#', but the previous
.+ pattern could not match the empty capture after it. All eight
operators now consistently accept empty values.

The quantifier change affects adjacent-unrestricted-var resolution:
{a}{b} matching 'xy' now gives {a: 'xy', b: ''} (greedy first-wins)
instead of the previous {a: 'x', b: 'y'} (artifact of + backtracking).
Adjacent vars without a separating literal are inherently ambiguous
either way; a literal between them ({a}-{b}) still disambiguates.

Author: maxisbey

src/mcp/shared/uri_template.py

@@ -86,11 +86,11 @@ class _OperatorSpec:
 # the characters that can appear in an expanded value for that operator,
 # stopping at the next structural delimiter.
 _MATCH_PATTERN: dict[Operator, str] = {
-    "": r"[^/?#&,]+",  # simple: everything structural is pct-encoded
-    "+": r"[^?#]+",  # reserved: / allowed, stop at query/fragment
-    "#": r".+",  # fragment: tail of URI
-    ".": r"[^./?#]+",  # label: stop at next .
-    "/": r"[^/?#]+",  # path segment: stop at next /
+    "": r"[^/?#&,]*",  # simple: everything structural is pct-encoded
+    "+": r"[^?#]*",  # reserved: / allowed, stop at query/fragment
+    "#": r".*",  # fragment: tail of URI
+    ".": r"[^./?#]*",  # label: stop at next .
+    "/": r"[^/?#]*",  # path segment: stop at next /
     ";": r"[^;/?#]*",  # path-param value (may be empty: ;name)
     "?": r"[^&#]*",  # query value (may be empty: ?name=)
     "&": r"[^&#]*",  # query-cont value
@@ -140,15 +140,32 @@ def _is_str_sequence(value: object) -> bool:
     return all(isinstance(item, str) for item in seq)
 
 
+_PCT_TRIPLET_RE = re.compile(r"%[0-9A-Fa-f]{2}")
+
+
 def _encode(value: str, *, allow_reserved: bool) -> str:
     """Percent-encode a value per RFC 6570 §3.2.1.
 
     Simple expansion encodes everything except unreserved characters.
-    Reserved expansion ({+var}, {#var}) additionally keeps RFC 3986
-    reserved characters intact.
+    Reserved expansion (``{+var}``, ``{#var}``) additionally keeps
+    RFC 3986 reserved characters intact and passes through existing
+    ``%XX`` pct-triplets unchanged (RFC 6570 §3.2.3). A bare ``%`` not
+    followed by two hex digits is still encoded to ``%25``.
     """
-    safe = _RESERVED if allow_reserved else ""
-    return quote(value, safe=safe)
+    if not allow_reserved:
+        return quote(value, safe="")
+
+    # Reserved expansion: walk the string, pass through triplets as-is,
+    # quote the gaps between them. A bare % with no triplet lands in a
+    # gap and gets encoded normally.
+    out: list[str] = []
+    last = 0
+    for m in _PCT_TRIPLET_RE.finditer(value):
+        out.append(quote(value[last : m.start()], safe=_RESERVED))
+        out.append(m.group())
+        last = m.end()
+    out.append(quote(value[last:], safe=_RESERVED))
+    return "".join(out)
 
 
 def _expand_expression(expr: _Expression, variables: Mapping[str, str | Sequence[str]]) -> str:

tests/shared/test_uri_template.py

@@ -277,6 +277,16 @@ def test_frozen():
         # Level 2: reserved expansion keeps / ? # etc.
         ("{+var}", {"var": "a/b/c"}, "a/b/c"),
         ("{+var}", {"var": "a?b#c"}, "a?b#c"),
+        # RFC §3.2.3: reserved expansion passes through existing
+        # pct-triplets unchanged; bare % is still encoded.
+        ("{+var}", {"var": "path%2Fto"}, "path%2Fto"),
+        ("{+var}", {"var": "50%"}, "50%25"),
+        ("{+var}", {"var": "50%2"}, "50%252"),
+        ("{+var}", {"var": "a%2Fb%20c"}, "a%2Fb%20c"),
+        ("{#var}", {"var": "a%2Fb"}, "#a%2Fb"),
+        # Simple expansion still encodes % unconditionally (triplet
+        # preservation is reserved-only).
+        ("{var}", {"var": "path%2Fto"}, "path%252Fto"),
         ("file://docs/{+path}", {"path": "src/main.py"}, "file://docs/src/main.py"),
         # Level 2: fragment
         ("{#var}", {"var": "section"}, "#section"),
@@ -422,12 +432,17 @@ def test_match_no_match(template: str, uri: str):
 def test_match_adjacent_vars_with_prefix_names():
     # Two adjacent simple vars where one name is a prefix of the other.
     # We use positional capture groups, so names only affect the result
-    # dict keys, not the regex. Standard greedy matching: the first var
-    # takes as much as it can while still letting the second satisfy +.
+    # dict keys, not the regex. Adjacent unrestricted vars are inherently
+    # ambiguous; greedy * resolution means the first takes everything.
     t = UriTemplate.parse("{var}{vara}")
-    assert t.match("ab") == {"var": "a", "vara": "b"}
-    assert t.match("abc") == {"var": "ab", "vara": "c"}
-    assert t.match("abcd") == {"var": "abc", "vara": "d"}
+    assert t.match("ab") == {"var": "ab", "vara": ""}
+    assert t.match("abcd") == {"var": "abcd", "vara": ""}
+
+
+def test_match_adjacent_vars_disambiguated_by_literal():
+    # A literal between vars resolves the ambiguity.
+    t = UriTemplate.parse("{a}-{b}")
+    assert t.match("foo-bar") == {"a": "foo", "b": "bar"}
 
 
 def test_match_decodes_percent_encoding():
@@ -515,6 +530,12 @@ def test_match_explode_encoded_separator_in_segment():
         ("{var}", {"var": "hello world"}),
         ("item{;id}", {"id": "42"}),
         ("item{;id}", {"id": ""}),
+        # Defined-but-empty values still emit the operator prefix; match
+        # must accept the empty capture after it.
+        ("page{#section}", {"section": ""}),
+        ("file{.ext}", {"ext": ""}),
+        ("api{/v}", {"v": ""}),
+        ("x{name}y", {"name": ""}),
         ("item{;keys*}", {"keys": ["a", "b", "c"]}),
         ("item{;keys*}", {"keys": ["a", "", "b"]}),
         # Partial query expansion round-trips: expand omits undefined