Swagger MCP Server

# Swagger MCP 服务器开发路线图 ## 项目概述 开发一个MCP服务器，能够根据用户提供的Swagger/OpenAPI地址，解析API定义，并自动生成对应的接口代码和TypeScript类型约束。 ## 开发路线 ### 第一阶段：基础设施搭建 - [x] 1.1 创建项目结构和配置文件 - [x] 1.2 实现请求适配器接口及Axios实现 - [x] 1.3 实现Swagger解析器，能够解析API定义 - [x] 1.4 创建MCP服务器基础实现 - [x] 1.5 配置环境（包括测试和调试环境） ### 第二阶段：代码生成器开发 - [x] 2.1 设计代码生成器接口 - [x] 2.2 实现TypeScript类型定义生成器 - [x] 2.2.1 分析Swagger模式定义 - [x] 2.2.2 转换为TypeScript接口/类型 - [x] 2.2.3 生成类型文件 - [x] 2.3 实现API接口代码生成器 - [x] 2.3.1 设计API接口模板 - [x] 2.3.2 根据API操作生成接口函数 - [x] 2.3.3 生成完整的API客户端代码 ### 第三阶段：MCP工具实现 - [x] 3.1 实现解析Swagger文档的MCP工具 - [x] 3.1.1 实现基本解析功能 - [x] 3.1.2 处理不同版本的OpenAPI规范 - [x] 3.1.3 添加参数过滤（按标签、路径等） - [x] 3.1.4 优化返回结果格式 - [x] 3.2 实现生成TypeScript类型的MCP工具 - [x] 3.2.1 集成类型生成器 - [x] 3.2.2 添加类型生成选项 - [x] 3.2.3 支持不同的模式解析策略 - [x] 3.3 实现生成API接口代码的MCP工具 - [x] 3.3.1 集成API客户端生成器 - [x] 3.3.2 支持多种框架（Axios、Fetch、React Query） - [x] 3.3.3 添加代码生成选项 - [x] 3.4 实现文件读写的MCP工具集成 ### 第四阶段：性能优化与大型文档处理 - [x] 4.1 实现高效的缓存机制 - [x] 4.1.1 添加内存缓存层 - [x] 4.1.2 实现文件系统缓存 - [x] 4.1.3 添加缓存版本控制和TTL机制 - [x] 4.2 实现异步和并行处理 - [x] 4.2.1 使用Worker线程进行文档解析 - [x] 4.2.2 实现解析任务队列 - [x] 4.2.3 添加取消和超时机制 - [x] 4.3 优化大型文档解析 - [x] 4.3.1 实现懒加载解析策略 - [x] 4.3.2 增量解析与部分结果返回 - [x] 4.3.3 添加进度反馈机制 - [x] 4.4 提高解析稳定性 - [x] 4.4.1 增强错误处理和容错能力 - [x] 4.4.2 添加自动重试和降级策略 - [x] 4.4.3 改进非标准API文档支持 ### 第五阶段：高级功能与框架支持 - [ ] 5.1 添加模板自定义功能 - [ ] 5.1.1 设计模板系统 - [ ] 5.1.2 支持自定义模板引入 - [ ] 5.1.3 添加模板编辑工具 - [ ] 5.2 扩展框架支持 - [ ] 5.2.1 添加SWR支持 - [ ] 5.2.2 添加TanStack Query (React Query) 支持 - [ ] 5.2.3 添加Vue与Angular客户端支持 - [ ] 5.3 实现多语言支持 - [ ] 5.3.1 Python客户端生成 - [ ] 5.3.2 Java客户端生成 - [ ] 5.3.3 Go客户端生成 - [ ] 5.4 添加批量生成和项目集成 - [ ] 5.4.1 批量处理多个API端点 - [ ] 5.4.2 集成到现有项目结构 - [ ] 5.4.3 添加代码风格适配 ### 第六阶段：测试、文档和部署 - [ ] 6.1 编写单元测试和集成测试 - [ ] 6.1.1 解析器测试 - [ ] 6.1.2 生成器测试 - [ ] 6.1.3 性能测试 - [ ] 6.2 编写用户文档和API文档 - [ ] 6.2.1 使用指南 - [ ] 6.2.2 API参考 - [ ] 6.2.3 示例和最佳实践 - [ ] 6.3 准备容器化部署配置 - [ ] 6.3.1 创建Docker配置 - [ ] 6.3.2 设置Kubernetes部署 - [ ] 6.3.3 配置云服务部署 - [ ] 6.4 设置CI/CD流程 - [ ] 6.4.1 自动构建 - [ ] 6.4.2 自动测试 - [ ] 6.4.3 自动部署 - [ ] 6.5 发布和维护 - [ ] 6.5.1 版本控制 - [ ] 6.5.2 更新机制 - [ ] 6.5.3 用户反馈处理 ## 当前进度 目前已完成第一阶段和第二阶段，部分实现了第三阶段和第四阶段： 1. 基础设施搭建 - 创建了项目结构和配置文件 - 实现了请求适配器接口及Axios实现 - 实现了Swagger解析器，能够解析API定义 - 创建了MCP服务器基础实现 - 配置了测试和调试环境 2. 代码生成器开发 - 设计了代码生成器接口 - 实现了TypeScript类型定义生成器，能够分析Swagger模式并生成对应的TypeScript类型 - 实现了API接口代码生成器，能够生成基于不同框架（如Axios、Fetch、React Query）的API客户端代码 - 集成了fs mcp工具实现文件读写功能 3. MCP工具实现（完成） - 实现了文件读写的MCP工具集成（3.4） - 实现了解析Swagger文档的MCP工具（3.1） - 实现了TypeScript类型生成MCP工具（3.2） - 标准版和优化版两种工具 - 支持缓存和懒加载等性能优化选项 - 支持过滤和自定义类型生成 - 实现了API客户端生成MCP工具（3.3） - 标准版和优化版两种工具 - 支持多种框架（Axios、Fetch、React Query） - 提供性能优化选项如缓存和懒加载 - 添加进度反馈机制 - 新增了优化版解析工具，支持各种高级选项 4. 性能优化与大型文档处理（已完成） - 实现了内存和文件系统缓存机制（4.1） - 添加了懒加载解析策略，支持大型文档（4.3） - 实现了进度反馈机制（4.3.3） - 提高了解析稳定性和容错能力（4.4） - 添加了轻量级解析模式，专为大型文档优化 ## 当前问题 1. **大型Swagger文档解析性能问题** - 解析大型文档时会导致服务卡顿 - 缺少缓存机制，每次请求都重新解析 - 解析过程是同步的，阻塞主线程 - 缺少分步解析和进度反馈 2. **MCP工具实现不完整** - 解析Swagger工具需要完善 - 类型生成和API客户端生成工具尚未实现 3. **错误处理和稳定性问题** - 解析非标准API文档时容错性不足 - 错误处理机制简单 ## 下一步计划 1. 优先实现第四阶段的性能优化，特别是缓存机制和异步处理 2. 改进Swagger解析工具，增加对大型文档的处理能力 3. 完成剩余MCP工具的实现 4. 提高整体稳定性和错误处理