ross-ultrix-mcp/README.md

# Ross Ultrix MCP Server

A Model Context Protocol (MCP) server for controlling Ross Ultrix video production systems through the Ross Talk protocol. This server enables Claude to interact with Ross Ultrix switchers, providing seamless control over video production workflows.

## Features

- **Ross Talk Protocol Support**: Native communication with Ross Ultrix systems
- **Docker Containerized**: Easy deployment with network isolation
- **Real-time State Management**: Live updates from the Ultrix system
- **Comprehensive Control**: Support for mix effects, sources, panels, and macros
- **Health Monitoring**: Built-in health checks for container orchestration
- **Auto-reconnection**: Automatic reconnection handling for robust operation

## Quick Start

### Using Docker Compose (Recommended)

1. Clone the repository:
```bash
git clone https://forge.wilddragon.net/zgaetano/ross-ultrix-mcp.git
cd ross-ultrix-mcp
```

2. Create environment configuration:
```bash
cp .env.example .env
# Edit .env with your Ross Ultrix connection details
```

3. Start the container:
```bash
docker-compose up -d
```

### Manual Build

```bash
# Install dependencies
npm install

# Build TypeScript
npm run build

# Start the server
npm start
```

## Configuration

### Environment Variables

| Variable | Description | Default |
|----------|-------------|----------|
| `ROSS_TALK_HOST` | Ross Ultrix system IP address | `192.168.1.100` |
| `ROSS_TALK_PORT` | Ross Talk protocol port | `7788` |
| `MCP_SERVER_PORT` | MCP server listening port | `3000` |
| `LOG_LEVEL` | Logging level (debug, info, warn, error) | `info` |
| `NODE_ENV` | Node.js environment | `production` |

### Docker Network

The server creates a custom Docker network (`ross-network`) to ensure proper communication with your Ross Ultrix system. Make sure your Ultrix system is accessible from this network.

## Available Tools

The MCP server provides the following tools for Claude:

### Connection Management
- `ross_connect` - Connect to Ross Ultrix system
- `ross_disconnect` - Disconnect from Ross Ultrix system
- `ross_get_status` - Get current system status

### Switcher Control
- `ross_take_transition` - Execute a take/cut transition
- `ross_auto_transition` - Execute an auto transition with duration
- `ross_set_preview` - Set preview source on mix effect
- `ross_set_program` - Set program source on mix effect

### Panel Management
- `ross_switch_panel` - Switch to specific control panel
- `ross_get_panels` - Get list of available panels

### Source Management
- `ross_get_sources` - Get list of available video sources

### Macro Execution
- `ross_macro_run` - Execute macros by name or ID

## Usage Examples

Once connected to Claude with this MCP server, you can control your Ross Ultrix system naturally:

```
"Connect to the Ross Ultrix system"
"Switch to camera 2 on preview"
"Take the transition"
"Run the opening graphics macro"
"Get the current system status"
```

## Ross Talk Protocol

This server implements the Ross Talk protocol for communication with Ultrix systems. Ross Talk uses XML-based messaging over WebSocket connections.

### Supported Commands

- Panel switching and control
- Mix Effect operations (take, auto, preview, program)
- Source management and routing
- Macro execution
- System status monitoring

## Development

### Prerequisites

- Node.js 20+
- TypeScript
- Docker (for containerization)
- Access to Ross Ultrix system with Ross Talk enabled

### Development Commands

```bash
# Install dependencies
npm install

# Run in development mode
npm run dev

# Watch for changes
npm run watch

# Build TypeScript
npm run build

# Clean build artifacts
npm run clean
```

### Testing

To test the connection to your Ross Ultrix system:

1. Ensure your Ultrix system has Ross Talk enabled
2. Configure the correct IP and port in your environment
3. Start the server and monitor the logs for connection status

## Network Requirements

- **Port 7788**: Ross Talk protocol (default, configurable)
- **Port 3000**: MCP server (configurable)
- **Network Access**: The container must be able to reach your Ross Ultrix system

## Troubleshooting

### Connection Issues

1. **Check Network Connectivity**:
   ```bash
   docker exec ross-ultrix-mcp ping <ultrix-ip>
   ```

2. **Verify Ross Talk Port**:
   ```bash
   telnet <ultrix-ip> 7788
   ```

3. **Check Container Logs**:
   ```bash
   docker logs ross-ultrix-mcp
   ```

### Common Issues

- **Connection Timeout**: Verify Ultrix IP address and network routing
- **Protocol Errors**: Ensure Ross Talk is enabled on the Ultrix system
- **Permission Denied**: Check firewall settings and network policies

## Security Considerations

- The container runs as a non-root user (`rossuser`)
- Network access is limited to the custom Docker network
- No persistent data storage (stateless operation)
- Health checks ensure container reliability

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details.

## Support

For issues and questions:
- Create an issue in the repository
- Contact: zgaetano@wilddragon.net

---

**Note**: This server requires access to a Ross Ultrix system with Ross Talk protocol enabled. Ensure proper network configuration and access permissions before deployment.