refactor: remove post-decode structural checks from UriTemplate.match

UriTemplate.match() no longer rejects decoded values containing
characters like /, ?, #, &. It now faithfully returns whatever
expand() would have encoded, so match(expand(x)) == x holds for all
inputs.

The previous check broke round-trip for legitimate values (a&b
expanded to a%26b but match rejected it) and was inconsistent with
every other MCP SDK. The spec's own canonical example file:///{path}
requires multi-segment values; Kotlin and C# already decode without
rejection and document handler-side validation as the security
contract.

Path-safety validation remains in ResourceSecurity (configurable) and
safe_join (the gold-standard check). The %2F path-traversal attack
vector is still blocked: ..%2Fetc%2Fpasswd decodes to ../etc/passwd,
which contains_path_traversal rejects. Tests confirm this end-to-end.

This aligns us with Kotlin's documented model: decode once, pass to
handler, handler validates.

Author: maxisbey

docs/migration.md

@@ -566,8 +566,9 @@ By default, extracted parameter values are now rejected if they:
 
 - Contain `..` as a path component (e.g., `..`, `../etc`, `a/../../b`)
 - Look like an absolute filesystem path (e.g., `/etc/passwd`, `C:\Windows`)
-- Decode to contain structural delimiters that their operator forbids
-  (e.g., `%2F` smuggled into a simple `{name}`)
+
+These checks apply to the decoded value, so they catch traversal
+regardless of encoding (`../etc`, `..%2Fetc`, `%2E%2E/etc` all caught).
 
 If your template parameters legitimately contain `..` (e.g., git commit
 ranges like `HEAD~3..HEAD`) or absolute paths, exempt them:

docs/server/resources.md

@@ -140,8 +140,10 @@ Before your handler runs, the SDK rejects any parameter that:
 
 - contains `..` as a path component
 - looks like an absolute path (`/etc/passwd`, `C:\Windows`)
