fix: URL-decode parameters extracted from resource templates (#973)

Github-Issue: #973
Reported-by: codeonym

Author: felixweinberger

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

@@ -6,6 +6,7 @@
 import re
 from collections.abc import Callable
 from typing import TYPE_CHECKING, Any
+from urllib.parse import unquote
 
 from pydantic import BaseModel, Field, validate_call
 
@@ -83,12 +84,16 @@ def from_function(
         )
 
     def matches(self, uri: str) -> dict[str, Any] | None:
-        """Check if URI matches template and extract parameters."""
+        """Check if URI matches template and extract parameters.
+
+        Extracted parameters are URL-decoded to handle percent-encoded characters.
+        """
         # Convert template to regex pattern
         pattern = self.uri_template.replace("{", "(?P<").replace("}", ">[^/]+)")
         match = re.match(f"^{pattern}$", uri)
         if match:
-            return match.groupdict()
+            # URL-decode all extracted parameter values
+            return {key: unquote(value) for key, value in match.groupdict().items()}
         return None
 
     async def create_resource(

tests/issues/test_973_url_decoding.py

@@ -39,7 +39,7 @@ def search(query: str) -> str:  # pragma: no cover
 
         params = template.matches("search://caf%C3%A9")
         assert params is not None
-        assert params["query"] == "cafe"  # encoded as UTF-8
+        assert params["query"] == "café"
 
     def test_template_matches_decodes_complex_phrase(self):
         """Test complex French phrase from the original issue."""
@@ -53,11 +53,9 @@ def search(query: str) -> str:  # pragma: no cover
             name="search",
         )
 
-        params = template.matches(
-            "search://stick%20correcteur%20teint%C3%A9%20anti-imperfections"
-        )
+        params = template.matches("search://stick%20correcteur%20teint%C3%A9%20anti-imperfections")
         assert params is not None
-        assert params["query"] == "stick correcteur teinte anti-imperfections"
+        assert params["query"] == "stick correcteur teinté anti-imperfections"
 
     def test_template_matches_preserves_plus_sign(self):
         """Test that plus sign remains as plus (not converted to space).
@@ -77,4 +75,4 @@ def search(query: str) -> str:  # pragma: no cover
 
         params = template.matches("search://hello+world")
         assert params is not None
-        assert params["query"] == "hello+world"
+        assert params["query"] == "hello+world"