Mcp-Swagger-Server

# MCP Swagger Parser 技术文档 ## 概述 **MCP Swagger Parser** 是一个高性能、类型安全的 OpenAPI/Swagger 规范解析器，专为 Model Context Protocol (MCP) 项目设计。该包提供了完整的 OpenAPI 规范解析、验证、规范化和转换功能，支持将 OpenAPI 规范转换为 MCP 工具。 ## 技术架构 ### 整体架构设计 ``` mcp-swagger-parser/ ├── src/ │ ├── core/ # 核心解析引擎 │ │ ├── parser.ts # 主解析器 │ │ ├── validator.ts # 规范验证器 │ │ └── normalizer.ts # 数据规范化器 │ ├── parsers/ # 输入源解析器 │ │ ├── base-parser.ts # 解析器基类 │ │ ├── url-parser.ts # URL 资源解析 │ │ ├── file-parser.ts # 文件解析 │ │ └── text-parser.ts # 文本内容解析 │ ├── extractors/ # 数据提取器 │ │ ├── endpoint-extractor.ts # API 端点提取 │ │ ├── schema-extractor.ts # 数据模型提取 │ │ ├── security-extractor.ts # 安全配置提取 │ │ └── metadata-extractor.ts # 元数据提取 │ ├── transformer/ # OpenAPI 到 MCP 转换器 │ │ ├── index.ts # 主转换器 │ │ └── types.ts # MCP 类型定义 │ ├── types/ # TypeScript 类型定义 │ │ ├── openapi.ts # OpenAPI 规范类型 │ │ ├── validation.ts # 验证相关类型 │ │ ├── input.ts # 输入参数类型 │ │ ├── output.ts # 输出结果类型 │ │ └── config.ts # 配置类型 │ ├── utils/ # 工具函数 │ ├── errors/ # 错误处理 │ └── index.ts # 包入口文件 ``` ### 技术栈选择 **核心技术:** - **TypeScript 5.2+**: 提供强类型支持和现代 JavaScript 特性 - **CommonJS 模块系统**: 确保 Node.js 环境兼容性 - **Zod**: Schema 验证和类型推导 - **Swagger Parser**: OpenAPI 规范解析和引用解析 **构建工具:** - **TypeScript Compiler**: 代码编译和类型检查 - **Rollup**: 模块打包和优化 - **Jest**: 单元测试框架 **质量保证:** - **ESLint**: 代码质量检查 - **Strict TypeScript**: 严格的类型检查 - **Declaration Files**: 完整的类型声明 ## 核心模块详解 ### 1. 主解析器 (OpenAPIParser) **位置**: `src/core/parser.ts` **职责**: - 统一的解析入口点 - 协调各个子模块的工作 - 错误处理和异常管理 - 结果聚合和元数据生成 **关键特性**: ```typescript export class OpenAPIParser { // 支持多种输入源 async parseFromUrl(url: string): Promise<ParseResult> async parseFromFile(filePath: string): Promise<ParseResult> async parseFromString(content: string): Promise<ParseResult> // 内置验证和规范化 private async processSpec(spec: OpenAPISpec): Promise<ParseResult> } ``` **技术亮点**: - **依赖注入**: 通过构造函数注入配置和子解析器 - **错误链**: 统一的错误处理和上下文保留 - **性能监控**: 内置解析时间统计 - **配置驱动**: 灵活的解析行为配置 ### 2. 规范验证器 (Validator) **位置**: `src/core/validator.ts` **职责**: - OpenAPI 规范格式验证 - Schema 结构验证 - 业务逻辑验证 - 自定义验证规则支持 **验证层次**: ```typescript interface ValidationResult { valid: boolean; isValid: boolean; errors: ValidationError[]; warnings: ValidationWarning[]; metadata?: ValidationMetadata; } ``` **验证策略**: 1. **Schema 验证**: 使用 Swagger Parser 进行基础格式验证 2. **语义验证**: 检查业务逻辑一致性 3. **自定义验证**: 支持插件式验证规则 4. **渐进式验证**: 非严格模式下继续处理警告 ### 3. 数据规范化器 (Normalizer) **位置**: `src/core/normalizer.ts` **职责**: - 数据结构标准化 - 默认值填充 - 引用解析和扁平化 - 兼容性处理 **规范化流程**: ```typescript export class Normalizer { normalize(spec: OpenAPISpec): Promise<ParsedApiSpec> { // 1. 基础结构规范化 // 2. 默认值处理 // 3. 引用解析 // 4. 数据清理 } } ``` ### 4. 输入源解析器 **多态设计**: ```typescript abstract class BaseParser<TOptions = any> { abstract parse(input: string, options?: TOptions): Promise<OpenAPISpec>; } class UrlParser extends BaseParser<UrlParseOptions> class FileParser extends BaseParser<FileParseOptions> class TextParser extends BaseParser<TextParseOptions> ``` **技术特点**: - **策略模式**: 不同输入源使用不同解析策略 - **错误恢复**: 智能的错误处理和重试机制 - **格式检测**: 自动检测 JSON/YAML 格式 - **性能优化**: 流式读取和增量解析 ### 5. 数据提取器 **模块化设计**: - **EndpointExtractor**: API 端点信息提取 - **SchemaExtractor**: 数据模型和类型提取 - **SecurityExtractor**: 认证和授权配置提取 - **MetadataExtractor**: 元数据和统计信息提取 **提取器模式**: ```typescript interface ExtractorResult<T> { data: T; metadata: ExtractionMetadata; warnings: string[]; } ``` ### 6. MCP 转换器 **位置**: `src/transformer/index.ts` **核心功能**: - OpenAPI 操作到 MCP 工具的映射 - HTTP 请求处理器生成 - 参数 Schema 转换 - 响应格式标准化 **转换流程**: ```typescript export class OpenAPIToMCPTransformer { transformToMCPTools(): MCPTool[] { // 1. 遍历所有 API 端点 // 2. 生成 MCP 工具定义 // 3. 创建请求处理器 // 4. 配置参数验证 } } ``` ## 类型系统设计 ### 核心类型定义 **OpenAPI 规范类型**: ```typescript interface OpenAPISpec { openapi: string; info: InfoObject; paths: PathsObject; components?: ComponentsObject; servers?: ServerObject[]; security?: SecurityRequirementObject[]; } ``` **解析结果类型**: ```typescript interface ParseResult { spec: ParsedApiSpec; validation: ValidationResult; metadata: ParseMetadata; } ``` **MCP 工具类型**: ```typescript interface MCPTool { name: string; description: string; inputSchema: JSONSchema; handler: (args: any) => Promise<MCPToolResponse>; metadata?: ToolMetadata; } ``` ### 类型安全特性 1. **严格类型检查**: 启用 TypeScript strict 模式 2. **类型推导**: 使用 Zod 进行运行时类型验证和推导 3. **泛型支持**: 广泛使用泛型提高代码复用性 4. **联合类型**: 精确的状态和错误类型定义 ## 性能优化 ### 解析性能 **优化策略**: 1. **增量解析**: 大文件分块处理 2. **并行处理**: 多个提取器并行执行 3. **缓存机制**: 重复解析结果缓存 4. **懒加载**: 按需加载和解析组件 **性能监控**: ```typescript interface ParseMetadata { parsingDuration: number; endpointCount: number; pathCount: number; schemaCount: number; openApiVersion: string; } ``` ### 内存优化 1. **流式处理**: 避免大文件全量加载 2. **对象池**: 重用频繁创建的对象 3. **引用计数**: 及时释放不需要的引用 4. **垃圾回收友好**: 避免循环引用 ## 错误处理机制 ### 错误类型层次 ```typescript class OpenAPIParseError extends Error { code: string; context?: any; } class OpenAPIValidationError extends OpenAPIParseError { errors: ValidationError[]; warnings: ValidationWarning[]; } ``` ### 错误处理策略 1. **分层错误处理**: 不同层次的错误处理策略 2. **上下文保留**: 错误信息包含完整的上下文 3. **可恢复错误**: 区分致命错误和可恢复错误 4. **错误聚合**: 批量收集和报告错误 ## 配置系统 ### 解析器配置 ```typescript interface ParserConfig { validateSchema?: boolean; // 是否验证 Schema resolveReferences?: boolean; // 是否解析引用 allowEmptyPaths?: boolean; // 是否允许空路径 strictMode?: boolean; // 严格模式 customValidators?: ValidationRule[]; // 自定义验证规则 } ``` ### 转换器配置 ```typescript interface TransformerOptions { baseUrl?: string; // 基础 URL includeDeprecated?: boolean; // 包含废弃的 API includeTags?: string[]; // 包含的标签 excludeTags?: string[]; // 排除的标签 requestTimeout?: number; // 请求超时 defaultHeaders?: Record<string, string>; // 默认请求头 } ``` ## 扩展性设计 ### 插件机制 **自定义验证器**: ```typescript interface ValidationRule { name: string; validate: (spec: OpenAPISpec) => ValidationResult; } ``` **自定义转换器**: ```typescript interface TransformerPlugin { name: string; transform: (operation: OperationObject) => MCPTool | null; } ``` ### 中间件模式 ```typescript interface ParserMiddleware { name: string; process: (spec: OpenAPISpec, context: ParseContext) => Promise<OpenAPISpec>; } ``` ## 改进方向 ### 1. 性能优化 **当前挑战**: - 大型 OpenAPI 文件解析速度 - 内存占用优化 - 并发解析性能 **改进方案**: ```typescript // 流式解析器 class StreamingParser { async parseStream(stream: ReadableStream): Promise<ParseResult> { // 实现流式解析，减少内存占用 } } // 并行处理引擎 class ParallelProcessor { async processInParallel(tasks: ParseTask[]): Promise<ParseResult[]> { // 使用 Worker Threads 并行处理 } } // 智能缓存 class ParseCache { async get(key: string): Promise<ParseResult | null> { // 基于内容哈希的智能缓存 } } ``` ### 2. 错误处理增强 **改进目标**: - 更精确的错误定位 - 可恢复的错误处理 - 智能错误修复建议 **实现方案**: ```typescript // 错误修复建议 interface ErrorSuggestion { type: 'fix' | 'warning' | 'info'; message: string; autoFix?: (spec: OpenAPISpec) => OpenAPISpec; } // 增强的错误报告 class EnhancedErrorReporter { generateReport(errors: ValidationError[]): ErrorReport { // 生成详细的错误报告和修复建议 } } ``` ### 3. 类型系统完善 **改进方向**: - 更精确的 OpenAPI 类型定义 - 运行时类型检查优化 - 类型推导增强 **技术方案**: ```typescript // 更精确的类型定义 type OpenAPIVersion = '3.0.0' | '3.0.1' | '3.0.2' | '3.0.3' | '3.1.0'; // 条件类型支持 type OperationMethods<T extends OpenAPISpec> = T['openapi'] extends '3.1.0' ? ExtendedMethods : StandardMethods; // 运行时类型验证 const OpenAPISchema = z.object({ openapi: z.string().regex(/^3\.(0|1)\.\d+$/), info: InfoSchema, paths: PathsSchema }); ``` ### 4. 功能扩展 **规划功能**: - GraphQL 规范支持 - gRPC 协议支持 - 异步 API 规范支持 - 多版本 API 管理 **架构扩展**: ```typescript // 协议抽象 interface APISpecParser<TSpec, TOptions> { parse(input: string, options?: TOptions): Promise<TSpec>; validate(spec: TSpec): ValidationResult; transform(spec: TSpec): MCPTool[]; } // GraphQL 支持 class GraphQLParser implements APISpecParser<GraphQLSpec, GraphQLOptions> { // GraphQL 规范解析实现 } // 多协议工厂 class ParserFactory { static create(type: 'openapi' | 'graphql' | 'grpc'): APISpecParser<any, any> { // 根据类型创建对应的解析器 } } ``` ### 5. 开发工具增强 **目标改进**: - 更好的调试支持 - 性能分析工具 - 可视化解析结果 **实现思路**: ```typescript // 调试工具 class ParserDebugger { enableDebug(options: DebugOptions): void { // 启用详细的调试信息 } getPerformanceReport(): PerformanceReport { // 获取性能分析报告 } } // 可视化支持 class ResultVisualizer { generateHTML(result: ParseResult): string { // 生成 HTML 可视化报告 } generateJSON(result: ParseResult): object { // 生成结构化的 JSON 报告 } } ``` ### 6. 测试覆盖增强 **改进计划**: - 增加边界用例测试 - 性能基准测试 - 兼容性测试套件 **测试架构**: ```typescript // 测试数据生成器 class TestDataGenerator { generateValidSpec(): OpenAPISpec { // 生成有效的测试规范 } generateInvalidSpec(errorType: string): OpenAPISpec { // 生成特定错误类型的规范 } } // 性能基准测试 class PerformanceBenchmark { async runBenchmark(specs: OpenAPISpec[]): Promise<BenchmarkResult> { // 运行性能基准测试 } } ``` ## 最佳实践 ### 使用建议 1. **配置优化**: 根据项目需求调整解析器配置 2. **错误处理**: 实现完善的错误处理逻辑 3. **性能监控**: 监控解析性能和内存使用 4. **类型安全**: 充分利用 TypeScript 类型系统 ### 集成指南 ```typescript // 基础使用 import { parseFromUrl, transformToMCPTools } from 'mcp-swagger-parser'; const result = await parseFromUrl('https://api.example.com/swagger.json'); const tools = transformToMCPTools(result.spec); // 高级配置 import { OpenAPIParser, OpenAPIToMCPTransformer } from 'mcp-swagger-parser'; const parser = new OpenAPIParser({ strictMode: false, validateSchema: true, customValidators: [myValidator] }); const transformer = new OpenAPIToMCPTransformer(spec, { includeDeprecated: false, baseUrl: 'https://api.example.com' }); ``` ## 总结 MCP Swagger Parser 采用了模块化、类型安全、高性能的设计理念，提供了完整的 OpenAPI 规范处理能力。通过合理的架构设计和技术选型，实现了高度的可扩展性和可维护性。 未来的改进方向主要集中在性能优化、功能扩展和开发体验提升，将使这个解析器成为 MCP 生态系统中的核心组件。