fix: don't JSON pre-parse string args whose annotation only accepts str or None

pre_parse_json decided whether to json.loads a string argument with
'field_info.annotation is not str', which treats 'str | None' like a
non-string annotation. A valid string value that happens to parse as a
JSON object or array (e.g. a JSON-serialized template body) was silently
replaced with a dict/list and then failed model validation.

Only skip pre-parsing when every union member is str or None, so a plain
string is already fully valid. Unions with non-str members such as
'str | list[str]' keep the existing stringified-JSON handling.

Fixes #3055

Author: akminx

src/mcp/server/mcpserver/utilities/func_metadata.py

@@ -33,6 +33,25 @@ def _is_input_required_type(obj: Any) -> bool:
     return isinstance(obj, type) and issubclass(obj, InputRequiredResult)
 
 
+def _accepts_only_str_or_none(annotation: Any) -> bool:
+    """Whether every member of the annotation is `str` or `None`.
+
+    For such annotations a string value is already fully valid, so JSON
+    pre-parsing could only corrupt it (e.g. `body: str | None` receiving a
+    JSON-serialized string). Unions with non-str members (e.g. `str | list[str]`)
+    still opt in to pre-parsing, since the string may be a stringified value
+    for one of those members.
+    """
+    if annotation is str or annotation is type(None):
+        return True
+    origin = get_origin(annotation)
+    if origin is Annotated:
+        return _accepts_only_str_or_none(get_args(annotation)[0])
+    if is_union_origin(origin):
+        return all(_accepts_only_str_or_none(arg) for arg in get_args(annotation))
+    return False
+
+
 class StrictJsonSchema(GenerateJsonSchema):
     """A JSON schema generator that raises exceptions instead of emitting warnings.
 
@@ -169,7 +188,7 @@ def pre_parse_json(self, data: dict[str, Any]) -> dict[str, Any]:
                 continue
 
             field_info = key_to_field_info[data_key]
-            if isinstance(data_value, str) and field_info.annotation is not str:
+            if isinstance(data_value, str) and not _accepts_only_str_or_none(field_info.annotation):
                 try:
                     pre_parsed = json.loads(data_value)
                 except json.JSONDecodeError:

tests/server/mcpserver/test_func_metadata.py

@@ -204,6 +204,48 @@ def func_with_str_types(str_or_list: str | list[str]):  # pragma: no cover
     assert result["str_or_list"] == ["hello", "world"]
 
 
+def test_optional_str_not_parsed_as_json():
+    """A `str | None` parameter must keep JSON-looking string values as strings.
+
+    Regression test for https://github.com/modelcontextprotocol/python-sdk/issues/3055:
+    the annotation is not literally `str`, but a plain string is already fully
+    valid for it, so pre-parsing could only corrupt the value.
+    """
+
+    def func_with_optional_str(body: str | None = None):  # pragma: no cover
+        return body
+
+    meta = func_metadata(func_with_optional_str)
+
+    json_object_str = '{"blocks": ["a", "b"]}'
+    result = meta.pre_parse_json({"body": json_object_str})
+    assert result["body"] == json_object_str
+    validated = meta.arg_model.model_validate(result)
+    assert getattr(validated, "body") == json_object_str
+
+    json_array_str = '["a", "b"]'
+    result = meta.pre_parse_json({"body": json_array_str})
+    assert result["body"] == json_array_str
+
+    # Annotated str members are unwrapped before the check
+    def func_with_annotated_str(
+        body: Annotated[str, Field(description="a body")] | None = None,
+    ):  # pragma: no cover
+        return body
+
+    meta = func_metadata(func_with_annotated_str)
+    result = meta.pre_parse_json({"body": json_object_str})
+    assert result["body"] == json_object_str
+
+    # A union with a non-str member still opts in to pre-parsing
+    def func_with_str_list_none(value: str | list[str] | None = None):  # pragma: no cover
+        return value
+
+    meta = func_metadata(func_with_str_list_none)
+    result = meta.pre_parse_json({"value": '["a", "b"]'})
+    assert result["value"] == ["a", "b"]
+
+
 def test_skip_names():
     """Test that skipped parameters are not included in the model"""