Resource template registration fails when param names contain hyphens

[strawgate]

URI templates with hyphenated parameter names fail at registration time.

@mcp.resource("data://{user-id}/profile")
def get_profile(user_id: str) -> str:
    return f"profile for {user_id}"
# ValueError: URI template must contain at least one parameter

The regex in template.py:505 uses \w+ which matches [a-zA-Z0-9_] — hyphens are excluded:

path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))

So {user-id} is not recognized as a parameter, and the template appears to have zero parameters.

RFC 6570 allows hyphens in variable names. The fix is [\w-]+ or [\w.-]+ in the regex.

[marvin-context-protocol]

Claude finished @strawgate's task in 2m 27s —— View job

---

tl;dr

The bug is real but the suggested fix is incomplete. Broadening the regex to [\w-]+ on line 537 lets the parameter be detected, but the downstream path — build_regex (line 47) — intentionally rejects hyphenated names because Python re group names can't contain hyphens, and Python function parameters can't contain hyphens either. So even if we "fix" the extraction regex, there's no function parameter the URI value could bind to.

The right fix is to raise a targeted, actionable error at registration time instead of the misleading "URI template must contain at least one parameter" error. Hyphens in URI parameter names should not be silently supported because they cannot map to valid Python identifiers.

Recommendation

Change from_function in src/fastmcp/resources/template.py so that URI-template parameter names are extracted with a regex that captures any {...} placeholder (e.g. r"\{([^}*?]+)\*?\}" — anything except }, *, ?), then explicitly validate that each captured name is a valid Python identifier. If not, raise a clear error pointing at the offending name.

This gives the user of @mcp.resource("data://{user-id}/profile") a diagnostic like:

URI template parameter 'user-id' is not a valid Python identifier. Rename it (e.g. 'user_id') in both the URI template and the function signature.

…rather than the current "must contain at least one parameter", which sends people hunting in the wrong direction. This approach is consistent with how build_regex already treats hyphenated names as malformed for remote-sourced templates (see TestMalformedURITemplates in tests/resources/test_resource_template.py:756).

Findings

Reproduction

$ python3 -c "
import fastmcp
mcp = fastmcp.FastMCP()
@mcp.resource('data://{user-id}/profile')
def get_profile(user_id: str) -> str:
    return f'profile for {user_id}'
"
ValueError: URI template must contain at least one parameter

Confirmed on main (HEAD 7d76074).

Why just broadening the regex isn't enough

1. src/fastmcp/resources/template.py:537 uses \w+, which misses {user-id} entirely → path_params becomes empty → the "must contain at least one parameter" error fires.
2. Even if we change it to [\w-]+, the parameter is now detected, and validation at template.py:583 would emit URI parameters {'user-id'} must be a subset of the function arguments: {'user_id'} — better, but still wrong framing.
3. More importantly, build_regex at template.py:47-76 uses named capture groups ((?P<{name}>...)) and re.compile raises for hyphenated names. The existing tests at tests/resources/test_resource_template.py:756-812 lock in the behavior that hyphenated templates return None (treated as malformed) — this is a deliberate choice for remote-sourced templates coming through a proxy.
4. There is no way to bind a URI parameter named user-id to a function parameter, because Python identifiers disallow hyphens. Automatic hyphen→underscore mapping would be magical and ambiguous (what if a function has both user_id and user-id intended meanings?).

So the only useful "support" for hyphenated names at local registration is a clearer error message.

Related: the RFC 6570 angle

The issue correctly notes RFC 6570 allows hyphens in variable names. FastMCP partially supports this for remote templates (they fail gracefully via build_regex returning None), but it cannot support them for locally registered templates without some naming convention (e.g. auto-mapping {user-id} ↔ user_id). That is a larger design decision worth its own issue/discussion; this ticket should just fix the misleading error.

Detailed Action Plan

1. Edit src/fastmcp/resources/template.py, around line 537:

   • Replace path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template)) with a capture that matches any placeholder content except the {?query,list} form, e.g.:

     # Capture path parameter names (ignore the {?a,b} query form)
     path_placeholders = re.findall(
         r"\{([^?}][^}*]*)\*?\}", uri_template
     )
     path_params = set(path_placeholders)

   • After the all_uri_params union, add:

     invalid = {p for p in all_uri_params if not p.isidentifier()}
     if invalid:
         raise ValueError(
             f"URI template parameter names {sorted(invalid)} are not valid "
             "Python identifiers. Use names matching [A-Za-z_][A-Za-z0-9_]* "
             "(for example, rename 'user-id' to 'user_id' in both the URI "
             "template and the function signature)."
         )

   • Keep the existing "must contain at least one parameter" check after the invalid-name check, so hyphenated-name users don't get the misleading message.

2. Add tests in tests/resources/test_resource_template.py:

   • A parametrized test covering {user-id}, {1leading}, {foo.bar} — assert each raises ValueError whose message mentions the offending name and "valid Python identifier".
   • A regression test asserting the original "URI template must contain at least one parameter" error still fires for "data://static/path" (no placeholders at all).

3. Run the suite:

   uv sync
   uv run pytest tests/resources/test_resource_template.py -x
   uv run prek run --all-files

4. Do not change build_regex / match_uri_template. Their hyphen-returns-None behavior is intentional for proxied remote templates and is explicitly tested. Leaving them alone keeps the scope of this fix tight.

5. Docs: No doc change needed — this is an error-message improvement. If the maintainer wants to document that URI template param names must be valid Python identifiers, docs/servers/resources.mdx is the place.

Related Items

Related Issues and Pull Requests

Repository	Issue or PR	Relevance
PrefectHQ/fastmcp	#3918 — Stop pydantic 2.13 from leaking _WrappedResult docstring into tool output schemas	Most recent merge on main — unrelated, included only as current-HEAD context.

No prior hyphen-related issues found in the repo; TestMalformedURITemplates (added with the build_regex introduction) is the closest design precedent.

Related Files

Repository	File	Relevance	Sections
PrefectHQ/fastmcp	src/fastmcp/resources/template.py	Contains the faulty \w+ regex and the registration-time validation that produces the misleading error. Also contains build_regex, whose hyphen handling informs why we should not try to fully support hyphenated names.	537, 47-76, 573-586
PrefectHQ/fastmcp	tests/resources/test_resource_template.py	Houses TestMalformedURITemplates, which locks in current hyphen-is-malformed behavior for build_regex. New tests for the improved registration error go here.	756-812

Related Webpages

Name	URL	Relevance
RFC 6570 — URI Template	https://datatracker.ietf.org/doc/html/rfc6570#section-2.3	Defines varname = varchar *( ["."] varchar ) with varchar = ALPHA / DIGIT / "_" / pct-encoded — note: RFC 6570 does not actually permit raw hyphens in varnames; only ALPHA, DIGIT, _, ., and percent-encoded chars. The issue's claim that "RFC 6570 allows hyphens" is incorrect. This further supports rejecting hyphens outright.
Python re — group name rules	https://docs.python.org/3/library/re.html#regular-expression-syntax	(?P<name>...) requires name to be a valid Python identifier, which is why build_regex fails on hyphens.

Todos

• Reproduce the bug locally
• Read the relevant code paths (from_function, build_regex, existing tests)
• Determine the right fix and scope
• Draft recommendation and action plan
  · branch claude/issue-3921-20260414-0405

---

Marvin Context Protocol | Type /marvin to interact further

Give us feedback! React with 🚀 if perfect, 👍 if helpful, 👎 if not.