fix: ifemp round-trip + stale docstrings from linear-scan refactor

One logic fix and a sweep of stale references left over from the
regex-to-scan rewrite.

ifemp round-trip (_scan_prefix): the name-continuation guard rejected
the empty-value case when the template's next literal started with a
non-stop-char. api{;key}X{+rest} with key='' expands to api;keyX/tail
but matched None because 'X' after ;key was treated as a name
continuation. Now checks whether the next literal starts at the
current position before rejecting.

Doc/style cleanups:
- match() docstring: 'regex derived from the template' -> 'linear scan'
- _split_query_tail: 'strict regex' -> 'strict scan'
- test comments: 5x 'regex' -> 'scan'
- DEFAULT_RESOURCE_SECURITY: docstring now mentions null-byte rejection
- migration.md: describe client-visible 'Unknown resource' error rather
  than the internal ResourceSecurityError type
- _Atom type alias: remove unnecessary string quoting
- UriTemplate fields: list[...] not tuple[..., ...] — arbitrary-sized
  tuples are not a defence worth having

Author: maxisbey

docs/migration.md

@@ -552,13 +552,13 @@ Several behaviors have changed:
 
 **Path-safety checks applied by default.** Extracted parameter values
 containing `..` as a path component, a null byte, or looking like an
-absolute path (`/etc/passwd`, `C:\Windows`) now raise
-`ResourceSecurityError` and halt template iteration — a strict
-template's rejection no longer falls through to a later permissive
-template. This is checked on the decoded value, so `..%2Fetc`,
-`%2E%2E`, and `%00` are caught too. Note that `..` is only flagged as
-a standalone path component, so values like `v1.0..v2.0` or
-`HEAD~3..HEAD` are unaffected.
+absolute path (`/etc/passwd`, `C:\Windows`) now cause the read to
+fail — the client receives an "Unknown resource" error and template
+iteration stops, so a strict template's rejection does not fall
+through to a later permissive template. This is checked on the
+decoded value, so `..%2Fetc`, `%2E%2E`, and `%00` are caught too.
+Note that `..` is only flagged as a standalone path component, so
+values like `v1.0..v2.0` or `HEAD~3..HEAD` are unaffected.
 
 If a parameter legitimately needs to receive absolute paths or
 traversal sequences, exempt it:

src/mcp/server/mcpserver/resources/templates.py

@@ -80,7 +80,7 @@ def validate(self, params: Mapping[str, str | list[str]]) -> str | None:
 
 
 DEFAULT_RESOURCE_SECURITY = ResourceSecurity()
-"""Secure-by-default policy: traversal and absolute paths rejected."""
+"""Secure-by-default policy: traversal, absolute paths, and null bytes rejected."""
 
 
 class ResourceSecurityError(ValueError):

src/mcp/shared/uri_template.py

@@ -169,7 +169,7 @@ class _Cap:
     ifemp: bool = False
 
 
-_Atom: TypeAlias = "_Lit | _Cap"
+_Atom: TypeAlias = _Lit | _Cap
 
 
 def _is_greedy(var: Variable) -> bool:
@@ -286,12 +286,12 @@ class UriTemplate:
     """
 
     template: str
-    _parts: tuple[_Part, ...] = field(repr=False, compare=False)
-    _variables: tuple[Variable, ...] = field(repr=False, compare=False)
-    _prefix: tuple[_Atom, ...] = field(repr=False, compare=False)
+    _parts: list[_Part] = field(repr=False, compare=False)
+    _variables: list[Variable] = field(repr=False, compare=False)
+    _prefix: list[_Atom] = field(repr=False, compare=False)
     _greedy: Variable | None = field(repr=False, compare=False)
-    _suffix: tuple[_Atom, ...] = field(repr=False, compare=False)
-    _query_variables: tuple[Variable, ...] = field(repr=False, compare=False)
+    _suffix: list[_Atom] = field(repr=False, compare=False)
+    _query_variables: list[Variable] = field(repr=False, compare=False)
 
     @staticmethod
     def is_template(value: str) -> bool:
@@ -356,12 +356,12 @@ def parse(
 
         return cls(
             template=template,
-            _parts=tuple(parts),
-            _variables=tuple(variables),
-            _prefix=tuple(prefix),
+            _parts=parts,
+            _variables=variables,
+            _prefix=prefix,
             _greedy=greedy,
-            _suffix=tuple(suffix),
-            _query_variables=tuple(query_vars),
+            _suffix=suffix,
+            _query_variables=query_vars,
         )
 
     @property
@@ -436,8 +436,8 @@ def expand(self, variables: Mapping[str, str | Sequence[str]]) -> str:
     def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> dict[str, str | list[str]] | None:
         """Match a concrete URI against this template and extract variables.
 
-        This is the inverse of :meth:`expand`. The URI is matched against
-        a regex derived from the template and captured values are
+        This is the inverse of :meth:`expand`. The URI is matched via a
+        linear scan of the template and captured values are
         percent-decoded. The round-trip ``match(expand({k: v})) == {k: v}``
         holds when ``v`` does not contain its operator's separator
         unencoded: ``{.ext}`` with ``ext="tar.gz"`` expands to
@@ -446,7 +446,7 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
         inherent reversal limitation.
 
         Matching is structural at the URI level only: a simple ``{name}``
