Swagger Explorer MCP

Un servidor de plano de control de gestión (MCP) para explorar y analizar las especificaciones Swagger/OpenAPI a través de Claude.

Inicio rápido

Instalar y ejecutar globalmente usando npx:

npx -y @johnneerdael/swagger-mcp

O instalar con variables de entorno:

npx -y @johnneerdael/swagger-mcp \
  --env BASE_URL=/api \
  --env AUTH_TOKEN=your-token \
  --env PORT=3000

Related MCP server: MCP-QA

Instalación para Claude Desktop

1. Abra Claude Desktop

2. Haga clic en Configuración (icono de engranaje)

3. Seleccione "Herramientas e integraciones".

4. Haga clic en "Agregar servidor MCP"

5. Introduzca lo siguiente:

   Name: Swagger Explorer
   Command: npx -y @johnneerdael/swagger-mcp
   Arguments: --swagger-url=$SWAGGER_URL

6. Haga clic en "Instalar"

Uso con Claude

A continuación se muestran algunos ejemplos de interacciones con Claude:

Exploración básica de Swagger

Human: Can you explore the Swagger documentation at http://localhost:8080/docs?

Claude: I'll help you explore that Swagger documentation using the Swagger Explorer MCP.

Let me analyze the API endpoints and schemas for you:

[Claude would then use the MCP to fetch and analyze the Swagger documentation]

Análisis de puntos finales específicos

Human: What are the available response schemas for the /pets POST endpoint?

Claude: I'll check the response schemas for that endpoint using the MCP.

[Claude would use the MCP to fetch specific endpoint details]

Análisis de esquemas

Human: Can you show me the detailed structure of the Pet schema?

Claude: I'll retrieve the detailed schema information using the MCP.

[Claude would use the MCP to analyze the schema structure]

Características

1. Soporte de autenticación

   • Autenticación de token de portador

   • Configurable a través de variables de entorno

2. Formato de respuesta personalizado

   • Formato mínimo: elimina valores nulos o vacíos

   • Formato detallado: incluye metadatos y marcas de tiempo.

   • Formato sin procesar: Respuesta sin modificar

3. Análisis de esquemas

   • Exploración detallada de la propiedad

   • Análisis del esquema de respuesta

   • Relaciones de esquema

4. Exploración de API

   • Listado de rutas

   • Filtrado de métodos

   • Análisis del formato de respuesta

Configuración

Variables de entorno:

• BASE_URL : Ruta base para la API (predeterminado: '')

• AUTH_TOKEN : Token portador para autenticación

• PORT : Puerto del servidor (predeterminado: 3000)

• SWAGGER_URL : URL de documentación de Swagger predeterminada

Puntos finales de API

Explorar API

curl -X POST http://localhost:3000/api/explore \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "options": {
      "paths": true,
      "schemas": true
    }
  }'

Obtener detalles del esquema

curl -X POST http://localhost:3000/api/schema-details \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "schemaName": "Pet"
  }'

Obtener esquemas de respuesta

curl -X POST http://localhost:3000/api/response-schemas \
  -H "Authorization: Bearer your-token" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "http://your-swagger-url",
    "path": "/pets",
    "method": "post"
  }'

Formatos de respuesta

Formato mínimo

{
  "status": "success",
  "data": {
    // Only non-null values
  }
}

Formato detallado

{
  "status": "success",
  "timestamp": "2025-01-29T10:00:00.000Z",
  "data": {
    // Full response
  },
  "metadata": {
    "version": "1.0",
    "format": "detailed"
  }
}

Casos de uso comunes

1. Revisión de la documentación de la API

   Human: Can you summarize all the available endpoints and their purposes?

2. Validación de esquemas

   Human: What fields are required for creating a new pet?

3. Análisis de respuesta

   Human: What are the possible error responses for the login endpoint?

4. Planificación de la integración

   Human: How should I structure my request to create a new order?

Solución de problemas

1. Problemas de conexión

   • Asegúrese de que la URL de Swagger sea accesible

   • Comprobar si el token de autenticación es correcto

   • Verificar que el puerto no esté en uso

2. Errores de autorización

   • Verifique que AUTH_TOKEN esté configurado correctamente

   • Asegúrese de que el token portador esté incluido en las solicitudes

3. Esquema no encontrado

   • Comprobar si el nombre del esquema coincide exactamente

   • Verifique que la especificación Swagger esté cargada correctamente

Notas de seguridad

1. El MCP requiere autenticación si AUTH_TOKEN está configurado

2. Todas las solicitudes se registran para su depuración.

3. La información confidencial no se almacena en caché

4. Se aplica una limitación de velocidad para evitar el abuso.

Desarrollo

Para contribuir o modificar:

1. Clonar el repositorio

2. Instalar dependencias:

   npm install

3. Construir:

   npm run build

4. Ejecutar localmente:

   npm start

Licencia

Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles