Swagger MCP Server

Instructions

Implementation Reference

• src/tools/typescript-types-generator-tool.ts:153-230 (handler)

  Core handler function that executes the TypeScript types generation, manages progress reporting, handles the generator instance, processes results, and formats the MCP response content.

  async execute(params: z.infer<typeof this.schema>) {
    let progress = 0;
    let progressMessage = '';
    
    // 定义进度回调
    const progressCallback = (newProgress: number, message: string) => {
      progress = newProgress;
      progressMessage = message;
      console.log(`[Progress] ${Math.round(newProgress * 100)}%: ${message}`);
    };
    
    try {
      console.log(`[TypeScriptTypesGeneratorTool] 开始生成TypeScript类型: ${params.swaggerUrl}`);
      console.log(`[TypeScriptTypesGeneratorTool] 缓存: ${params.useCache ? '启用' : '禁用'}, 懒加载: ${params.lazyLoading ? '启用' : '禁用'}`);
      
      // 创建生成器实例
      const generator = new TypeScriptTypesGenerator();
      
      // 执行生成
      const result = await generator.generate({
        ...params,
        progressCallback
      } as TypeScriptTypesGeneratorOptions);
      
      // 处理结果
      if (result.success) {
        console.log(`[TypeScriptTypesGeneratorTool] 类型生成成功，生成了 ${result.files.length} 个文件`);
        
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: true,
                files: result.files,
                warnings: result.warnings,
                progress: 1.0,
                progressMessage: '完成'
              }, null, 2)
            }
          ]
        };
      } else {
        console.error(`[TypeScriptTypesGeneratorTool] 类型生成失败: ${result.error}`);
        
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify({
                success: false,
                error: result.error,
                progress: progress,
                progressMessage: progressMessage
              }, null, 2)
            }
          ]
        };
      }
    } catch (error) {
      console.error(`[TypeScriptTypesGeneratorTool] 执行异常:`, error);
      
      // 返回错误结果
      return {
        content: [
          {
            type: 'text' as const,
            text: JSON.stringify({
              success: false,
              error: error instanceof Error ? error.message : String(error),
              progress: progress,
              progressMessage: progressMessage
            }, null, 2)
          }
        ]
      };
    }
  }

• src/tools/typescript-types-generator-tool.ts:132-147 (registration)

  MCP server.tool() registration specifically for the 'generate-typescript-types-optimized' tool, applying optimized default parameters before delegating to the execute handler.

  // 注册优化版工具
  server.tool(
    TS_TYPES_GENERATOR_OPTIMIZED_TOOL_NAME,
    TS_TYPES_GENERATOR_OPTIMIZED_TOOL_DESCRIPTION,
    this.schema.shape,
    async (params) => {
      // 默认启用性能优化选项
      const options = {
        ...params,
        useCache: params.useCache !== false,
        skipValidation: params.skipValidation !== false,
        lazyLoading: params.lazyLoading !== false
      };
      return await this.execute(options);
    }
  );

• src/tools/typescript-types-generator-tool.ts:24-109 (schema)

  Zod schema defining the input parameters for the tool, including swaggerUrl, output options, filtering, and optimization flags like useCache, skipValidation, lazyLoading.

  schema = z.object({
    /**
     * Swagger/OpenAPI document URL
     */
    swaggerUrl: z.string().describe('Swagger/OpenAPI document URL'),
    
    /**
     * Output directory
     */
    outputDir: z.string().optional().describe('Output directory'),
    
    /**
     * Whether to overwrite existing files
     */
    overwrite: z.boolean().optional().describe('Whether to overwrite existing files'),
    
    /**
     * File prefix
     */
    filePrefix: z.string().optional().describe('File prefix'),
    
    /**
     * File suffix
     */
    fileSuffix: z.string().optional().describe('File suffix'),
    
    /**
     * Whether to use namespace
     */
    useNamespace: z.boolean().optional().describe('Whether to use namespace for wrapping types'),
    
    /**
     * Namespace name
     */
    namespace: z.string().optional().describe('Namespace name'),
    
    /**
     * Whether to generate enums
     */
    generateEnums: z.boolean().optional().describe('Whether to generate enum types'),
    
    /**
     * Whether to use strict types
     */
    strictTypes: z.boolean().optional().describe('Whether to use strict types'),
    
    /**
     * Excluded schema names
     */
    excludeSchemas: z.array(z.string()).optional().describe('Array of schema names to exclude'),
    
    /**
     * Included schema names
     */
    includeSchemas: z.array(z.string()).optional().describe('Array of schema names to include'),
    
    /**
     * Whether to generate index file
     */
    generateIndex: z.boolean().optional().describe('Whether to generate an index file'),
    
    /**
     * Request headers
     */
    headers: z.record(z.string()).optional().describe('Request headers'),
    
    /**
     * Whether to use cache
     */
    useCache: z.boolean().optional().describe('Whether to use cache'),
    
    /**
     * Cache TTL in minutes
     */
    cacheTTLMinutes: z.number().optional().describe('Cache TTL in minutes'),
    
    /**
     * Whether to skip validation
     */
    skipValidation: z.boolean().optional().describe('Whether to skip validation'),
    
    /**
     * Whether to use lazy loading
     */
    lazyLoading: z.boolean().optional().describe('Whether to use lazy loading')
  });

• src/tools/typescript-types-generator-tool.ts:13-14 (helper)

  Constants defining the tool name and description for the optimized version.

  const TS_TYPES_GENERATOR_OPTIMIZED_TOOL_NAME = 'generate-typescript-types-optimized';
  const TS_TYPES_GENERATOR_OPTIMIZED_TOOL_DESCRIPTION = 'Generate TypeScript type definitions from Swagger/OpenAPI document with optimized options for caching and large document support.';