# Swagger Explorer MCP A Management Control Plane (MCP) server for exploring and analyzing Swagger/OpenAPI specifications through Claude. ## Quick Start Install and run globally using npx: \`\`\`bash npx -y @johnneerdael/swagger-mcp \`\`\` Or install with environment variables: \`\`\`bash npx -y @johnneerdael/swagger-mcp \ --env BASE_URL=/api \ --env AUTH_TOKEN=your-token \ --env PORT=3000 \`\`\` ## Installation for Claude Desktop 1. Open Claude Desktop 2. Click on Settings (gear icon) 3. Select "Tools & Integrations" 4. Click "Add MCP Server" 5. Enter the following: \`\`\` Name: Swagger Explorer Command: npx -y @johnneerdael/swagger-mcp Arguments: --swagger-url=$SWAGGER_URL \`\`\` 6. Click "Install" ## Usage with Claude Here are some example interactions with Claude: ### Basic Swagger Exploration \`\`\` 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] \`\`\` ### Analyzing Specific Endpoints \`\`\` 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] \`\`\` ### Schema Analysis \`\`\` 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] \`\`\` ## Features 1. **Authentication Support** - Bearer token authentication - Configurable through environment variables 2. **Custom Response Formatting** - Minimal format: Removes null/empty values - Detailed format: Includes metadata and timestamps - Raw format: Unmodified response 3. **Schema Analysis** - Detailed property exploration - Response schema analysis - Schema relationships 4. **API Exploration** - Path listing - Method filtering - Response format analysis ## Configuration Environment Variables: - \`BASE_URL\`: Base path for the API (default: '') - \`AUTH_TOKEN\`: Bearer token for authentication - \`PORT\`: Server port (default: 3000) - \`SWAGGER_URL\`: Default Swagger documentation URL ## API Endpoints ### Explore API \`\`\`bash 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 \} \}' \`\`\` ### Get Schema Details \`\`\`bash 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" \}' \`\`\` ### Get Response Schemas \`\`\`bash 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" \}' \`\`\` ## Response Formats ### Minimal Format \`\`\`json \{ "status": "success", "data": \{ // Only non-null values \} \} \`\`\` ### Detailed Format \`\`\`json \{ "status": "success", "timestamp": "2025-01-29T10:00:00.000Z", "data": \{ // Full response \}, "metadata": \{ "version": "1.0", "format": "detailed" \} \} \`\`\` ## Common Use Cases 1. **API Documentation Review** \`\`\` Human: Can you summarize all the available endpoints and their purposes? \`\`\` 2. **Schema Validation** \`\`\` Human: What fields are required for creating a new pet? \`\`\` 3. **Response Analysis** \`\`\` Human: What are the possible error responses for the login endpoint? \`\`\` 4. **Integration Planning** \`\`\` Human: How should I structure my request to create a new order? \`\`\` ## Troubleshooting 1. **Connection Issues** - Ensure the Swagger URL is accessible - Check if authentication token is correct - Verify port is not in use 2. **Authorization Errors** - Verify AUTH_TOKEN is set correctly - Ensure bearer token is included in requests 3. **Schema Not Found** - Check if schema name is exact match - Verify Swagger spec is loaded correctly ## Security Notes 1. The MCP requires authentication if AUTH_TOKEN is set 2. All requests are logged for debugging 3. Sensitive information is not cached 4. Rate limiting is applied to prevent abuse ## Development To contribute or modify: 1. Clone the repository 2. Install dependencies: \`\`\`bash npm install \`\`\` 3. Build: \`\`\`bash npm run build \`\`\` 4. Run locally: \`\`\`bash npm start \`\`\` ## License MIT License - See LICENSE file for details