Fix invalid output schema for tool result/defaultValue fields (#63)

mneudert · web-flow · commit e8925f6cddf7 · 2026-05-27T16:52:38.000+02:00
* Fix invalid output schema for tool result/defaultValue fields

* Add JSON schema validation tests for inputSchema/outputSchema
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -4,6 +4,7 @@
 
 - Updated `mcp/sdk` to 0.5.
 - Surfaced nested SegmentEditor validation messages through MCP tool errors instead of collapsing them to the generic failure message.
+- Aligned the declared MCP `outputSchema` for the `matomo_api_*` tools so the `result` and `defaultValue` entries serialize as `{}` rather than `[]`, matching the MCP requirement that every schema value is a JSON object.
 
 ### 5.0.3
 
diff --git a/McpTools/ApiCallCreate.php b/McpTools/ApiCallCreate.php
@@ -36,7 +36,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiCallToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiCallToolOutputSchema::ITEM;
+        $this->outputSchema = ApiCallToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiCallDelete.php b/McpTools/ApiCallDelete.php
@@ -36,7 +36,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiCallToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiCallToolOutputSchema::ITEM;
+        $this->outputSchema = ApiCallToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiCallFull.php b/McpTools/ApiCallFull.php
@@ -36,7 +36,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiCallToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiCallToolOutputSchema::ITEM;
+        $this->outputSchema = ApiCallToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiCallRead.php b/McpTools/ApiCallRead.php
@@ -35,7 +35,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiCallToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiCallToolOutputSchema::ITEM;
+        $this->outputSchema = ApiCallToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiCallUpdate.php b/McpTools/ApiCallUpdate.php
@@ -36,7 +36,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiCallToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiCallToolOutputSchema::ITEM;
+        $this->outputSchema = ApiCallToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiGet.php b/McpTools/ApiGet.php
@@ -47,7 +47,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiGetToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiMethodSummaryToolOutputSchema::ITEM;
+        $this->outputSchema = ApiMethodSummaryToolOutputSchema::item();
     }
 
     public function shouldRegister(): bool
diff --git a/McpTools/ApiList.php b/McpTools/ApiList.php
@@ -52,7 +52,7 @@ protected function init(): void
             openWorldHint: false,
         );
         $this->inputSchema = ApiListToolInputSchema::SCHEMA;
-        $this->outputSchema = ApiMethodSummaryToolOutputSchema::PAGINATED_LIST;
+        $this->outputSchema = ApiMethodSummaryToolOutputSchema::paginatedList();
     }
 
     public function shouldRegister(): bool
diff --git a/Schemas/Api/ApiCallToolOutputSchema.php b/Schemas/Api/ApiCallToolOutputSchema.php
@@ -13,13 +13,21 @@
 
 final class ApiCallToolOutputSchema
 {
-    public const ITEM = [
-        'type' => 'object',
-        'properties' => [
-            'result' => [],
-            'resolvedMethod' => ApiMethodSummaryToolOutputSchema::ITEM,
-        ],
-        'required' => ['result', 'resolvedMethod'],
-        'additionalProperties' => false,
-    ];
+    /**
+     * @return array<string, mixed>
+     */
+    public static function item(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                // `new \stdClass()` so `json_encode` emits `{}` (an empty JSON Schema =
+                // "any value"); `[]` would encode as `[]` and fail MCP schema validation.
+                'result' => new \stdClass(),
+                'resolvedMethod' => ApiMethodSummaryToolOutputSchema::item(),
+            ],
+            'required' => ['result', 'resolvedMethod'],
+            'additionalProperties' => false,
+        ];
+    }
 }
