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

src/Capability/Registry/Loader/ArrayLoader.php

@@ -47,7 +47,8 @@ final class ArrayLoader implements LoaderInterface
      *     description: ?string,
      *     annotations: ?ToolAnnotations,
      *     icons: ?Icon[],
-     *     meta: ?array<string, mixed>
+     *     meta: ?array<string, mixed>,
+     *     outputSchema: ?array<string, mixed>
      * }[] $tools
      * @param array{
      *     handler: Handler,
@@ -117,6 +118,7 @@ final class ArrayLoader implements LoaderInterface
                     annotations: $data['annotations'] ?? null,
                     icons: $data['icons'] ?? null,
                     meta: $data['meta'] ?? null,
+                    outputSchema: $data['outputSchema'] ?? null,
                 );
                 $registry->registerTool($tool, $data['handler'], true);
 

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;
+    }
 }