mcp-swagger-server/docs/deployment-guide.md

MCP Swagger 完整部署指南

概述

本指南介绍如何在不同场景下部署和使用 mcp-swagger-api 和 mcp-swagger-server。

目录

1. 快速开始
2. mcp-swagger-api 部署
3. mcp-swagger-server 部署
4. 集成使用
5. 生产环境部署
6. 监控和维护

快速开始

环境要求

• Node.js >= 18.0.0
• pnpm >= 8.0.0

安装依赖

# 根目录安装所有依赖
pnpm install

# 构建所有包
pnpm run build

mcp-swagger-api 部署

本地开发

cd packages/mcp-swagger-api
pnpm run start:dev

服务将在 http://localhost:3000 启动，API文档可在 http://localhost:3000/api 查看。

环境配置

创建 .env 文件：

# 服务配置
PORT=3000
NODE_ENV=development

# MCP 配置
MCP_DEFAULT_PORT=8765
MCP_API_KEY=your-secure-api-key

# 数据库配置（如果需要）
DATABASE_URL=postgresql://user:password@localhost:5432/mcp_swagger

# 日志配置
LOG_LEVEL=info

Docker 部署

创建 Dockerfile：

FROM node:18-alpine

WORKDIR /app

# 复制依赖文件
COPY package*.json ./
COPY pnpm-lock.yaml ./

# 安装 pnpm
RUN npm install -g pnpm

# 安装依赖
RUN pnpm install --frozen-lockfile

# 复制源代码
COPY . .

# 构建应用
RUN pnpm run build

# 暴露端口
EXPOSE 3000

# 启动应用
CMD ["pnpm", "run", "start:prod"]

# 构建镜像
docker build -t mcp-swagger-api .

# 运行容器
docker run -p 3000:3000 -e MCP_API_KEY=your-key mcp-swagger-api

使用示例

# 创建 MCP 服务器
curl -X POST http://localhost:3000/api/v1/mcp/create \
  -H "Content-Type: application/json" \
  -H "x-api-key: your-key" \
  -d '{
    "openApiData": "https://petstore.swagger.io/v2/swagger.json",
    "config": {
      "name": "Petstore API",
      "port": 8765,
      "transport": "http"
    }
  }'

# 查看状态
curl http://localhost:3000/api/v1/mcp/status \
  -H "x-api-key: your-key"

# 获取监控指标
curl http://localhost:3000/api/v1/monitoring/metrics \
  -H "x-api-key: your-key"

mcp-swagger-server 部署

CLI 使用

cd packages/mcp-swagger-server

# 基本使用
pnpm run cli:help

# 使用远程 OpenAPI
pnpm run cli -- -t streamable -p 3322 -o https://api.github.com/openapi.json

# 使用本地文件并监听变化
pnpm run cli -- -t sse -p 3322 -o ./openapi.json -w

# 使用配置文件
pnpm run cli -- -c ./config.json

配置文件示例

创建 mcp-config.json：

{
  "transport": "streamable",
  "port": 3322,
  "endpoint": "/mcp",
  "openapi": "https://api.github.com/openapi.json",
  "watch": false,
  "verbose": true
}

Claude Desktop 集成

在 Claude Desktop 的配置文件中添加：

{
  "mcpServers": {
    "mcp-swagger": {
      "command": "node",
      "args": ["/path/to/mcp-swagger-server/dist/cli.js", 
               "-t", "stdio", 
               "-o", "https://api.github.com/openapi.json", 
               "-v"]
    }
  }
}

系统服务部署

创建 systemd 服务文件 /etc/systemd/system/mcp-swagger.service：

[Unit]
Description=MCP Swagger Server
After=network.target

[Service]
Type=simple
User=mcp
WorkingDirectory=/opt/mcp-swagger-server
ExecStart=/usr/bin/node dist/cli.js -t streamable -p 3322 -o https://api.github.com/openapi.json -v
Restart=always
RestartSec=10
Environment=NODE_ENV=production

[Install]
WantedBy=multi-user.target

启动服务：

sudo systemctl enable mcp-swagger
sudo systemctl start mcp-swagger
sudo systemctl status mcp-swagger

集成使用

前端集成 (mcp-swagger-ui)

// 在前端应用中集成
const createMCPServer = async (openApiUrl: string) => {
  const response = await fetch('/api/v1/mcp/create', {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'x-api-key': 'your-api-key'
    },
    body: JSON.stringify({
      openApiData: openApiUrl,
      config: {
        name: 'Dynamic API',
        transport: 'websocket'
      }
    })
  });

  return response.json();
};

// 监控服务状态
const monitorStatus = async () => {
  const response = await fetch('/api/v1/mcp/status', {
    headers: { 'x-api-key': 'your-api-key' }
  });
  
  return response.json();
};

API 网关集成

使用 Nginx 作为反向代理：

upstream mcp_api {
    server localhost:3000;
}

upstream mcp_server {
    server localhost:3322;
}

