StructuredContent call tool result, added ability to return error from tool

Author: ineersa

src/Schema/Result/CallToolResult.php

@@ -17,7 +17,6 @@
 use Mcp\Schema\Content\EmbeddedResource;
 use Mcp\Schema\Content\ImageContent;
 use Mcp\Schema\Content\TextContent;
-use Mcp\Schema\JsonRpc\ResultInterface;
 
 /**
  * The server's response to a tool call.
@@ -33,7 +32,7 @@
  *
  * @author Kyrian Obikwelu <[email protected]>
  */
-class CallToolResult implements ResultInterface
+class CallToolResult implements CallToolResultInterface
 {
     /**
      * Create a new CallToolResult.

src/Schema/Result/CallToolResultInterface.php

@@ -0,0 +1,18 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Schema\Result;
+
+use Mcp\Schema\JsonRpc\ResultInterface;
+
+interface CallToolResultInterface extends ResultInterface
+{
+}

src/Schema/Result/CallToolStructuredContentResult.php

@@ -0,0 +1,34 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Schema\Result;
+
+class CallToolStructuredContentResult implements CallToolResultInterface
+{
+    /**
+     * Creates a new CallToolResult with structured content.
+     *
+     * @see https://modelcontextprotocol.io/specification/2025-06-18/server/tools#structured-content
+     *
+     * @param mixed[]                 $structuredContent JSON content for `structuredContent`
+     * @param CallToolResultInterface $callToolResult    Traditional result
+     */
+    public function __construct(
+        public readonly array $structuredContent,
+        public readonly CallToolResultInterface $callToolResult,
+    ) {
+    }
+
+    public function jsonSerialize(): mixed
+    {
+        return ['structuredContent' => $this->structuredContent] + $this->callToolResult->jsonSerialize();
+    }
+}

src/Server/Handler/Request/CallToolHandler.php

@@ -21,6 +21,7 @@
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CallToolResultInterface;
 use Mcp\Server\Session\SessionInterface;
 use Psr\Log\LoggerInterface;
 use Psr\Log\NullLogger;
@@ -59,14 +60,17 @@ public function handle(Request $request, SessionInterface $session): Response|Er
             }
 
             $result = $this->referenceHandler->handle($reference, $arguments);
-            $formatted = $reference->formatResult($result);
+
+            if (!$result instanceof CallToolResultInterface) {
+                $result = new CallToolResult($reference->formatResult($result));
+            }
 
             $this->logger->debug('Tool executed successfully', [
                 'name' => $toolName,
                 'result_type' => \gettype($result),
             ]);
 
-            return new Response($request->getId(), new CallToolResult($formatted));
+            return new Response($request->getId(), $result);
         } catch (ToolNotFoundException $e) {
             $this->logger->error('Tool not found', ['name' => $toolName]);
 

tests/Unit/Schema/Result/CallToolStructuredContentResultTest.php

@@ -0,0 +1,65 @@
+<?php
+
+/*
+ * This file is part of the official PHP MCP SDK.
+ *
+ * A collaboration between Symfony and the PHP Foundation.
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+namespace Mcp\Tests\Unit\Schema\Result;
+
+use Mcp\Schema\Content\TextContent;
+use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CallToolStructuredContentResult;
+use PHPUnit\Framework\TestCase;
+
+class CallToolStructuredContentResultTest extends TestCase
+{
+    /**
+     * @dataProvider provideJsonSerializeScenarios
+     *
+     * @param array<string, mixed> $structuredContent
+     * @param array<string, mixed> $expected
+     */
+    public function testJsonSerialize(
+        array $structuredContent,
+        CallToolResult $callToolResult,
+        array $expected,
+    ): void {
+        $result = new CallToolStructuredContentResult($structuredContent, $callToolResult);
+
+        $this->assertEquals($expected, $result->jsonSerialize());
+    }
+
+    /**
+     * @return iterable<string, array{array<string, mixed>, CallToolResult, array<string, mixed>}>
+     */
+    public static function provideJsonSerializeScenarios(): iterable
+    {
+        $successContent = new TextContent('Hello, World!');
+        $errorContent = new TextContent('Failure details');
+
+        yield 'success' => [
+            ['result' => 'Hello, World!'],
+            new CallToolResult([$successContent]),
+            [
+                'structuredContent' => ['result' => 'Hello, World!'],
+                'content' => [$successContent],
+                'isError' => false,
+            ],
+        ];
+
+        yield 'error' => [
+            ['result' => 'Failure details'],
+            CallToolResult::error([$errorContent]),
+            [
+                'structuredContent' => ['result' => 'Failure details'],
+                'content' => [$errorContent],
+                'isError' => true,
+            ],
+        ];
+    }
+}

tests/Unit/Server/Handler/Request/CallToolHandlerTest.php

@@ -21,6 +21,7 @@
 use Mcp\Schema\JsonRpc\Response;
 use Mcp\Schema\Request\CallToolRequest;
 use Mcp\Schema\Result\CallToolResult;
+use Mcp\Schema\Result\CallToolStructuredContentResult;
 use Mcp\Server\Handler\Request\CallToolHandler;
 use Mcp\Server\Session\SessionInterface;
 use PHPUnit\Framework\MockObject\MockObject;
@@ -342,6 +343,63 @@ public function testHandleWithSpecialCharactersInArguments(): void
         $this->assertEquals($expectedResult, $response->result);
     }
 
+    public function testHandleReturnsStructuredContentResult(): void
+    {
+        $request = $this->createCallToolRequest('structured_tool', ['query' => 'php']);
+        $toolReference = $this->createMock(ToolReference::class);
+        $innerResult = new CallToolResult([new TextContent('Rendered results')]);
+        $structuredResult = new CallToolStructuredContentResult(['result' => 'Rendered results'], $innerResult);
+
+        $this->referenceProvider
+            ->expects($this->once())
+            ->method('getTool')
+            ->with('structured_tool')
+            ->willReturn($toolReference);
+
+        $this->referenceHandler
+            ->expects($this->once())
+            ->method('handle')
+            ->with($toolReference, ['query' => 'php'])
+            ->willReturn($structuredResult);
+
+        $toolReference
+            ->expects($this->never())
+            ->method('formatResult');
+
+        $response = $this->handler->handle($request, $this->session);
+
+        $this->assertInstanceOf(Response::class, $response);
+        $this->assertSame($structuredResult, $response->result);
+    }
+
+    public function testHandleReturnsCallToolResult(): void
+    {
+        $request = $this->createCallToolRequest('result_tool', ['query' => 'php']);
+        $toolReference = $this->createMock(ToolReference::class);
+        $callToolResult = new CallToolResult([new TextContent('Rendered results')]);
+
+        $this->referenceProvider
+            ->expects($this->once())
+            ->method('getTool')
+            ->with('result_tool')
+            ->willReturn($toolReference);
+
+        $this->referenceHandler
+            ->expects($this->once())
+            ->method('handle')
+            ->with($toolReference, ['query' => 'php'])
+            ->willReturn($callToolResult);
+
+        $toolReference
+            ->expects($this->never())
+            ->method('formatResult');
+
+        $response = $this->handler->handle($request, $this->session);
+
+        $this->assertInstanceOf(Response::class, $response);
+        $this->assertSame($callToolResult, $response->result);
+    }
+
     /**
      * @param array<string, mixed> $arguments
      */