π The fast, Pythonic way to build MCP servers and clients.
fix: allow hyphens in resource template parameter names (#3929)
Bill Easton970b92bb16b0
diff --git a/src/fastmcp/resources/template.py b/src/fastmcp/resources/template.pyindex 53ea6a15e..f4e8b0be0 100644--- a/src/fastmcp/resources/template.py+++ b/src/fastmcp/resources/template.py@@ -52,8 +52,11 @@ def build_regex(template: str) -> re.Pattern[str] | None:- `{var*}` - wildcard path parameter (captures multiple segments)- `{?var1,var2}` - query parameters (ignored in path matching)+ Hyphens in parameter names are normalized to underscores in regex group+ names so that matched groups are valid Python identifiers.+Returns None if the template produces an invalid regex (e.g. parameter- names with hyphens, leading digits, or duplicates from a remote server).+ names with leading digits or duplicates from a remote server)."""# Remove query parameter syntax for path matchingtemplate_without_query = re.sub(r"\{\?[^}]+\}", "", template)@@ -65,9 +68,11 @@ def build_regex(template: str) -> re.Pattern[str] | None:name = part[1:-1]if name.endswith("*"):name = name[:-1]- pattern += f"(?P<{name}>.+)"+ group = name.replace("-", "_")+ pattern += f"(?P<{group}>.+)"else:- pattern += f"(?P<{name}>[^/]+)"+ group = name.replace("-", "_")+ pattern += f"(?P<{group}>[^/]+)"else:pattern += re.escape(part)try:@@ -103,8 +108,12 @@ def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:for name in query_param_names:if name in parsed_query:- # Take first value if multiple provided- params[name] = parsed_query[name][0]+ # Take first value if multiple provided.+ # Normalize hyphens to underscores to match Python param names.+ # Don't overwrite path params that were already extracted.+ key = name.replace("-", "_")+ if key not in params:+ params[key] = parsed_query[name][0]return params@@ -118,20 +127,28 @@ def expand_uri_template(uri_template: str, params: dict[str, Any]) -> str:"""result = uri_template- # Replace {name} and {name*} path placeholders+ # Replace {name} and {name*} path placeholders.+ # Params use underscored keys (e.g. user_id) but templates may use+ # hyphens (e.g. {user-id}), so try both forms.for key, value in params.items():value_str = str(value)result = result.replace(f"{{{key}}}", value_str)result = result.replace(f"{{{key}*}}", value_str)+ hyphenated = key.replace("_", "-")+ if hyphenated != key:+ result = result.replace(f"{{{hyphenated}}}", value_str)+ result = result.replace(f"{{{hyphenated}*}}", value_str)# Expand {?param1,param2,...} query parameter blocksdef _expand_query_block(match: re.Match[str]) -> str:names = [n.strip() for n in match.group(1).split(",")]- parts = [- f"{quote(name)}={quote(str(params[name]))}"- for name in names- if name in params- ]+ parts = []+ for name in names:+ underscored = name.replace("-", "_")+ if name in params:+ parts.append(f"{quote(name)}={quote(str(params[name]))}")+ elif underscored in params:+ parts.append(f"{quote(name)}={quote(str(params[underscored]))}")if parts:return "?" + "&".join(parts)return ""@@ -533,9 +550,28 @@ class FunctionResourceTemplate(ResourceTemplate):"Functions with *args are not supported as resource templates")- # Extract path and query parameters from URI template- path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))- query_params = extract_query_params(uri_template)+ # Extract path and query parameters from URI template.+ # Allow hyphens in names and normalize to underscores so they+ # match Python function parameter names.+ raw_path_params = set(re.findall(r"{([\w-]+)(?:\*)?}", uri_template))+ raw_query_params = extract_query_params(uri_template)++ # Detect collisions: two raw param names that normalize to the+ # same Python identifier (e.g. {user-id} and {user_id}).+ all_raw = raw_path_params | raw_query_params+ seen: dict[str, str] = {}+ for raw_name in sorted(all_raw):+ normalized = raw_name.replace("-", "_")+ if normalized in seen:+ raise ValueError(+ f"URI template parameters '{seen[normalized]}' and "+ f"'{raw_name}' both normalize to '{normalized}'. "+ f"Use one or the other, not both."+ )+ seen[normalized] = raw_name++ path_params = {p.replace("-", "_") for p in raw_path_params}+ query_params = {p.replace("-", "_") for p in raw_query_params}all_uri_params = path_params | query_paramsif not all_uri_params:diff --git a/tests/resources/test_resource_template.py b/tests/resources/test_resource_template.pyindex d15c8da63..2aa81a97f 100644--- a/tests/resources/test_resource_template.py+++ b/tests/resources/test_resource_template.py@@ -759,14 +759,10 @@ class TestMalformedURITemplates:@pytest.mark.parametrize("template",[- "test://{bad-name}/path",- "test://{hyphen-param}/{other-param}/path","test://{1leading}/path","test://{123}/path",],ids=[- "hyphen_in_name",- "multiple_hyphens","leading_digit","all_digits",],@@ -774,18 +770,24 @@ class TestMalformedURITemplates:def test_build_regex_returns_none_for_invalid_group_names(self, template: str):assert build_regex(template) is None+ def test_build_regex_normalizes_hyphens(self):+ """Hyphens in param names produce valid regex with underscored groups."""+ regex = build_regex("test://{user-id}/path")+ assert regex is not None+ match = regex.match("test://alice/path")+ assert match is not None+ assert match.group("user_id") == "alice"+def test_build_regex_returns_none_for_duplicate_group_names(self):assert build_regex("test://{a}/{a}/path") is None@pytest.mark.parametrize("template",[- "test://{bad-name}/path","test://{a}/{a}/path","test://{1leading}/path",],ids=[- "hyphen_in_name","duplicate_groups","leading_digit",],@@ -795,13 +797,71 @@ class TestMalformedURITemplates:):assert match_uri_template("test://anything/path", template) is None- def test_resource_template_matches_returns_none_for_malformed_template(self):+ def test_match_uri_template_normalizes_hyphens(self):+ """Hyphenated params match and return underscored keys."""+ result = match_uri_template("test://alice/path", "test://{user-id}/path")+ assert result == {"user_id": "alice"}++ def test_resource_template_matches_with_hyphenated_params(self):template = ResourceTemplate(- uri_template="test://{bad-name}/path",+ uri_template="test://{user-id}/path",name="test",parameters={},)- assert template.matches("test://anything/path") is None+ result = template.matches("test://alice/path")+ assert result == {"user_id": "alice"}++ async def test_hyphenated_template_end_to_end(self):+ """Register and read a resource with hyphenated URI param names."""+ from fastmcp import FastMCP++ mcp = FastMCP("test")++ @mcp.resource("data://{user-id}/profile")+ def get_profile(user_id: str) -> str:+ return f"profile for {user_id}"++ templates = await mcp.list_resource_templates()+ assert len(templates) == 1+ assert templates[0].uri_template == "data://{user-id}/profile"++ result = await mcp.read_resource("data://alice/profile")+ assert "profile for alice" in str(result)++ def test_build_regex_normalizes_wildcard_hyphens(self):+ """Wildcard params with hyphens also get underscored groups."""+ regex = build_regex("files://{file-path*}")+ assert regex is not None+ match = regex.match("files://a/b/c")+ assert match is not None+ assert match.group("file_path") == "a/b/c"++ def test_expand_uri_template_with_hyphens(self):+ """expand_uri_template maps underscored params to hyphenated placeholders."""+ result = expand_uri_template("data://{user-id}/profile", {"user_id": "alice"})+ assert result == "data://alice/profile"++ def test_query_param_does_not_clobber_path_param(self):+ """If path and query have the same normalized name, path wins."""+ result = match_uri_template(+ "test://alice?user-id=bob", "test://{user-id}{?user-id}"+ )+ # path param should be 'alice', not clobbered by query 'bob'+ assert result is not None+ assert result["user_id"] == "alice"++ def test_from_function_rejects_hyphen_underscore_collision(self):+ """Two raw param names that normalize to the same key are rejected."""++ def handler(user_id: str) -> str:+ return user_id++ with pytest.raises(ValueError, match="both normalize to 'user_id'"):+ ResourceTemplate.from_function(+ fn=handler,+ uri_template="test://{user-id}/{user_id}",+ name="collision",+ )def test_build_regex_still_works_for_valid_templates(self):regex = build_regex("test://{name}/{id}")