Mcp-Swagger-Server

# MCP Swagger Server Monorepo 架构重构方案 ## 📋 文档概述 本文档描述了将 MCP Swagger Server 项目重构为 monorepo 架构的设计方案，重点是将 OpenAPI 解析逻辑抽离为独立的 `mcp-swagger-parser` 库。 **文档版本**: v1.0 **创建日期**: 2025-06-17 **状态**: 架构设计阶段 --- ## 🎯 重构目标 ### 核心目标 1. **关注点分离**: 将 OpenAPI 解析逻辑从主服务中抽离 2. **代码复用**: 创建可被其他项目使用的独立解析库 3. **架构清晰**: 建立职责明确的模块化架构 4. **可维护性**: 提高代码的可测试性和可维护性 ### 业务价值 - 📈 **提升开发效率**: 模块化开发，减少代码耦合 - 🔄 **增强可复用性**: 解析库可服务于多个项目 - 🧪 **改善测试质量**: 独立模块更易于单元测试 - 📦 **简化依赖管理**: 清晰的包依赖关系 - 🌟 **促进开源生态**: 独立的解析库更容易被社区采用 --- ## 🏗️ 现状分析 ### 当前架构问题 ``` 现有结构 (存在的问题): packages/mcp-swagger-server/ ├── src/ │ ├── transform/ │ │ ├── openapi-to-mcp.ts ❌ 解析 + 转换逻辑混合 │ │ └── transformOpenApiToMcpTools.ts ❌ 职责不清晰 │ ├── tools/ │ └── transportUtils/ ``` **存在的问题**: 1. 🔴 **职责混合**: OpenAPI 解析与 MCP 转换逻辑耦合 2. 🔴 **代码复用困难**: 解析逻辑无法独立使用 3. 🔴 **测试复杂**: 无法单独测试解析功能 4. 🔴 **维护困难**: 修改解析逻辑可能影响转换逻辑 ### 依赖关系分析 ```typescript // 当前依赖混乱 openapi-to-mcp.ts: ├── swagger-parser (外部依赖) ├── MCP 协议相关逻辑 (混合) ├── 业务转换逻辑 (混合) └── 错误处理 (分散) ``` --- ## 🎨 目标架构设计 ### Monorepo 整体结构 ``` mcp-swagger-server/ (monorepo root) ├── packages/ │ ├── mcp-swagger-parser/ ✅ 新增：OpenAPI 解析库 │ │ ├── src/ │ │ │ ├── parsers/ # 解析器实现 │ │ │ ├── validators/ # 验证器 │ │ │ ├── normalizers/ # 标准化工具 │ │ │ ├── types/ # TypeScript 类型 │ │ │ └── index.ts # 公共 API │ │ ├── tests/ # 单元测试 │ │ └── package.json │ │ │ ├── mcp-swagger-server/ ✅ 重构：MCP 服务器 │ │ ├── src/ │ │ │ ├── converters/ # MCP 转换逻辑 │ │ │ ├── protocols/ # MCP 协议实现 │ │ │ ├── transports/ # 传输层 │ │ │ └── server.ts # 服务器主逻辑 │ │ └── package.json │ │ │ ├── mcp-swagger-ui/ ✅ 保持：前端界面 │ │ │ └── mcp-swagger-cli/ ✅ 新增：命令行工具 (可选) │ ├── docs/ ✅ 文档目录 ├── tools/ ✅ 开发工具 └── package.json ✅ Workspace 配置 ``` ### 核心包职责分工 #### 📦 `mcp-swagger-parser` - OpenAPI 解析库 **核心职责**: - OpenAPI 2.0/3.x 规范解析 - 多种输入格式支持 (URL、文件、文本) - 规范验证和标准化 - 错误处理和诊断 **API 设计**: ```typescript // 主要接口设计 export interface OpenApiParser { parseFromUrl(url: string, options?: ParseOptions): Promise<ParsedApiSpec>; parseFromFile(filePath: string, options?: ParseOptions): Promise<ParsedApiSpec>; parseFromText(content: string, options?: ParseOptions): Promise<ParsedApiSpec>; validate(spec: any): Promise<ValidationResult>; normalize(spec: ParsedApiSpec): Promise<NormalizedApiSpec>; } export interface ParsedApiSpec { openapi: string; info: ApiInfo; servers: ServerInfo[]; paths: PathsObject; components?: ComponentsObject; metadata: ParseMetadata; } ``` #### ⚙️ `mcp-swagger-server` - MCP 服务器 **核心职责**: - MCP 协议实现 - OpenAPI 到 MCP 格式转换 - 多种传输协议支持 - 服务器生命周期管理 **依赖关系**: ```typescript // 依赖解析库 import { OpenApiParser } from 'mcp-swagger-parser'; export class McpSwaggerServer { constructor(private parser: OpenApiParser) {} async convertApiToMcp(source: InputSource): Promise<McpConfig> { // 1. 使用解析库解析 OpenAPI const spec = await this.parser.parseFromUrl(source.url); // 2. 专注于 MCP 转换逻辑 return this.convertToMcpFormat(spec); } } ``` #### 🎨 `mcp-swagger-ui` - 前端界面 **核心职责**: - 用户界面交互 - 文件上传和 URL 输入 - 转换结果展示 - 配置选项管理 #### 💻 `mcp-swagger-cli` - 命令行工具 (新增) **核心职责**: - 命令行接口 - 批量处理 - CI/CD 集成 - 脚本化操作 --- ## 🔄 数据流架构 ### 重构前数据流 ``` Input → [mcp-swagger-server] → Output ↓ 解析 + 转换 + 协议处理 (所有逻辑混合在一起) ``` ### 重构后数据流 ``` Input → [mcp-swagger-parser] → ParsedSpec → [mcp-swagger-server] → McpConfig ↓ ↓ 专注解析和验证 专注转换和协议处理 ↓ ↓ 可独立测试和复用 清晰的业务逻辑 ``` ### 详细数据流图 ``` ┌─────────────────┐ ┌──────────────────┐ ┌─────────────────┐ │ 输入源 │ │ 解析层 │ │ 转换层 │ │ │ │ │ │ │ │ • URL │────▶│ mcp-swagger- │────▶│ mcp-swagger- │ │ • File │ │ parser │ │ server │ │ • Text │ │ │ │ │ │ │ │ • 验证 │ │ • MCP 转换 │ │ │ │ • 标准化 │ │ • 协议处理 │ │ │ │ • 错误处理 │ │ • 传输层 │ └─────────────────┘ └──────────────────┘ └─────────────────┘ │ │ ▼ ▼ ParsedApiSpec McpConfig (标准化的规范) (MCP 格式) ``` --- ## 📊 技术实现方案 ### 包管理策略 #### Workspace 配置 (package.json) ```json { "name": "mcp-swagger-monorepo", "private": true, "workspaces": [ "packages/*" ], "scripts": { "build": "pnpm -r build", "test": "pnpm -r test", "lint": "pnpm -r lint", "dev:parser": "pnpm --filter mcp-swagger-parser dev", "dev:server": "pnpm --filter @mcp-swagger/server dev", "dev:ui": "pnpm --filter @mcp-swagger/ui dev" } } ``` #### 版本管理策略 ```json // packages/mcp-swagger-parser/package.json { "name": "mcp-swagger-parser", "version": "1.0.0", "exports": { ".": { "import": "./dist/index.js", "require": "./dist/index.cjs", "types": "./dist/index.d.ts" } } } // packages/mcp-swagger-server/package.json { "name": "@mcp-swagger/server", "version": "1.0.0", "dependencies": { "mcp-swagger-parser": "workspace:^1.0.0" } } ``` ### 构建策略 #### TypeScript 配置 ```json // 根目录 tsconfig.json { "compilerOptions": { "composite": true, "declaration": true, "declarationMap": true }, "references": [ { "path": "./packages/mcp-swagger-parser" }, { "path": "./packages/mcp-swagger-server" }, { "path": "./packages/mcp-swagger-ui" } ] } ``` #### 构建工具选择 - **主构建工具**: Rollup (支持多格式输出) - **开发工具**: Vite (快速热重载) - **类型检查**: TypeScript Project References - **代码检查**: ESLint (workspace 配置) --- ## 🧪 测试策略 ### 分层测试架构 #### 解析库测试 (`mcp-swagger-parser`) ```typescript // 单元测试示例 describe('OpenApiParser', () => { describe('parseFromUrl', () => { it('should parse valid OpenAPI 3.0 spec', async () => { const parser = new OpenApiParser(); const result = await parser.parseFromUrl('https://petstore.swagger.io/v2/swagger.json'); expect(result.openapi).toBe('3.0.0'); expect(result.info.title).toBeDefined(); expect(result.paths).toBeDefined(); }); it('should handle invalid URLs gracefully', async () => { const parser = new OpenApiParser(); await expect(parser.parseFromUrl('invalid-url')) .rejects.toThrow('Invalid URL format'); }); }); }); ``` #### 集成测试 (`mcp-swagger-server`) ```typescript // 集成测试示例 describe('McpSwaggerServer Integration', () => { it('should convert complete OpenAPI spec to MCP format', async () => { const server = new McpSwaggerServer(); const mcpConfig = await server.convertApiToMcp({ type: 'url', content: 'https://petstore.swagger.io/v2/swagger.json' }); expect(mcpConfig.tools).toBeDefined(); expect(mcpConfig.tools.length).toBeGreaterThan(0); }); }); ``` #### 端到端测试 ```typescript // E2E 测试示例 describe('Complete Workflow', () => { it('should handle full conversion pipeline', async () => { // 1. 解析阶段 const parser = new OpenApiParser(); const spec = await parser.parseFromFile('./test-fixtures/petstore.yaml'); // 2. 转换阶段 const server = new McpSwaggerServer(parser); const mcpConfig = await server.convertSpecToMcp(spec); // 3. 验证结果 expect(mcpConfig).toMatchSnapshot(); }); }); ``` --- ## 📈 迁移策略 ### 分阶段迁移计划 #### 阶段 1: 解析库创建 (1 周) 1. **创建包结构** ```bash mkdir -p packages/mcp-swagger-parser/src/{parsers,validators,types} ``` 2. **抽离解析逻辑** - 从 `openapi-to-mcp.ts` 提取解析相关代码 - 创建独立的解析器类 - 建立类型定义 3. **建立测试套件** - 单元测试覆盖率 > 80% - 集成测试关键场景 #### 阶段 2: 服务器重构 (1 周) 1. **重构服务器代码** - 移除解析逻辑 - 集成新的解析库 - 优化转换逻辑 2. **更新依赖关系** - 配置 workspace 依赖 - 更新构建脚本 #### 阶段 3: 前端集成 (3-5 天) 1. **更新前端调用** - 适配新的 API 接口 - 更新错误处理 2. **端到端测试** - 完整流程验证 - 性能回归测试 #### 阶段 4: 文档和发布 (2-3 天) 1. **完善文档** - API 文档 - 使用指南 - 迁移指南 2. **发布准备** - 版本号规划 - 发布脚本 - CI/CD 配置 ### 风险控制 #### 向后兼容策略 ```typescript // 在过渡期保留旧接口 export class LegacyOpenApiParser { /** * @deprecated Use mcp-swagger-parser instead */ static async parseOpenApi(source: any): Promise<any> { console.warn('This method is deprecated. Please use mcp-swagger-parser'); const parser = new OpenApiParser(); return parser.parseFromUrl(source.url); } } ``` #### 回滚方案 1. **功能标志**: 使用环境变量控制新旧实现 2. **版本锁定**: 固定解析库版本，避免破坏性更改 3. **测试覆盖**: 确保新旧实现输出一致性 --- ## 📊 效益分析 ### 开发效率提升 | 方面 | 重构前 | 重构后 | 提升 | |------|--------|--------|------| | **代码复用** | 0% | 80% | +80% | | **测试隔离** | 困难 | 简单 | +200% | | **并行开发** | 不可能 | 完全支持 | +100% | | **问题定位** | 复杂 | 清晰 | +150% | | **新功能开发** | 慢 | 快 | +50% | ### 技术债务减少 ``` 重构前技术债务: - 代码耦合度: 高 (8/10) - 测试覆盖率: 低 (30%) - 文档完整性: 中 (50%) - 维护复杂度: 高 (8/10) 重构后技术债务: - 代码耦合度: 低 (3/10) ⬇️ -62% - 测试覆盖率: 高 (85%) ⬆️ +183% - 文档完整性: 高 (90%) ⬆️ +80% - 维护复杂度: 低 (3/10) ⬇️ -62% ``` ### 长期维护成本 ``` 年度维护成本估算: 重构前: 100% (基准) ├── 问题定位时间: 40% ├── 功能开发时间: 35% ├── 测试维护时间: 15% └── 文档更新时间: 10% 重构后: 60% (预期) ├── 问题定位时间: 15% ⬇️ -62% ├── 功能开发时间: 25% ⬇️ -29% ├── 测试维护时间: 10% ⬇️ -33% └── 文档更新时间: 10% ⬇️ 0% 总成本降低: 40% ``` --- ## 🎯 成功标准 ### 技术指标 1. **代码质量** - [ ] 测试覆盖率 ≥ 85% - [ ] 代码重复率 ≤ 5% - [ ] 圈复杂度 ≤ 10 - [ ] TypeScript 严格模式通过 2. **性能指标** - [ ] 解析速度不降低 - [ ] 内存使用优化 10% - [ ] 构建时间减少 20% - [ ] 包大小优化 15% 3. **可维护性** - [ ] 模块间耦合度 ≤ 30% - [ ] API 文档覆盖率 100% - [ ] 错误处理完整性 95% ### 业务指标 1. **开发效率** - [ ] 新功能开发速度提升 50% - [ ] Bug 修复时间减少 40% - [ ] 代码评审时间减少 30% 2. **用户体验** - [ ] API 响应时间保持不变 - [ ] 错误信息更加友好 - [ ] 功能完整性 100% --- ## 🔮 未来扩展计划 ### 短期扩展 (3-6 个月) 1. **解析库增强** ```typescript // 支持更多格式 export interface MultiFormatParser extends OpenApiParser { parsePostmanCollection(collection: any): Promise<ParsedApiSpec>; parseInsomniaWorkspace(workspace: any): Promise<ParsedApiSpec>; parseApiBlueprint(blueprint: string): Promise<ParsedApiSpec>; } ``` 2. **插件系统** ```typescript // 可扩展的解析器 export interface ParserPlugin { name: string; supports(input: any): boolean; parse(input: any): Promise<ParsedApiSpec>; } ``` ### 中期扩展 (6-12 个月) 1. **多语言支持** - Python 绑定 - Rust 性能优化版本 - WebAssembly 浏览器版本 2. **云服务集成** - AWS API Gateway 导入 - Azure API Management 集成 - Kong Gateway 支持 ### 长期愿景 (1-2 年) 1. **API 生态系统** - 成为 OpenAPI 解析的标准库 - 支持所有主流 API 规范格式 - 建立活跃的开源社区 2. **企业级特性** - 大规模 API 批量处理 - 企业级安全和合规 - 高级分析和监控 --- ## 📝 结论和建议 ### 核心建议 1. **立即开始重构** 🚀 - 架构设计合理，收益明显 - 技术风险可控 - 长期价值巨大 2. **分阶段实施** 📈 - 降低实施风险 - 保证项目连续性 - 便于团队适应 3. **重视测试** 🧪 - 确保重构质量 - 建立回归测试体系 - 提高代码可信度 ### 实施优先级 1. **🔥 高优先级** (立即执行) - 创建 `mcp-swagger-parser` 包结构 - 抽离核心解析逻辑 - 建立基础测试套件 2. **⚡ 中优先级** (2 周内) - 重构 `mcp-swagger-server` - 更新前端集成 - 完善文档 3. **💡 低优先级** (1 个月内) - 性能优化 - 扩展功能 - 社区推广 ### 最终期望 通过这次架构重构，我们期望： - 🎯 **提升开发效率** 50% - 🔧 **降低维护成本** 40% - 📈 **增强代码复用** 80% - 🚀 **加速功能迭代** 100% - 🌟 **建立技术影响力** 提升项目在开源社区的地位 这次重构不仅是技术升级，更是为项目的长期发展奠定坚实基础的战略投资。 --- **文档维护**: 本文档将随着项目进展持续更新，确保架构设计与实际实现保持一致。