fix: correct lenient query matching for +, fragments, and standalone {&var}

Three fixes to the two-phase query matching path:

Replaced parse_qs with a manual &/= split using unquote(). parse_qs
follows application/x-www-form-urlencoded semantics where + decodes
to space, but RFC 6570 and RFC 3986 treat + as a literal sub-delim.
A client sending ?q=C++ previously got 'C  '; the path-portion
decoder (unquote) already handled this correctly, so the two code
paths disagreed.

Fragment is now stripped before splitting on ?. A URI like
logs://api?level=error#section1 previously returned
level='error#section1' via the lenient path while the strict-regex
path correctly stopped at #.

_split_query_tail now requires the trailing tail to start with a
{?...} expression. A standalone {&page} expands with an & prefix
(no ?), so partition('?') found no split and the path regex failed.
Such templates now fall through to strict regex which handles them
correctly. Also extends the path-portion check to bail on {?...}
expressions left in the path, not just literal ?.

Author: maxisbey

src/mcp/shared/uri_template.py

@@ -39,7 +39,7 @@
 from collections.abc import Mapping, Sequence
 from dataclasses import dataclass, field
 from typing import Literal, cast
-from urllib.parse import parse_qs, quote, unquote
+from urllib.parse import quote, unquote
 
 __all__ = ["InvalidUriTemplate", "Operator", "UriTemplate", "Variable"]
 
@@ -441,22 +441,24 @@ def match(self, uri: str, *, max_uri_length: int = DEFAULT_MAX_URI_LENGTH) -> di
             return None
 
         if self._query_variables:
-            # Two-phase: regex matches the path, parse_qs handles the
-            # query. Query params may be partial, reordered, or include
-            # extras; absent params stay absent so downstream defaults
-            # can apply.
-            path, _, query = uri.partition("?")
+            # Two-phase: regex matches the path, the query is split and
+            # decoded manually. Query params may be partial, reordered,
+            # or include extras; absent params stay absent so downstream
+            # defaults can apply. Fragment is stripped first since the
+            # template's {?...} tail never describes a fragment.
+            before_fragment, _, _ = uri.partition("#")
+            path, _, query = before_fragment.partition("?")
             m = self._pattern.fullmatch(path)
             if m is None:
                 return None
             result = _extract_path(m, self._path_variables)
             if result is None:
                 return None
             if query:
-                parsed = parse_qs(query, keep_blank_values=True)
+                parsed = _parse_query(query)
                 for var in self._query_variables:
                     if var.name in parsed:
-                        result[var.name] = parsed[var.name][0]
+                        result[var.name] = parsed[var.name]
             return result
 
         m = self._pattern.fullmatch(uri)
@@ -468,6 +470,26 @@ def __str__(self) -> str:
         return self.template
 
 
+def _parse_query(query: str) -> dict[str, str]:
+    """Parse a query string into a name→value mapping.
+
+    Unlike ``urllib.parse.parse_qs``, this follows RFC 3986 semantics:
+    ``+`` is a literal sub-delim, not a space. Form-urlencoding treats
+    ``+`` as space for HTML form submissions, but RFC 6570 and MCP
+    resource URIs follow RFC 3986 where only ``%20`` encodes a space.
+
+    Duplicate keys keep the first value. Pairs without ``=`` are
+    treated as empty-valued.
+    """
+    result: dict[str, str] = {}
+    for pair in query.split("&"):
+        name, _, value = pair.partition("=")
+        name = unquote(name)
+        if name and name not in result:
+            result[name] = unquote(value)
+    return result
+
+
 def _extract_path(m: re.Match[str], variables: Sequence[Variable]) -> dict[str, str | list[str]] | None:
     """Decode regex capture groups into a variable-name mapping.
 
@@ -535,10 +557,22 @@ def _split_query_tail(parts: list[_Part]) -> tuple[list[_Part], list[Variable]]:
     if split == len(parts):
         return parts, []
 
-    # If the path portion contains a literal ?, the URI's ? won't align
-    # with our template split. Fall back to strict regex.
+    # The tail must start with a {?...} expression so that expand()
+    # emits a ? the URI can split on. A standalone {&page} expands
+    # with an & prefix, which partition("?") won't find.
+    first = parts[split]
+    assert isinstance(first, _Expression)
+    if first.operator != "?":
+        return parts, []
+
+    # If the path portion contains a literal ? or a {?...} expression,
+    # the URI's ? split won't align with our template boundary. Fall
+    # back to strict regex.
     for part in parts[:split]:
-        if isinstance(part, str) and "?" in part:
+        if isinstance(part, str):
+            if "?" in part:
+                return parts, []
+        elif part.operator == "?":
             return parts, []
 
     query_vars: list[Variable] = []

tests/shared/test_uri_template.py

@@ -437,8 +437,17 @@ def test_expand_rejects_invalid_value_types(value: object):
         ("search{?q}", "search?q=mcp&utm=x&ref=y", {"q": "mcp"}),
         # URL-encoded query values are decoded
         ("search{?q}", "search?q=hello%20world", {"q": "hello world"}),
+        # + is a literal sub-delim per RFC 3986, not a space (form-encoding)
+        ("search{?q}", "search?q=C++", {"q": "C++"}),
+        ("search{?q}", "search?q=1.0+build.5", {"q": "1.0+build.5"}),
+        # Fragment is stripped before query parsing
+        ("logs://{service}{?level}", "logs://api?level=error#section1", {"service": "api", "level": "error"}),
+        ("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)
+        ("api{&page}", "api&page=2", {"page": "2"}),
         # Level 3: query continuation with literal ? falls back to
         # strict regex (template-order, all-present required)
         ("?a=1{&b}", "?a=1&b=2", {"b": "2"}),