Python: Parse MCP CallToolResult.structuredContent field to prevent tool results returning None

.gitignore

@@ -206,6 +206,7 @@ temp*/
 .temp/
 
 # AI
+**/.checkpoints/
 .claude/
 .omc/
 .omx/

python/packages/core/agent_framework/_mcp.py

@@ -539,6 +539,9 @@ def _parse_tool_result_from_mcp(
                 case _:
                     result.append(Content.from_text(str(item)))
 
+        if mcp_type.structuredContent is not None:
+            result.append(Content.from_text(json.dumps(mcp_type.structuredContent, default=str)))
+
         if not result:
             result.append(Content.from_text("null"))
         return result

python/packages/core/agent_framework/_skills.py

@@ -3516,9 +3516,7 @@ async def get_content(self) -> str:
         result = await self._client.read_resource(_mcp_any_url(self._skill_md_uri))
         text = _mcp_join_text(result)
         if not text:
-            raise ValueError(
-                f"The MCP server returned no text content for SKILL.md resource '{self._skill_md_uri}'."
-            )
+            raise ValueError(f"The MCP server returned no text content for SKILL.md resource '{self._skill_md_uri}'.")
         self._content = text
         return text
 
@@ -3572,11 +3570,7 @@ def _validate_resource_name(name: str) -> str | None:
             or ``None`` if the name is unsafe.
         """
         normalized = name.replace("\\", "/")
-        if (
-            normalized.startswith("/")
-            or "://" in normalized
-            or any(seg == ".." for seg in normalized.split("/"))
-        ):
+        if normalized.startswith("/") or "://" in normalized or any(seg == ".." for seg in normalized.split("/")):
             logger.debug("Rejecting resource name with unsafe path components: %r", name)
             return None
         return normalized

python/packages/core/tests/core/test_mcp.py

@@ -342,6 +342,69 @@ def test_parse_tool_result_from_mcp_resource_link_text_resource_and_unknown():
     assert result[1].text == "Embedded result"
 
 
+def test_parse_tool_result_from_mcp_structured_content_only():
+    """Test that structuredContent is parsed when content list is empty."""
+    mcp_result = types.CallToolResult(
+        content=[],
+        structuredContent={"Tables": [{"Name": "Sales", "Columns": ["Amount", "Date"]}]},
+    )
+    result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)
+
+    assert isinstance(result, list)
+    assert len(result) == 1
+    assert result[0].type == "text"
+    parsed = json.loads(result[0].text)
+    assert parsed == {"Tables": [{"Name": "Sales", "Columns": ["Amount", "Date"]}]}
+
+
+def test_parse_tool_result_from_mcp_structured_content_with_text():
+    """Test that structuredContent is appended alongside regular content items."""
+    mcp_result = types.CallToolResult(
+        content=[types.TextContent(type="text", text="Summary")],
+        structuredContent={"data": [1, 2, 3]},
+    )
+    result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)
+
+    assert isinstance(result, list)
+    assert len(result) == 2
+    assert result[0].type == "text"
+    assert result[0].text == "Summary"
+    assert result[1].type == "text"
+    parsed = json.loads(result[1].text)
+    assert parsed == {"data": [1, 2, 3]}
+
+
+def test_parse_tool_result_from_mcp_structured_content_none():
+    """Test that None structuredContent does not affect results."""
+    mcp_result = types.CallToolResult(
+        content=[types.TextContent(type="text", text="Hello")],
+        structuredContent=None,
+    )
+    result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)
+
+    assert isinstance(result, list)
+    assert len(result) == 1
+    assert result[0].type == "text"
+    assert result[0].text == "Hello"
+
+
+def test_parse_tool_result_from_mcp_structured_content_non_serializable():
+    """Test that non-JSON-serializable values in structuredContent degrade gracefully."""
+    mcp_result = types.CallToolResult(
+        content=[],
+        structuredContent={"data": b"raw bytes", "count": 42},
+    )
+    result = _HELPER_MCP_TOOL._parse_tool_result_from_mcp(mcp_result)
+
+    assert isinstance(result, list)
+    assert len(result) == 1
+    assert result[0].type == "text"
+    parsed = json.loads(result[0].text)
+    assert parsed["count"] == 42
+    # bytes should be converted to string representation via default=str
+    assert "raw bytes" in parsed["data"]
+
+
 def test_mcp_content_types_to_ai_content_text():
     """Test conversion of MCP text content to AI content."""
     mcp_content = types.TextContent(type="text", text="Sample text")

python/packages/core/tests/core/test_mcp_observability.py

@@ -76,6 +76,7 @@ def _make_call_tool_result(text: str = "result", is_error: bool = False) -> Mock
     result = Mock()
     result.isError = is_error
     result.content = [types.TextContent(type="text", text=text)]
+    result.structuredContent = None
     return result
 
 
@@ -281,9 +282,7 @@ async def test_mcp_prompts_get_creates_client_span(span_exporter: InMemorySpanEx
 async def test_mcp_prompts_get_mcp_error_sets_error_type(span_exporter: InMemorySpanExporter):
     """When session.get_prompt() raises McpError, the span should have error.type and ERROR status."""
     tool = _make_connected_mcp_tool()
-    tool.session.get_prompt = AsyncMock(
-        side_effect=McpError(ErrorData(code=-32602, message="prompt not found"))
-    )
+    tool.session.get_prompt = AsyncMock(side_effect=McpError(ErrorData(code=-32602, message="prompt not found")))
 
     span_exporter.clear()
     with pytest.raises(ToolExecutionException):