MCP Swagger Server

MCP Swagger Server(mss)

---

🎬 Demonstração Rápida

🎯 Capturas de Tela do Projeto

🎯 Sobre o Projeto

MCP Swagger Server é uma ferramenta que converte especificações OpenAPI/Swagger no formato Model Context Protocol (MCP).

📦 Estrutura do Projeto

mcp-swagger-server/
├── packages/
│   ├── mcp-swagger-server/     # 🔧 核心 MCP 服务器 (可用)
│   ├── mcp-swagger-parser/     # 📝 OpenAPI 解析器 (可用)
│   └── mcp-swagger-api/        # 🔗 REST API 后端 (可用)
└── scripts/                    # 🔨 构建脚本

✨ Recursos Principais

• 🔄 Conversão Zero Configuração: Insira a especificação OpenAPI e obtenha ferramentas MCP imediatamente
• 🎯 CLI Progressivo: Interface de linha de comando guiada passo a passo para facilitar a configuração
• 🖥️ Experiência com Foco no Terminal: CLI / terminal interativo como principal forma de uso
• 🔌 Múltiplos Protocolos de Transporte: Suporta transporte SSE, Streamable e Stdio
• 🔐 Autenticação Segura: Suporta autenticação Bearer Token para proteger o acesso à API

🚀 Início Rápido

Requisitos de Ambiente

• Node.js ≥ 20.0.0
• pnpm ≥ 8.0.0 (recomendado)

Instalação

npm i mcp-swagger-server -g

Descrição dos Comandos

• mss: Interface de terminal interativa (padrão)
• mcp-swagger-server / mcp-swagger: Linha de comando padrão (adequado para scripts e integração com clientes de IA)
• mss --openapi ...: Modo de inicialização direta (pula a interface interativa)

Nota: O modo de sessão interativa não suporta inicialização STDIO; se precisar de STDIO, use mss --openapi ... --transport stdio (alias compatível: mcp-swagger-server --transport stdio ...).

Inicialização Rápida

Inicialização Interativa (recomendado para iniciantes)

mss

Inicialização com Um Clique (não interativa)

mss --openapi https://api.example.com/openapi.json \
  --operation-filter-methods GET \
  --operation-filter-methods POST \
  --transport streamable \
  --auth-type bearer \
  --bearer-token "your-token-here"

# 使用配置文件
mss --config config.json

📖 Guia de Uso

Opções de Linha de Comando

# 基本用法
mss [选项]

# 选项：
--openapi, -o       OpenAPI 规范的 URL 或文件路径
--transport, -t     传输协议 (stdio|sse|streamable)
--port, -p          端口号
--endpoint, -e      自定义端点路径 (默认 sse:/sse, streamable:/mcp)
--base-url          覆盖 API 基础 URL（优先级最高）
--watch, -w         监控文件变化
--env               环境变量文件路径 (.env)

# Bearer Token 认证选项：
--auth-type         认证类型 (bearer)
--bearer-token      直接指定 Bearer Token
--bearer-env        从环境变量读取 Token
--config, -c        配置文件路径
--custom-header     自定义请求头 "Key=Value" (可重复)
--custom-header-env 环境变量请求头 "Key=VAR_NAME" (可重复)
--custom-headers-config  自定义请求头配置文件 (JSON)
--debug-headers     请求头调试日志

# 操作过滤选项：
--operation-filter-methods <method>         HTTP方法过滤 (可重复) [示例: GET]
--operation-filter-paths <path>             路径过滤 (支持通配符, 可重复) [示例: /api/*]
--operation-filter-operation-ids <id>       操作ID过滤 (可重复) [示例: getUserById]
--operation-filter-status-codes <code>      状态码过滤 (可重复) [示例: 200]
--operation-filter-parameters <param>       参数过滤 (可重复) [示例: userId]

Dica: Se quiser iniciar diretamente em mss (pulando a interface interativa), passe explicitamente o parâmetro --openapi. Se o servers.url no documento OpenAPI for um caminho relativo (como /v1), prefira carregar o documento via URL remota, ou passe explicitamente --base-url. Documentos Swagger 2.0 são convertidos automaticamente para OpenAPI 3.x na inicialização (incluindo mapeamento de host/basePath).

Exemplo de Cabeçalho de Requisição Xquik API Key

export XQUIK_API_KEY="your-xquik-api-key"
mss --openapi https://xquik.com/openapi.json \
  --base-url https://xquik.com \
  --custom-header-env x-api-key=XQUIK_API_KEY \
  --transport streamable \
  --port 3323

🔐 Autenticação Bearer Token

mcp-swagger-server suporta autenticação Bearer Token, protegendo o acesso a APIs que exigem autenticação.

Método de Autenticação

1. Especificar Token diretamente

mss --auth-type bearer --bearer-token "your-token-here" --openapi https://api.example.com/openapi.json --transport streamable

Configuração de Variáveis de Ambiente

Crie o arquivo .env:

# 基础配置
MCP_PORT=3322
MCP_TRANSPORT=stdio
MCP_OPENAPI_URL=https://api.example.com/openapi.json
MCP_ENDPOINT=/mcp
MCP_BASE_URL=https://api.example.com/v1

# 认证配置
MCP_AUTH_TYPE=bearer
API_TOKEN=your-bearer-token-here

🤖 Integração com Assistentes de IA

Configuração do Claude Desktop

{
  "mcpServers": {
    "swagger-converter": {
      "command": "mss",
      "args": [
        "--openapi", "https://petstore.swagger.io/v2/swagger.json",
        "--transport", "stdio"
      ]
    },
    "secured-api": {
      "command": "mss",
      "args": [
        "--openapi", "https://api.example.com/openapi.json",
        "--transport", "stdio",
        "--auth-type", "bearer",
        "--bearer-env", "API_TOKEN"
      ],
      "env": {
        "API_TOKEN": "your-bearer-token-here"
      }
    }
  }
}

🛠️ Desenvolvimento

Sistema de Build

# 构建所有包
pnpm build

# 构建核心工作区包
pnpm build:packages

# 终端开发模式（CLI / parser watch）
pnpm dev

# 清理构建产物
pnpm clean

🤝 Contribuição

Contribuições são bem-vindas! Leia primeiro o Guia de Contribuição.

📄 Licença

Licença MIT - consulte o arquivo LICENSE.

---