feat: add an output DTO to MCP

Author: alexislefebvre

tests/Fixtures/TestBundle/Dto/McpBookDto.php

@@ -0,0 +1,28 @@
+<?php
+
+/*
+ * This file is part of the API Platform project.
+ *
+ * (c) Kévin Dunglas <[email protected]>
+ *
+ * For the full copyright and license information, please view the LICENSE
+ * file that was distributed with this source code.
+ */
+
+declare(strict_types=1);
+
+namespace ApiPlatform\Tests\Fixtures\TestBundle\Dto;
+
+use ApiPlatform\Tests\Fixtures\TestBundle\Entity\McpBook as McpBookEntity;
+use Symfony\Component\ObjectMapper\Attribute\Map;
+
+#[Map(source: McpBookEntity::class)]
+final class McpBookDto
+{
+    public int $id;
+
+    #[Map(source: 'title')]
+    public string $name;
+
+    public string $isbn;
+}

tests/Fixtures/TestBundle/Entity/McpBook.php

@@ -16,6 +16,7 @@
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\McpTool;
 use ApiPlatform\Metadata\McpToolCollection;
+use ApiPlatform\Tests\Fixtures\TestBundle\Dto\McpBookDto;
 use ApiPlatform\Tests\Fixtures\TestBundle\Dto\SearchDto;
 use ApiPlatform\Tests\Fixtures\TestBundle\State\McpBookListProcessor;
 use Doctrine\ORM\Mapping as ORM;
@@ -36,6 +37,13 @@
             processor: McpBookListProcessor::class,
             structuredContent: true,
         ),
+        'list_books_dto' => new McpToolCollection(
+            description: 'List Books and return a DTO',
+            input: SearchDto::class,
+            output: McpBookDto::class,
+            processor: [self::class, 'processDto'],
+            structuredContent: true,
+        ),
     ]
 )]
 #[ORM\Entity]
@@ -106,4 +114,14 @@ public static function process($data): mixed
 
         return $data;
     }
+
+    public static function processDto(): McpBookDto
+    {
+        $book = new McpBookDto();
+        $book->id = 528491;
+        $book->name = 'Raiders of the Lost Ark';
+        $book->isbn = '1-528491';
+
+        return $book;
+    }
 }

tests/Functional/McpTest.php

@@ -420,6 +420,7 @@ public function testToolsList(): void
         self::assertContains('generate_markdown', $toolNames);
         self::assertContains('process_message', $toolNames);
         self::assertContains('list_books', $toolNames);
+        self::assertContains('list_books_dto', $toolNames);
 
         foreach ($tools as $tool) {
             self::assertArrayHasKey('name', $tool);
@@ -785,6 +786,82 @@ public function testMcpListBooks(): void
         self::assertArrayHasKeyAndValue('status', 'available', $actualBook);
     }
 
+    public function testMcpListBooksDto(): void
+    {
+        if (!class_exists(McpBundle::class)) {
+            $this->markTestSkipped('MCP bundle is not installed');
+        }
+
+        if ($this->isMongoDB()) {
+            $this->markTestSkipped('MCP is not supported with MongoDB');
+        }
+
+        if (!$this->isPsr17FactoryAvailable()) {
+            $this->markTestSkipped('PSR-17 HTTP factory implementation not available (required for MCP)');
+        }
+
+        $this->recreateSchema([
+            McpBook::class,
+        ]);
+
+        $book = new McpBook();
+        $book->setTitle('API Platform Guide for MCP');
+        $book->setIsbn('1-528491');
+        $book->setStatus('available');
+        $manager = $this->getContainer()->get('doctrine.orm.entity_manager');
+        $manager->persist($book);
+        $manager->flush();
+
+        $client = self::createClient();
+        $sessionId = $this->initializeMcpSession($client);
+
+        $res = $client->request('POST', '/mcp', [
+            'headers' => [
+                'Accept' => 'application/json, text/event-stream',
+                'Content-Type' => 'application/json',
+                'mcp-session-id' => $sessionId,
+            ],
+            'json' => [
+                'jsonrpc' => '2.0',
+                'id' => 2,
+                'method' => 'tools/call',
+                'params' => [
+                    'name' => 'list_books_dto',
+                    'arguments' => [
+                        'search' => '',
+                    ],
+                ],
+            ],
+        ]);
+
+        self::assertResponseIsSuccessful();
+        $result = $res->toArray()['result'] ?? null;
+        self::assertIsArray($result);
+        self::assertArrayHasKey('content', $result);
+        $content = $result['content'][0]['text'] ?? null;
+        self::assertNotNull($content, 'No text content in result');
+        self::assertStringContainsString('Raiders of the Lost Ark', $content);
+        self::assertStringContainsString('1-528491', $content);
+
+        $structuredContent = $result['structuredContent'] ?? null;
+        $this->assertIsArray($structuredContent);
+
+        $actualBook = $structuredContent;
+
+        // when api_platform.use_symfony_listeners is true, the result is formatted as JSON-LD
+        if (true === $this->getContainer()->getParameter('api_platform.use_symfony_listeners')) {
+            self::assertArrayHasKey('@context', $structuredContent);
+            $context = $structuredContent['@context'];
+            self::assertArrayHasKeyAndValue('@vocab', 'http://localhost/docs.jsonld#', $context);
+            self::assertArrayHasKeyAndValue('hydra', 'http://www.w3.org/ns/hydra/core#', $context);
+        }
+
+        self::assertArrayHasKeyAndValue('id', 528491, $actualBook);
+        self::assertArrayHasKeyAndValue('name', 'Raiders of the Lost Ark', $actualBook);
+        self::assertArrayHasKeyAndValue('isbn', '1-528491', $actualBook);
+        self::assertArrayNotHasKey('status', $actualBook);
+    }
+
     private static function assertArrayHasKeyAndValue(string $key, mixed $value, array $data): void
     {
         self::assertArrayHasKey($key, $data);