core/api
8
0
Fork 0
Code Issues 4 Pull requests Projects Releases Packages Wiki Activity Actions

feat(api-docs): document MCP tool call body

Browse source 
Co-Authored-By: Virgil <virgil@lethean.io>
This commit is contained in:
Virgil 2026-04-01 18:12:30 +00:00
parent cdef85dcc9
commit 6e878778dc
2 changed files with 56 additions and 2 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

41
src/php/src/Api/Documentation/OpenApiBuilder.php
View file

@ -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' => [

17
src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php
View file

@ -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();
});
});
// ─────────────────────────────────────────────────────────────────────────────