16 KiB

Raw Blame History

MCP Swagger Server Monorepo 架构重构方案

📋 文档概述

本文档描述了将 MCP Swagger Server 项目重构为 monorepo 架构的设计方案，重点是将 OpenAPI 解析逻辑抽离为独立的 mcp-swagger-parser 库。

文档版本: v1.0
创建日期: 2025-06-17
状态: 架构设计阶段

🎯 重构目标

核心目标

关注点分离: 将 OpenAPI 解析逻辑从主服务中抽离
代码复用: 创建可被其他项目使用的独立解析库
架构清晰: 建立职责明确的模块化架构
可维护性: 提高代码的可测试性和可维护性

业务价值

📈 提升开发效率: 模块化开发，减少代码耦合
🔄 增强可复用性: 解析库可服务于多个项目
🧪 改善测试质量: 独立模块更易于单元测试
📦 简化依赖管理: 清晰的包依赖关系
🌟 促进开源生态: 独立的解析库更容易被社区采用

🏗️ 现状分析

当前架构问题

现有结构 (存在的问题):
packages/mcp-swagger-server/
├── src/
│   ├── transform/
│   │   ├── openapi-to-mcp.ts        ❌ 解析 + 转换逻辑混合
│   │   └── transformOpenApiToMcpTools.ts ❌ 职责不清晰
│   ├── tools/
│   └── transportUtils/

存在的问题:

🔴 职责混合: OpenAPI 解析与 MCP 转换逻辑耦合
🔴 代码复用困难: 解析逻辑无法独立使用
🔴 测试复杂: 无法单独测试解析功能
🔴 维护困难: 修改解析逻辑可能影响转换逻辑

依赖关系分析

// 当前依赖混乱
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 设计:

// 主要接口设计
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 格式转换
多种传输协议支持
服务器生命周期管理

依赖关系:

// 依赖解析库
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)

{
  "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"
  }
}

版本管理策略

// 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 配置

// 根目录 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`)