diff --git a/Schemas/Api/ApiMethodSummaryToolOutputSchema.php b/Schemas/Api/ApiMethodSummaryToolOutputSchema.php
@@ -15,63 +15,83 @@
 
 final class ApiMethodSummaryToolOutputSchema
 {
-    public const PARAMETER = [
-        'type' => 'object',
-        'properties' => [
-            'name' => ['type' => 'string'],
-            'type' => ['type' => ['string', 'null']],
-            'required' => ['type' => 'boolean'],
-            'allowsNull' => ['type' => 'boolean'],
-            'hasDefault' => ['type' => 'boolean'],
-            'defaultValue' => [],
-        ],
-        'required' => ['name', 'type', 'required', 'allowsNull', 'hasDefault', 'defaultValue'],
-        'additionalProperties' => false,
-    ];
-
-    public const ITEM = [
-        'type' => 'object',
-        'properties' => [
-            'module' => ['type' => 'string'],
-            'action' => ['type' => 'string'],
-            'method' => ['type' => 'string'],
-            'parameters' => [
-                'type' => 'array',
-                'items' => self::PARAMETER,
+    /**
+     * @return array<string, mixed>
+     */
+    public static function parameter(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'name' => ['type' => 'string'],
+                'type' => ['type' => ['string', 'null']],
+                'required' => ['type' => 'boolean'],
+                'allowsNull' => ['type' => 'boolean'],
+                'hasDefault' => ['type' => 'boolean'],
+                // `new \stdClass()` so `json_encode` emits `{}` (an empty JSON Schema =
+                // "any value"); `[]` would encode as `[]` and fail MCP schema validation.
+                'defaultValue' => new \stdClass(),
             ],
-            'operationCategory' => [
-                'type' => ['string', 'null'],
-                'enum' => [
-                    ApiMethodOperationClassifier::CATEGORY_READ,
-                    ApiMethodOperationClassifier::CATEGORY_CREATE,
-                    ApiMethodOperationClassifier::CATEGORY_UPDATE,
-                    ApiMethodOperationClassifier::CATEGORY_DELETE,
-                    null,
+            'required' => ['name', 'type', 'required', 'allowsNull', 'hasDefault', 'defaultValue'],
+            'additionalProperties' => false,
+        ];
+    }
+
+    /**
+     * @return array<string, mixed>
+     */
+    public static function item(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'module' => ['type' => 'string'],
+                'action' => ['type' => 'string'],
+                'method' => ['type' => 'string'],
+                'parameters' => [
+                    'type' => 'array',
+                    'items' => self::parameter(),
+                ],
+                'operationCategory' => [
+                    'type' => ['string', 'null'],
+                    'enum' => [
+                        ApiMethodOperationClassifier::CATEGORY_READ,
+                        ApiMethodOperationClassifier::CATEGORY_CREATE,
+                        ApiMethodOperationClassifier::CATEGORY_UPDATE,
+                        ApiMethodOperationClassifier::CATEGORY_DELETE,
+                        null,
+                    ],
                 ],
             ],
-        ],
-        'required' => [
-            'module',
-            'action',
-            'method',
-            'parameters',
-            'operationCategory',
-        ],
-        'additionalProperties' => false,
-    ];
+            'required' => [
+                'module',
+                'action',
+                'method',
+                'parameters',
+                'operationCategory',
+            ],
+            'additionalProperties' => false,
+        ];
+    }
 
-    public const PAGINATED_LIST = [
-        'type' => 'object',
-        'properties' => [
-            'methods' => [
-                'type' => 'array',
-                'items' => self::ITEM,
+    /**
+     * @return array<string, mixed>
+     */
+    public static function paginatedList(): array
+    {
+        return [
+            'type' => 'object',
+            'properties' => [
+                'methods' => [
+                    'type' => 'array',
+                    'items' => self::item(),
+                ],
+                'next_cursor' => ['type' => ['string', 'null']],
+                'has_more' => ['type' => 'boolean'],
+                'total_rows' => ['type' => 'integer'],
             ],
-            'next_cursor' => ['type' => ['string', 'null']],
-            'has_more' => ['type' => 'boolean'],
-            'total_rows' => ['type' => 'integer'],
-        ],
-        'required' => ['methods', 'next_cursor', 'has_more', 'total_rows'],
-        'additionalProperties' => false,
-    ];
+            'required' => ['methods', 'next_cursor', 'has_more', 'total_rows'],
+            'additionalProperties' => false,
+        ];
+    }
 }
