From 6e878778dc53190a7a117ddf40edb254f9df8cb1 Mon Sep 17 00:00:00 2001
From: Virgil <virgil@lethean.io>
Date: Wed, 1 Apr 2026 18:12:30 +0000
Subject: [PATCH] feat(api-docs): document MCP tool call body

Co-Authored-By: Virgil <virgil@lethean.io>
---
 .../src/Api/Documentation/OpenApiBuilder.php  | 41 ++++++++++++++++++-
 .../OpenApiDocumentationComprehensiveTest.php | 17 ++++++++
 2 files changed, 56 insertions(+), 2 deletions(-)

diff --git a/src/php/src/Api/Documentation/OpenApiBuilder.php b/src/php/src/Api/Documentation/OpenApiBuilder.php
index 8a21b8e..81a3a18 100644
--- a/src/php/src/Api/Documentation/OpenApiBuilder.php
+++ b/src/php/src/Api/Documentation/OpenApiBuilder.php
@@ -328,7 +328,7 @@ class OpenApiBuilder
 
         // Add request body for POST/PUT/PATCH
         if (in_array($method, ['post', 'put', 'patch'])) {
-            $operation['requestBody'] = $this->buildRequestBody($controller, $action);
+            $operation['requestBody'] = $this->buildRequestBody($route, $controller, $action);
         }
 
         // Add security requirements
@@ -661,8 +661,45 @@ class OpenApiBuilder
     /**
      * Build request body schema.
      */
-    protected function buildRequestBody(?object $controller, string $action): array
+    protected function buildRequestBody(Route $route, ?object $controller, string $action): array
     {
+        if ($controller instanceof \Core\Api\Controllers\McpApiController && $action === 'callTool') {
+            return [
+                'required' => true,
+                'content' => [
+                    'application/json' => [
+                        'schema' => [
+                            'type' => 'object',
+                            'properties' => [
+                                'server' => [
+                                    'type' => 'string',
+                                    'maxLength' => 64,
+                                    'description' => 'MCP server identifier.',
+                                ],
+                                'tool' => [
+                                    'type' => 'string',
+                                    'maxLength' => 128,
+                                    'description' => 'Tool name to invoke on the selected server.',
+                                ],
+                                'arguments' => [
+                                    'type' => 'object',
+                                    'description' => 'Tool arguments passed through to MCP.',
+                                    'additionalProperties' => true,
+                                ],
+                                'version' => [
+                                    'type' => 'string',
+                                    'maxLength' => 32,
+                                    'description' => 'Optional tool version to execute. Defaults to the latest supported version.',
+                                ],
+                            ],
+                            'required' => ['server', 'tool'],
+                            'additionalProperties' => true,
+                        ],
+                    ],
+                ],
+            ];
+        }
+
         return [
             'required' => true,
             'content' => [
diff --git a/src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php b/src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php
index bfc8255..8bfc5a7 100644
--- a/src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php
+++ b/src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php
@@ -211,6 +211,23 @@ describe('Application Endpoint Parameter Docs', function () {
         expect($includeContent['in'])->toBe('query');
         expect($includeContent['schema']['type'])->toBe('boolean');
     });
+
+    it('documents the MCP tool call request body shape', function () {
+        $builder = new OpenApiBuilder;
+        $spec = $builder->build();
+
+        $operation = $spec['paths']['/api/mcp/tools/call']['post'];
+        $schema = $operation['requestBody']['content']['application/json']['schema'] ?? null;
+
+        expect($schema)->not->toBeNull();
+        expect($schema['type'])->toBe('object');
+        expect($schema['properties'])->toHaveKey('server')
+            ->toHaveKey('tool')
+            ->toHaveKey('arguments')
+            ->toHaveKey('version');
+        expect($schema['required'])->toBe(['server', 'tool']);
+        expect($schema['additionalProperties'])->toBeTrue();
+    });
 });
 
 // ─────────────────────────────────────────────────────────────────────────────