Swagger/Postman MCP Server

# Swagger/Postman MCP Server Server that ingests and serves Swagger/OpenAPI specifications and Postman collections as MCP (Model Context Protocol) tools using a **simplified strategic approach**. Instead of generating hundreds of individual tools for each API endpoint, this server provides **only 4 strategic tools** that allow AI agents to dynamically discover and interact with APIs: ```bash Example prompt: Help me generate an axios call using our api mcp. I want to implement updating a user. Follow our same DDD pattern (tanstack hook -> axios service) ``` ## Features - **Strategic Tool Approach**: Only 4 tools instead of hundreds for better AI agent performance - **OpenAPI/Swagger Support**: Load OpenAPI 2.0/3.0 specifications from URLs or local files - **Postman Collection Support**: Load Postman collection JSON files from URLs or local files - **Environment Variables**: Support for Postman environment files - **Authentication**: Multiple authentication methods (Basic, Bearer, API Key, OAuth2) - **Dynamic API Discovery**: Tools for listing, searching, and getting details about API endpoints - **Request Execution**: Execute API requests with proper parameter handling and authentication ## Security This is a personal server!! Do not expose it to the public internet. If the underlying API requires authentication, you should not expose the MCP server to the public internet. ## TODO - secrets - the MCP server should be able to use secrets from the user to authenticate requests to the API - Comprehensive test suite ## Prerequisites - Node.js (v18 or higher) - Yarn package manager - TypeScript ## Installation ```bash # Clone the repository git clone <repository-url> cd swag-mcp # Install dependencies npm install # or yarn install # Build the project npm run build # or yarn build # Make the start script executable (Linux/macOS) chmod +x start-mcp.sh ``` ### Quick Setup for Cursor 1. **Clone and build** (commands above) 2. **Configure** your `config.json` with your API details 3. **Update paths**: Edit `start-mcp.sh` and change the `cd` path to your installation directory 4. **Add to Cursor**: Edit `~/.cursor/mcp.json` and add: ```json { "mcpServers": { "postman-swagger-api": { "command": "/full/path/to/your/swag-mcp/start-mcp.sh" } } } ``` 5. **Restart Cursor** and start using the 4 strategic MCP tools! ## Configuration The server uses a `config.json` file for configuration. You can specify either OpenAPI/Swagger specifications or Postman collections. ### OpenAPI/Swagger Configuration ```json { "api": { "type": "openapi", "openapi": { "url": "https://petstore.swagger.io/v2/swagger.json", "apiBaseUrl": "https://petstore.swagger.io/v2", "defaultAuth": { "type": "apiKey", "apiKey": "special-key", "apiKeyName": "api_key", "apiKeyIn": "header" } } }, "log": { "level": "info" } } ``` ### Postman Collection Configuration ```json { "api": { "type": "postman", "postman": { "collectionUrl": "https://www.postman.com/collections/your-collection-id", "collectionFile": "./examples/postman-collection.json", "environmentUrl": "https://www.postman.com/environments/your-environment-id", "environmentFile": "./examples/postman-environment.json", "defaultAuth": { "type": "bearer", "token": "your-api-token-here" } } }, "log": { "level": "info" } } ``` ### Configuration Options #### API Configuration - `api.type`: Either `"openapi"` or `"postman"` - `api.openapi`: OpenAPI/Swagger specific configuration - `url`: URL to the OpenAPI specification - `apiBaseUrl`: Base URL for API requests - `defaultAuth`: Default authentication configuration - `api.postman`: Postman specific configuration - `collectionUrl`: URL to the Postman collection (optional) - `collectionFile`: Path to local Postman collection file (optional) - `environmentUrl`: URL to the Postman environment (optional) - `environmentFile`: Path to local Postman environment file (optional) - `defaultAuth`: Default authentication configuration #### Authentication Configuration - `type`: Authentication type (`"basic"`, `"bearer"`, `"apiKey"`, `"oauth2"`) - `username`: Username (for basic auth) - `password`: Password (for basic auth) - `token`: Token (for bearer/oauth2 auth) - `apiKey`: API key value - `apiKeyName`: API key parameter name - `apiKeyIn`: Where to send API key (`"header"` or `"query"`) #### Logging Configuration - `log.level`: Logging level (`"debug"`, `"info"`, `"warn"`, `"error"`) ## Usage ### Starting the MCP Server The server runs via stdio transport for MCP connections: ```bash # Start the simplified MCP server via stdio ./start-mcp.sh # Or directly with node node dist/simple-stdio.js # For development with auto-reload npm run dev:simple # or yarn dev:simple ``` ### MCP Integration This server uses stdio transport and is designed to be used with MCP clients like Claude Desktop or Cursor. ## Installing in Cursor To use this MCP server with Cursor, you need to add it to your Cursor MCP configuration: ### 1. Locate your Cursor MCP configuration file The configuration file is located at: - **Linux/macOS**: `~/.cursor/mcp.json` - **Windows**: `%APPDATA%\.cursor\mcp.json` ### 2. Add the MCP server configuration Edit your `mcp.json` file to include this server: ```json { "mcpServers": { "postman-swagger-api": { "command": "/path/to/your/swag-mcp/start-mcp.sh" } } } ``` **⚠️ Important: Change the path!** Replace `/path/to/your/swag-mcp/start-mcp.sh` with the actual path to your cloned repository. For example: - **Linux/macOS**: `"/home/username/Documents/swag-mcp/start-mcp.sh"` - **Windows**: `"C:\\Users\\username\\Documents\\swag-mcp\\start-mcp.sh"` ### 3. Example complete configuration ```json { "mcpServers": { "supabase": { "command": "npx", "args": [ "-y", "@supabase/mcp-server-supabase@latest", "--access-token", "your-supabase-token" ] }, "postman-swagger-api": { "command": "/home/username/Documents/swag-mcp/start-mcp.sh" } } } ``` ### 4. Restart Cursor After saving the configuration file, restart Cursor for the changes to take effect. ### 5. Verify installation In Cursor, you should now have access to the 4 strategic MCP tools: - `list_requests` - List all available requests - `get_request_details` - Get detailed request information - `search_requests` - Search requests by keyword - `make_request` - Execute any API request ### Troubleshooting If the MCP server fails to start: 1. **Update start-mcp.sh path**: Edit `start-mcp.sh` and change the `cd` path from `/path/to/your/swag-mcp` to your actual installation directory 2. **Check the path**: Ensure the path in `mcp.json` points to your actual `start-mcp.sh` file 3. **Check permissions**: Make sure `start-mcp.sh` is executable (`chmod +x start-mcp.sh`) 4. **Check build**: Ensure you've run `npm run build` to compile the TypeScript files 5. **Check logs**: Look in Cursor's MCP logs for error messages ### Example Path Updates If you cloned to `/home/username/Documents/swag-mcp/`, then: **In `start-mcp.sh`:** ```bash cd "/home/username/Documents/swag-mcp" ``` **In `~/.cursor/mcp.json`:** ```json "command": "/home/username/Documents/swag-mcp/start-mcp.sh" ``` ## How It Works ### Strategic Tool Approach Instead of generating hundreds of individual tools for each API endpoint, this server provides **4 strategic tools** that enable dynamic API discovery and interaction: ### OpenAPI/Swagger Mode **4 Strategic Tools:** 1. **`list_endpoints`** - List all available API endpoints 2. **`get_endpoint_details`** - Get detailed information about specific endpoints 3. **`search_endpoints`** - Search endpoints by keyword 4. **`make_api_call`** - Execute any API call with proper authentication **Process:** 1. Loads the OpenAPI specification from the configured URL or file 2. Parses the specification to extract API endpoints, parameters, and security schemes 3. Makes endpoint information available through the 4 strategic tools 4. Handles authentication and parameter validation dynamically 5. Executes API requests and returns responses ### Postman Collection Mode **4 Strategic Tools:** 1. **`list_requests`** - List all available requests in the collection 2. **`get_request_details`** - Get detailed information about specific requests 3. **`search_requests`** - Search requests by keyword 4. **`make_request`** - Execute any request from the collection **Process:** 1. Loads the Postman collection JSON from the configured URL or file 2. Optionally loads a Postman environment file for variable substitution 3. Parses requests, folders, and nested items in the collection 4. Makes request information available through the 4 strategic tools 5. Handles variable substitution, authentication, and parameter mapping dynamically 6. Executes requests with proper headers, query parameters, and body data ### Benefits of Strategic Tools - **Better AI Performance**: 4 tools vs hundreds means faster decision making - **Dynamic Discovery**: AI agents can explore APIs without knowing endpoints beforehand - **Flexible Interaction**: Any endpoint can be called through `make_api_call`/`make_request` - **Reduced Overwhelm**: AI agents aren't flooded with tool options ## Strategic Tools Reference ### For OpenAPI/Swagger APIs 1. **`list_endpoints`** - Lists all available API endpoints with methods and paths - No parameters required - Returns: Array of endpoint summaries 2. **`get_endpoint_details`** - Get detailed information about a specific endpoint - Parameters: `method` (GET/POST/etc), `path` (/users/{id}/etc) - Returns: Full endpoint specification with parameters, body schema, responses 3. **`search_endpoints`** - Search endpoints by keyword in path, summary, or description - Parameters: `query` (search term) - Returns: Filtered list of matching endpoints 4. **`make_api_call`** - Execute an API call to any endpoint - Parameters: `method`, `path`, `pathParams`, `queryParams`, `headers`, `body` - Returns: API response with status and data ### For Postman Collections 1. **`list_requests`** - Lists all available requests in the collection - No parameters required - Returns: Array of request summaries 2. **`get_request_details`** - Get detailed information about a specific request - Parameters: `requestId` or `requestName` - Returns: Full request specification 3. **`search_requests`** - Search requests by keyword - Parameters: `query` (search term) - Returns: Filtered list of matching requests 4. **`make_request`** - Execute any request from the collection - Parameters: `requestId`, `variables` (for substitution) - Returns: Request response ### Authentication The server supports multiple authentication methods: - **Basic Authentication**: Username/password - **Bearer Token**: JWT or other bearer tokens - **API Key**: In headers or query parameters - **OAuth2**: Bearer token based Authentication can be configured globally or overridden per request. ## Example Configuration Your `config.json` should specify either OpenAPI or Postman configuration as shown above. ### Example Postman Collection Structure ```json { "info": { "name": "Sample API Collection", "description": "A sample Postman collection" }, "item": [ { "name": "Get Users", "request": { "method": "GET", "header": [], "url": { "raw": "{{baseUrl}}/users", "host": ["{{baseUrl}}"], "path": ["users"] } } } ] } ``` ## Development ```bash # Install dependencies npm install # Run in development mode npm run dev # Run tests npm test # Build for production npm run build ``` ## License ISC ## Environment Variables - `PORT`: Server port (default: 3000) - `API_USERNAME`: Username for API authentication (fallback) - `API_PASSWORD`: Password for API authentication (fallback) - `API_TOKEN`: API token for authentication (fallback) - `DEFAULT_API_BASE_URL`: Default base URL for API endpoints (fallback) - `DEFAULT_SWAGGER_URL`: Default Swagger specification URL