diff --git a/tests/Framework/McpToolSchemaMetaschema.php b/tests/Framework/McpToolSchemaMetaschema.php
@@ -0,0 +1,86 @@
+<?php
+
+/**
+ * Matomo - free/libre analytics platform
+ *
+ * @link    https://matomo.org
+ * @license https://www.gnu.org/licenses/gpl-3.0.html GPL v3 or later
+ */
+
+declare(strict_types=1);
+
+namespace Piwik\Plugins\McpServer\tests\Framework;
+
+/**
+ * Returns a JSON metaschema for validating MCP tool inputSchema and outputSchema.
+ *
+ * Encodes the constraints from the canonical MCP schema definition of
+ * `Tool.inputSchema` / `Tool.outputSchema` (see
+ * https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/schema/2025-11-25/schema.json)
+ * and adds a recursive requirement that every nested subschema entry under
+ * `properties`, `items`, `additionalProperties`, `oneOf`, `anyOf`, `allOf`,
+ * or `not` is itself a JSON object. The recursive part catches the common
+ * PHP pitfall of writing `'someProp' => []` where an empty JSON Schema is
+ * intended: that serializes as JSON `[]` rather than `{}`, which fails the
+ * MCP constraint that every schema value is a JSON object.
+ */
+final class McpToolSchemaMetaschema
+{
+    /**
+     * @return array<string, mixed>
+     */
+    public static function get(): array
+    {
+        // Shared between the top-level metaschema and the recursive `jsonSchemaObject` def.
+        $schemaBearingProperties = [
+            'properties' => [
+                'type' => 'object',
+                'additionalProperties' => ['$ref' => '#/$defs/jsonSchemaObject'],
+            ],
+            'items' => ['$ref' => '#/$defs/jsonSchemaObject'],
+            'additionalProperties' => [
+                'anyOf' => [
+                    ['type' => 'boolean'],
+                    ['$ref' => '#/$defs/jsonSchemaObject'],
+                ],
+            ],
+            'oneOf' => [
+                'type' => 'array',
+                'items' => ['$ref' => '#/$defs/jsonSchemaObject'],
+            ],
+            'anyOf' => [
+                'type' => 'array',
+                'items' => ['$ref' => '#/$defs/jsonSchemaObject'],
+            ],
+            'allOf' => [
+                'type' => 'array',
+                'items' => ['$ref' => '#/$defs/jsonSchemaObject'],
+            ],
+            'not' => ['$ref' => '#/$defs/jsonSchemaObject'],
+        ];
+
+        $jsonSchemaObject = [
+            'type' => 'object',
+            'properties' => $schemaBearingProperties,
+        ];
+
+        return [
+            'type' => 'object',
+            '$defs' => [
+                'jsonSchemaObject' => $jsonSchemaObject,
+            ],
+            'properties' => array_merge(
+                [
+                    'type' => ['const' => 'object'],
+                    '$schema' => ['type' => 'string'],
+                    'required' => [
+                        'type' => 'array',
+                        'items' => ['type' => 'string'],
+                    ],
+                ],
+                $schemaBearingProperties,
+            ),
+            'required' => ['type'],
+        ];
+    }
+}
diff --git a/tests/Integration/McpToolSchemaConformanceTest.php b/tests/Integration/McpToolSchemaConformanceTest.php
diff --git a/tests/Integration/McpToolsContractBaselineTest.php b/tests/Integration/McpToolsContractBaselineTest.php

Original file line number	Diff line number	Diff line change
`@@ -36,7 +36,7 @@ protected function init(): void`
`36`	`36`	`openWorldHint: false,`
`37`	`37`	`);`
`38`	`38`	`$this->inputSchema = ApiCallToolInputSchema::SCHEMA;`
`39`		`- $this->outputSchema = ApiCallToolOutputSchema::ITEM;`
	`39`	`+ $this->outputSchema = ApiCallToolOutputSchema::item();`
`40`	`40`	`}`
`41`	`41`
`42`	`42`	`public function shouldRegister(): bool`
Original file line number	Diff line number	Diff line change
`@@ -35,7 +35,7 @@ protected function init(): void`
`35`	`35`	`openWorldHint: false,`
`36`	`36`	`);`
`37`	`37`	`$this->inputSchema = ApiCallToolInputSchema::SCHEMA;`
`38`		`- $this->outputSchema = ApiCallToolOutputSchema::ITEM;`
	`38`	`+ $this->outputSchema = ApiCallToolOutputSchema::item();`
`39`	`39`	`}`
`40`	`40`
`41`	`41`	`public function shouldRegister(): bool`
Original file line number	Diff line number	Diff line change
`@@ -47,7 +47,7 @@ protected function init(): void`
`47`	`47`	`openWorldHint: false,`
`48`	`48`	`);`
`49`	`49`	`$this->inputSchema = ApiGetToolInputSchema::SCHEMA;`
`50`		`- $this->outputSchema = ApiMethodSummaryToolOutputSchema::ITEM;`
	`50`	`+ $this->outputSchema = ApiMethodSummaryToolOutputSchema::item();`
`51`	`51`	`}`
`52`	`52`
`53`	`53`	`public function shouldRegister(): bool`
Original file line number	Diff line number	Diff line change
`@@ -52,7 +52,7 @@ protected function init(): void`
`52`	`52`	`openWorldHint: false,`
`53`	`53`	`);`
`54`	`54`	`$this->inputSchema = ApiListToolInputSchema::SCHEMA;`
`55`		`- $this->outputSchema = ApiMethodSummaryToolOutputSchema::PAGINATED_LIST;`
	`55`	`+ $this->outputSchema = ApiMethodSummaryToolOutputSchema::paginatedList();`
`56`	`56`	`}`
`57`	`57`
`58`	`58`	`public function shouldRegister(): bool`