fix(core): Recursive schema parsing for array items

Fixes #552 & googleapis/genai-toolbox#2437

This PR refactors `McpHttpTransportBase` to support recursive schema parsing for nested array types and arrays of complex objects. Previously, `items` definitions were dropped for array parameters, leading to validation errors when mandatory `items` fields were missing.

Author: anubhav756

packages/toolbox-core/src/toolbox_core/mcp_transport/transport_base.py

@@ -81,6 +81,45 @@ def _process_tool_result_content(self, content: list) -> str:
 
         return "".join(texts) or "null"
 
+    def _convert_parameter_schema(
+        self, name: str, schema: dict, required_fields: list[str]
+    ) -> ParameterSchema:
+        """Recursively converts a JSON Schema node to a ParameterSchema."""
+        param_type = schema.get("type", "string")
+        description = schema.get("description", "")
+
+        # Handle Array Recursion
+        items_schema = None
+        if param_type == "array" and "items" in schema:
+            items_data = schema["items"]
+            if isinstance(items_data, dict):
+                # Recursive call for items (items don't have separate required fields usually in this context)
+                items_schema = self._convert_parameter_schema("", items_data, [])
+
+        # Handle Object (Map) AdditionalProperties
+        additional_properties = None
+        if param_type == "object":
+            add_props = schema.get("additionalProperties")
+            if isinstance(add_props, dict) and "type" in add_props:
+                # If it has a type, it's a typed map
+                additional_properties = AdditionalPropertiesSchema(
+                    type=add_props["type"]
+                )
+            elif isinstance(add_props, bool):
+                # If boolean (e.g. True), it allows anything
+                additional_properties = add_props
+            # If None, it technically allows anything (Any) by default in our protocol
+
+        return ParameterSchema(
+            name=name,
+            type=param_type,
+            description=description,
+            required=name in required_fields if name else True,
+            items=items_schema,
+            additionalProperties=additional_properties,
+            # Auth is handled by _convert_tool_schema
+        )
+
     def _convert_tool_schema(self, tool_data: dict) -> ToolSchema:
         """
         Safely converts the raw tool dictionary from the server into a ToolSchema object,
@@ -106,28 +145,14 @@ def _convert_tool_schema(self, tool_data: dict) -> ToolSchema:
         required = input_schema.get("required", [])
 
         for name, schema in properties.items():
-            additional_props = schema.get("additionalProperties")
-            if isinstance(additional_props, dict):
-                additional_props = AdditionalPropertiesSchema(
-                    type=additional_props["type"]
-                )
-            else:
-                additional_props = True
-
+            # Convert basic schema recursively
+            param_schema = self._convert_parameter_schema(name, schema, required)
+            
+            # Apply top-level auth metadata (not recursive for now as per protocol)
             if param_auth and name in param_auth:
-                auth_sources = param_auth[name]
-            else:
-                auth_sources = None
-            parameters.append(
-                ParameterSchema(
-                    name=name,
-                    type=schema["type"],
-                    description=schema.get("description", ""),
-                    required=name in required,
-                    additionalProperties=additional_props,
-                    authSources=auth_sources,
-                )
-            )
+                param_schema.authSources = param_auth[name]
+            
+            parameters.append(param_schema)
 
         return ToolSchema(
             description=tool_data.get("description") or "",

packages/toolbox-core/src/toolbox_core/protocol.py

@@ -92,8 +92,9 @@ def __get_type(self) -> Type:
         base_type: Type
         if self.type == "array":
             if self.items is None:
-                raise ValueError("Unexpected value: type is 'array' but items is None")
-            base_type = list[self.items.__get_type()]  # type: ignore
+                base_type = list[Any]
+            else:
+                base_type = list[self.items.__get_type()]  # type: ignore
         elif self.type == "object":
             if isinstance(self.additionalProperties, AdditionalPropertiesSchema):
                 value_type = self.additionalProperties.get_value_type()

packages/toolbox-core/tests/mcp_transport/test_base.py

@@ -245,3 +245,60 @@ def test_process_tool_result_content(self, transport):
             SimpleNamespace(type="text", text="kept"),
         ]
         assert transport._process_tool_result_content(c6) == "kept"
+
+    def test_convert_tool_schema_recursive(self, transport):
+        """Test converting schema with recursive types (nested arrays, arrays of maps)."""
+        raw_tool = {
+            "name": "recursive_tool",
+            "inputSchema": {
+                "type": "object",
+                "properties": {
+                    # List[List[str]]
+                    "nested_array": {
+                        "type": "array",
+                        "items": {
+                            "type": "array",
+                            "items": {"type": "string"}
+                        }
+                    },
+                    # List[Dict[str, int]]
+                    "array_of_maps": {
+                        "type": "array",
+                        "items": {
+                            "type": "object",
+                            "additionalProperties": {"type": "integer"}
+                        }
+                    },
+                    # Dict[str, List[int]]
+                    "map_of_arrays": {
+                        "type": "object",
+                        "additionalProperties": {
+                            "type": "array",
+                            "items": {"type": "integer"}
+                        }
+                    }
+                }
+            }
+        }
+
+        schema = transport._convert_tool_schema(raw_tool)
+        
+        # 1. Nested Array
+        p_nested = next(p for p in schema.parameters if p.name == "nested_array")
+        assert p_nested.type == "array"
+        assert p_nested.items is not None
+        assert p_nested.items.type == "array"
+        assert p_nested.items.items is not None
+        assert p_nested.items.items.type == "string"
+
+        # 2. Array of Maps
+        p_arr_map = next(p for p in schema.parameters if p.name == "array_of_maps")
+        assert p_arr_map.type == "array"
+        assert p_arr_map.items is not None
+        assert p_arr_map.items.type == "object"
+        assert p_arr_map.items.additionalProperties.type == "integer"
+
+        # 3. Map of Arrays
+        p_map_arr = next(p for p in schema.parameters if p.name == "map_of_arrays")
+        assert p_map_arr.type == "object"
+        assert p_map_arr.additionalProperties.type == "array"

packages/toolbox-core/tests/test_protocol.py

@@ -93,18 +93,22 @@ def test_parameter_schema_array_integer():
     assert param.kind == Parameter.POSITIONAL_OR_KEYWORD
 
 
-def test_parameter_schema_array_no_items_error():
-    """Tests that 'array' type raises error if 'items' is None."""
+
+def test_parameter_schema_array_no_items_defaults_to_any():
+    """Tests that 'array' type defaults to list[Any] if 'items' is None."""
     schema = ParameterSchema(
-        name="bad_list", type="array", description="List without item type"
+        name="any_list", type="array", description="List without item type"
     )
 
-    expected_error_msg = "Unexpected value: type is 'array' but items is None"
-    with pytest.raises(ValueError, match=expected_error_msg):
-        schema._ParameterSchema__get_type()
+    expected_type = list[Any]
+    assert schema._ParameterSchema__get_type() == expected_type
+
+    param = schema.to_param()
+    assert isinstance(param, Parameter)
+    assert param.name == "any_list"
+    assert param.annotation == expected_type
+    assert param.kind == Parameter.POSITIONAL_OR_KEYWORD
 
-    with pytest.raises(ValueError, match=expected_error_msg):
-        schema.to_param()
 
 
 def test_parameter_schema_unsupported_type_error():