# OpenAPI MCP Server

A generic [Model Context Protocol (MCP)](https://modelcontextprotocol.io/) server that exposes any OpenAPI-documented REST API to LLMs like Claude.

## Features

- **Auto-discovers endpoints** from any OpenAPI 3.x specification (YAML or JSON)
- **Two simple tools**: `api_discover` and `api_request`
- **Flexible authentication**: None, API Key, or Bearer token
- **Caching**: Caches OpenAPI spec locally with configurable TTL
- **Retry logic**: Automatic retry on rate limits (429) with exponential backoff

## Installation

```bash
npm install @cloudwarriors/openapi-mcp
```

Or run directly with npx:

```bash
npx @cloudwarriors/openapi-mcp
```

## Configuration

The server is configured via environment variables:

### Required

| Variable | Description | Example |
|----------|-------------|---------|
| `API_BASE_URL` | Base URL of the API | `https://api.example.com` |

### Optional

| Variable | Description | Default |
|----------|-------------|---------|
| `API_OPENAPI_PATH` | Path to OpenAPI spec | `/openapi.yaml` |
| `API_AUTH_TYPE` | Authentication type: `none`, `apiKey`, `bearer` | `none` |
| `API_KEY` | API key (when `API_AUTH_TYPE=apiKey`) | - |
| `API_KEY_HEADER` | Header name for API key | `X-API-Key` |
| `API_BEARER_TOKEN` | Bearer token (when `API_AUTH_TYPE=bearer`) | - |
| `API_TIMEOUT_MS` | Request timeout in milliseconds | `30000` |
| `API_CACHE_TTL_MS` | OpenAPI spec cache TTL | `3600000` (1 hour) |

## Usage with Claude Code

Add to your `.mcp.json` or Claude Code settings:

```json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "https://api.example.com",
        "API_OPENAPI_PATH": "/docs/openapi.yaml"
      }
    }
  }
}
```

### Example: Connecting to Hermes

```json
{
  "mcpServers": {
    "hermes": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "http://localhost:3345",
        "API_OPENAPI_PATH": "/api/docs/openapi.yaml"
      }
    }
  }
}
```

### Example: Connecting to a Protected API

```json
{
  "mcpServers": {
    "my-api": {
      "command": "npx",
      "args": ["@cloudwarriors/openapi-mcp"],
      "env": {
        "API_BASE_URL": "https://api.mycompany.com",
        "API_OPENAPI_PATH": "/openapi.json",
        "API_AUTH_TYPE": "bearer",
        "API_BEARER_TOKEN": "your-token-here"
      }
    }
  }
}
```

## Tools

### `api_discover`

Lists all available API endpoints grouped by domain/tag.

**Parameters:**
- `domain` (optional): Filter endpoints by domain/tag
- `includeParameters` (optional): Include parameter details (default: false)

**Example:**
```json
{ "domain": "users", "includeParameters": true }
```

### `api_request`

Makes an HTTP request to any API endpoint.

**Parameters:**
- `method` (required): HTTP method (`GET`, `POST`, `PUT`, `DELETE`, `PATCH`)
- `path` (required): API path (e.g., `/api/users/{id}`)
- `body` (optional): Request body for POST/PUT/PATCH
- `query` (optional): Query parameters as key-value pairs
- `pathParams` (optional): Path parameter substitutions

**Example:**
```json
{
  "method": "GET",
  "path": "/api/users/{id}",
  "pathParams": { "id": "123" }
}
```

## Finding Your API's OpenAPI Spec

Common locations for OpenAPI specifications:

- `/openapi.yaml` or `/openapi.json`
- `/api/docs/openapi.yaml`
- `/swagger.json`
- `/v1/openapi.json`
- `/api-docs`

Check your API's documentation or try accessing these paths directly.

## Development

```bash
# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Development mode (watch)
npm run dev
```

## License

MIT

## Author

CloudWarriors