Swagger MCP

Extrae la interfaz de Swagger UI para generar dinámicamente herramientas MCP en tiempo de ejecución usando LLMs.

Documentación

swagger-mcp

Resumen

swagger-mcp es una herramienta que lee una especificación Swagger 2.0 u OpenAPI 3.0 y genera dinámicamente herramientas MCP en tiempo de ejecución — una herramienta por endpoint de API. Estas herramientas pueden ser utilizadas por cualquier cliente MCP para la interacción con API impulsada por LLM.

Formatos de especificación admitidos:

Swagger 2.0 (swagger: "2.0") — parámetros de ruta/consulta/cabecera y cuerpos de solicitud in: body
OpenAPI 3.0 (openapi: "3.0.x") — parámetros de ruta/consulta/cabecera y requestBody con esquemas en línea o $ref

Los campos obligatorios y opcionales se leen del array required del esquema y se respetan en las definiciones de herramientas generadas.

📽️ Video de demostración

Mira el video de demostración que muestra el proyecto en acción:

🙌 Soporte

Si encuentras valioso este proyecto, por favor apóyame en LinkedIn:

👍 Dando "me gusta" y compartiendo nuestra publicación de demostración
💬 Dejando tus opiniones y comentarios en los comentarios
🔗 Conectando conmigo para futuras actualizaciones

Tu apoyo en LinkedIn me ayudará a llegar a más personas y mejorar el proyecto.

Requisitos previos

Para usar swagger-mcp, asegúrate de tener las siguientes dependencias:

Clave de API de modelo LLM / LLM local: Requiere acceso a modelos de OpenAI, Claude u Ollama.
Cualquier cliente MCP: (Usado mark3labs - mcphost)

Instalación y configuración

go install github.com/danishjsheikh/swagger-mcp@latest

Configuración de ejecución

Modo Stdio (predeterminado)

swagger-mcp --specUrl=https://your_swagger_api_docs.json

Modo SSE

swagger-mcp --specUrl=https://your_swagger_api_docs.json --sse --sseAddr=:8080

Modo StreamableHTTP

swagger-mcp --specUrl=https://your_swagger_api_docs.json --http --httpAddr=:8080

Todas las banderas

Bandera	Descripción
`--specUrl`	URL o ruta `file://` de la especificación JSON de Swagger/OpenAPI (obligatorio)
`--baseUrl`	Sobrescribir la URL base para las solicitudes de API
`--sse`	Ejecutar en modo SSE en lugar de stdio
`--sseAddr`	Dirección de escucha SSE, `:Port` o `IP:Port`
`--sseUrl`	URL base SSE (derivada automáticamente de `--sseAddr` si se omite)
`--sseHeaders`	Cabeceras de solicitud separadas por comas para reenviar de SSE a la API (p. ej. `Authorization,X-Tenant`)
`--http`	Ejecutar en modo StreamableHTTP en lugar de stdio
`--httpAddr`	Dirección de escucha StreamableHTTP, `:Port` o `IP:Port`
`--httpPath`	Ruta del endpoint StreamableHTTP (predeterminado `/mcp`)
`--httpHeaders`	Cabeceras de solicitud separadas por comas para reenviar de HTTP a la API
`--includePaths`	Rutas o patrones regex separados por comas para incluir
`--excludePaths`	Rutas o patrones regex separados por comas para excluir
`--includeMethods`	Métodos HTTP separados por comas para incluir (p. ej. `GET,POST`)
`--excludeMethods`	Métodos HTTP separados por comas para excluir
`--security`	Tipo de autenticación: `basic`, `bearer` o `apiKey`
`--basicAuth`	Credenciales de autenticación básica en formato `user:password`
`--bearerAuth`	Token Bearer para la cabecera `Authorization`
`--apiKeyAuth`	Clave(s) de API: `passAs:name=value` — `passAs` es `header`, `query` o `cookie`; múltiples entradas separadas por comas (p. ej. `header:token=abc,query:user=foo`)
`--headers`	Cabeceras estáticas adicionales para cada solicitud, `name1=value1,name2=value2`

Ejemplo de OpenAPI de Xquik

Xquik publica un documento OpenAPI remoto para su API de automatización de X/Twitter. Debido a que utiliza una cabecera de clave de API, pasa la clave con --security=apiKey y --apiKeyAuth:

export XQUIK_API_KEY="your-xquik-api-key"

swagger-mcp \
  --specUrl=https://xquik.com/openapi.json \
  --baseUrl=https://xquik.com \
  --security=apiKey \
  --apiKeyAuth=header:x-api-key=$XQUIK_API_KEY

Los mismos argumentos se pueden usar en una configuración de cliente MCP:

{
  "mcpServers": {
    "xquik": {
      "command": "swagger-mcp",
      "args": [
        "--specUrl=https://xquik.com/openapi.json",
        "--baseUrl=https://xquik.com",
        "--security=apiKey",
        "--apiKeyAuth=header:x-api-key=<XQUIK_API_KEY>"
      ]
    }
  }
}

Configuración de MCP

Para integrarte con mcphost, incluye la siguiente configuración en .mcp.json:

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": ["--specUrl=<swagger/doc.json_url>"]
        }
    }
}

Con autenticación Bearer y filtrado de rutas:

{
    "mcpServers": {
        "swagger_loader": {
            "command": "swagger-mcp",
            "args": [
                "--specUrl=https://api.example.com/openapi.json",
                "--security=bearer",
                "--bearerAuth=your-token-here",
                "--includeMethods=GET,POST"
            ]
        }
    }
}

Soporte de cuerpo de solicitud

Se admiten cuerpos de solicitud tanto de Swagger 2.0 como de OpenAPI 3.0:

Swagger 2.0: parameters con in: body y un esquema $ref o en línea bajo definitions
OpenAPI 3.0: requestBody.content.<media-type>.schema — resuelto desde components/schemas si es un $ref, o usado en línea si es un esquema de objeto

Los campos enumerados en el array required del esquema se marcan como obligatorios en la herramienta MCP. Todos los demás campos son opcionales y se omiten de la solicitud si no se proporcionan.

Flujo de demostración

Algún backend:

go install github.com/danishjsheikh/go-backend-demo@latest 
go-backend-demo

Ollama
```
ollama run llama3.2
```

Cliente MCP

go install github.com/mark3labs/mcphost@latest
mcphost -m ollama:llama3.2 --config <.mcp.json_file_path>

Diagrama de flujo

Flow Diagram

🛠️ Necesito ayuda

Estoy trabajando en mejorar las definiciones de herramientas para mejorar:
✅ Mejor manejo de errores para respuestas más precisas
✅ Control del comportamiento del LLM para asegurar que se base solo en las respuestas de la API y no use su propia memoria
✅ Prevenir alucinaciones y generación de datos aleatorios al imponer una recuperación estricta de datos desde las APIs

Si tienes ideas o sugerencias para mejorar estos aspectos, por favor contribuye:

Compartiendo tu experiencia con implementaciones similares
Sugiriendo modificaciones a las definiciones de herramientas
Proporcionando comentarios sobre las limitaciones actuales

Tu aporte será invaluable para hacer esta herramienta más confiable y efectiva. 🚀