Mcp-Swagger-Server

# MCP Swagger Server 架构文档 ## 📋 文档概览 本目录包含 MCP Swagger Server 项目的详细架构设计文档，涵盖系统设计、重构方案和实施计划。 --- ## 📚 文档索引 ### 🏗️ 核心架构文档 #### 1. [Monorepo 重构方案](./monorepo-refactoring-proposal.md) **状态**: ✅ 完成 **概要**: 将项目重构为 monorepo 架构的完整设计方案 **核心内容**: - 🎯 重构目标和业务价值分析 - 🔍 现状问题分析和解决方案 - 🏗️ 目标架构设计和包结构规划 - 🔄 数据流架构和技术实现方案 - 📊 效益分析和成功标准定义 **关键决策**: - 将 OpenAPI 解析逻辑抽离为独立的 `mcp-swagger-parser` 库 - 建立清晰的职责分工和依赖关系 - 采用 workspace 管理策略实现 monorepo #### 2. [解析库抽离实施计划](./parser-extraction-implementation-plan.md) **状态**: ✅ 完成 **概要**: `mcp-swagger-parser` 库抽离的详细实施计划 **核心内容**: - 📊 当前代码状态分析和边界划分 - 🎨 目标架构设计和 API 接口规范 - 📋 详细实施步骤和时间线规划 - 🧪 测试策略和质量保证措施 - 🚨 风险控制和回滚计划 **实施亮点**: - 14天完整实施时间线 - 分阶段渐进式重构策略 - 全面的测试覆盖和文档支持 --- ## 🎯 架构决策记录 (ADR) ### ADR-001: 选择 Monorepo 架构 ``` 决策: 采用 monorepo 管理多个相关包 原因: 提升代码复用性，简化依赖管理，改善开发体验 影响: 需要重构现有代码结构，但长期收益显著 状态: ✅ 批准 ``` ### ADR-002: 抽离 OpenAPI 解析库 ``` 决策: 将解析逻辑抽离为独立的 mcp-swagger-parser 包 原因: 关注点分离，提高可测试性和复用性 影响: 短期增加重构工作量，长期降低维护成本 状态: ✅ 批准 ``` ### ADR-003: 使用 TypeScript Project References ``` 决策: 采用 TypeScript Project References 管理包间依赖 原因: 提升构建性能，支持增量编译，保证类型安全 影响: 需要配置复杂的 tsconfig 文件，但构建效率显著提升 状态: ✅ 批准 ``` --- ## 📊 架构图谱 ### 系统整体架构 ``` ┌─────────────────────────────────────────────────────────────┐ │ MCP Swagger Server Ecosystem │ ├─────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────────┐ ┌──────────────────┐ │ │ │ Frontend UI │ │ CLI Tool │ │ │ │ (Vue 3 + TS) │ │ (Optional) │ │ │ └─────────┬───────┘ └─────────┬────────┘ │ │ │ │ │ │ └──────────┬───────────┘ │ │ │ │ │ ┌─────────────────────▼────────────────────┐ │ │ │ MCP Swagger Server │ │ │ │ ┌─────────────────┐ ┌─────────────────┐ │ │ │ │ │ MCP Converter │ │ Protocol Layer │ │ │ │ │ │ │ │ (stdio/sse/ │ │ │ │ │ │ │ │ streamable) │ │ │ │ │ └─────────┬───────┘ └─────────────────┘ │ │ │ └─────────────┼─────────────────────────────┘ │ │ │ │ │ ┌─────────────▼────────────────────┐ │ │ │ OpenAPI Parser │ │ │ │ ┌─────────────────┐ │ │ │ │ │ Core Parser │ │ │ │ │ │ Validators │ │ │ │ │ │ Extractors │ │ │ │ │ └─────────────────┘ │ │ │ └──────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 包依赖关系图 ``` @mcp-swagger/ui ────────┐ │ ▼ @mcp-swagger/server ────► mcp-swagger-parser │ ▼ @mcp-swagger/cli ───────┘ 依赖方向: 从左到右，右侧包不依赖左侧包 ``` ### 数据流架构 ``` Input Source → Parser → Validation → Extraction → Conversion → MCP Output │ │ │ │ │ │ │ │ │ │ │ │ URL/File/ OpenAPI Spec Endpoints MCP Tools Config Text Spec Validation Metadata Generation JSON ``` --- ## 🚀 实施状态 ### 当前进展 ``` ┌─────────────────────────────────────────────────────────────┐ │ 实施阶段 │ 状态 │ 完成度 │ 备注 │ ├─────────────────────────────────────────────────────────────┤ │ 架构设计 │ ✅ 完成 │ 100% │ │ │ 文档编写 │ ✅ 完成 │ 100% │ │ │ 代码重构 │ ⏳ 待开始 │ 0% │ 准备开始 │ │ 测试实施 │ ⏳ 待开始 │ 0% │ │ │ 文档完善 │ ⏳ 待开始 │ 0% │ │ └─────────────────────────────────────────────────────────────┘ ``` ### 下一步行动 1. **立即开始**: 创建 `mcp-swagger-parser` 包结构 2. **本周目标**: 完成核心代码抽离 3. **下周计划**: 服务器端重构和测试 --- ## 🎯 设计原则 ### 核心原则 #### 1. 单一职责 (Single Responsibility) - 每个包都有明确的单一职责 - 避免功能混合和职责模糊 - 便于独立开发和维护 #### 2. 开放封闭 (Open/Closed) - 对扩展开放，对修改封闭 - 通过接口和插件机制支持扩展 - 保持 API 稳定性 #### 3. 依赖倒置 (Dependency Inversion) - 高层模块不依赖低层模块 - 通过抽象接口解耦依赖关系 - 便于测试和替换实现 #### 4. 接口隔离 (Interface Segregation) - 提供细粒度的接口 - 避免强制依赖不需要的功能 - 提高系统灵活性 ### 技术原则 #### 1. 类型安全优先 - 全面的 TypeScript 类型定义 - 编译时错误检查 - 运行时类型验证 #### 2. 测试驱动开发 - 高测试覆盖率要求 (≥85%) - 单元测试和集成测试并重 - 测试先行的开发模式 #### 3. 文档即代码 - 代码和文档同步维护 - 自动生成 API 文档 - 丰富的使用示例 #### 4. 性能优先考虑 - 避免不必要的性能开销 - 优化关键路径执行效率 - 内存使用优化 --- ## 📈 质量保证 ### 代码质量标准 #### 静态分析 - **TypeScript**: 严格模式，完整类型注解 - **ESLint**: 代码风格检查和最佳实践 - **Prettier**: 统一代码格式化 - **SonarQube**: 代码质量分析 (计划中) #### 测试策略 ``` 测试金字塔: ▲ / \ /E2E\ ← 端到端测试 (10%) /─────\ / Int \ ← 集成测试 (20%) /─────────\ / Unit \ ← 单元测试 (70%) /─────────────\ ``` #### 性能监控 - **构建时间**: 目标 < 2分钟 - **包大小**: 优化目标 -15% - **解析性能**: 保持或提升 - **内存使用**: 优化目标 -10% ### 发布标准 #### 版本发布检查清单 - [ ] ✅ 所有测试通过 (单元 + 集成 + E2E) - [ ] ✅ 代码覆盖率 ≥ 85% - [ ] ✅ 静态分析无错误 - [ ] ✅ 性能回归测试通过 - [ ] ✅ 文档更新完成 - [ ] ✅ 变更日志更新 --- ## 🔮 未来展望 ### 短期目标 (3-6 个月) - 完成 monorepo 重构 - 发布 v1.0 稳定版本 - 建立完整的 CI/CD 流程 - 扩展解析器支持更多格式 ### 中期目标 (6-12 个月) - 建立插件生态系统 - 支持多语言绑定 - 云服务平台集成 - 性能优化和扩展 ### 长期愿景 (1-2 年) - 成为 OpenAPI 解析的标准库 - 建立活跃的开源社区 - 企业级功能支持 - 多平台和多语言生态 --- ## 📞 联系和贡献 ### 文档维护 - **主要维护者**: 开发团队 - **更新频率**: 随项目进展持续更新 - **反馈渠道**: GitHub Issues / Discussions ### 贡献指南 1. 阅读相关架构文档 2. 遵循设计原则和标准 3. 提交 PR 前完成质量检查 4. 更新相关文档 --- **最后更新**: 2025-06-17 **文档版本**: v1.0 **状态**: 当前版本