fix(jsonschema): don't require @id in single-item MCP output schema

IriConverter returns a null IRI for a non-collection McpTool/McpResource,
so the serializer omits @id but the schema still required it — strict MCP
clients rejected the structuredContent. Kept required for
McpToolCollection members, which do get an IRI.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: alexisLefebvre

src/Hydra/JsonSchema/SchemaFactory.php

@@ -22,6 +22,9 @@
 use ApiPlatform\JsonSchema\SchemaFactoryAwareInterface;
 use ApiPlatform\JsonSchema\SchemaFactoryInterface;
 use ApiPlatform\JsonSchema\SchemaUriPrefixTrait;
+use ApiPlatform\Metadata\CollectionOperationInterface;
+use ApiPlatform\Metadata\McpResource;
+use ApiPlatform\Metadata\McpTool;
 use ApiPlatform\Metadata\Operation;
 use ApiPlatform\Metadata\Resource\Factory\ResourceMetadataCollectionFactoryInterface;
 
@@ -133,7 +136,7 @@ public function buildSchema(string $className, string $format = 'jsonld', string
 
         if (!$collectionKey) {
             $definitionName = $schema->getRootDefinitionKey() ?? $this->definitionNameFactory->create($className, $format, $inputOrOutputClass, $operation, $serializerContext);
-            $this->decorateItemDefinition($definitionName, $definitions, $prefix, $type, $serializerContext);
+            $this->decorateItemDefinition($definitionName, $definitions, $prefix, $type, $serializerContext, $operation);
 
             if (isset($definitions[$definitionName])) {
                 $currentDefinitions = $schema->getDefinitions();
@@ -254,7 +257,7 @@ public function buildSchema(string $className, string $format = 'jsonld', string
         unset($schema['items']);
 
         if (isset($definitions[$collectionKey])) {
-            $this->decorateItemDefinition($collectionKey, $definitions, $prefix, $type, $serializerContext);
+            $this->decorateItemDefinition($collectionKey, $definitions, $prefix, $type, $serializerContext, $operation);
         }
 
         return $schema;
@@ -267,13 +270,16 @@ public function setSchemaFactory(SchemaFactoryInterface $schemaFactory): void
         }
     }
 
-    private function decorateItemDefinition(string $definitionName, \ArrayObject $definitions, string $prefix, string $type, ?array $serializerContext): void
+    private function decorateItemDefinition(string $definitionName, \ArrayObject $definitions, string $prefix, string $type, ?array $serializerContext, ?Operation $operation = null): void
     {
         if (!isset($definitions[$definitionName])) {
             return;
         }
 
-        $hasNoId = Schema::TYPE_OUTPUT === $type && false === ($serializerContext['gen_id'] ?? true);
+        // A single-item MCP operation has no routed item URI: the serializer omits `@id`, so don't require it.
+        $isMcpItem = ($operation instanceof McpTool || $operation instanceof McpResource) && !$operation instanceof CollectionOperationInterface;
+
+        $hasNoId = Schema::TYPE_OUTPUT === $type && (false === ($serializerContext['gen_id'] ?? true) || $isMcpItem);
         $baseName = self::ITEM_BASE_SCHEMA_NAME;
         if ($hasNoId) {
             $baseName = self::ITEM_WITHOUT_ID_BASE_SCHEMA_NAME;

src/Hydra/Tests/JsonSchema/SchemaFactoryTest.php

@@ -23,6 +23,8 @@
 use ApiPlatform\Metadata\ApiResource;
 use ApiPlatform\Metadata\Get;
 use ApiPlatform\Metadata\GetCollection;
+use ApiPlatform\Metadata\McpTool;
+use ApiPlatform\Metadata\McpToolCollection;
 use ApiPlatform\Metadata\Property\Factory\PropertyMetadataFactoryInterface;
 use ApiPlatform\Metadata\Property\Factory\PropertyNameCollectionFactoryInterface;
 use ApiPlatform\Metadata\Property\PropertyNameCollection;
@@ -161,6 +163,32 @@ public function testSchemaTypeBuildSchema(): void
         $this->assertEquals($resultSchema['allOf'][0]['$ref'], $forcedCollection['allOf'][0]['$ref']);
     }
 
+    // Single-item McpTool: serializer omits `@id`, so the output schema must not require it.
+    public function testSingleItemMcpToolOutputSchemaDoesNotRequireId(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new McpTool(class: Dummy::class));
+
+        $definitions = $resultSchema->getDefinitions();
+        $rootDefinitionKey = $resultSchema->getRootDefinitionKey();
+
+        $this->assertSame(['$ref' => '#/definitions/HydraItemBaseSchemaWithoutId'], $definitions[$rootDefinitionKey]['allOf'][0]);
+        $this->assertArrayHasKey('HydraItemBaseSchemaWithoutId', $definitions);
+        $this->assertSame(['@type'], $definitions['HydraItemBaseSchemaWithoutId']['required']);
+        $this->assertArrayNotHasKey('HydraItemBaseSchema', $definitions);
+    }
+
+    // McpToolCollection: members get `@id` (member normalization sets item_uri_template), so it stays required.
+    public function testMcpToolCollectionOutputSchemaStillRequiresIdOnMembers(): void
+    {
+        $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new McpToolCollection(class: Dummy::class));
+
+        $definitions = $resultSchema->getDefinitions();
+
+        $this->assertSame(['$ref' => '#/definitions/HydraItemBaseSchema'], $definitions['Dummy.jsonld']['allOf'][0]);
+        $this->assertSame(['@id', '@type'], $definitions['HydraItemBaseSchema']['required']);
+        $this->assertArrayNotHasKey('HydraItemBaseSchemaWithoutId', $definitions);
+    }
+
     public function testSchemaTypeBuildSchemaWithoutPrefix(): void
     {
         $resultSchema = $this->schemaFactory->buildSchema(Dummy::class, 'jsonld', Schema::TYPE_OUTPUT, new GetCollection(), null, [ContextBuilder::HYDRA_CONTEXT_HAS_PREFIX => false]);