14 KiB
14 KiB
MCP Swagger Server 技术架构设计
🏗️ 系统架构概览
┌─────────────────────────────────────────────────────────────┐
│ 前端界面层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 输入组件 │ │ 预览组件 │ │ 配置组件 │ │
│ │ URL/文件/文本│ │ API信息展示 │ │ 转换参数设置│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
│ │ │ │ │
│ └───────────────┼───────────────┘ │
│ │ │
└─────────────────────────┼─────────────────────────────────┘
│ HTTP API 调用
▼
┌─────────────────────────────────────────────────────────────┐
│ API 网关层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 路由管理 │ │ 认证鉴权 │ │ CORS处理 │ │
│ │ /api/convert│ │ API Key │ │ 跨域请求 │ │
│ │ /api/validate│ │ Rate Limit│ │ 安全头 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 业务逻辑层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ OpenAPI解析 │ │ MCP转换器 │ │ 配置生成器 │ │
│ │ 格式验证 │ │ 工具生成 │ │ JSON输出格式│ │
│ │ 结构分析 │ │ 参数映射 │ │ YAML输出 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────┼─────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────────────┐
│ 数据处理层 │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ 文件系统IO │ │ HTTP客户端 │ │ 缓存管理 │ │
│ │ 本地文件 │ │ 远程URL │ │ 结果缓存 │ │
│ │ 临时存储 │ │ 认证处理 │ │ 配置缓存 │ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────────────────────────┘
🔧 技术栈详细设计
前端技术栈
┌─────────────────────────────────────────┐
│ React.js 18+ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 状态管理 │ │ UI组件库 │ │
│ │ Zustand │ │ Ant Design │ │
│ │ Context │ │ Tailwind │ │
│ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ HTTP客户端│ │ 开发工具 │ │
│ │ Axios │ │ Vite │ │
│ │ SWR/RQ │ │ TypeScript │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────┘
后端技术栈
┌─────────────────────────────────────────┐
│ Node.js │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ Web框架 │ │ 数据验证 │ │
│ │ Express │ │ Zod │ │
│ │ CORS │ │ Joi/Yup │ │
│ └─────────────┘ └─────────────┘ │
│ ┌─────────────┐ ┌─────────────┐ │
│ │ 文件处理 │ │ 类型系统 │ │
│ │ Multer │ │ TypeScript │ │
│ │ fs-extra │ │ ESLint │ │
│ └─────────────┘ └─────────────┘ │
└─────────────────────────────────────────┘
📡 API 接口设计
核心 API 端点
1. 转换 API
POST /api/v1/convert
Content-Type: application/json
{
"source": {
"type": "url|file|text",
"content": "https://api.example.com/swagger.json",
"auth": {
"type": "bearer|apikey|basic",
"token": "your-token"
}
},
"config": {
"filters": {
"methods": ["GET", "POST"],
"tags": ["pet", "store"],
"includeDeprecated": false
},
"transport": "stdio|sse|streamable",
"optimization": {
"generateValidation": true,
"includeExamples": false,
"optimizeNames": true
}
}
}
响应格式：
{
"success": true,
"data": {
"mcpConfig": {
"mcpServers": { /* MCP配置 */ },
"tools": [ /* 工具列表 */ ]
},
"metadata": {
"apiInfo": {
"title": "Pet Store API",
"version": "1.0.0",
"serverUrl": "https://petstore.swagger.io/v2"
},
"stats": {
"totalEndpoints": 20,
"convertedTools": 15,
"skippedEndpoints": 5
}
}
},
"processingTime": 1234
}
2. 验证 API
POST /api/v1/validate
Content-Type: application/json
{
"source": {
"type": "url|file|text",
"content": "OpenAPI规范内容"
}
}
3. 预览 API
POST /api/v1/preview
Content-Type: application/json
{
"source": { /* 同上 */ }
}
4. 健康检查 API
GET /api/v1/health
🔐 安全设计
输入验证
// Zod 验证模式
const ConvertRequestSchema = z.object({
source: z.object({
type: z.enum(['url', 'file', 'text']),
content: z.string().min(1).max(1024 * 1024), // 1MB限制
auth: z.object({
type: z.enum(['bearer', 'apikey', 'basic']).optional(),
token: z.string().optional()
}).optional()
}),
config: z.object({
filters: z.object({
methods: z.array(z.enum(['GET', 'POST', 'PUT', 'DELETE', 'PATCH'])).optional(),
tags: z.array(z.string()).optional(),
includeDeprecated: z.boolean().default(false)
}).optional(),
transport: z.enum(['stdio', 'sse', 'streamable']).default('stdio'),
optimization: z.object({
generateValidation: z.boolean().default(true),
includeExamples: z.boolean().default(false),
optimizeNames: z.boolean().default(true)
}).optional()
}).optional()
});
安全措施
- 输入大小限制: 文件上传限制 5MB
- URL 白名单: 可配置的允许访问的域名列表
- 速率限制: 每IP每分钟最多10个请求
- CORS 配置: 正确配置跨域访问策略
- 内容类型验证: 严格验证上传文件类型
📊 性能优化
缓存策略
interface CacheStrategy {
// Redis 缓存配置
redis: {
host: string;
port: number;
ttl: number; // 24小时
};
// 内存缓存
memory: {
maxSize: number; // 100MB
ttl: number; // 1小时
};
// 缓存键策略
keyGeneration: {
source: (content: string) => string; // SHA256
config: (config: object) => string;
};
}
异步处理
// 大文件异步处理
class AsyncProcessor {
async processLargeSpec(spec: OpenAPISpec): Promise<string> {
const jobId = generateJobId();
// 加入队列
await jobQueue.add('convert', {
jobId,
spec,
timestamp: Date.now()
});
return jobId;
}
async getJobStatus(jobId: string): Promise<JobStatus> {
return await jobQueue.getJob(jobId);
}
}
🔍 监控与日志
日志系统
import winston from 'winston';
const logger = winston.createLogger({
level: 'info',
format: winston.format.combine(
winston.format.timestamp(),
winston.format.errors({ stack: true }),
winston.format.json()
),
transports: [
new winston.transports.File({
filename: 'logs/error.log',
level: 'error'
}),
new winston.transports.File({
filename: 'logs/combined.log'
})
]
});
性能监控
// 请求耗时追踪
app.use((req, res, next) => {
const start = Date.now();
res.on('finish', () => {
const duration = Date.now() - start;
logger.info('Request processed', {
method: req.method,
url: req.url,
statusCode: res.statusCode,
duration,
userAgent: req.get('User-Agent')
});
});
next();
});
🚀 部署架构
Docker 容器化
# 多阶段构建
FROM node:18-alpine AS builder
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
FROM node:18-alpine AS runtime
WORKDIR /app
COPY --from=builder /app/node_modules ./node_modules
COPY . .
EXPOSE 3000
CMD ["npm", "start"]
Kubernetes 部署
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-swagger-server
spec:
replicas: 3
selector:
matchLabels:
app: mcp-swagger-server
template:
metadata:
labels:
app: mcp-swagger-server
spec:
containers:
- name: server
image: mcp-swagger-server:latest
ports:
- containerPort: 3000
env:
- name: NODE_ENV
value: "production"
resources:
requests:
memory: "256Mi"
cpu: "250m"
limits:
memory: "512Mi"
cpu: "500m"
📈 扩展性设计
插件系统
interface ConverterPlugin {
name: string;
version: string;
// 支持的OpenAPI版本
supportedVersions: string[];
// 转换逻辑
convert(spec: OpenAPISpec, config: ConvertConfig): Promise<MCPTools>;
// 验证逻辑
validate(spec: OpenAPISpec): Promise<ValidationResult>;
}
class PluginManager {
private plugins: Map<string, ConverterPlugin> = new Map();
register(plugin: ConverterPlugin): void {
this.plugins.set(plugin.name, plugin);
}
async convert(pluginName: string, spec: OpenAPISpec, config: ConvertConfig): Promise<MCPTools> {
const plugin = this.plugins.get(pluginName);
if (!plugin) {
throw new Error(`Plugin ${pluginName} not found`);
}
return await plugin.convert(spec, config);
}
}
微服务架构
┌─────────────┐ ┌─────────────┐ ┌─────────────┐
│ 前端服务 │ │ API网关 │ │ 转换服务 │
│ Nginx │◄──►│ Express │◄──►│ Worker │
│ 静态资源 │ │ 路由/认证 │ │ 队列处理 │
└─────────────┘ └─────────────┘ └─────────────┘
│
▼
┌─────────────┐
│ 缓存服务 │
│ Redis │
│ 结果缓存 │
└─────────────┘
这个技术架构设计提供了完整的前后端交互方案，确保系统的可扩展性、安全性和性能。