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;
  }