@g1cloud/api-gen 1.0.0

package/src/lib.ts

@@ -0,0 +1,240 @@
+/**
+ * Library entry point for programmatic API generation
+ * This module exports the core functionality for use by MCP server and other integrations
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import * as yaml from 'js-yaml';
+import { CLIOptions, ProcessingContext, OpenAPISpec, ControllerInfo } from './types';
+import { parseJavaSource } from './parser/javaParser';
+import { analyzeControllers } from './analyzer/controllerAnalyzer';
+import { generateOpenAPISpec, generateOpenAPISpecForController } from './generator/openapiGenerator';
+
+export interface GenerateOptions {
+  /** Java source directories to parse */
+  source: string[];
+  /** Optional: specific directory to search for RestControllers */
+  apiSource?: string;
+  /** API title */
+  title?: string;
+  /** API version */
+  version?: string;
+  /** API base path */
+  basePath?: string;
+}
+
+export interface GenerateResult {
+  /** Generated OpenAPI spec object */
+  spec: OpenAPISpec;
+  /** YAML string of the spec */
+  yaml: string;
+  /** Summary information */
+  summary: {
+    controllerCount: number;
+    endpointCount: number;
+    schemaCount: number;
+    controllers: Array<{
+      name: string;
+      endpointCount: number;
+    }>;
+  };
+}
+
+export interface GeneratePerControllerResult {
+  /** Map of controller name to generated spec */
+  specs: Map<string, { spec: OpenAPISpec; yaml: string }>;
+  /** Summary information */
+  summary: {
+    controllerCount: number;
+    totalEndpointCount: number;
+    controllers: Array<{
+      name: string;
+      endpointCount: number;
+      schemaCount: number;
+    }>;
+  };
+}
+
+/**
+ * Generate OpenAPI specification from Spring Boot Java source code
+ * Returns a single combined spec for all controllers
+ */
+export async function generateOpenAPI(options: GenerateOptions): Promise<GenerateResult> {
+  const sources = options.source;
+
+  if (sources.length === 0) {
+    throw new Error('At least one source path is required');
+  }
+
+  // Validate source paths exist
+  for (const src of sources) {
+    const sourcePath = path.resolve(src);
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Source path does not exist: ${sourcePath}`);
+    }
+  }
+
+  // Parse Java files from all source directories
+  const javaClasses = new Map<string, any>();
+
+  for (const src of sources) {
+    const sourcePath = path.resolve(src);
+    const classes = await parseJavaSource(sourcePath);
+    for (const [name, cls] of classes) {
+      javaClasses.set(name, cls);
+    }
+  }
+
+  if (javaClasses.size === 0) {
+    throw new Error('No Java files found in the specified directories');
+  }
+
+  // Initialize processing context
+  const apiSourcePath = options.apiSource ? path.resolve(options.apiSource) : undefined;
+  const context: ProcessingContext = {
+    javaClasses,
+    controllers: [],
+    dtoSchemas: new Map(),
+    referencedTypes: new Set(),
+    apiSourcePath,
+  };
+
+  // Analyze controllers
+  const controllers = analyzeControllers(context);
+  context.controllers = controllers;
+
+  if (controllers.length === 0) {
+    throw new Error('No REST controllers found in the source files');
+  }
+
+  // Generate OpenAPI spec
+  const cliOptions: CLIOptions = {
+    source: sources,
+    apiSource: options.apiSource,
+    title: options.title || 'API Documentation',
+    version: options.version || '1.0.0',
+    basePath: options.basePath,
+  };
+
+  const spec = generateOpenAPISpec(controllers, context, cliOptions);
+
+  // Convert to YAML
+  const yamlContent = yaml.dump(spec, {
+    indent: 2,
+    lineWidth: -1,
+    noRefs: true,
+    sortKeys: false,
+  });
+
+  const totalEndpoints = controllers.reduce((sum, c) => sum + c.endpoints.length, 0);
+
+  return {
+    spec,
+    yaml: yamlContent,
+    summary: {
+      controllerCount: controllers.length,
+      endpointCount: totalEndpoints,
+      schemaCount: Object.keys(spec.components.schemas).length,
+      controllers: controllers.map(c => ({
+        name: c.className,
+        endpointCount: c.endpoints.length,
+      })),
+    },
+  };
+}
+
+/**
+ * Generate separate OpenAPI specifications per controller
+ */
+export async function generateOpenAPIPerController(options: GenerateOptions): Promise<GeneratePerControllerResult> {
+  const sources = options.source;
+
+  if (sources.length === 0) {
+    throw new Error('At least one source path is required');
+  }
+
+  // Validate source paths exist
+  for (const src of sources) {
+    const sourcePath = path.resolve(src);
+    if (!fs.existsSync(sourcePath)) {
+      throw new Error(`Source path does not exist: ${sourcePath}`);
+    }
+  }
+
+  // Parse Java files from all source directories
+  const javaClasses = new Map<string, any>();
+
+  for (const src of sources) {
+    const sourcePath = path.resolve(src);
+    const classes = await parseJavaSource(sourcePath);
+    for (const [name, cls] of classes) {
+      javaClasses.set(name, cls);
+    }
+  }
+
+  if (javaClasses.size === 0) {
+    throw new Error('No Java files found in the specified directories');
+  }
+
+  // Initialize processing context
+  const apiSourcePath = options.apiSource ? path.resolve(options.apiSource) : undefined;
+  const context: ProcessingContext = {
+    javaClasses,
+    controllers: [],
+    dtoSchemas: new Map(),
+    referencedTypes: new Set(),
+    apiSourcePath,
+  };
+
+  // Analyze controllers
+  const controllers = analyzeControllers(context);
+  context.controllers = controllers;
+
+  if (controllers.length === 0) {
+    throw new Error('No REST controllers found in the source files');
+  }
+
+  // Generate OpenAPI specs per controller
+  const cliOptions: CLIOptions = {
+    source: sources,
+    apiSource: options.apiSource,
+    title: options.title || 'API Documentation',
+    version: options.version || '1.0.0',
+    basePath: options.basePath,
+  };
+
+  const specs = new Map<string, { spec: OpenAPISpec; yaml: string }>();
+  const controllerSummaries: Array<{ name: string; endpointCount: number; schemaCount: number }> = [];
+
+  for (const controller of controllers) {
+    const spec = generateOpenAPISpecForController(controller, context, cliOptions);
+    const yamlContent = yaml.dump(spec, {
+      indent: 2,
+      lineWidth: -1,
+      noRefs: true,
+      sortKeys: false,
+    });
+
+    specs.set(controller.className, { spec, yaml: yamlContent });
+    controllerSummaries.push({
+      name: controller.className,
+      endpointCount: controller.endpoints.length,
+      schemaCount: Object.keys(spec.components.schemas).length,
+    });
+  }
+
+  const totalEndpoints = controllers.reduce((sum, c) => sum + c.endpoints.length, 0);
+
+  return {
+    specs,
+    summary: {
+      controllerCount: controllers.length,
+      totalEndpointCount: totalEndpoints,
+      controllers: controllerSummaries,
+    },
+  };
+}
+
+// Re-export types for consumers
+export type { CLIOptions, ProcessingContext, OpenAPISpec, ControllerInfo } from './types';

package/src/mcp-server.ts

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+
+/**
+ * MCP Server for Spring Boot to OpenAPI generation
+ *
+ * This server exposes the API generation functionality as MCP tools
+ * that can be called by AI assistants.
+ */
+
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from '@modelcontextprotocol/sdk/types.js';
+import { generateOpenAPI, generateOpenAPIPerController } from './lib';
+
+// Create MCP server
+const server = new Server(
+  {
+    name: 'spring-to-openapi',
+    version: '1.0.0',
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  }
+);
+
+// Define tool schemas
+const tools = [
+  {
+    name: 'generate-openapi',
+    description:
+      'Generate OpenAPI v3 YAML specification from Spring Boot Java source code. Returns a single combined spec for all REST controllers found.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        source: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Java source code directory path(s) to parse',
+        },
+        apiSource: {
+          type: 'string',
+          description:
+            'Optional: specific directory to search for RestControllers (defaults to first source)',
+        },
+        title: {
+          type: 'string',
+          description: 'API title (default: "API Documentation")',
+        },
+        version: {
+          type: 'string',
+          description: 'API version (default: "1.0.0")',
+        },
+        basePath: {
+          type: 'string',
+          description: 'API base path (e.g., "/api/v1")',
+        },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'generate-openapi-per-controller',
+    description:
+      'Generate separate OpenAPI v3 YAML specifications for each REST controller. Useful when you need individual API docs per controller.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        source: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Java source code directory path(s) to parse',
+        },
+        apiSource: {
+          type: 'string',
+          description: 'Optional: specific directory to search for RestControllers',
+        },
+        title: {
+          type: 'string',
+          description: 'API title prefix',
+        },
+        version: {
+          type: 'string',
+          description: 'API version (default: "1.0.0")',
+        },
+        basePath: {
+          type: 'string',
+          description: 'API base path',
+        },
+        controllerName: {
+          type: 'string',
+          description: 'Optional: only generate for specific controller name',
+        },
+      },
+      required: ['source'],
+    },
+  },
+  {
+    name: 'list-controllers',
+    description:
+      'List all REST controllers found in the Spring Boot source code without generating full specs. Useful for exploring the codebase first.',
+    inputSchema: {
+      type: 'object' as const,
+      properties: {
+        source: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'Java source code directory path(s) to parse',
+        },
+        apiSource: {
+          type: 'string',
+          description: 'Optional: specific directory to search for RestControllers',
+        },
+      },
+      required: ['source'],
+    },
+  },
+];
+
+// Register tools list handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+  return { tools };
+});
+
+// Register tool call handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case 'generate-openapi': {
+        const { source, apiSource, title, version, basePath } = args as {
+          source: string[];
+          apiSource?: string;
+          title?: string;
+          version?: string;
+          basePath?: string;
+        };
+
+        const result = await generateOpenAPI({
+          source,
+          apiSource,
+          title,
+          version,
+          basePath,
+        });
+
+        const summaryText = [
+          '## Generation Summary',
+          `- Controllers: ${result.summary.controllerCount}`,
+          `- Endpoints: ${result.summary.endpointCount}`,
+          `- Schemas: ${result.summary.schemaCount}`,
+          '',
+          '### Controllers:',
+          ...result.summary.controllers.map(
+            (c) => `- ${c.name}: ${c.endpointCount} endpoint(s)`
+          ),
+          '',
+          '---',
+          '',
+          '## OpenAPI Specification (YAML)',
+          '',
+          '```yaml',
+          result.yaml,
+          '```',
+        ].join('\n');
+
+        return {
+          content: [{ type: 'text', text: summaryText }],
+        };
+      }
+
+      case 'generate-openapi-per-controller': {
+        const { source, apiSource, title, version, basePath, controllerName } =
+          args as {
+            source: string[];
+            apiSource?: string;
+            title?: string;
+            version?: string;
+            basePath?: string;
+            controllerName?: string;
+          };
+
+        const result = await generateOpenAPIPerController({
+          source,
+          apiSource,
+          title,
+          version,
+          basePath,
+        });
+
+        if (controllerName) {
+          const spec = result.specs.get(controllerName);
+          if (!spec) {
+            const available = Array.from(result.specs.keys()).join(', ');
+            return {
+              content: [
+                {
+                  type: 'text',
+                  text: `Controller "${controllerName}" not found. Available controllers: ${available}`,
+                },
+              ],
+              isError: true,
+            };
+          }
+
+          return {
+            content: [
+              {
+                type: 'text',
+                text: [
+                  `## OpenAPI Specification for ${controllerName}`,
+                  '',
+                  '```yaml',
+                  spec.yaml,
+                  '```',
+                ].join('\n'),
+              },
+            ],
+          };
+        }
+
+        const parts: string[] = [
+          '## Generation Summary',
+          `- Total Controllers: ${result.summary.controllerCount}`,
+          `- Total Endpoints: ${result.summary.totalEndpointCount}`,
+          '',
+          '### Controllers:',
+          ...result.summary.controllers.map(
+            (c) =>
+              `- ${c.name}: ${c.endpointCount} endpoint(s), ${c.schemaCount} schema(s)`
+          ),
+          '',
+          '---',
+          '',
+        ];
+
+        for (const [specName, spec] of result.specs) {
+          parts.push(`## ${specName}`);
+          parts.push('');
+          parts.push('```yaml');
+          parts.push(spec.yaml);
+          parts.push('```');
+          parts.push('');
+        }
+
+        return {
+          content: [{ type: 'text', text: parts.join('\n') }],
+        };
+      }
+
+      case 'list-controllers': {
+        const { source, apiSource } = args as {
+          source: string[];
+          apiSource?: string;
+        };
+
+        const result = await generateOpenAPI({
+          source,
+          apiSource,
+        });
+
+        const parts: string[] = [
+          '## REST Controllers Found',
+          '',
+          `Total: ${result.summary.controllerCount} controller(s) with ${result.summary.endpointCount} endpoint(s)`,
+          '',
+        ];
+
+        for (const controller of result.summary.controllers) {
+          parts.push(`### ${controller.name}`);
+          parts.push(`- Endpoints: ${controller.endpointCount}`);
+          parts.push('');
+        }
+
+        return {
+          content: [{ type: 'text', text: parts.join('\n') }],
+        };
+      }
+
+      default:
+        return {
+          content: [{ type: 'text', text: `Unknown tool: ${name}` }],
+          isError: true,
+        };
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: 'text', text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error('Spring-to-OpenAPI MCP Server running on stdio');
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});