whatsease-mcp 0.1.0
CLI tool to run Whatsease MCP server from OpenAPI spec
Requires Python: >=3.9
Keywords: cli, mcp, model-context-protocol, openapi, whatsease

# Whatsease MCP

CLI tool to run a Model Context Protocol (MCP) server for the Whatsease API.

## Installation

```bash
pip install whatsease-mcp
```

## Usage

### Basic Usage

```bash
whatsease-mcp --api-url https://api.whatsease.com
```

Or using environment variable:

```bash
export WHATSEASE_API_BASE_URL=https://api.whatsease.com
whatsease-mcp
```

### Options

| Option             | Short | Default          | Description                        |
| ------------------ | ----- | ---------------- | ---------------------------------- |
| `--api-url`        | `-u`  | (required)       | Base URL of the Whatsease API      |
| `--port`           | `-p`  | `8001`           | Port to run the MCP server on      |
| `--host`           | `-h`  | `0.0.0.0`        | Host to bind the MCP server to     |
| `--include-config` | `-c`  | `./include.json` | Path to include.json config file   |
| `--transport`      | `-t`  | `http`           | Transport type (`http` or `stdio`) |

### Examples

```bash
# Run on custom port
whatsease-mcp -u https://api.whatsease.com -p 8080

# Run on localhost only
whatsease-mcp -u https://api.whatsease.com -h localhost

# Use stdio transport (for direct MCP client integration)
whatsease-mcp -u https://api.whatsease.com -t stdio

# Use custom config file
whatsease-mcp -u https://api.whatsease.com -c /path/to/include.json
```

## Configuration

### include.json

Create an `include.json` file to control which API routes are exposed as MCP
tools.

**Default behavior (no config or empty config):** All routes from the OpenAPI
spec are exposed.

**With config:** Only matching routes are exposed, plus a catch-all exclude at
the end.

#### Format

```json
{
    "include": [
        {
            "mcp_type": "TOOL",
            "methods": ["GET", "POST"],
            "pattern": "/platforms/.*"
        },
        {
            "mcp_type": "TOOL",
            "methods": ["GET"],
            "pattern": "/templates/.*"
        }
    ]
}
```

#### Fields

| Field      | Type   | Description                                                |
| ---------- | ------ | ---------------------------------------------------------- |
| `mcp_type` | string | One of: `TOOL`, `RESOURCE`, `RESOURCE_TEMPLATE`, `EXCLUDE` |
| `methods`  | array  | HTTP methods to match: `GET`, `POST`, `PUT`, `DELETE`      |
| `pattern`  | string | Regex pattern to match route paths                         |

#### Example Configurations

**Expose only GET routes:**

```json
{
    "include": [
        {
            "mcp_type": "TOOL",
            "methods": ["GET"],
            "pattern": ".*"
        }
    ]
}
```

**Expose specific endpoints:**

```json
{
    "include": [
        {
            "mcp_type": "TOOL",
            "methods": ["GET", "POST"],
            "pattern": "^/platforms/.*"
        },
        {
            "mcp_type": "TOOL",
            "methods": ["GET"],
            "pattern": "^/templates/.*"
        },
        {
            "mcp_type": "TOOL",
            "methods": ["GET", "POST"],
            "pattern": "^/campaigns/.*"
        }
    ]
}
```

## License

MIT