fix: tighten parse-time validation and document matching limits

Four small corrections:

Varname grammar: the RFC grammar requires dots only between varchar
groups, so {foo..bar} and {foo.} are now rejected. Previously the
regex allowed any dot placement after the first char.

Adjacent explodes: previously only same-operator adjacent explodes
({/a*}{/b*}) were rejected. Different operators ({/a*}{.b*}) are
equally ambiguous because the first operator's character class
typically includes the second's separator, so the first explode
greedily consumes both. All adjacent explodes are now rejected; a
literal or non-explode variable between them still disambiguates.

Documented the inherent ambiguity of multi-var reserved expressions
({+x,y} with commas in values) and the intentional tradeoff that
{+var} match stops at ? and # so {+path}{?q} can separate correctly.

Author: maxisbey

src/mcp/shared/uri_template.py

@@ -8,6 +8,26 @@
 Supports Levels 1-3 fully, plus Level 4 explode modifier for path-like
 operators (``{/var*}``, ``{.var*}``, ``{;var*}``). The Level 4 prefix
 modifier (``{var:N}``) and query-explode (``{?var*}``) are not supported.
+
+Known matching limitations
+--------------------------
+
+Matching is not specified by RFC 6570. A few templates can expand to
+URIs that ``match()`` cannot unambiguously reverse:
+
+* Multi-variable reserved expressions like ``{+x,y}`` use a comma as
+  separator but also permit commas *inside* values (commas are in the
+  reserved set). ``match("a,b,c")`` cannot know which comma is the
+  separator. The matcher takes the last comma as the split point; if
+  your values contain commas, prefer separate expressions (``{+x}/{+y}``)
+  or a different operator.
+
+* Reserved expansion ``{+var}`` leaves ``?`` and ``#`` unencoded, but
+  the match pattern stops at those characters so that templates like
+  ``{+path}{?q}`` can correctly separate path from query. A value
+  containing a literal ``?`` or ``#`` expands fine but will not
+  round-trip through ``match()``. Use simple ``{var}`` (which encodes
+  them) if round-trip matters for such values.
 """
 
 from __future__ import annotations
@@ -25,8 +45,9 @@
 _OPERATORS: frozenset[str] = frozenset({"+", "#", ".", "/", ";", "?", "&"})
 
 # RFC 6570 §2.3: varname = varchar *(["."] varchar), varchar = ALPHA / DIGIT / "_"
+# Dots appear only between varchar groups — not consecutive, not trailing.
 # (Percent-encoded varchars are technically allowed but unseen in practice.)
-_VARNAME_RE = re.compile(r"^[A-Za-z0-9_][A-Za-z0-9_.]*$")
+_VARNAME_RE = re.compile(r"^[A-Za-z0-9_]+(?:\.[A-Za-z0-9_]+)*$")
 
 DEFAULT_MAX_TEMPLATE_LENGTH = 1_000_000
 DEFAULT_MAX_EXPRESSIONS = 10_000
@@ -717,33 +738,35 @@ def _check_duplicate_variables(template: str, variables: list[Variable]) -> None
 
 
 def _check_adjacent_explodes(template: str, parts: list[_Part]) -> None:
-    """Reject templates with adjacent same-operator explode variables.
+    """Reject templates with adjacent explode variables.
 
     Patterns like ``{/a*}{/b*}`` are ambiguous for matching: given
-    ``/x/y/z``, the split between ``a`` and ``b`` is undetermined. We
-    reject these at parse time rather than picking an arbitrary
-    resolution. A literal between them (``{/a*}/x{/b*}``) or a different
-    operator (``{/a*}{.b*}``) disambiguates.
+    ``/x/y/z``, the split between ``a`` and ``b`` is undetermined.
+    Different operators (``{/a*}{.b*}``) do not help in general because
+    the first operator's character class often includes the second's
+    separator, so the first explode greedily consumes both. We reject
+    all adjacent explodes at parse time rather than picking an arbitrary
+    resolution. A literal between them (``{/a*}/x{/b*}``) still
+    disambiguates.
 
     Raises:
-        InvalidUriTemplate: If two explode variables with the same
-            operator appear with no literal or non-explode variable
-            between them.
+        InvalidUriTemplate: If two explode variables appear with no
+            literal or non-explode variable between them.
     """
