feat(mcp): carry union keywords to the provider instead of skipping the tool (#853)

Implements the decision on #848: carry the union, do not skip the tool.

**The rule that was there is sound, but it answered a different
question.** Refusing `anyOf` protects against *dropping* it — a stored
schema without the union permits more than the server does, so a model
can produce arguments the server then rejects. Carrying the keyword
unchanged does not do that: `ToolSpec::toArray()` puts the stored schema
into the provider payload verbatim, and the providers this extension
talks to accept a union in a function schema. The narrowing the server
declared survives end to end.

`anyOf`, `oneOf`, `allOf` and `not` are therefore carried now, and added
to the retained top-level keys so a union declared at the root survives
the filter too (inside a property it rides along with the property
schema, which is copied whole).

**What stays refused, and why the line runs exactly there:**

- `$ref`, `$dynamicRef`, `$defs`, `definitions` — a reference points
into a definition block this filter does not carry, so carrying the
pointer alone would hand the provider a dangling reference. Refusing is
the honest answer until the definition block is carried too.
- `if`/`then`/`else`, `dependentSchemas`, `dependentRequired`,
`unevaluatedProperties`, `patternProperties`, `propertyNames` — the
draft-2019/2020 applicators have no dependable support across providers.
Carrying them would trade an import-time refusal, which names the
keyword since #849, for a call-time failure with a worse message.

**The case that prompted this.** `https://mcp.deepwiki.com/mcp`
advertises three tools; `ask_question` declares `repoName` as
`anyOf[string, array<string>]` and was the one skipped, while its two
siblings imported. That is now the test: the schema is carried verbatim
from the real server's response, and the assertion checks the `anyOf`
block arrives unchanged rather than merely that the tool imports.

**Tests:** the real-world union imports and keeps its `anyOf`; a
top-level union survives the key filter; a `$ref` schema is still
refused and its reason names the keyword. Two existing data-provider
cases asserted the old behaviour for `allOf` and nested `oneOf` — they
are replaced by cases for the applicators that remain refused, so the
provider still pins a real boundary rather than shrinking.

Gates run locally: cgl, PHPStan level 10, the normaliser unit suite, and
the functional `McpImport` suite on sqlite. CI covers the eight-cell
matrix.

Closes #848.

_Assisted by claude-code:claude-fable-5 —
[Session](https://claude.ai/code/session_0144iD1P22LotW8rxmxrNGro)_

Author: CybotTM

CHANGELOG.md

@@ -8,6 +8,7 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ### Changed
 
+- **An MCP tool whose schema uses a union now imports.** `anyOf`, `oneOf`, `allOf` and `not` are carried to the provider verbatim instead of causing the whole tool to be skipped. The rule they were caught by protects against *dropping* a constraint — which would let a model produce arguments the server rejects — and carrying one unchanged does not do that. References (`$ref`, `$defs`) and the draft-2019/2020 applicators (`if`/`then`/`else`, `dependentRequired`, `unevaluatedProperties`, …) stay refused: the first would arrive dangling because the definition block is not carried, the second have no dependable provider support. Concretely, DeepWiki's `ask_question` imports now (#848).
 - **An MCP tool that is skipped on import now says why.** The report used to state that a tool had "no usable parameter schema", which is true and unactionable: an operator could not tell a malformed schema from an oversized one from a well-formed one this import deliberately does not carry. It now names the reason — for the common case, the keyword (`anyOf`, `$ref`, …) whose removal would widen what the tool accepts. The rejections themselves are unchanged.
 
 ## [0.31.1] - 2026-08-20

Classes/Service/Tool/Mcp/McpSchemaNormalizer.php

@@ -49,21 +49,36 @@
      * The only top-level keys carried over. Everything else is either an
      * annotation a provider ignores (`title`, `$id`, `examples`, vendor
      * extensions) or a constraint handled by self::UNSUPPORTED_KEYWORDS.
+     *
+     * The applicators are listed so a union declared at the TOP level survives
+     * the filter; inside a property they ride along with the property schema,
+     * which is copied whole.
      */
     private const RETAINED_KEYS = [
         'type',
         'description',
         'properties',
         'required',
         'additionalProperties',
+        'allOf',
+        'anyOf',
+        'oneOf',
+        'not',
     ];
 
     /**
-     * Keywords whose removal would widen what the server accepts: references
-     * into a definition block we do not carry over, and applicators that
-     * further constrain the arguments. Dropping any of them yields a schema
-     * that permits calls the server rejects, so their presence at any level
-     * rejects the whole schema.
+     * Keywords this import refuses to carry, because carrying them would be a
+     * lie and dropping them would widen what the tool accepts.
+     *
+     * The distinction that decides membership is whether the keyword is
+     * SELF-CONTAINED. A union (`anyOf`) carries its alternatives inline, so
+     * handing it to the provider verbatim preserves exactly what the server
+     * said — those keywords are carried (see self::RETAINED_KEYS). A reference
+     * points into a definition block this filter does not carry, so it would
+     * arrive dangling; and the draft-2019/2020 applicators below have no
+     * dependable support across the providers this extension talks to, so
+     * carrying them trades an import-time refusal for a call-time failure with
+     * a worse error message.
      *
      * A property literally named after one of these keywords is rejected along
      * with them: the walk does not distinguish a schema position from a
@@ -74,10 +89,6 @@
         '$dynamicRef',
         '$defs',
         'definitions',
-        'allOf',
-        'anyOf',
-        'oneOf',
-        'not',
         'if',
         'then',
         'else',

Tests/Unit/Service/Tool/Mcp/Conformance/AbstractMcpConformanceTestCase.php

@@ -238,8 +238,12 @@ public static function unrepresentableSchemas(): array
             'a reference into a definition block we do not carry' => [
                 ['type' => 'object', 'properties' => ['a' => ['$ref' => '#/$defs/a']]],
             ],
-            'an applicator that narrows what the server accepts' => [
-                ['type' => 'object', 'properties' => ['a' => ['anyOf' => [['type' => 'string']]]]],
+            // A union is representable and IS carried now — the guard this case
+            // exists for is the keyword whose removal would widen the schema,
+            // and a keyword carried verbatim never gets removed. What stays
+            // unrepresentable is the applicator no provider dependably reads.
+            'an applicator no provider dependably reads' => [
+                ['type' => 'object', 'properties' => ['a' => ['dependentRequired' => ['x' => ['y']]]]],
             ],
             'a conditional' => [
                 ['type' => 'object', 'if' => ['required' => ['a']], 'then' => ['required' => ['b']]],

Tests/Unit/Service/Tool/Mcp/McpSchemaNormalizerTest.php

@@ -102,12 +102,6 @@ public function aKeywordWeCannotCarryOverRejectsTheWholeSchema(array $inputSchem
      */
     public static function unsupportedKeywordSchemas(): iterable
     {
-        yield 'root allOf' => [[
-            'type'       => 'object',
-            'properties' => ['q' => ['type' => 'string']],
-            'allOf'      => [['required' => ['q']]],
-        ]];
-
         yield 'reference into a dropped definition block' => [[
             'type'       => 'object',
             '$defs'      => ['Id' => ['type' => 'string']],
@@ -119,9 +113,19 @@ public static function unsupportedKeywordSchemas(): iterable
             'properties' => ['id' => ['$ref' => 'https://example.invalid/Id']],
         ]];
 
-        yield 'nested oneOf' => [[
+        // The draft-2019/2020 applicators stay refused: unlike a union they
+        // have no dependable support across the providers this extension talks
+        // to, so carrying them would trade an import-time refusal for a
+        // call-time failure with a worse message.
+        yield 'nested if/then' => [[
             'type'       => 'object',
-            'properties' => ['id' => ['oneOf' => [['type' => 'string'], ['type' => 'integer']]]],
+            'properties' => ['id' => ['if' => ['type' => 'string'], 'then' => ['minLength' => 1]]],
+        ]];
+
+        yield 'root dependentRequired' => [[
+            'type'              => 'object',
+            'properties'        => ['a' => ['type' => 'string'], 'b' => ['type' => 'string']],
+            'dependentRequired' => ['a' => ['b']],
         ]];
     }
 
@@ -236,7 +240,7 @@ private function nestedObjectSchema(int $levels): array
     }
 
     #[Test]
-    public function rejectionReasonNamesTheKeywordForARealWorldSchema(): void
+    public function aRealWorldUnionSchemaIsCarriedThrough(): void
     {
         // Verbatim from https://mcp.deepwiki.com/mcp (tools/list, 2026-08-20):
         // the `ask_question` tool, whose `repoName` accepts either one repo or
@@ -263,11 +267,58 @@ public function rejectionReasonNamesTheKeywordForARealWorldSchema(): void
 
         $subject = new McpSchemaNormalizer();
 
-        self::assertNull($subject->normalise($schema), 'the schema is still refused');
+        $normalised = $subject->normalise($schema);
+        self::assertIsArray($normalised, 'the tool imports instead of being skipped');
+        self::assertNull($subject->rejectionReason($schema));
+
+        // The union survives verbatim: carrying it is what keeps the stored
+        // schema as narrow as the server's own, where dropping it would widen.
+        self::assertIsArray($normalised['properties'] ?? null);
+        $properties = $normalised['properties'];
+        self::assertIsArray($properties['repoName'] ?? null);
+        self::assertSame($schema['properties']['repoName']['anyOf'], $properties['repoName']['anyOf']);
+    }
+
+    #[Test]
+    public function aTopLevelUnionSurvivesTheKeyFilter(): void
+    {
+        // Inside a property the union rides along with the property schema,
+        // which is copied whole. At the top level it only survives because the
+        // applicators are retained keys.
+        $subject = new McpSchemaNormalizer();
+
+        $schema = [
+            'type'  => 'object',
+            'anyOf' => [
+                ['required' => ['a']],
+                ['required' => ['b']],
+            ],
+            'properties' => ['a' => ['type' => 'string'], 'b' => ['type' => 'string']],
+        ];
+
+        $normalised = $subject->normalise($schema);
+        self::assertIsArray($normalised);
+        self::assertSame($schema['anyOf'], $normalised['anyOf'] ?? null);
+    }
+
+    #[Test]
+    public function aReferenceIsStillRefusedBecauseItsTargetIsNotCarried(): void
+    {
+        // The distinction that decides the keyword list: a union carries its
+        // alternatives inline, a $ref points into a $defs block this filter
+        // drops — carrying it would hand the provider a dangling pointer.
+        $subject = new McpSchemaNormalizer();
+
+        $schema = [
+            'type'       => 'object',
+            'properties' => ['repoName' => ['$ref' => '#/$defs/repo']],
+            '$defs'      => ['repo' => ['type' => 'string']],
+        ];
 
+        self::assertNull($subject->normalise($schema));
         $reason = $subject->rejectionReason($schema);
         self::assertIsString($reason);
-        self::assertStringContainsString('anyOf', $reason);
+        self::assertStringContainsString('$', $reason);
     }
 
     #[Test]