π The fast, Pythonic way to build MCP servers and clients.
Fix query parameter serialization to respect OpenAPI explode/style settings (#3595)
Jeremiah Lowin6f30e89dd16e
diff --git a/src/fastmcp/utilities/openapi/director.py b/src/fastmcp/utilities/openapi/director.pyindex 537fdffdc..6b2d6eb95 100644--- a/src/fastmcp/utilities/openapi/director.py+++ b/src/fastmcp/utilities/openapi/director.py@@ -1,6 +1,6 @@"""Request director using openapi-core for stateless HTTP request building."""-from typing import Any+from typing import Any, ClassVarfrom urllib.parse import quote, urljoinimport httpx@@ -8,11 +8,22 @@ from jsonschema_path import SchemaPathfrom fastmcp.utilities.logging import get_logger-from .models import HTTPRoute+from .models import HTTPRoute, ParameterInfologger = get_logger(__name__)+def _query_scalar_to_str(value: Any) -> str:+ """Convert a scalar to its query-string representation.++ Booleans are lowercased to match JSON/OpenAPI conventions (true/false)+ rather than Python's str(True) β "True".+ """+ if isinstance(value, bool):+ return "true" if value else "false"+ return str(value)++class RequestDirector:"""Builds httpx.Request objects from HTTPRoute and arguments using openapi-core."""@@ -50,24 +61,27 @@ class RequestDirector:f"Unflattened - path: {path_params}, query: {query_params}, headers: {header_params}, body: {body}")- # Step 2: Build base URL with path parameters+ # Step 2: Serialize query parameters according to OpenAPI style/explode+ query_params = self._serialize_query_params(route, query_params)++ # Step 3: Build base URL with path parametersurl = self._build_url(route.path, path_params, base_url)- # Step 3: Prepare request data+ # Step 4: Prepare request datamethod: str = route.method.upper()params = query_params if query_params else Noneheaders = header_params if header_params else Nonejson_body: dict[str, Any] | list[Any] | None = Nonecontent: str | bytes | None = None- # Step 4: Handle request body+ # Step 5: Handle request bodyif body is not None:if isinstance(body, dict | list):json_body = bodyelse:content = body- # Step 5: Create httpx.Request+ # Step 6: Create httpx.Requestreturn httpx.Request(method=method,url=url,@@ -191,6 +205,65 @@ class RequestDirector:return path_params, query_params, header_params, body+ # Delimiter per OpenAPI style when explode=false+ _STYLE_DELIMITERS: ClassVar[dict[str, str]] = {+ "form": ",",+ "spaceDelimited": " ",+ "pipeDelimited": "|",+ }++ def _serialize_query_params(+ self,+ route: HTTPRoute,+ query_params: dict[str, Any],+ ) -> dict[str, Any]:+ """+ Serialize query parameter values according to their OpenAPI style/explode settings.++ By default (style=form, explode=true), list values are passed through as-is+ so httpx repeats the key (e.g. values=a&values=b). When explode=false,+ list values are joined with the style-appropriate delimiter:+ - form (default): comma (values=a,b)+ - pipeDelimited: pipe (values=a|b)+ - spaceDelimited: space (values=a%20b)+ """+ if not query_params:+ return query_params++ # Build a lookup from openapi_name -> ParameterInfo for query params+ param_lookup: dict[str, ParameterInfo] = {+ p.name: p for p in route.parameters if p.location == "query"+ }++ serialized: dict[str, Any] = {}+ for key, value in query_params.items():+ param_info = param_lookup.get(key)+ if param_info is not None:+ explode = param_info.explode if param_info.explode is not None else True+ if not explode:+ style = param_info.style or "form"+ delimiter = self._STYLE_DELIMITERS.get(style, ",")+ if isinstance(value, list):+ if not value:+ continue+ serialized[key] = delimiter.join(+ _query_scalar_to_str(v) for v in value+ )+ continue+ elif isinstance(value, dict):+ if not value:+ continue+ # form,explode=false on objects: key,value pairs+ # e.g. {"R": 100, "G": 200} β "R,100,G,200"+ parts: list[str] = []+ for k, v in value.items():+ parts.append(_query_scalar_to_str(k))+ parts.append(_query_scalar_to_str(v))+ serialized[key] = delimiter.join(parts)+ continue+ serialized[key] = value+ return serialized+def _build_url(self, path_template: str, path_params: dict[str, Any], base_url: str) -> str:diff --git a/tests/utilities/openapi/test_director.py b/tests/utilities/openapi/test_director.pyindex edad3eab2..4f7a8f514 100644--- a/tests/utilities/openapi/test_director.py+++ b/tests/utilities/openapi/test_director.py@@ -385,6 +385,305 @@ class TestRequestDirector:assert body_data == {"prop1": "value1", "prop2": "value2"}+class TestQueryParameterSerialization:+ """Test that query parameters respect OpenAPI explode/style settings."""++ @pytest.fixture+ def director(self, basic_openapi_30_spec):+ spec = SchemaPath.from_dict(basic_openapi_30_spec)+ return RequestDirector(spec)++ def test_explode_true_repeats_keys(self, director):+ """Default behavior: explode=true sends values=a&values=b."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="values",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "string"}},+ explode=True,+ )+ ],+ parameter_map={+ "values": {"location": "query", "openapi_name": "values"},+ },+ )++ request = director.build(+ route, {"values": ["hello", "world"]}, "https://example.com"+ )+ url = str(request.url)+ assert "values=hello" in url+ assert "values=world" in url++ def test_explode_false_comma_joins(self, director):+ """explode=false sends values=hello,world."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="values",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "string"}},+ explode=False,+ )+ ],+ parameter_map={+ "values": {"location": "query", "openapi_name": "values"},+ },+ )++ request = director.build(+ route, {"values": ["hello", "world"]}, "https://example.com"+ )+ url = str(request.url)+ assert "values=hello%2Cworld" in url or "values=hello,world" in url+ # Must NOT have repeated keys+ assert url.count("values=") == 1++ def test_explode_none_defaults_to_true(self, director):+ """When explode is unset, OpenAPI default for form style is explode=true."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="tags",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "string"}},+ explode=None,+ )+ ],+ parameter_map={+ "tags": {"location": "query", "openapi_name": "tags"},+ },+ )++ request = director.build(route, {"tags": ["a", "b"]}, "https://example.com")+ url = str(request.url)+ assert "tags=a" in url+ assert "tags=b" in url++ def test_explode_false_with_integers(self, director):+ """explode=false works with non-string values."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="ids",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "integer"}},+ explode=False,+ )+ ],+ parameter_map={+ "ids": {"location": "query", "openapi_name": "ids"},+ },+ )++ request = director.build(route, {"ids": [1, 2, 3]}, "https://example.com")+ url = str(request.url)+ assert "ids=1%2C2%2C3" in url or "ids=1,2,3" in url+ assert url.count("ids=") == 1++ def test_scalar_query_param_unaffected_by_explode(self, director):+ """Non-list values pass through regardless of explode setting."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="get_item",+ parameters=[+ ParameterInfo(+ name="name",+ location="query",+ required=True,+ schema={"type": "string"},+ explode=False,+ )+ ],+ parameter_map={+ "name": {"location": "query", "openapi_name": "name"},+ },+ )++ request = director.build(route, {"name": "foo"}, "https://example.com")+ assert "name=foo" in str(request.url)++ def test_pipe_delimited_explode_false(self, director):+ """style=pipeDelimited, explode=false sends ids=1|2|3."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="ids",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "string"}},+ explode=False,+ style="pipeDelimited",+ )+ ],+ parameter_map={+ "ids": {"location": "query", "openapi_name": "ids"},+ },+ )++ request = director.build(route, {"ids": ["1", "2", "3"]}, "https://example.com")+ url = str(request.url)+ assert "ids=1%7C2%7C3" in url or "ids=1|2|3" in url+ assert url.count("ids=") == 1++ def test_space_delimited_explode_false(self, director):+ """style=spaceDelimited, explode=false sends ids=1%202%203."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="ids",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "string"}},+ explode=False,+ style="spaceDelimited",+ )+ ],+ parameter_map={+ "ids": {"location": "query", "openapi_name": "ids"},+ },+ )++ request = director.build(route, {"ids": ["1", "2", "3"]}, "https://example.com")+ url = str(request.url)+ assert "ids=1+2+3" in url or "ids=1%202%203" in url+ assert url.count("ids=") == 1++ def test_explode_false_booleans_lowercased(self, director):+ """Booleans serialize as true/false, not True/False."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="flags",+ location="query",+ required=True,+ schema={"type": "array", "items": {"type": "boolean"}},+ explode=False,+ )+ ],+ parameter_map={+ "flags": {"location": "query", "openapi_name": "flags"},+ },+ )++ request = director.build(route, {"flags": [True, False]}, "https://example.com")+ url = str(request.url)+ assert "true" in url and "false" in url+ assert "True" not in url and "False" not in url++ def test_explode_false_empty_list_omitted(self, director):+ """Empty list with explode=false omits the parameter entirely."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="ids",+ location="query",+ required=False,+ schema={"type": "array", "items": {"type": "string"}},+ explode=False,+ )+ ],+ parameter_map={+ "ids": {"location": "query", "openapi_name": "ids"},+ },+ )++ request = director.build(route, {"ids": []}, "https://example.com")+ assert "ids" not in str(request.url)++ def test_explode_false_dict_value(self, director):+ """style=form, explode=false on objects serializes as key,value pairs."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="color",+ location="query",+ required=True,+ schema={+ "type": "object",+ "properties": {+ "R": {"type": "integer"},+ "G": {"type": "integer"},+ "B": {"type": "integer"},+ },+ },+ explode=False,+ style="form",+ )+ ],+ parameter_map={+ "color": {"location": "query", "openapi_name": "color"},+ },+ )++ request = director.build(+ route,+ {"color": {"R": 100, "G": 200, "B": 150}},+ "https://example.com",+ )+ url = str(request.url)+ assert "color=R" in url+ assert url.count("color=") == 1+ # Should contain alternating key,value pairs+ assert "100" in url and "200" in url and "150" in url++ def test_explode_false_empty_dict_omitted(self, director):+ """Empty dict with explode=false omits the parameter."""+ route = HTTPRoute(+ path="/items",+ method="GET",+ operation_id="list_items",+ parameters=[+ ParameterInfo(+ name="filter",+ location="query",+ required=False,+ schema={"type": "object"},+ explode=False,+ )+ ],+ parameter_map={+ "filter": {"location": "query", "openapi_name": "filter"},+ },+ )++ request = director.build(route, {"filter": {}}, "https://example.com")+ assert "filter" not in str(request.url)++class TestRequestDirectorIntegration:"""Test RequestDirector with real parsed routes."""