# Red Bee MCP Server

**Model Context Protocol (MCP) Server for Red Bee Media OTT Platform**

Connect to Red Bee Media streaming services from MCP-compatible clients like Claude Desktop, or integrate via HTTP/SSE for web applications. This server provides 65 tools aligned with the [Exposure API](https://exposure.api.redbee.live/docs/index.html) for authentication, catalog search, recommendations, user management, purchases, and system operations.

[![PyPI version](https://badge.fury.io/py/redbee-mcp.svg)](https://badge.fury.io/py/redbee-mcp)
[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)

## 🆕 New: HTTP/SSE Mode

**Version 1.5.0** aligns tools with the current Exposure API and supports multiple operating modes:

- **Stdio Mode** (original): For local AI agents like Claude Desktop
- **HTTP Mode**: REST API with JSON-RPC for web integration  
- **SSE Mode**: Server-Sent Events for real-time communication
- **Both Modes**: Run stdio and HTTP simultaneously

## 🚀 Quick Start

### Option 1: Using uvx (Recommended)

```bash
# Test the server
uvx redbee-mcp --help

# Stdio mode (original)
uvx redbee-mcp --stdio --customer YOUR_CUSTOMER --business-unit YOUR_BU

# HTTP mode (new)
uvx redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU

# Both modes simultaneously
uvx redbee-mcp --both --customer YOUR_CUSTOMER --business-unit YOUR_BU
```

### Option 2: Using pip

```bash
pip install redbee-mcp

# Same usage as uvx, but with redbee-mcp command
redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU
```

## 📋 Configuration

### For Claude Desktop (Stdio Mode)

Add to your Claude Desktop MCP configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "redbee-mcp": {
      "command": "uvx",
      "args": ["redbee-mcp", "--stdio"],
      "env": {
        "REDBEE_CUSTOMER": "CUSTOMER_NAME",
        "REDBEE_BUSINESS_UNIT": "BUSINESS_UNIT_NAME"
      }
    }
  }
}
```

### For Web Applications (HTTP Mode)

Start the HTTP server:
```bash
redbee-mcp --http --customer YOUR_CUSTOMER --business-unit YOUR_BU
```

The server will be available at `http://localhost:8000` with these endpoints:

| Method | URL | Description |
|--------|-----|-------------|
| GET | `/` | API information |
| GET | `/health` | Server health check |
| POST | `/` | JSON-RPC MCP requests |
| GET | `/sse` | Server-Sent Events stream |

## 🌐 HTTP/SSE API Usage

### Example HTTP Requests

#### Health Check
```bash
curl http://localhost:8000/health
```

#### List Available Tools
```bash
curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": "1"
  }'
```

#### Search Content
```bash
curl -X POST http://localhost:8000/ \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/call",
    "params": {
      "name": "search_content_v2",
      "arguments": {
        "query": "french films",
        "types": "MOVIE",
        "pageSize": 5
      }
    },
    "id": "search-1"
  }'
```

### Web Integration Example

```javascript
class RedBeeMCPClient {
  constructor(baseUrl = 'http://localhost:8000') {
    this.baseUrl = baseUrl;
  }

  async callTool(toolName, arguments) {
    const response = await fetch(this.baseUrl, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        jsonrpc: '2.0',
        method: 'tools/call',
        params: { name: toolName, arguments },
        id: Date.now().toString()
      })
    });
    return response.json();
  }

  async searchContent(query, options = {}) {
    return this.callTool('search_content_v2', {
      query,
      types: options.types || 'MOVIE,TV_SHOW',
      pageSize: options.pageSize || 10,
      ...options
    });
  }
}

// Usage
const mcp = new RedBeeMCPClient();
const results = await mcp.searchContent('comedy movies');
```

### Server-Sent Events

Connect to real-time event stream:

```javascript
const eventSource = new EventSource('http://localhost:8000/sse');

eventSource.onmessage = function(event) {
  const data = JSON.parse(event.data);
  console.log('Event received:', data.type);
  
  if (data.type === 'welcome') {
    console.log('Connected with client ID:', data.client_id);
  } else if (data.type === 'tools') {
    console.log('Available tools:', data.tools.length);
  }
};
```

## 🔧 Environment Variables

| Variable | Required | Description | Example |
|----------|----------|-------------|---------|
| `REDBEE_CUSTOMER` | ✅ Yes | Red Bee customer identifier | `CUSTOMER_NAME` |
| `REDBEE_BUSINESS_UNIT` | ✅ Yes | Red Bee business unit | `BUSINESS_UNIT_NAME` |
| `REDBEE_EXPOSURE_BASE_URL` | ❌ No | API base URL | `https://exposure.api.redbee.live` |
| `REDBEE_USERNAME` | ❌ No | Username for authentication | `user@example.com` |
| `REDBEE_PASSWORD` | ❌ No | Password for authentication | `password123` |
| `REDBEE_SESSION_TOKEN` | ❌ No | Existing session token | `eyJhbGciOiJIUzI1...` |
| `REDBEE_DEVICE_ID` | ❌ No | Device identifier | `web-browser-123` |
| `REDBEE_CONFIG_ID` | ❌ No | Configuration ID | `sandwich` |
| `REDBEE_TIMEOUT` | ❌ No | Request timeout in seconds | `30` |

## Available Tools

Aligned with [Exposure API 1.0.0](https://exposure.api.redbee.live/docs/index.html) (OAS 3.1).

### Authentication
- `login_user` - Login via `POST /v3/.../auth/login`
- `create_anonymous_session` - Anonymous session via `POST /v2/.../auth/anonymous`
- `validate_session_token` - Validate session via `GET /v2/.../auth/session`
- `logout_user` - Logout via `DELETE /v2/.../auth/login`
- `request_password_reset` - Send a reset email via `GET /v2/.../user/password/reset/{username}`

### Content
- `get_public_asset_details` - Public asset by ID or slug
- `search_content_v2` - Free-text search including descriptions
- `get_asset_details` - Asset details (anonymous session if needed)
- `get_playback_info` - Play entitlement via `GET /v2/.../entitlement/{assetId}/play`
- `entitle_asset` - Entitle the user to an asset
- `search_assets_autocomplete` - Title autocomplete
- `get_epg_for_channel` - EPG for one channel (slugs supported)
- `get_epg_all_channels` - EPG for all channels
- `get_episodes_for_season` - Season by ID or slug
- `get_season_episodes` - Episodes of season N of a series
- `get_assets_by_tag` - Unique tags referenced by assets
- `list_tags` / `get_tag` - Tag catalog
- `list_assets` - Main catalog listing
- `search_multi_v3` - Prefix search on assets and tags
- `get_asset_collection_entries` - Collection entries
- `get_asset_thumbnail` - Thumbnail URL (307 redirect)
- `get_seasons_for_series` - Seasons of a TV series
- `get_next_episode` / `get_previous_episode` - Adjacent episodes

### Discovery
- `get_watch_next` - Watch-next list (works without login)
- `get_user_recommendations` - Personalized recommendations
- `get_continue_watching` - Continue-watching rail
- `get_last_viewed_offset` - Playback bookmarks
- `get_continue_tvshow` - Episode in progress for a series

### User Management
- `signup_user` - Create account (`emailAddress` becomes username)
- `change_user_password` / `change_user_email`
- `get_user_details` / `update_user_details`
- `get_user_profiles` / `add_user_profile` / `select_user_profile`
- `update_user_profile` / `delete_user_profile`
- `get_user_preferences` / `set_user_preferences`
- `get_preference_list` / `add_asset_to_list` / `remove_asset_from_list` - favorites / watchlists

### Purchases
- `get_account_purchases` / `get_account_transactions` / `get_active_purchases`
- `get_offerings` - Offerings for a country (IP-detected if omitted)
- `initialize_purchase` - Payment types and discounted price (experimental)
- `purchase_product_offering` / `cancel_purchase_subscription`
- `get_stored_payment_methods` / `add_payment_method` / `delete_payment_method`
- `get_account_products` - Entitled vs not-entitled products

### System
- `get_system_config` - `GET /v2/.../system/config`
- `get_system_time` - `GET /v2/time`
- `get_user_location` - `GET /v2/location`
- `get_active_channels` / `get_channel_onnow` - Live channel status
- `get_user_devices` / `delete_user_device`
- `get_client_config` - Whitelabel pages and components
- `get_document` - Privacy policy, terms, consent documents

## 🧪 Testing

### Test HTTP Server

```bash
# Start the server
redbee-mcp --http --customer DEMO --business-unit DEMO

# In another terminal, run the test script
python example_usage.py
```

### Test Stdio Mode

```bash
# Using uvx
REDBEE_CUSTOMER=CUSTOMER_NAME REDBEE_BUSINESS_UNIT=BUSINESS_UNIT_NAME uvx redbee-mcp --stdio

# Using pip installation
REDBEE_CUSTOMER=CUSTOMER_NAME REDBEE_BUSINESS_UNIT=BUSINESS_UNIT_NAME redbee-mcp --stdio
```

### Test MCP Protocol Manually

```bash
# Initialize and list tools
echo '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {"roots": {"listChanged": true}}, "clientInfo": {"name": "test", "version": "1.0.0"}}}
{"jsonrpc": "2.0", "method": "notifications/initialized"}
{"jsonrpc": "2.0", "id": 2, "method": "tools/list", "params": {}}' | uvx redbee-mcp --stdio
```

## 🏗️ Architecture

### Multi-Mode Design

The server is architected with clean separation of concerns:

- **McpHandler**: Core business logic shared between all modes
- **Stdio Server**: Traditional MCP stdio interface for AI agents
- **HTTP Server**: FastAPI-based REST/SSE interface for web apps
- **CLI**: Multi-mode command line interface

### File Structure

```
src/redbee_mcp/
├── handler.py          # Core business logic
├── server.py           # Stdio MCP server
├── http_server.py      # HTTP/SSE server
├── cli.py              # Multi-mode CLI
├── models.py           # Data models
└── tools/              # Tool modules
    ├── _common.py
    ├── auth.py
    ├── content.py
    ├── discovery.py
    ├── purchases.py
    ├── system.py
    └── user_management.py
```

## 📖 Usage Examples

### Search for French Movies (Stdio Mode)

Ask your AI assistant:
> "Search for French documentaries about nature"

### Search for Content (HTTP Mode)

```javascript
const mcp = new RedBeeMCPClient();
const results = await mcp.searchContent('french documentaries', {
  types: 'MOVIE',
  locale: ['fr'],
  pageSize: 10
});
```

### Get TV Show Information

```python
# First search for a TV show
{
  "query": "Game of Thrones",
  "types": "TV_SHOW"
}

# Then get its seasons
{
  "assetId": "tv-show-asset-id"
}
```

### User Authentication

```python
{
  "username": "user@example.com",
  "password": "password123",
  "remember_me": true
}
```

## 🚀 Production Deployment

### Docker

```dockerfile
FROM python:3.11-slim

WORKDIR /app
COPY . .
RUN pip install -e .

EXPOSE 8000

# HTTP mode
CMD ["redbee-mcp", "--http", "--host", "0.0.0.0", "--port", "8000"]
```

### Environment Setup

```bash
export REDBEE_CUSTOMER="your-customer"
export REDBEE_BUSINESS_UNIT="your-business-unit"
export REDBEE_EXPOSURE_BASE_URL="https://exposure.api.redbee.live"
```

### Systemd Service

```ini
# /etc/systemd/system/redbee-mcp-http.service
[Unit]
Description=Red Bee MCP HTTP Server
After=network.target

[Service]
Type=simple
User=www-data
WorkingDirectory=/opt/redbee-mcp
Environment=REDBEE_CUSTOMER=your-customer
Environment=REDBEE_BUSINESS_UNIT=your-business-unit
ExecStart=/usr/local/bin/redbee-mcp --http --host 0.0.0.0 --port 8000
Restart=always

[Install]
WantedBy=multi-user.target
```

## 🔒 Security Considerations

### CORS Configuration

For production HTTP deployments, configure CORS properly in `http_server.py`:

```python
self.app.add_middleware(
    CORSMiddleware,
    allow_origins=["https://yourdomain.com"],  # Specify allowed domains
    allow_credentials=True,
    allow_methods=["GET", "POST"],
    allow_headers=["Content-Type"],
)
```

## 📝 API Reference

The Red Bee MCP Server provides access to Red Bee Media Exposure API through:

- **MCP Tools**: For AI agents and local applications
- **HTTP/JSON-RPC**: For web applications and remote integration
- **Server-Sent Events**: For real-time updates

Each tool includes:
- Input validation with required and optional parameters
- Comprehensive error handling and messages
- Type safety for all inputs and outputs
- Detailed documentation and examples

## 🛠️ Development

### Requirements

- Python 3.8+
- MCP SDK
- pydantic for data validation
- FastAPI and uvicorn for HTTP mode

### Local Development

```bash
# Clone and install
git clone https://github.com/tamsibesson/redbee-mcp
cd redbee-mcp
pip install -e .

# Run in development mode
PYTHONPATH=src python -m redbee_mcp --http --customer TEST --business-unit TEST
```

## 📄 License

MIT License - see LICENSE file for details.

## 🆘 Support

For issues and questions:
- GitHub Issues: https://github.com/tamsibesson/redbee-mcp/issues
- Red Bee Media Documentation: https://exposure.api.redbee.live/docs/index.html

## 🔗 Related

- [Model Context Protocol](https://modelcontextprotocol.io/)
- [Claude Desktop](https://claude.ai/desktop)
- [Red Bee Media](https://www.redbeemedia.com/)
- [FastAPI](https://fastapi.tiangolo.com/)