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
Instalación para Claude Desktop
- Abra Claude Desktop
- Haga clic en Configuración (icono de engranaje)
- Seleccione "Herramientas e integraciones".
- Haga clic en "Agregar servidor MCP"
- Introduzca lo siguiente:
Name: Swagger Explorer
Command: npx -y @johnneerdael/swagger-mcp
Arguments: --swagger-url=$SWAGGER_URL
- 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
- Soporte de autenticación
- Autenticación de token de portador
- Configurable a través de variables de entorno
- 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
- Análisis de esquemas
- Exploración detallada de la propiedad
- Análisis del esquema de respuesta
- Relaciones de esquema
- 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ónPORT : 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"
}'
{
"status": "success",
"data": {
// Only non-null values
}
}
{
"status": "success",
"timestamp": "2025-01-29T10:00:00.000Z",
"data": {
// Full response
},
"metadata": {
"version": "1.0",
"format": "detailed"
}
}
Casos de uso comunes
- Revisión de la documentación de la API
Human: Can you summarize all the available endpoints and their purposes?
- Validación de esquemas
Human: What fields are required for creating a new pet?
- Análisis de respuesta
Human: What are the possible error responses for the login endpoint?
- Planificación de la integración
Human: How should I structure my request to create a new order?
Solución de problemas
- 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
- Errores de autorización
- Verifique que AUTH_TOKEN esté configurado correctamente
- Asegúrese de que el token portador esté incluido en las solicitudes
- Esquema no encontrado
- Comprobar si el nombre del esquema coincide exactamente
- Verifique que la especificación Swagger esté cargada correctamente
Notas de seguridad
- El MCP requiere autenticación si AUTH_TOKEN está configurado
- Todas las solicitudes se registran para su depuración.
- La información confidencial no se almacena en caché
- Se aplica una limitación de velocidad para evitar el abuso.
Desarrollo
Para contribuir o modificar:
- Clonar el repositorio
- Instalar dependencias:
- Construir:
- Ejecutar localmente:
Licencia
Licencia MIT: consulte el archivo de LICENCIA para obtener más detalles