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:

git clone https://forge.wilddragon.net/zgaetano/ross-ultrix-mcp.git
cd ross-ultrix-mcp

2. Create environment configuration:

cp .env.example .env
# Edit .env with your Ross Ultrix connection details

3. Start the container:

docker-compose up -d

Manual Build

# 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

# 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:

   docker exec ross-ultrix-mcp ping <ultrix-ip>
   

2. Verify Ross Talk Port:

   telnet <ultrix-ip> 7788
   

3. Check Container Logs:

   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.