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

src/Capability/Discovery/Discoverer.php

@@ -222,6 +222,7 @@ class Discoverer
                     $name = $instance->name ?? ('__invoke' === $methodName ? $classShortName : $methodName);
                     $description = $instance->description ?? $this->docBlockParser->getSummary($docBlock) ?? null;
                     $inputSchema = $this->schemaGenerator->generate($method);
+                    $outputSchema = $this->schemaGenerator->generateOutputSchema($method);
                     $tool = new Tool(
                         $name,
                         $inputSchema,
@@ -229,6 +230,7 @@ class Discoverer
                         $instance->annotations,
                         $instance->icons,
                         $instance->meta,
+                        $outputSchema,
                     );
                     $tools[$name] = new ToolReference($tool, [$className, $methodName], false);
                     ++$discoveredCount['tools'];

src/Capability/Discovery/SchemaGenerator.php

@@ -11,6 +11,7 @@
 
 namespace Mcp\Capability\Discovery;
 
+use Mcp\Capability\Attribute\McpTool;
 use Mcp\Capability\Attribute\Schema;
 use Mcp\Exception\InvalidArgumentException;
 use Mcp\Server\RequestContext;
@@ -81,6 +82,27 @@ class SchemaGenerator
         return $this->buildSchemaFromParameters($parametersInfo, $methodSchema);
     }
 
+    /**
+     * Generates a JSON Schema object (as a PHP array) for a method's or function's return type.
+     *
+     * Only returns an outputSchema if explicitly provided in the McpTool attribute.
+     * Per MCP spec, outputSchema should only be present when explicitly provided.
+     *
+     * @return array<string, mixed>|null
+     */
+    public function generateOutputSchema(\ReflectionMethod|\ReflectionFunction $reflection): ?array
+    {
+        // Only return outputSchema if explicitly provided in McpTool attribute
+        $mcpToolAttrs = $reflection->getAttributes(McpTool::class, \ReflectionAttribute::IS_INSTANCEOF);
+        if ($mcpToolAttrs) {
+            $mcpToolInstance = $mcpToolAttrs[0]->newInstance();
+
+            return $mcpToolInstance->outputSchema;
+        }
+
+        return null;
+    }
+
     /**
      * Extracts method-level or function-level Schema attribute.
      *