10 KiB
10 KiB
MCP Swagger Server 架构文档
📋 文档概览
本目录包含 MCP Swagger Server 项目的详细架构设计文档，涵盖系统设计、重构方案和实施计划。
📚 文档索引
🏗️ 核心架构文档
1. Monorepo 重构方案
状态: ✅ 完成
概要: 将项目重构为 monorepo 架构的完整设计方案
核心内容:
- 🎯 重构目标和业务价值分析
- 🔍 现状问题分析和解决方案
- 🏗️ 目标架构设计和包结构规划
- 🔄 数据流架构和技术实现方案
- 📊 效益分析和成功标准定义
关键决策:
- 将 OpenAPI 解析逻辑抽离为独立的
mcp-swagger-parser库 - 建立清晰的职责分工和依赖关系
- 采用 workspace 管理策略实现 monorepo
2. 解析库抽离实施计划
状态: ✅ 完成
概要: 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% │ │
└─────────────────────────────────────────────────────────────┘
下一步行动
- 立即开始: 创建
mcp-swagger-parser包结构 - 本周目标: 完成核心代码抽离
- 下周计划: 服务器端重构和测试
🎯 设计原则
核心原则
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
贡献指南
- 阅读相关架构文档
- 遵循设计原则和标准
- 提交 PR 前完成质量检查
- 更新相关文档
最后更新: 2025-06-17
文档版本: v1.0
状态: 当前版本