mcp-swagger-server/docs/monorepo-architecture-proposal.md

MCP Swagger Server Monorepo 架构提案

🏗️ 推荐的 Monorepo 结构

mcp-swagger-server/
├── packages/
│   ├── mcp-swagger-parser/          # 🔍 核心解析库
│   │   ├── src/
│   │   │   ├── parsers/
│   │   │   │   ├── openapi-parser.ts      # OpenAPI 3.x 解析器
│   │   │   │   ├── swagger-parser.ts      # Swagger 2.0 解析器
│   │   │   │   ├── postman-parser.ts      # Postman Collection 解析器
│   │   │   │   └── index.ts
│   │   │   ├── validators/
│   │   │   │   ├── schema-validator.ts    # 规范验证
│   │   │   │   ├── security-validator.ts  # 安全配置验证
│   │   │   │   └── index.ts
│   │   │   ├── normalizers/
│   │   │   │   ├── path-normalizer.ts     # 路径标准化
│   │   │   │   ├── schema-normalizer.ts   # Schema 标准化
│   │   │   │   └── index.ts
│   │   │   ├── types/
│   │   │   │   ├── openapi.ts            # OpenAPI 类型定义
│   │   │   │   ├── parser.ts             # 解析器接口
│   │   │   │   └── index.ts
│   │   │   └── index.ts                  # 主入口
│   │   ├── tests/
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── mcp-swagger-converter/       # 🔄 转换逻辑库
│   │   ├── src/
│   │   │   ├── converters/
│   │   │   │   ├── openapi-to-mcp.ts     # OpenAPI → MCP 转换
│   │   │   │   ├── postman-to-mcp.ts     # Postman → MCP 转换
│   │   │   │   └── index.ts
│   │   │   ├── strategies/
│   │   │   │   ├── rest-strategy.ts      # REST API 转换策略
│   │   │   │   ├── graphql-strategy.ts   # GraphQL 转换策略
│   │   │   │   └── index.ts
│   │   │   ├── optimizers/
│   │   │   │   ├── tool-optimizer.ts     # MCP 工具优化
│   │   │   │   ├── schema-optimizer.ts   # Schema 优化
│   │   │   │   └── index.ts
│   │   │   └── index.ts
│   │   ├── tests/
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── mcp-swagger-server/          # ⚙️ MCP 协议服务器
│   │   ├── src/
│   │   │   ├── server.ts            # MCP 服务器核心
│   │   │   ├── transports/          # 传输层
│   │   │   ├── tools/               # MCP 工具实现
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── mcp-swagger-ui/              # 🎨 Web 用户界面
│   │   ├── src/
│   │   ├── package.json
│   │   └── README.md
│   │
│   ├── mcp-swagger-cli/             # 💻 命令行工具 (新增)
│   │   ├── src/
│   │   │   ├── commands/
│   │   │   │   ├── convert.ts       # 转换命令
│   │   │   │   ├── validate.ts      # 验证命令
│   │   │   │   └── index.ts
│   │   │   ├── cli.ts               # CLI 入口
│   │   │   └── index.ts
│   │   ├── package.json
│   │   └── README.md
│   │
│   └── mcp-swagger-types/           # 📋 共享类型定义
│       ├── src/
│       │   ├── openapi.ts           # OpenAPI 类型
│       │   ├── mcp.ts               # MCP 类型
│       │   ├── config.ts            # 配置类型
│       │   └── index.ts
│       ├── package.json
│       └── README.md
│
├── apps/                            # 🚀 应用示例
│   ├── playground/                  # 在线演示
│   └── examples/                    # 使用示例
│
├── tools/                           # 🔧 开发工具
│   ├── build/                       # 构建脚本
│   ├── testing/                     # 测试工具
│   └── linting/                     # 代码检查
│
├── docs/                            # 📚 文档
├── package.json                     # 根 package.json
├── pnpm-workspace.yaml             # PNPM 工作空间配置
└── README.md

🎯 核心包职责分工

📦 mcp-swagger-parser

职责: 专注于 API 规范的解析和标准化

// 主要 API 设计
export class OpenApiParser {
  async parseFromUrl(url: string, options?: ParseOptions): Promise<ParsedApi>
  async parseFromFile(filepath: string, options?: ParseOptions): Promise<ParsedApi>
  async parseFromText(content: string, format: 'json' | 'yaml', options?: ParseOptions): Promise<ParsedApi>
  
  validate(spec: any): ValidationResult
  normalize(spec: ParsedApi): NormalizedApi
}

export interface ParsedApi {
  version: '2.0' | '3.0' | '3.1'
  info: ApiInfo
  paths: ApiPath[]
  components: ApiComponents
  security: SecurityScheme[]
}

🔄 mcp-swagger-converter

职责: 专注于格式转换逻辑

// 主要 API 设计
export class McpConverter {
  constructor(private options: ConvertOptions) {}
  
  async convertFromParsedApi(api: ParsedApi): Promise<McpConfig>
  async convertFromOpenApi(spec: OpenApiSpec): Promise<McpConfig>
  
  setStrategy(strategy: ConversionStrategy): void
  addOptimizer(optimizer: Optimizer): void
}

export interface ConvertOptions {
  filters: FilterConfig
  optimization: OptimizationConfig
  transport: TransportConfig
}

⚙️ mcp-swagger-server

职责: 专注于 MCP 协议实现

// 主要 API 设计
export class McpSwaggerServer {
  constructor(private config: ServerConfig) {}
  
  async start(): Promise<void>
  async stop(): Promise<void>
  
  addTool(tool: McpTool): void
  setTransport(transport: Transport): void
}

📊 依赖关系图

mcp-swagger-types ← (所有包都依赖)
       ↑
mcp-swagger-parser ← mcp-swagger-converter ← mcp-swagger-server
                                          ← mcp-swagger-cli
                                          ← mcp-swagger-ui

🚀 迁移计划

阶段 1: 创建核心解析库 (1-2 天)

• 创建 mcp-swagger-parser 包
• 抽离现有的 OpenAPI 解析逻辑
• 添加完整的类型定义
• 编写单元测试

阶段 2: 创建转换库 (2-3 天)

• 创建 mcp-swagger-converter 包
• 抽离转换逻辑
• 实现策略模式
• 添加优化器支持

阶段 3: 重构现有服务器 (1-2 天)

• 更新 mcp-swagger-server 使用新的库
• 更新 mcp-swagger-ui 使用新的库
• 更新依赖关系

阶段 4: 增强和扩展 (按需)

• 创建 CLI 工具
• 添加更多解析器支持
• 性能优化

💡 额外优势

1. 生态系统扩展

// 其他开发者可以轻松扩展
import { BaseParser } from 'mcp-swagger-parser';

class CustomApiParser extends BaseParser {
  // 自定义解析逻辑
}

2. 插件系统

// 支持插件扩展
const converter = new McpConverter()
  .use(new ValidationPlugin())
  .use(new OptimizationPlugin())
  .use(new CustomTransformPlugin());

3. 多环境支持

// Node.js 环境
import { OpenApiParser } from 'mcp-swagger-parser/node';

// 浏览器环境
import { OpenApiParser } from 'mcp-swagger-parser/browser';

// Deno 环境
import { OpenApiParser } from 'mcp-swagger-parser/deno';

🎯 结论

强烈推荐 进行这次重构！这不仅会让代码更加模块化和可维护，还为未来的扩展奠定了坚实的基础。这种架构设计体现了现代软件开发的最佳实践。