// 单元测试示例
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`)

// 集成测试示例
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);
  });
});

端到端测试

// 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 周)

创建包结构

mkdir -p packages/mcp-swagger-parser/src/{parsers,validators,types}

抽离解析逻辑
- 从 openapi-to-mcp.ts 提取解析相关代码
- 创建独立的解析器类
- 建立类型定义
建立测试套件
- 单元测试覆盖率 > 80%
- 集成测试关键场景

阶段 2: 服务器重构 (1 周)

重构服务器代码
- 移除解析逻辑
- 集成新的解析库
- 优化转换逻辑
更新依赖关系
- 配置 workspace 依赖
- 更新构建脚本

阶段 3: 前端集成 (3-5 天)

更新前端调用
- 适配新的 API 接口
- 更新错误处理
端到端测试
- 完整流程验证
- 性能回归测试

阶段 4: 文档和发布 (2-3 天)

完善文档
- API 文档
- 使用指南
- 迁移指南
发布准备
- 版本号规划
- 发布脚本
- CI/CD 配置

风险控制

向后兼容策略

// 在过渡期保留旧接口
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);
  }
}

回滚方案

功能标志: 使用环境变量控制新旧实现
版本锁定: 固定解析库版本，避免破坏性更改
测试覆盖: 确保新旧实现输出一致性

📊 效益分析

开发效率提升

方面	重构前	重构后	提升
代码复用	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%

🎯 成功标准

技术指标

代码质量
- 测试覆盖率 ≥ 85%
- 代码重复率 ≤ 5%
- 圈复杂度 ≤ 10
- TypeScript 严格模式通过
性能指标
- 解析速度不降低
- 内存使用优化 10%
- 构建时间减少 20%
- 包大小优化 15%
可维护性
- 模块间耦合度 ≤ 30%
- API 文档覆盖率 100%
- 错误处理完整性 95%

业务指标

开发效率
- 新功能开发速度提升 50%
- Bug 修复时间减少 40%
- 代码评审时间减少 30%
用户体验
- API 响应时间保持不变
- 错误信息更加友好
- 功能完整性 100%

🔮 未来扩展计划

短期扩展 (3-6 个月)

解析库增强

// 支持更多格式
export interface MultiFormatParser extends OpenApiParser {
  parsePostmanCollection(collection: any): Promise<ParsedApiSpec>;
  parseInsomniaWorkspace(workspace: any): Promise<ParsedApiSpec>;
  parseApiBlueprint(blueprint: string): Promise<ParsedApiSpec>;
}

插件系统

// 可扩展的解析器
export interface ParserPlugin {
  name: string;
  supports(input: any): boolean;
  parse(input: any): Promise<ParsedApiSpec>;
}

中期扩展 (6-12 个月)

多语言支持
- Python 绑定
- Rust 性能优化版本
- WebAssembly 浏览器版本
云服务集成
- AWS API Gateway 导入
- Azure API Management 集成
- Kong Gateway 支持

长期愿景 (1-2 年)

API 生态系统
- 成为 OpenAPI 解析的标准库
- 支持所有主流 API 规范格式
- 建立活跃的开源社区
企业级特性
- 大规模 API 批量处理
- 企业级安全和合规
- 高级分析和监控

📝 结论和建议

核心建议

立即开始重构 🚀
- 架构设计合理，收益明显
- 技术风险可控
- 长期价值巨大
分阶段实施 📈
- 降低实施风险
- 保证项目连续性
- 便于团队适应
重视测试 🧪
- 确保重构质量
- 建立回归测试体系
- 提高代码可信度

实施优先级

🔥 高优先级 (立即执行)
- 创建 mcp-swagger-parser 包结构
- 抽离核心解析逻辑
- 建立基础测试套件
⚡ 中优先级 (2 周内)
- 重构 mcp-swagger-server
- 更新前端集成
- 完善文档
💡 低优先级 (1 个月内)
- 性能优化
- 扩展功能
- 社区推广

最终期望

通过这次架构重构，我们期望：

🎯 提升开发效率 50%
🔧 降低维护成本 40%
📈 增强代码复用 80%
🚀 加速功能迭代 100%
🌟 建立技术影响力 提升项目在开源社区的地位

这次重构不仅是技术升级，更是为项目的长期发展奠定坚实基础的战略投资。

文档维护: 本文档将随着项目进展持续更新，确保架构设计与实际实现保持一致。

16 KiB Raw Blame History Unescape Escape

MCP Swagger Server Monorepo 架构重构方案

📋 文档概述

🎯 重构目标

核心目标

业务价值

🏗️ 现状分析

当前架构问题

依赖关系分析

🎨 目标架构设计

Monorepo 整体结构

核心包职责分工

📦 mcp-swagger-parser - OpenAPI 解析库

⚙️ mcp-swagger-server - MCP 服务器

🎨 mcp-swagger-ui - 前端界面

💻 mcp-swagger-cli - 命令行工具 (新增)

🔄 数据流架构

重构前数据流

重构后数据流

详细数据流图

📊 技术实现方案

包管理策略

Workspace 配置 (package.json)

版本管理策略

构建策略

TypeScript 配置

构建工具选择

🧪 测试策略

分层测试架构

解析库测试 (mcp-swagger-parser)

集成测试 (mcp-swagger-server)

端到端测试

📈 迁移策略

分阶段迁移计划

阶段 1: 解析库创建 (1 周)

阶段 2: 服务器重构 (1 周)

阶段 3: 前端集成 (3-5 天)

阶段 4: 文档和发布 (2-3 天)

风险控制

向后兼容策略

回滚方案

📊 效益分析

开发效率提升

技术债务减少

长期维护成本

🎯 成功标准

技术指标

业务指标

🔮 未来扩展计划

短期扩展 (3-6 个月)

中期扩展 (6-12 个月)

长期愿景 (1-2 年)

📝 结论和建议

核心建议

实施优先级

最终期望

16 KiB

Raw Blame History

📦 `mcp-swagger-parser` - OpenAPI 解析库

⚙️ `mcp-swagger-server` - MCP 服务器

🎨 `mcp-swagger-ui` - 前端界面

💻 `mcp-swagger-cli` - 命令行工具 (新增)

解析库测试 (`mcp-swagger-parser`)

集成测试 (`mcp-swagger-server`)