# 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