-- smuggles a delimiter through URL encoding (for example, `%2F` in a
-  plain `{name}` where `/` isn't allowed)
+
+These checks apply to the decoded value, so they catch traversal
+regardless of how it was encoded in the URI (`../etc`, `..%2Fetc`,
+`%2E%2E/etc`, `..%5Cetc` all get caught).
 
 A request that trips these checks is treated as a non-match: the SDK
 raises `ResourceError("Unknown resource: {uri}")`, which the client
@@ -271,8 +273,8 @@ templates (below) if you have any, then raise for anything else.
 ### Templates
 
 The template engine `MCPServer` uses lives in `mcp.shared.uri_template`
-and works on its own. You get the same parsing, matching, and
-structural checks; you wire up the routing and policy yourself.
+and works on its own. You get the same parsing and matching; you wire
+up the routing and security policy yourself.
 
 #### Matching requests
 
@@ -306,8 +308,8 @@ server = Server("my-server", on_read_resource=on_read_resource)
 ```
 
 `UriTemplate.match()` returns the extracted variables or `None`. URL
-decoding and the structural checks (rejecting `%2F` in simple `{name}`
-and so on) happen inside `match()`, the same as in `MCPServer`.
+decoding happens inside `match()`; the decoded values are returned
+as-is without path-safety validation.
 
 Values come out as strings. Convert them yourself: `int(vars["id"])`,
 `Path(vars["path"])`, whatever your handler needs.

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

@@ -25,11 +25,10 @@
 class ResourceSecurity:
     """Security policy applied to extracted resource template parameters.
 
-    These checks run **after** :meth:`~mcp.shared.uri_template.UriTemplate.match`
-    has already enforced structural integrity (e.g., rejected ``%2F`` in
-    simple ``{var}``). They catch semantic attacks that structural checks
-    cannot: ``..`` traversal and absolute-path injection work even with
-    perfectly-formed URI components.
+    These checks run after :meth:`~mcp.shared.uri_template.UriTemplate.match`
+    has extracted and decoded parameter values. They catch path-traversal
+    and absolute-path injection regardless of how the value was encoded in
+    the URI (literal, ``%2F``, ``%5C``, ``%2E%2E``).
 
     Example::
 
@@ -153,10 +152,9 @@ def from_function(
     def matches(self, uri: str) -> dict[str, str | list[str]] | None:
         """Check if a URI matches this template and extract parameters.
 
-        Delegates to :meth:`UriTemplate.match` for RFC 6570 matching
-        with structural integrity (``%2F`` smuggling rejected for simple
-        vars), then applies this template's :class:`ResourceSecurity`
-        policy (path traversal, absolute paths).
+        Delegates to :meth:`UriTemplate.match` for RFC 6570 extraction,
+        then applies this template's :class:`ResourceSecurity` policy
+        (path traversal, absolute paths).
 
         Returns:
             Extracted parameters on success, or ``None`` if the URI

src/mcp/shared/uri_template.py

@@ -75,20 +75,6 @@ class _OperatorSpec:
     "&": r"[^&#]*",  # query-cont value
 }
 
-# Characters that must not appear in a DECODED value for each operator.
-# If %2F smuggles a / into a simple {var}, the decoded value violates
-# the template author's declared structure and the match is rejected.
-_STRUCTURAL_FORBIDDEN: dict[Operator, frozenset[str]] = {
-    "": frozenset("/?#&"),
-    "+": frozenset(),
-    "#": frozenset(),
-    ".": frozenset("./?#"),
-    "/": frozenset("/?#"),
-    ";": frozenset(";/?#"),
-    "?": frozenset("&#"),
-    "&": frozenset("&#"),
-}
-
 
 class InvalidUriTemplate(ValueError):
     """Raised when a URI template string is malformed or unsupported.
@@ -343,16 +329,15 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
         """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; captured values are
-        percent-decoded and validated for structural integrity.
+        a regex derived from the template and captured values are
+        percent-decoded. For any value ``v``, ``match(expand({k: v}))``
+        returns ``{k: v}``.
 
-        **Structural integrity**: decoded values must not contain
-        characters that are structurally significant for their operator.
-        A simple ``{name}`` whose value decodes to contain ``/`` is
-        rejected — if that was intended, the template author should use
-        ``{+name}``. This blocks the ``%2F``-smuggling vector where a
-        client encodes a path separator to bypass single-segment
-        semantics.
+        Matching is structural at the URI level only: a simple ``{name}``
+        will not match across a literal ``/`` in the URI (the regex 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`.
 
         Example::
 
@@ -361,8 +346,6 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
             {'name': 'readme.txt'}
             >>> t.match("file://docs/hello%20world.txt")
             {'name': 'hello world.txt'}
-            >>> t.match("file://docs/..%2Fetc%2Fpasswd") is None  # / in simple var
-            True
 
             >>> t = UriTemplate.parse("file://docs/{+path}")
             >>> t.match("file://docs/src/main.py")
@@ -381,8 +364,7 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
         Returns:
             A mapping from variable names to decoded values (``str`` for
             scalar variables, ``list[str]`` for explode variables), or
-            ``None`` if the URI does not match the template, a decoded
-            value violates structural integrity, or the URI exceeds
+            ``None`` if the URI does not match the template or exceeds
             ``max_uri_length``.
         """
         if len(uri) > max_uri_length:
@@ -395,12 +377,10 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
         # One capture group per variable, emitted in template order.
         for var, raw in zip(self._variables, m.groups()):
             spec = _OPERATOR_SPECS[var.operator]
-            forbidden = _STRUCTURAL_FORBIDDEN[var.operator]
 
             if var.explode:
                 # Explode capture holds the whole run including separators,
-                # e.g. "/a/b/c" or ";keys=a;keys=b". Split, decode each
-                # segment, check each.
+                # e.g. "/a/b/c" or ";keys=a;keys=b". Split and decode each.
                 if not raw:
                     result[var.name] = []
                     continue
@@ -419,18 +399,10 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
                             seg = ""
                         else:
                             return None
-                    decoded = unquote(seg)
-                    if any(c in decoded for c in forbidden):
-                        return None
-                    segments.append(decoded)
+                    segments.append(unquote(seg))
                 result[var.name] = segments
             else:
-                decoded = unquote(raw)
-                # Structural integrity: reject if decoding revealed a
-                # delimiter the operator doesn't permit.
-                if any(c in decoded for c in forbidden):
-                    return None
-                result[var.name] = decoded
+                result[var.name] = unquote(raw)
 
         return result
 

tests/server/mcpserver/resources/test_resource_template.py

@@ -26,8 +26,9 @@ def test_matches_rfc6570_reserved_expansion():
     assert t.matches("file://docs/src/main.py") == {"path": "src/main.py"}
 
 
-def test_matches_rejects_encoded_slash_in_simple_var():
-    # Path traversal via encoded slash: %2F smuggled into a simple {var}
+def test_matches_rejects_encoded_slash_traversal():
+    # %2F decodes to / in UriTemplate.match(), giving "../../etc/passwd".
+    # ResourceSecurity's traversal check then rejects the '..' components.
     t = _make("file://docs/{name}")
     assert t.matches("file://docs/..%2F..%2Fetc%2Fpasswd") is None
 
@@ -73,29 +74,35 @@ def test_matches_explode_checks_each_segment():
     assert t.matches("api/a/../c") is None
 
 
-def test_matches_encoded_backslash_caught_by_traversal_layer():
-    # %5C decodes to '\\'. Backslash is not a URI delimiter, so it passes
-    # structural integrity (layer 1). The traversal check (layer 2)
-    # normalizes '\\' to '/' and catches the '..' components.
+def test_matches_encoded_backslash_caught_by_traversal_check():
+    # %5C decodes to '\\'. The traversal check normalizes '\\' to '/'
+    # and catches the '..' components.
     t = _make("file://docs/{name}")
     assert t.matches("file://docs/..%5C..%5Csecret") is None
 
 
-def test_matches_encoded_dots_caught_by_traversal_layer():
-    # %2E%2E decodes to '..'. Contains no structural delimiter, so passes
-    # layer 1. Layer 2's traversal check catches the '..' component.
+def test_matches_encoded_dots_caught_by_traversal_check():
+    # %2E%2E decodes to '..' which the traversal check rejects.
     t = _make("file://docs/{name}")
     assert t.matches("file://docs/%2E%2E") is None
 
 
 def test_matches_mixed_encoded_and_literal_slash():
-    # One encoded slash + one literal: literal '/' prevents the regex
-    # match at layer 0 (simple var stops at '/'), so this never reaches
-    # decoding. Different failure mode than pure-encoded traversal.
+    # The literal '/' stops the simple-var regex, so the URI doesn't
+    # match the template at all.
     t = _make("file://docs/{name}")
     assert t.matches("file://docs/..%2F../etc") is None
 
 
+def test_matches_encoded_slash_without_traversal_allowed():
+    # %2F decoding to '/' is fine when there's no traversal involved.
+    # UriTemplate accepts it; ResourceSecurity only blocks '..' and
+    # absolute paths. Handlers that need single-segment should use
+    # safe_join or validate explicitly.
+    t = _make("file://docs/{name}")
+    assert t.matches("file://docs/sub%2Ffile.txt") == {"name": "sub/file.txt"}
+
+
 def test_matches_escapes_template_literals():
     # Regression: old impl treated . as regex wildcard
     t = _make("data://v1.0/{id}")

tests/shared/test_uri_template.py

@@ -410,54 +410,38 @@ def test_match_escapes_template_literals():
 
 
 @pytest.mark.parametrize(
-    ("template", "uri"),
+    ("template", "uri", "expected"),
     [
-        # %2F in simple var — encoded-slash path traversal
-        ("file://docs/{name}", "file://docs/..%2F..%2Fetc%2Fpasswd"),
-        ("file://docs/{name}", "file://docs/..%2f..%2fetc%2fpasswd"),
-        # %3F (?) in simple var
-        ("{var}", "a%3Fb"),
-        # %2E (.) in label var — would break label structure
-        ("file{.ext}", "file.a%2Eb"),
-        # %2F in path-segment var
-        ("api{/v}", "api/a%2Fb"),
-        # %26 (&) in query var — would break query structure
-        ("search{?q}", "search?q=a%26b"),
+        # Percent-encoded delimiters round-trip through match/expand.
+        # Path-safety validation belongs to ResourceSecurity, not here.
+        ("file://docs/{name}", "file://docs/a%2Fb", {"name": "a/b"}),
+        ("{var}", "a%3Fb", {"var": "a?b"}),
+        ("{var}", "a%23b", {"var": "a#b"}),
+        ("{var}", "a%26b", {"var": "a&b"}),
+        ("file{.ext}", "file.a%2Eb", {"ext": "a.b"}),
+        ("api{/v}", "api/a%2Fb", {"v": "a/b"}),
+        ("search{?q}", "search?q=a%26b", {"q": "a&b"}),
+        ("{;filter}", ";filter=a%3Bb", {"filter": "a;b"}),
     ],
 )
-def test_match_structural_integrity_rejects_smuggled_delimiters(template: str, uri: str):
-    assert UriTemplate.parse(template).match(uri) is None
+def test_match_encoded_delimiters_roundtrip(template: str, uri: str, expected: dict[str, str]):
+    assert UriTemplate.parse(template).match(uri) == expected
 
 
-def test_match_structural_integrity_allows_slash_in_reserved():
-    # {+var} explicitly permits / — structural check must not block it
+def test_match_reserved_expansion_handles_slash():
+    # {+var} allows literal / (not just encoded)
     t = UriTemplate.parse("{+path}")
     assert t.match("a%2Fb") == {"path": "a/b"}
     assert t.match("a/b") == {"path": "a/b"}
 
 
 def test_match_double_encoding_decoded_once():
     # %252F is %2F encoded again. Single decode gives "%2F" (a literal
-    # percent sign, a '2', and an 'F'), which contains no '/' and should
-    # be accepted. Guards against over-decoding.
+    # percent sign, a '2', and an 'F'). Guards against over-decoding.
     t = UriTemplate.parse("file://docs/{name}")
     assert t.match("file://docs/..%252Fetc") == {"name": "..%2Fetc"}
 
 
-def test_match_multi_param_one_poisoned_rejects_whole():
-    # One bad param in a multi-param template rejects the entire match
-    t = UriTemplate.parse("file://{org}/{repo}")
-    assert t.match("file://acme/..%2Fsecret") is None
-    # But the same template with clean params matches fine
-    assert t.match("file://acme/project") == {"org": "acme", "repo": "project"}
-
-
-def test_match_bare_encoded_delimiter_rejected():
-    # A value that decodes to only the forbidden delimiter
-    t = UriTemplate.parse("file://docs/{name}")
-    assert t.match("file://docs/%2F") is None
-
-
 def test_match_rejects_oversized_uri():
     t = UriTemplate.parse("{var}")
     assert t.match("x" * 100, max_uri_length=50) is None
@@ -478,10 +462,11 @@ def test_match_default_uri_length_limit():
     assert t.match("x" * (DEFAULT_MAX_URI_LENGTH + 1)) is None
 
 
-def test_match_structural_integrity_per_explode_segment():
+def test_match_explode_encoded_separator_in_segment():
+    # An encoded separator inside a segment decodes as part of the value,
+    # not as a split point. The split happens at literal separators only.
     t = UriTemplate.parse("/files{/path*}")
-    # Each segment checked independently
-    assert t.match("/files/a%2Fb/c") is None
+    assert t.match("/files/a%2Fb/c") == {"path": ["a/b", "c"]}
 
 
 @pytest.mark.parametrize(