feat(api): document SEO and MCP query parameters

Co-Authored-By: Virgil <virgil@lethean.io>

src/php/src/Api/Controllers/Api/SeoReportController.php

@@ -5,6 +5,7 @@ declare(strict_types=1);
 namespace Core\Api\Controllers\Api;
 
 use Core\Api\Concerns\HasApiResponses;
+use Core\Api\Documentation\Attributes\ApiParameter;
 use Core\Api\Documentation\Attributes\ApiTag;
 use Core\Api\Services\SeoReportService;
 use Core\Front\Controller;
@@ -30,6 +31,14 @@ class SeoReportController extends Controller
      *
      * GET /api/seo/report?url=https://example.com
      */
+    #[ApiParameter(
+        name: 'url',
+        in: 'query',
+        type: 'string',
+        description: 'URL to analyse',
+        required: true,
+        format: 'uri'
+    )]
     public function show(Request $request): JsonResponse
     {
         $validated = $request->validate([

src/php/src/Api/Controllers/McpApiController.php

@@ -6,6 +6,7 @@ namespace Core\Api\Controllers;
 
 use Core\Front\Controller;
 use Core\Api\Concerns\HasApiResponses;
+use Core\Api\Documentation\Attributes\ApiParameter;
 use Core\Api\Models\ApiKey;
 use Core\Mod\Mcp\Models\McpApiRequest;
 use Core\Mod\Mcp\Models\McpToolCall;
@@ -70,6 +71,15 @@ class McpApiController extends Controller
      * Query params:
      * - include_versions: bool - include version info for each tool
      */
+    #[ApiParameter(
+        name: 'include_versions',
+        in: 'query',
+        type: 'boolean',
+        description: 'Include version information for each tool',
+        required: false,
+        example: false,
+        default: false
+    )]
     public function tools(Request $request, string $id): JsonResponse
     {
         $server = $this->loadServerFull($id);
@@ -118,6 +128,15 @@ class McpApiController extends Controller
      * Query params:
      * - include_content: bool - include resource content when the definition already contains it
      */
+    #[ApiParameter(
+        name: 'include_content',
+        in: 'query',
+        type: 'boolean',
+        description: 'Include resource content when the definition already contains it',
+        required: false,
+        example: false,
+        default: false
+    )]
     public function resources(Request $request, string $id): JsonResponse
     {
         $server = $this->loadServerFull($id);

src/php/src/Api/Tests/Feature/OpenApiDocumentationComprehensiveTest.php

@@ -175,6 +175,44 @@ describe('OpenApiBuilder Controller Scanning', function () {
     });
 });
 
+// ─────────────────────────────────────────────────────────────────────────────
+// Application Endpoint Parameter Docs
+// ─────────────────────────────────────────────────────────────────────────────
+
+describe('Application Endpoint Parameter Docs', function () {
+    it('documents the SEO report url query parameter', function () {
+        $builder = new OpenApiBuilder;
+        $spec = $builder->build();
+
+        $operation = $spec['paths']['/api/seo/report']['get'];
+        $urlParam = collect($operation['parameters'] ?? [])->firstWhere('name', 'url');
+
+        expect($urlParam)->not->toBeNull();
+        expect($urlParam['in'])->toBe('query');
+        expect($urlParam['required'])->toBeTrue();
+        expect($urlParam['schema']['format'])->toBe('uri');
+    });
+
+    it('documents MCP list query parameters', function () {
+        $builder = new OpenApiBuilder;
+        $spec = $builder->build();
+
+        $toolsOperation = $spec['paths']['/api/mcp/servers/{id}/tools']['get'];
+        $includeVersions = collect($toolsOperation['parameters'] ?? [])->firstWhere('name', 'include_versions');
+
+        expect($includeVersions)->not->toBeNull();
+        expect($includeVersions['in'])->toBe('query');
+        expect($includeVersions['schema']['type'])->toBe('boolean');
+
+        $resourcesOperation = $spec['paths']['/api/mcp/servers/{id}/resources']['get'];
+        $includeContent = collect($resourcesOperation['parameters'] ?? [])->firstWhere('name', 'include_content');
+
+        expect($includeContent)->not->toBeNull();
+        expect($includeContent['in'])->toBe('query');
+        expect($includeContent['schema']['type'])->toBe('boolean');
+    });
+});
+
 // ─────────────────────────────────────────────────────────────────────────────
 // ApiParameter Attribute Parsing
 // ─────────────────────────────────────────────────────────────────────────────