-        will not match across a literal ``/`` in the URI (the regex stops
+        will not match across a literal ``/`` in the URI (the scan stops
         there), but a percent-encoded ``%2F`` that decodes to ``/`` is
         accepted as part of the value. Path-safety validation belongs at
         a higher layer; see :mod:`mcp.shared.path_security`.
@@ -483,7 +483,7 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
         Args:
             uri: A concrete URI string.
             max_uri_length: Maximum permitted length of the input URI.
-                Oversized inputs return ``None`` without regex evaluation,
+                Oversized inputs return ``None`` without scanning,
                 guarding against resource exhaustion.
 
         Returns:
@@ -643,7 +643,7 @@ def _split_query_tail(parts: list[_Part]) -> tuple[list[_Part], list[Variable]]:
     expressions and the preceding path portion contains no literal
     ``?``. If the path has a literal ``?`` (e.g., ``?fixed=1{&page}``),
     the URI's ``?`` split won't align with the template's expression
-    boundary, so strict regex matching is used instead.
+    boundary, so the strict scan is used instead.
 
     Returns:
         A pair ``(path_parts, query_vars)``. If lenient matching does
@@ -671,8 +671,8 @@ def _split_query_tail(parts: list[_Part]) -> tuple[list[_Part], list[Variable]]:
 
     # If the path portion contains a literal ?/# or a {?...}/{#...}
     # expression, lenient matching's partition("#") then partition("?")
-    # would strip content the path regex expects to see. Fall back to
-    # strict regex.
+    # would strip content the path scan expects to see. Fall back to
+    # the strict scan.
     for part in parts[:split]:
         if isinstance(part, str):
             if "?" in part or "#" in part:
@@ -1024,11 +1024,14 @@ def _scan_prefix(
 
         if atom.ifemp:
             # Optional = after ;name. A non-= non-delimiter here means
-            # the name continued (e.g. ;keys vs ;key) — reject.
+            # the name continued (e.g. ;keys vs ;key) — reject, unless
+            # the template's next literal starts right here, in which
+            # case the value is legitimately empty.
             if pos < limit and uri[pos] == "=":
                 pos += 1
             elif pos < limit and uri[pos] not in stops:
-                return None
+                if not (isinstance(nxt, _Lit) and uri.startswith(nxt.text, pos)):
+                    return None
 
         # Latest valid end: the var stops at the first stop-char or
         # the scan limit, whichever comes first.

tests/shared/test_uri_template.py

@@ -444,15 +444,15 @@ def test_expand_rejects_invalid_value_types(value: object):
         ("search{?q}", "search#frag", {}),
         # Multiple ?/& expressions collected together
         ("api{?v}{&page,limit}", "api?limit=10&v=2", {"v": "2", "limit": "10"}),
-        # Standalone {&var} falls through to strict regex (expands with
-        # & prefix, no ? for lenient matching to split on)
+        # Standalone {&var} falls through to the strict scan (expands
+        # with & prefix, no ? for lenient matching to split on)
         ("api{&page}", "api&page=2", {"page": "2"}),
-        # Literal ? in path portion falls through to strict regex
+        # Literal ? in path portion falls through to the strict scan
         ("api?x{?page}", "api?x?page=2", {"page": "2"}),
         # {?...} expression in path portion also falls through
         ("api{?q}x{?page}", "api?q=1x?page=2", {"q": "1", "page": "2"}),
         # {#...} or literal # in path portion falls through: lenient
-        # matching would strip the fragment before the path regex sees it
+        # matching would strip the fragment before the path scan sees it
         ("page{#section}{?q}", "page#intro?q=x", {"section": "intro", "q": "x"}),
         ("page#lit{?q}", "page#lit?q=x", {"q": "x"}),
         # Empty & segments in query are skipped
@@ -465,7 +465,7 @@ def test_expand_rejects_invalid_value_types(value: object):
         ("api://x{?token}", "api://x?%74oken=evil&token=real", {"token": "real"}),
         ("api://x{?token}", "api://x?%74oken=evil", {}),
         # Level 3: query continuation with literal ? falls back to
-        # strict regex (template-order, all-present required)
+        # the strict scan (template-order, all-present required)
         ("?a=1{&b}", "?a=1&b=2", {"b": "2"}),
         # Explode: path segments as list
         ("/files{/path*}", "/files/a/b/c", {"path": ["a", "b", "c"]}),
@@ -512,8 +512,8 @@ 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. Adjacent unrestricted vars are inherently
+    # Capture positions are ordinal, so names only affect the result
+    # dict keys, not the scan. Adjacent unrestricted vars are inherently
     # ambiguous; greedy * resolution means the first takes everything.
     t = UriTemplate.parse("{var}{vara}")
     assert t.match("ab") == {"var": "ab", "vara": ""}
@@ -654,6 +654,22 @@ def test_match_prefix_ifemp_rejects_name_continuation():
     assert t.match("api;keys/xyz") is None
 
 
+def test_match_prefix_ifemp_empty_before_non_stop_literal():
+    # Regression: _scan_prefix rejected the empty-value case when the
+    # following template literal starts with a non-stop-char. The
+    # name-continuation guard saw 'X' after ';key' and assumed the
+    # name continued, but 'X' is the template's next literal.
+    t = UriTemplate.parse("api{;key}X{+rest}")
+    # Non-empty round-trips fine:
+    assert t.match(t.expand({"key": "abc", "rest": "/tail"})) == {"key": "abc", "rest": "/tail"}
+    # Empty value (ifemp → bare ;key, then X) must also round-trip:
+    uri = t.expand({"key": "", "rest": "/tail"})
+    assert uri == "api;keyX/tail"
+    assert t.match(uri) == {"key": "", "rest": "/tail"}
+    # But an actual name continuation still rejects:
+    assert t.match("api;keyZX/tail") is None
+
+
 def test_match_large_uri_against_greedy_template():
     # Large payload against a greedy template — the scan visits each
     # character once for the suffix anchor and once for the greedy