feat: Add output schema support to MCP tools (#153)

src/Capability/Registry/ToolReference.php

@@ -111,4 +111,33 @@ class ToolReference extends ElementReference
 
         return [new TextContent($jsonResult)];
     }
+
+    /**
+     * Extracts structured content from a tool result using the output schema.
+     *
+     * @param mixed $toolExecutionResult the raw value returned by the tool's PHP method
+     *
+     * @return array<string, mixed>|null the structured content, or null if not extractable
+     *
+     * @throws \JsonException if JSON encoding fails for non-Content array/object results
+     */
+    public function extractStructuredContent(mixed $toolExecutionResult): ?array
+    {
+        if (\is_array($toolExecutionResult)) {
+            return $toolExecutionResult;
+        }
+
+        if (\is_object($toolExecutionResult) && !($toolExecutionResult instanceof Content)) {
+            $jsonResult = json_encode(
+                $toolExecutionResult,
+                \JSON_PRETTY_PRINT | \JSON_UNESCAPED_SLASHES | \JSON_UNESCAPED_UNICODE | \JSON_THROW_ON_ERROR | \JSON_INVALID_UTF8_SUBSTITUTE
+            );
+
+            return json_decode(
+                $jsonResult, true, 512, \JSON_THROW_ON_ERROR
+            );
+        }
+
+        return null;
+    }
 }