# Generic OpenAPI / Swagger MCP Server & Code Generator

Turn **any** OpenAPI (v3.0 / v3.1) or Swagger (v2.0) specification file (`JSON` or `YAML`) into a fully functional **Model Context Protocol (MCP)** server.

This project supports two operating modes:
1. **Dynamic Runtime Mode (`main.py`)**: Drop your `swagger.json` or `openapi.yaml` into the root directory, configure `.env`, and immediately serve all API endpoints as LLM tools via MCP.
2. **Code Generator Mode (`generator.py`)**: Run a simple command to parse any OpenAPI spec and generate standalone, static, readable Python code containing explicit MCP tools with complete docstrings.

---

## 🚀 Features

- **Universal Support**: Parses OpenAPI 2.0 (Swagger) and OpenAPI 3.0 / 3.1 specs in JSON or YAML.
- **Reference Resolution**: Resolves `$ref` schema pointer references (`#/definitions/...` or `#/components/schemas/...`).
- **Rich LLM Docstrings**: Formats endpoint summaries, descriptions, path/query/header parameters, and JSON request body structures into clean Markdown for LLMs.
- **Flexible Authentication**:
  - Bearer Token / JWT
  - API Keys (Custom Header or Query Parameter)
  - Basic Authentication
  - Custom JSON Headers
- **Dual Operating Modes**: Dynamic execution vs. standalone code generation.

---

## 📦 Setup & Installation

### 1. Prerequisites
- Python >= 3.11
- [uv](https://github.com/astral-sh/uv) (recommended) or standard `pip`

### 2. Install Dependencies
```bash
pip install -e .
```
or with `uv`:
```bash
uv sync
```

---

## ⚙️ Configuration (`.env`)

Copy `.env.example` to `.env`:
```bash
cp .env.example .env
```

| Variable | Description | Default / Example |
| :--- | :--- | :--- |
| `SWAGGER_PATH` | Path to OpenAPI/Swagger spec file | Auto-detects `swagger.json`, `openapi.yaml`, etc. |
| `BASE_URL` | Override Base URL of target API | Spec's host/servers URL |
| `BEARER_TOKEN` | Bearer Token / JWT for `Authorization: Bearer <token>` | Optional |
| `API_KEY` | API Key value | Optional |
| `AUTH_HEADER_NAME` | Header name for API Key | `X-API-Key` |
| `AUTH_QUERY_PARAM` | Query parameter name for API Key | Optional (e.g. `api_key`) |
| `BASIC_AUTH_USER` | Basic Auth username | Optional |
| `BASIC_AUTH_PASS` | Basic Auth password | Optional |

---

## 🎯 Mode 1: Dynamic Runtime MCP Server (`main.py`)

Simply place your spec file (e.g., `swagger.json`) in the project directory and launch:

```bash
python main.py
```

`main.py` will:
1. Load and dereference `swagger.json` or `openapi.yaml`.
2. Discover all paths and HTTP operations.
3. Automatically register each endpoint as an MCP tool with full descriptions.
4. Listen on `stdio` for MCP client connections (Claude Desktop, Cursor, Smithery, etc.).

---

## 🛠️ Mode 2: Standalone Code Generator (`generator.py`)

Generate a clean, standalone Python script from any spec file:

```bash
python generator.py --spec swagger.json --output my_api_mcp.py --name "my-api-service"
```

### Options:
- `--spec`, `-s`: Path to spec file (`swagger.json`, `openapi.yaml`). Default: `swagger.json`.
- `--output`, `-o`: Output Python file path. Default: `generated_mcp.py`.
- `--name`, `-n`: FastMCP server name identifier. Default: `openapi-mcp`.

Once generated, run your generated server directly:
```bash
python my_api_mcp.py
```

---

## 💻 Integration with Claude Desktop / Cursor / Inspector

Add the server to your MCP client configuration (e.g., `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "my-openapi-service": {
      "command": "python",
      "args": [
        "c:/path/to/reward-rally-mcp/main.py"
      ],
      "env": {
        "SWAGGER_PATH": "c:/path/to/your/swagger.json",
        "BASE_URL": "https://api.yourdomain.com",
        "BEARER_TOKEN": "your_api_token_here"
      }
    }
  }
}
```

---

## 🔬 Testing

Run syntax compilation checks:
```bash
python -m py_compile main.py generator.py spec_parser.py
```