Mcp-Swagger-Server

# MCP Swagger Server 前端界面设计文档 ## 📋 概述 本文档描述了 MCP Swagger Server 前端界面的设计原型，该界面用于帮助用户轻松地将 OpenAPI/Swagger 规范转换为 MCP (Model Context Protocol) 格式。 ## 🎯 设计目标 1. **易用性**: 提供直观的用户界面，支持多种输入方式 2. **灵活性**: 支持 URL、文件上传和文本粘贴三种输入方式 3. **可视化**: 实时预览 API 信息和转换结果 4. **可配置**: 允许用户自定义转换选项 5. **响应式**: 适配不同屏幕尺寸的设备 ## 🎨 界面设计 ### 主要组件 #### 1. 头部区域 (Header) - **MCP Swagger Server** 主标题 - 简短的功能描述 - 采用渐变背景，提升视觉吸引力 #### 2. 输入区域 (Input Section) 提供三种输入方式的标签页切换： **🌐 URL 输入标签页** - Swagger/OpenAPI URL 输入框 - 可选的认证信息输入（Bearer token 或 API Key） - 预填充示例 URL：`https://petstore.swagger.io/v2/swagger.json` **📁 文件上传标签页** - 拖拽上传区域 - 支持 `.json`, `.yaml`, `.yml` 格式 - 视觉反馈：悬停效果和拖拽状态指示 **📝 文本输入标签页** - 大型文本框用于粘贴 OpenAPI 规范 - 支持 JSON 和 YAML 格式 #### 3. 操作按钮 - **🔄 转换为 MCP**: 主要操作按钮，带加载动画 - **🔍 验证规范**: 辅助功能，验证输入的 OpenAPI 规范 - 进度条显示转换进度 #### 4. API 信息预览区域 实时显示解析后的 API 信息： - **基本信息卡片**: - API 标题 - 版本号 - 服务器地址 - 端点数量 - **端点列表网格**: - HTTP 方法标签（颜色编码） - 端点路径 - 简短描述 #### 5. 转换配置区域 提供四个配置卡片： **🎯 端点过滤** - 按 HTTP 方法过滤（GET、POST 等） - 是否包含已弃用的端点 **🏷️ 标签过滤** - 按 OpenAPI 标签分类过滤 - 动态显示可用标签 **🔧 高级选项** - 生成参数验证 - 包含响应示例 - 优化工具名称 **🌐 传输协议** - stdio（标准输入输出） - SSE（服务器发送事件） - HTTP Stream（流式HTTP） #### 6. 转换结果区域 - **结果预览**: 语法高亮的 JSON 代码块 - **下载选项**: - 💾 下载 MCP 配置文件 - 📋 复制到剪贴板 - 🚀 直接启动服务 #### 7. 页脚区域 - 版权信息和项目介绍 ## 🎨 视觉设计特点 ### 颜色方案 - **主色调**: 渐变紫蓝色 (#667eea → #764ba2) - **背景色**: 浅灰色 (#f8f9fa) - **文字色**: 深灰色 (#333) - **状态颜色**: - 成功: 绿色 (#28a745) - 错误: 红色 (#dc3545) - 警告: 黄色 (#ffc107) ### 交互效果 - **悬停效果**: 轻微的阴影和位移 - **焦点状态**: 边框高亮和阴影 - **加载状态**: 旋转动画和进度条 - **拖拽状态**: 边框颜色变化和背景高亮 ### 响应式设计 - **桌面端**: 多列网格布局 - **平板端**: 自适应列数 - **移动端**: 单列布局，按钮堆叠 ## 🔄 用户交互流程 ### 主要使用场景 1. **URL 输入流程**: ``` 用户点击 URL 标签页 → 输入 Swagger URL → （可选）输入认证信息 → 点击"转换为 MCP" → 查看预览 → 配置选项 → 下载结果 ``` 2. **文件上传流程**: ``` 用户点击文件标签页 → 拖拽或选择文件 → 文件自动解析 → 点击"转换为 MCP" → 查看预览 → 配置选项 → 下载结果 ``` 3. **文本输入流程**: ``` 用户点击文本标签页 → 粘贴 OpenAPI 内容 → 点击"转换为 MCP" → 查看预览 → 配置选项 → 下载结果 ``` ### 错误处理 - **无效 URL**: 显示错误提示和建议 - **文件格式错误**: 高亮支持的格式 - **解析失败**: 显示具体错误信息和修复建议 - **网络错误**: 提供重试选项 ## 🚀 技术实现要点 ### 前端技术栈建议 - **基础**: HTML5, CSS3, JavaScript (ES6+) - **框架选择**: React.js 或 Vue.js - **UI 组件库**: Ant Design 或 Element UI - **代码高亮**: Prism.js 或 highlight.js - **文件处理**: File API 和 Drag & Drop API ### 后端集成 - **API 端点**: - `POST /api/convert` - 转换 OpenAPI 到 MCP - `POST /api/validate` - 验证 OpenAPI 规范 - `GET /api/health` - 健康检查 - **数据格式**: JSON - **错误处理**: 标准 HTTP 状态码和错误信息 ### 安全考虑 - **输入验证**: 严格验证所有用户输入 - **文件大小限制**: 限制上传文件大小 - **URL 白名单**: 可选的 URL 域名白名单 - **CORS 配置**: 正确配置跨域资源共享 ## 📱 移动端适配 ### 布局调整 - 单列布局替代多列网格 - 增大触摸目标尺寸 - 简化导航和交互 ### 功能优化 - 支持移动端文件选择 - 触摸友好的拖拽体验 - 适配屏幕键盘 ## 🎯 用户体验优化 ### 性能优化 - **懒加载**: 大型组件按需加载 - **缓存策略**: 缓存常用的 OpenAPI 规范 - **压缩**: 代码和资源压缩 ### 可访问性 - **键盘导航**: 完整的键盘操作支持 - **屏幕阅读器**: 正确的 ARIA 标签 - **对比度**: 符合 WCAG 标准的颜色对比度 ### 国际化 - 支持多语言切换 - 文本外部化 - 文化适配的图标和颜色 ## 📊 成功指标 ### 用户体验指标 - **任务完成率**: > 95% - **首次使用成功率**: > 85% - **平均完成时间**: < 2 分钟 ### 技术指标 - **页面加载时间**: < 3 秒 - **转换速度**: < 10 秒（中等复杂度 API） - **错误率**: < 1% ## 🔮 未来扩展 ### 高级功能 - **批量转换**: 支持多个 API 规范同时转换 - **模板系统**: 预定义的转换模板 - **API 测试**: 集成 API 测试功能 - **版本管理**: API 版本控制和比较 ### 集成功能 - **GitHub 集成**: 直接从 GitHub 仓库读取 OpenAPI 文件 - **云存储**: 支持云存储平台的文件导入 - **CI/CD**: 集成到持续集成流程 --- 本原型设计旨在提供直观、高效的用户体验，帮助开发者轻松地将 OpenAPI 规范转换为 MCP 格式，从而让 AI 助手能够更好地与 REST API 交互。