# UISP API MCP Server

A Model Context Protocol (MCP) server for interacting with UISP (Ubiquiti Internet Service Provider) API. This server dynamically loads all available endpoints from the UISP swagger specification and provides configurable access control through blacklisting.

## Features

- **Dynamic Tool Generation**: Automatically creates MCP tools from swagger.json
- **Comprehensive Coverage**: Exposes all UISP API endpoints (GET, POST, PUT, DELETE, PATCH)
- **Configurable Blacklist**: Control which endpoints are exposed via blacklist.yaml
- **Method-Based Filtering**: Block entire HTTP methods (e.g., all POST/PUT/DELETE operations)
- **Type Safety**: Preserves parameter types and enum values from API spec
- **Smart Parameter Handling**: Correctly handles both path and query parameters
- **Automatic Retries**: Built-in retry logic with exponential backoff
- **Detailed Error Messages**: Rich error information from API responses

## Installation

### Using UV (recommended)

```bash
cd uisp_api_mcp
uv sync
```

### Using pip

```bash
cd uisp_api_mcp
pip install -e .
```

## Configuration

### Environment Variables

Create a `.env` file in the project root:

```env
# Required
UISP_BASE_URL=https://your-uisp-instance.com
UISP_API_TOKEN=your-api-token

# Optional (with defaults)
UISP_API_TIMEOUT=30.0
UISP_API_RETRY_ATTEMPTS=3
UISP_API_RETRY_DELAY=1.0
UISP_DEFAULT_PAGE_SIZE=25
UISP_LOG_LEVEL=INFO
```

### Blacklist Configuration

The server uses `etc/blacklist.yaml` to control which endpoints are exposed. By default, all modifying operations (POST, PUT, DELETE, PATCH) and sensitive endpoints are blacklisted.

```yaml
# Methods to exclude (blocks all endpoints using these HTTP methods)
methods:
  - POST      # Create operations
  - PUT       # Update operations
  - DELETE    # Delete operations
  - PATCH     # Partial update operations

# Tags to exclude (blocks all endpoints with these tags)
tags:
  - Authorization
  - Users
  - Server
  # ... etc

# Path patterns to exclude (regex patterns)
paths:
  - .*login.*
  - .*password.*
  - .*auth.*
  # ... etc
```

With the default configuration, only GET (read-only) operations are exposed.

### Getting UISP API Token

1. Log in to your UISP instance
2. Navigate to Settings → Users
3. Select your user account
4. Generate an API token

## Usage

### Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "uisp": {
      "command": "uv",
      "args": ["--directory", "/path/to/uisp_api_mcp", "run", "uisp-api-mcp"],
      "env": {
        "UISP_BASE_URL": "https://your-uisp-instance.com",
        "UISP_API_TOKEN": "your-api-token"
      }
    }
  }
}
```

### Command Line

```bash
# With UV
uv run uisp-api-mcp

# With Python
python -m uisp_api_mcp
```

## Available Tools

The server dynamically generates tools from the UISP swagger specification. With the default blacklist (blocking all POST, PUT, DELETE, PATCH methods), approximately 120+ read-only tools are available, including:

### Common Tools

- **Sites**: `sites`, `sites_id`, `sites_search`, `sites_traffic`
- **Devices**: `devices`, `devices_id`, `devices_id_detail`, `devices_id_statistics`
- **Monitoring**: `logs`, `outages`, `nms_statistics`, `nms_summary`
- **Network**: `datalinks`, `datalinks_id`, `devices_id_interfaces`
- **System Info**: `nms_info`, `nms_version`, `nms_enums`

### Tool Naming Convention

Tools are named based on the API endpoint path and HTTP method:
- GET `/sites` → `sites`
- GET `/sites/{id}` → `sites_id`
- GET `/devices/{id}/detail` → `devices_id_detail`
- POST `/sites` → `sites_post` (if not blacklisted)
- PUT `/sites/{id}` → `sites_id_put` (if not blacklisted)
- DELETE `/sites/{id}` → `sites_id_delete` (if not blacklisted)

### Parameter Types

All tools preserve the original API parameter types:
- String enums show available values (e.g., "Available values: site, endpoint, client")
- Required vs optional parameters are properly marked
- Path parameters (like `{id}`) are automatically handled

## Examples

### List all sites
```
Tool: sites
Parameters:
  - type_: "site"  # Available values: site, endpoint, client, subscriber
  - ucrm: true     # Only sites bound with CRM
```

### Get specific site details
```
Tool: sites_id
Parameters:
  - id_: "9ef86767-fd8d-487c-8c97-77f763c5a99a"
  - ucrmDetails: true
```

### List devices
```
Tool: devices
Parameters:
  - siteId: "site-uuid"
  - type_: ["erouter", "eswitch"]  # Device types
  - role: ["router", "switch"]      # Device roles
```

### Get device statistics
```
Tool: devices_id_statistics
Parameters:
  - id_: "device-uuid"
  - interval: "hour"
  - start: "2024-01-01T00:00:00Z"
  - period: "86400000"  # 24 hours in milliseconds
```

## Error Handling

The server includes comprehensive error handling:
- Authentication errors (401)
- Not found errors (404)
- Validation errors (400)
- Rate limiting (429)
- Connection timeouts
- Automatic retry with exponential backoff

## Development

### Project Structure
```
uisp_api_mcp/
├── pyproject.toml
├── README.md
├── .env
├── etc/
│   ├── swagger.json      # UISP API specification
│   └── blacklist.yaml    # Endpoint blacklist configuration
└── src/
    └── uisp_api_mcp/
        ├── __init__.py
        ├── __main__.py
        ├── client.py       # HTTP client with retry logic
        ├── exceptions.py   # Custom exception types
        ├── server.py       # Dynamic MCP server
        ├── settings.py     # Configuration management
        └── swagger_tools.py # Swagger parsing and tool generation
```

### How It Works

1. **Swagger Loading**: The server reads `etc/swagger.json` at startup
2. **Blacklist Filtering**: Endpoints are filtered based on `etc/blacklist.yaml` (methods, tags, paths)
3. **Tool Generation**: Each allowed endpoint becomes an MCP tool with proper types
4. **Parameter Handling**: Path parameters are substituted, query parameters are passed
5. **Error Handling**: API errors are caught and enriched with details

### Adding/Removing Endpoints

To modify which endpoints are exposed:
1. Edit `etc/blacklist.yaml`
2. Add or remove:
   - HTTP methods (e.g., remove POST from methods list to allow POST operations)
   - Tags (to block/allow all endpoints with specific tags)
   - Path patterns (regex patterns to match specific endpoints)
3. Restart the server

### Updating the API Spec

To update with a newer UISP API version:
1. Replace `etc/swagger.json` with the latest version
2. The server will automatically pick up new endpoints

## License

MIT License - see LICENSE file for details.

## Support

For UISP API documentation, visit: https://help.ui.com/hc/en-us/articles/115002943188-UISP-API

For issues with this MCP server, please open an issue on GitHub.