Unwrap Annotated before the str-union check in pre_parse_json

Author: vientooscuro

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

@@ -33,8 +33,18 @@ def _is_input_required_type(obj: Any) -> bool:
     return isinstance(obj, type) and issubclass(obj, InputRequiredResult)
 
 
+def _unwrap_annotated(annotation: Any) -> Any:
+    """Strip `Annotated[...]` down to its underlying type, e.g. for
+    `Annotated[str, Field(description=...)]` (idiomatic for described params).
+    """
+    if get_origin(annotation) is Annotated:
+        return get_args(annotation)[0]
+    return annotation
+
+
 def _is_optional_str(annotation: Any) -> bool:
-    """Whether `annotation` is `str | None` (`Optional[str]`), modulo `None`.
+    """Whether `annotation` is `str | None` (`Optional[str]`), modulo `None`
+    and `Annotated` wrapping.
 
     Used by `pre_parse_json` to skip JSON pre-parsing for such annotations:
     unlike e.g. `str | list[str]`, no member of this union other than `str`
@@ -46,7 +56,7 @@ def _is_optional_str(annotation: Any) -> bool:
     origin = get_origin(annotation)
     if not is_union_origin(origin):
         return False
-    non_none_args = [arg for arg in get_args(annotation) if arg is not type(None)]
+    non_none_args = [_unwrap_annotated(arg) for arg in get_args(annotation) if arg is not type(None)]
     return non_none_args == [str]
 
 

tests/server/mcpserver/test_func_metadata.py

@@ -233,6 +233,24 @@ def func_with_optional_str(body: str | None = None):  # pragma: no cover
     assert result["body"] is None
 
 
+def test_annotated_optional_str_is_never_json_pre_parsed():
+    """`Annotated[str, Field(...)] | None` — idiomatic FastMCP style for a
+    described optional string param — must get the same treatment as plain
+    `str | None`: the `Annotated` wrapper must not defeat the `str` 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)
+
+    json_payload = '{"blocks": ["a", "b"]}'
+    result = meta.pre_parse_json({"body": json_payload})
+    assert result["body"] == json_payload
+
+
 def test_skip_names():
     """Test that skipped parameters are not included in the model"""