Metadata-Version: 2.4
Name: whatsease-mcp
Version: 0.1.0
Summary: CLI tool to run Whatsease MCP server from OpenAPI spec
Project-URL: Homepage, https://github.com/yashdesai/whatsease-mcp
Project-URL: Repository, https://github.com/yashdesai/whatsease-mcp
Author-email: Yash Desai <contact@yashddesai.com>
License-Expression: MIT
License-File: LICENSE
Keywords: cli,mcp,model-context-protocol,openapi,whatsease
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.9
Requires-Dist: click>=8.0.0
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: httpx>=0.25.0
Description-Content-Type: text/markdown

# 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
