Documentation MCP Server

Instructions

Implementation Reference

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

  Primary handler function that executes the docs_generate_openapi tool: analyzes PHP project, generates OpenAPI spec, exports to JSON/YAML file.
  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:202-237 (registration)

  Tool registration in the tools list, including name, 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/index.ts:333-382 (schema)

  Output structure and error handling defined in the handler response format.
  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/tools/generateOpenApi.ts:31-112 (helper)

  Core helper function that generates the OpenAPI 3.0 spec from PHP file analysis, handling routes, parameters, middleware, and security schemes.
  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-112 (helper)

  Type definition for the generated OpenAPI specification structure.
  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[]>>; } /** * Generate OpenAPI specification from analyzed files */ 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/index.ts:314-315 (registration)

  Dispatch/registration in the CallToolRequest handler switch statement.
  case "docs_generate_openapi": return await generateOpenApi(args);