-    prev_explode_op: Operator | None = None
+    prev_explode = False
     for part in parts:
         if isinstance(part, str):
             # Literal text breaks any adjacency.
-            prev_explode_op = None
+            prev_explode = False
             continue
         for var in part.variables:
             if var.explode:
-                if prev_explode_op == var.operator:
+                if prev_explode:
                     raise InvalidUriTemplate(
-                        f"Adjacent explode expressions with operator {var.operator!r} are ambiguous and not supported",
+                        "Adjacent explode expressions are ambiguous for matching and not supported",
                         template=template,
                     )
-                prev_explode_op = var.operator
+                prev_explode = True
             else:
                 # A non-explode variable also breaks adjacency.
-                prev_explode_op = None
+                prev_explode = False

tests/shared/test_uri_template.py

@@ -112,12 +112,28 @@ def test_parse_rejects_operator_without_variable():
         UriTemplate.parse("{+}")
 
 
-@pytest.mark.parametrize("name", ["-bad", "bad-name", "bad name", "bad/name"])
+@pytest.mark.parametrize(
+    "name",
+    [
+        "-bad",
+        "bad-name",
+        "bad name",
+        "bad/name",
+        # RFC §2.3: dots only between varchars, not consecutive or trailing
+        "foo..bar",
+        "foo.",
+    ],
+)
 def test_parse_rejects_invalid_varname(name: str):
     with pytest.raises(InvalidUriTemplate, match="Invalid variable name"):
         UriTemplate.parse(f"{{{name}}}")
 
 
+def test_parse_accepts_dotted_varname():
+    t = UriTemplate.parse("{a.b.c}")
+    assert t.variable_names == ("a.b.c",)
+
+
 def test_parse_rejects_empty_spec_in_list():
     with pytest.raises(InvalidUriTemplate, match="Invalid variable name"):
         UriTemplate.parse("{a,,b}")
@@ -134,9 +150,17 @@ def test_parse_rejects_unsupported_explode(template: str):
         UriTemplate.parse(template)
 
 
-def test_parse_rejects_adjacent_explodes_same_operator():
+@pytest.mark.parametrize(
+    "template",
+    [
+        "{/a*}{/b*}",  # same operator
+        "{/a*}{.b*}",  # different operators: / char class includes ., still ambiguous
+        "{.a*}{;b*}",
+    ],
+)
+def test_parse_rejects_adjacent_explodes(template: str):
     with pytest.raises(InvalidUriTemplate, match="Adjacent explode"):
-        UriTemplate.parse("{/a*}{/b*}")
+        UriTemplate.parse(template)
 
 
 @pytest.mark.parametrize(
@@ -201,16 +225,16 @@ def test_parse_stray_close_brace_between_expressions():
     assert tmpl.variable_names == ("a", "b")
 
 
-def test_parse_allows_adjacent_explodes_different_operator():
-    tmpl = UriTemplate.parse("{/a*}{.b*}")
-    assert len(tmpl.variables) == 2
-
-
 def test_parse_allows_explode_separated_by_literal():
     tmpl = UriTemplate.parse("{/a*}/x{/b*}")
     assert len(tmpl.variables) == 2
 
 
+def test_parse_allows_explode_separated_by_non_explode_var():
+    tmpl = UriTemplate.parse("{/a*}{b}{.c*}")
+    assert len(tmpl.variables) == 3
+
+
 def test_parse_rejects_oversized_template():
     with pytest.raises(InvalidUriTemplate, match="maximum length"):
         UriTemplate.parse("x" * 101, max_length=100)