Documentation MCP Server

Instructions

Implementation Reference

• src/index.ts:333-382 (handler)

  Main handler function 'generateOpenApi' that orchestrates project analysis, OpenAPI spec generation, and file export for the 'docs_generate_openapi' tool.
  async function generateOpenApi(args: any) { const projectPath = args.projectPath as string; const outputPath = (args.outputPath as string) || './openapi.json'; const format = (args.format as string) || 'json'; const title = args.title as string; const version = args.version as string; const serverUrl = args.serverUrl as string; try { // Analyze project first const analysisResult = await analyzeProject({ projectPath, language: 'php', deep: true, }); // Extract file analysis from result const files = analysisResult.content[0].text; const analysis = JSON.parse(files); // Generate OpenAPI spec const spec = generateOpenApiSpec(analysis.deepAnalysis?.files || [], { title, version, serverUrl, }); // Export to file const fs = await import('fs/promises'); const path = await import('path'); const fullPath = path.resolve(projectPath, outputPath); const content = format === 'yaml' ? exportOpenApiYaml(spec) : exportOpenApiJson(spec); await fs.writeFile(fullPath, content, 'utf-8'); return { content: [ { type: "text", text: `✅ OpenAPI ${format.toUpperCase()} specification generated successfully!\n\nFile: ${fullPath}\n\nStats:\n- Paths: ${Object.keys(spec.paths).length}\n- Security Schemes: ${spec.components?.securitySchemes ? Object.keys(spec.components.securitySchemes).length : 0}\n\nPreview:\n${JSON.stringify(spec, null, 2).substring(0, 1000)}...`, }, ], }; } catch (error) { throw new Error(`Failed to generate OpenAPI spec: ${error}`); } }
• src/index.ts:203-237 (registration)

  Registration of the 'docs_generate_openapi' tool in the tools array, including description and input schema definition.
  name: "docs_generate_openapi", description: "Generate OpenAPI 3.0 specification from analyzed PHP routes with middleware, parameters, and security schemes. Automatically converts controller routes to API documentation.", inputSchema: { type: "object", properties: { projectPath: { type: "string", description: "Path to the PHP project directory to analyze", }, outputPath: { type: "string", description: "Output path for OpenAPI spec file (default: ./openapi.json)", }, format: { type: "string", description: "Output format", enum: ["json", "yaml"], default: "json", }, title: { type: "string", description: "API title (default: 'API Documentation')", }, version: { type: "string", description: "API version (default: '1.0.0')", }, serverUrl: { type: "string", description: "API server URL (e.g., 'https://api.example.com')", }, }, required: ["projectPath"], }, },
• src/tools/generateOpenApi.ts:31-112 (handler)

  Core implementation function 'generateOpenApiSpec' that builds the OpenAPI 3.0 specification from analyzed PHP files, routes, middleware, and parameters.
  export function generateOpenApiSpec( files: FileAnalysis[], options: { title?: string; version?: string; description?: string; serverUrl?: string; } = {} ): OpenAPISpec { const spec: OpenAPISpec = { openapi: '3.0.0', info: { title: options.title || 'API Documentation', version: options.version || '1.0.0', description: options.description || 'Auto-generated API documentation from code analysis', }, paths: {}, components: { securitySchemes: {}, schemas: {}, }, }; if (options.serverUrl) { spec.servers = [ { url: options.serverUrl, description: 'API Server', }, ]; } // Collect all security schemes from middleware const securitySchemes = new Set<string>(); // Process each file for (const file of files) { if (!file.classes) continue; for (const classInfo of file.classes) { if (!classInfo.routes || classInfo.routes.length === 0) continue; // Process each route for (const route of classInfo.routes) { const pathItem = convertRouteToOpenAPI(route, classInfo.name || 'Unknown', file.frameworkInfo?.name); // Add to paths if (!spec.paths[route.path]) { spec.paths[route.path] = {}; } // Add each HTTP method for (const httpMethod of route.httpMethods) { spec.paths[route.path][httpMethod.toLowerCase()] = pathItem; // Collect security schemes if (route.middleware) { for (const middleware of route.middleware) { securitySchemes.add(middleware.name); } } } } } } // Add security schemes spec.components!.securitySchemes = generateSecuritySchemes(Array.from(securitySchemes)); // Remove empty components if (Object.keys(spec.components!.securitySchemes || {}).length === 0) { delete spec.components!.securitySchemes; } if (Object.keys(spec.components!.schemas || {}).length === 0) { delete spec.components!.schemas; } if (Object.keys(spec.components || {}).length === 0) { delete spec.components; } return spec; }
• src/tools/generateOpenApi.ts:9-26 (schema)

  Type definition for the OpenAPI specification object used throughout the implementation.
  export interface OpenAPISpec { openapi: string; info: { title: string; version: string; description?: string; }; servers?: Array<{ url: string; description?: string; }>; paths: Record<string, any>; components?: { schemas?: Record<string, any>; securitySchemes?: Record<string, any>; }; security?: Array<Record<string, string[]>>; }
• src/tools/generateOpenApi.ts:117-167 (helper)

  Helper function 'convertRouteToOpenAPI' that converts individual route information into OpenAPI path operation objects.
  function convertRouteToOpenAPI( route: RouteInfo, className: string, framework?: string | null ): any { const operation: any = { summary: `${className}.${route.method}`, description: `Route: ${route.path}`, operationId: `${className}_${route.method}`, tags: [className], parameters: [], responses: { '200': { description: 'Successful response', content: { 'application/json': { schema: { type: 'object', }, }, }, }, '400': { description: 'Bad request', }, '401': { description: 'Unauthorized', }, '500': { description: 'Internal server error', }, }, }; // Add parameters for (const param of route.parameters) { operation.parameters.push(convertParameterToOpenAPI(param, route.path)); } // Add security from middleware if (route.middleware && route.middleware.length > 0) { operation.security = []; for (const middleware of route.middleware) { operation.security.push({ [middleware.name]: middleware.parameters, }); } } return operation; }