Add RFC 6570 query parameter support to resource templates (#1971)

Author: jlowin

docs/servers/resources.mdx

@@ -412,14 +412,14 @@ With these two templates defined, clients can request a variety of resources:
 - `repos://jlowin/fastmcp/info` → Returns info about the jlowin/fastmcp repository
 - `repos://prefecthq/prefect/info` → Returns info about the prefecthq/prefect repository
 
-### Wildcard Parameters
+### RFC 6570 URI Templates
 
-<VersionBadge version="2.2.4" />
 
-<Tip>
-Please note: FastMCP's support for wildcard parameters is an **extension** of the Model Context Protocol standard, which otherwise follows RFC 6570. Since all template processing happens in the FastMCP server, this should not cause any compatibility issues with other MCP implementations.
-</Tip>
+FastMCP implements [RFC 6570 URI Templates](https://datatracker.ietf.org/doc/html/rfc6570) for resource templates, providing a standardized way to define parameterized URIs. This includes support for simple expansion, wildcard path parameters, and form-style query parameters.
 
+#### Wildcard Parameters
+
+<VersionBadge version="2.2.4" />
 
 Resource templates support wildcard parameters that can match multiple path segments. While standard parameters (`{param}`) only match a single path segment and don't cross "/" boundaries, wildcard parameters (`{param*}`) can capture multiple segments including slashes. Wildcards capture all subsequent path segments *up until* the defined part of the URI template (whether literal or another parameter). This allows you to have multiple wildcard parameters in a single URI template.
 
@@ -448,7 +448,7 @@ def get_path_content(filepath: str) -> str:
 # Mixing standard and wildcard parameters
 @mcp.resource("repo://{owner}/{path*}/template.py")
 def get_template_file(owner: str, path: str) -> dict:
-    """Retrieves a file from a specific repository and path, but 
+    """Retrieves a file from a specific repository and path, but
     only if the resource ends with `template.py`"""
     # Can match repo://jlowin/fastmcp/src/resources/template.py
     return {
@@ -466,43 +466,88 @@ Wildcard parameters are useful when:
 
 Note that like regular parameters, each wildcard parameter must still be a named parameter in your function signature, and all required function parameters must appear in the URI template.
 
-### Default Values
-
-<VersionBadge version="2.2.0" />
+#### Query Parameters
 
-When creating resource templates, FastMCP enforces two rules for the relationship between URI template parameters and function parameters:
+<VersionBadge version="2.13.0" />
 
-1. **Required Function Parameters:** All function parameters without default values (required parameters) must appear in the URI template.
-2. **URI Parameters:** All URI template parameters must exist as function parameters.
+FastMCP supports RFC 6570 form-style query parameters using the `{?param1,param2}` syntax. Query parameters provide a clean way to pass optional configuration to resources without cluttering the path.
 
-However, function parameters with default values don't need to be included in the URI template. When a client requests a resource, FastMCP will:
-
-- Extract parameter values from the URI for parameters included in the template
-- Use default values for any function parameters not in the URI template
-
-This allows for flexible API designs. For example, a simple search template with optional parameters:
+Query parameters must be optional function parameters (have default values), while path parameters map to required function parameters. This enforces a clear separation: required data goes in the path, optional configuration in query params.
 
 ```python
 from fastmcp import FastMCP
 
 mcp = FastMCP(name="DataServer")
 
-@mcp.resource("search://{query}")
-def search_resources(query: str, max_results: int = 10, include_archived: bool = False) -> dict:
-    """Search for resources matching the query string."""
-    # Only 'query' is required in the URI, the other parameters use their defaults
-    results = perform_search(query, limit=max_results, archived=include_archived)
+# Basic query parameters
+@mcp.resource("data://{id}{?format}")
+def get_data(id: str, format: str = "json") -> str:
+    """Retrieve data in specified format."""
+    if format == "xml":
+        return f"<data id='{id}' />"
+    return f'{{"id": "{id}"}}'
+
+# Multiple query parameters with type coercion
+@mcp.resource("api://{endpoint}{?version,limit,offset}")
+def call_api(endpoint: str, version: int = 1, limit: int = 10, offset: int = 0) -> dict:
+    """Call API endpoint with pagination."""
     return {
-        "query": query,
-        "max_results": max_results,
-        "include_archived": include_archived,
-        "results": results
+        "endpoint": endpoint,
+        "version": version,
+        "limit": limit,
+        "offset": offset,
+        "results": fetch_results(endpoint, version, limit, offset)
     }
+
+# Query parameters with wildcards
+@mcp.resource("files://{path*}{?encoding,lines}")
+def read_file(path: str, encoding: str = "utf-8", lines: int = 100) -> str:
+    """Read file with optional encoding and line limit."""
+    return read_file_content(path, encoding, lines)
+```
+
+**Example requests:**
+- `data://123` → Uses default format `"json"`
+- `data://123?format=xml` → Uses format `"xml"`
+- `api://users?version=2&limit=50` → `version=2, limit=50, offset=0`
+- `files://src/main.py?encoding=ascii&lines=50` → Custom encoding and line limit
+
+FastMCP automatically coerces query parameter string values to the correct types based on your function's type hints (`int`, `float`, `bool`, `str`).
+
+**Query parameters vs. hidden defaults:**
+
+Query parameters expose optional configuration to clients. To hide optional parameters from clients entirely (always use defaults), simply omit them from the URI template:
+
+```python
+# Clients CAN override max_results via query string
+@mcp.resource("search://{query}{?max_results}")
+def search_configurable(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
+
+# Clients CANNOT override max_results (not in URI template)
+@mcp.resource("search://{query}")
+def search_fixed(query: str, max_results: int = 10) -> dict:
+    return {"query": query, "limit": max_results}
 ```
 
-With this template, clients can request `search://python` and the function will be called with `query="python", max_results=10, include_archived=False`. MCP Developers can still call the underlying `search_resources` function directly with more specific parameters.
+### Template Parameter Rules
+
+<VersionBadge version="2.2.0" />
+
+FastMCP enforces these validation rules when creating resource templates:
+
+1. **Required function parameters** (no default values) must appear in the URI path template
+2. **Query parameters** (specified with `{?param}` syntax) must be optional function parameters with default values
+3. **All URI template parameters** (path and query) must exist as function parameters
+
+Optional function parameters (those with default values) can be:
+- Included as query parameters (`{?param}`) - clients can override via query string
+- Omitted from URI template - always uses default value, not exposed to clients
+- Used in alternative path templates - enables multiple ways to access the same resource
+
+**Multiple templates for one function:**
 
-You can also create multiple resource templates that provide different ways to access the same underlying data by manually applying decorators to a single function:
+Create multiple resource templates that expose the same function through different URI patterns by manually applying decorators:
 
 ```python
 from fastmcp import FastMCP

src/fastmcp/resources/template.py

@@ -6,7 +6,7 @@
 import re
 from collections.abc import Callable
 from typing import Any
-from urllib.parse import unquote
+from urllib.parse import parse_qs, unquote
 
 from mcp.types import Annotations
 from mcp.types import ResourceTemplate as MCPResourceTemplate
@@ -26,8 +26,26 @@
 )
 
 
+def extract_query_params(uri_template: str) -> set[str]:
+    """Extract query parameter names from RFC 6570 {?param1,param2} syntax."""
+    match = re.search(r"\{\?([^}]+)\}", uri_template)
+    if match:
+        return {p.strip() for p in match.group(1).split(",")}
+    return set()
+
+
 def build_regex(template: str) -> re.Pattern:
-    parts = re.split(r"(\{[^}]+\})", template)
+    """Build regex pattern for URI template, handling RFC 6570 syntax.
+
+    Supports:
+    - {var} - simple path parameter
+    - {var*} - wildcard path parameter (captures multiple segments)
+    - {?var1,var2} - query parameters (ignored in path matching)
+    """
+    # Remove query parameter syntax for path matching
+    template_without_query = re.sub(r"\{\?[^}]+\}", "", template)
+
+    parts = re.split(r"(\{[^}]+\})", template_without_query)
     pattern = ""
     for part in parts:
         if part.startswith("{") and part.endswith("}"):
@@ -43,11 +61,34 @@ def build_regex(template: str) -> re.Pattern:
 
 
 def match_uri_template(uri: str, uri_template: str) -> dict[str, str] | None:
+    """Match URI against template and extract both path and query parameters.
+
+    Supports RFC 6570 URI templates:
+    - Path params: {var}, {var*}
+    - Query params: {?var1,var2}
+    """
+    # Split URI into path and query parts
+    uri_path, _, query_string = uri.partition("?")
+
+    # Match path parameters
     regex = build_regex(uri_template)
-    match = regex.match(uri)
-    if match:
-        return {k: unquote(v) for k, v in match.groupdict().items()}
-    return None
+    match = regex.match(uri_path)
+    if not match:
+        return None
+
+    params = {k: unquote(v) for k, v in match.groupdict().items()}
+
+    # Extract query parameters if present in URI and template
+    if query_string:
+        query_param_names = extract_query_params(uri_template)
+        parsed_query = parse_qs(query_string)
+
+        for name in query_param_names:
+            if name in parsed_query:
+                # Take first value if multiple provided
+                params[name] = parsed_query[name][0]  # type: ignore[index]
+
+    return params
 
 
 class ResourceTemplate(FastMCPComponent):
@@ -206,6 +247,31 @@ async def read(self, arguments: dict[str, Any]) -> str | bytes:
         if context_kwarg and context_kwarg not in kwargs:
             kwargs[context_kwarg] = get_context()
 
+        # Type coercion for query parameters (which arrive as strings)
+        # Get function signature for type hints
+        sig = inspect.signature(self.fn)
+        for param_name, param_value in list(kwargs.items()):
+            if param_name in sig.parameters and isinstance(param_value, str):
+                param = sig.parameters[param_name]
+                annotation = param.annotation
+
+                # Skip if no annotation or annotation is str
+                if annotation is inspect.Parameter.empty or annotation is str:
+                    continue
+
+                # Handle common type coercions
+                try:
+                    if annotation is int:
+                        kwargs[param_name] = int(param_value)
+                    elif annotation is float:
+                        kwargs[param_name] = float(param_value)
+                    elif annotation is bool:
+                        # Handle boolean strings
+                        kwargs[param_name] = param_value.lower() in ("true", "1", "yes")
+                except (ValueError, AttributeError):
+                    # Let validate_call handle the error
+                    pass
+
         result = self.fn(**kwargs)
         if inspect.isawaitable(result):
             result = await result
@@ -245,38 +311,57 @@ def from_function(
 
         context_kwarg = find_kwarg_by_type(fn, kwarg_type=Context)
 
-        # Validate that URI params match function params
-        uri_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
-        if not uri_params:
+        # Extract path and query parameters from URI template
+        path_params = set(re.findall(r"{(\w+)(?:\*)?}", uri_template))
+        query_params = extract_query_params(uri_template)
+        all_uri_params = path_params | query_params
+
+        if not all_uri_params:
             raise ValueError("URI template must contain at least one parameter")
 
         func_params = set(sig.parameters.keys())
         if context_kwarg:
             func_params.discard(context_kwarg)
 
-        # get the parameters that are required
+        # Get required and optional function parameters
         required_params = {
             p
             for p in func_params
             if sig.parameters[p].default is inspect.Parameter.empty
             and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
             and p != context_kwarg
         }
+        optional_params = {
+            p
+            for p in func_params
+            if sig.parameters[p].default is not inspect.Parameter.empty
+            and sig.parameters[p].kind != inspect.Parameter.VAR_KEYWORD
+            and p != context_kwarg
+        }
+
+        # Validate RFC 6570 query parameters
+        # Query params must be optional (have defaults)
+        if query_params:
+            invalid_query_params = query_params - optional_params
+            if invalid_query_params:
+                raise ValueError(
+                    f"Query parameters {invalid_query_params} must be optional function parameters with default values"
+                )
 
-        # Check if required parameters are a subset of the URI parameters
-        if not required_params.issubset(uri_params):
+        # Check if required parameters are a subset of the path parameters
+        if not required_params.issubset(path_params):
             raise ValueError(
-                f"Required function arguments {required_params} must be a subset of the URI parameters {uri_params}"
+                f"Required function arguments {required_params} must be a subset of the URI path parameters {path_params}"
             )
 
-        # Check if the URI parameters are a subset of the function parameters (skip if **kwargs present)
+        # Check if all URI parameters are valid function parameters (skip if **kwargs present)
         if not any(
             param.kind == inspect.Parameter.VAR_KEYWORD
             for param in sig.parameters.values()
         ):
-            if not uri_params.issubset(func_params):
+            if not all_uri_params.issubset(func_params):
                 raise ValueError(
-                    f"URI parameters {uri_params} must be a subset of the function arguments: {func_params}"
+                    f"URI parameters {all_uri_params} must be a subset of the function arguments: {func_params}"
                 )
 
         description = description or inspect.getdoc(fn)