server {
    listen 80;
    server_name api.yourdomain.com;

    # API 服务
    location /api/ {
        proxy_pass http://mcp_api;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    # MCP 服务器
    location /mcp/ {
        proxy_pass http://mcp_server;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
    }
}

生产环境部署

使用 Docker Compose

创建 docker-compose.yml：

version: '3.8'

services:
  mcp-swagger-api:
    build: ./packages/mcp-swagger-api
    ports:
      - "3000:3000"
    environment:
      - NODE_ENV=production
      - MCP_API_KEY=${MCP_API_KEY}
      - DATABASE_URL=${DATABASE_URL}
    depends_on:
      - postgres
      - redis
    restart: always

  mcp-swagger-server:
    build: ./packages/mcp-swagger-server
    ports:
      - "3322:3322"
    environment:
      - NODE_ENV=production
    command: ["node", "dist/cli.js", "-t", "streamable", "-p", "3322", "-o", "${OPENAPI_URL}", "-v"]
    restart: always

  postgres:
    image: postgres:15
    environment:
      - POSTGRES_DB=mcp_swagger
      - POSTGRES_USER=${DB_USER}
      - POSTGRES_PASSWORD=${DB_PASSWORD}
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    volumes:
      - redis_data:/data

  nginx:
    image: nginx:alpine
    ports:
      - "80:80"
      - "443:443"
    volumes:
      - ./nginx.conf:/etc/nginx/nginx.conf
      - ./ssl:/etc/ssl/certs
    depends_on:
      - mcp-swagger-api
      - mcp-swagger-server

volumes:
  postgres_data:
  redis_data:

Kubernetes 部署

创建 k8s-deployment.yaml：

apiVersion: apps/v1
kind: Deployment
metadata:
  name: mcp-swagger-api
spec:
  replicas: 3
  selector:
    matchLabels:
      app: mcp-swagger-api
  template:
    metadata:
      labels:
        app: mcp-swagger-api
    spec:
      containers:
      - name: api
        image: mcp-swagger-api:latest
        ports:
        - containerPort: 3000
        env:
        - name: MCP_API_KEY
          valueFrom:
            secretKeyRef:
              name: mcp-secrets
              key: api-key
        resources:
          requests:
            memory: "256Mi"
            cpu: "250m"
          limits:
            memory: "512Mi"
            cpu: "500m"

---
apiVersion: v1
kind: Service
metadata:
  name: mcp-swagger-api-service
spec:
  selector:
    app: mcp-swagger-api
  ports:
  - port: 80
    targetPort: 3000
  type: LoadBalancer

监控和维护

健康检查

# API 服务健康检查
curl http://localhost:3000/api/v1/monitoring/health

# MCP 服务器健康检查
curl http://localhost:3322/health

日志管理

# 查看 API 服务日志
docker logs mcp-swagger-api

# 查看 MCP 服务器日志
sudo journalctl -u mcp-swagger -f

# 使用 ELK 栈收集日志
# Logstash 配置示例
input {
  file {
    path => "/var/log/mcp-swagger/*.log"
    type => "mcp-swagger"
  }
}

filter {
  if [type] == "mcp-swagger" {
    json {
      source => "message"
    }
  }
}

output {
  elasticsearch {
    hosts => ["localhost:9200"]
    index => "mcp-swagger-%{+YYYY.MM.dd}"
  }
}

性能监控

使用 Prometheus 和 Grafana：

# prometheus.yml
global:
  scrape_interval: 15s

scrape_configs:
  - job_name: 'mcp-swagger-api'
    static_configs:
      - targets: ['localhost:3000']
    metrics_path: '/api/v1/monitoring/metrics'
    
  - job_name: 'mcp-swagger-server'
    static_configs:
      - targets: ['localhost:3322']
    metrics_path: '/metrics'

备份策略

#!/bin/bash
# backup.sh - 备份脚本

# 备份配置文件
cp /opt/mcp-swagger/config/*.json /backup/config/

# 备份数据库
pg_dump mcp_swagger | gzip > /backup/db/mcp_swagger_$(date +%Y%m%d).sql.gz

# 清理旧备份
find /backup -name "*.gz" -mtime +7 -delete

故障排除

常见问题

1. 端口冲突

   # 检查端口占用
   lsof -i :3000
   lsof -i :3322
   
   # 更换端口
   export PORT=3001
   

2. OpenAPI 加载失败

   # 检查 URL 可访问性
   curl -I https://api.github.com/openapi.json
   
   # 检查本地文件权限
   ls -la ./openapi.json
   

3. 内存不足

   # 检查内存使用
   free -h
   
   # 增加 Node.js 内存限制
   export NODE_OPTIONS="--max-old-space-size=4096"
   

性能优化

1. API 服务优化

   • 启用 Redis 缓存
   • 配置连接池
   • 启用 gzip 压缩

2. MCP 服务器优化

   • 减少轮询频率
   • 启用工具缓存
   • 优化 OpenAPI 解析

通过以上配置，你就可以在各种环境下成功部署和使用 MCP Swagger 系统了。