Race MCP Server

# Race MCP Server A comprehensive MCP (Model Context Protocol) server for iRacing telemetry data that provides real-time racing advice, car spotting, telemetry analysis, and conversational interaction about racing data. ## 🏁 Overview This MCP server transforms iRacing telemetry data into actionable racing insights through: - **Real-time telemetry streaming** with advanced analytics - **AI-powered racing coaching** based on driving patterns - **Intelligent car spotting** and traffic awareness - **Detailed lap analysis** with improvement suggestions - **Session monitoring** with performance trends - **Conversational interface** for natural racing discussions ## 🚀 Features ### Core Capabilities - **Live Telemetry Processing**: Real-time data from iRacing via pyirsdk - **Advanced Analytics**: G-force calculations, racing line analysis, gear optimization - **Racing AI Coach**: Personalized advice based on driving style and situation - **Car Spotting System**: Traffic awareness and positioning intelligence - **Performance Analysis**: Lap-by-lap breakdown with improvement suggestions - **Session Tracking**: Long-term performance trends and statistics ### MCP Integration - **5 Interactive Tools**: Direct telemetry access and analysis functions - **3 Live Resources**: Streaming data feeds for continuous monitoring - **3 AI Prompts**: Specialized coaching personalities (coach, spotter, setup analyst) - **JSON-RPC 2.0**: Standard MCP protocol compliance - **STDIO Transport**: Ready for integration with MCP clients ## 📦 Installation ### Prerequisites - Python 3.8+ - iRacing simulator (for live telemetry) - Virtual environment (recommended) ### Quick Setup ```bash # Clone the repository git clone <your-repo-url> cd race-mcp # Create virtual environment python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate # Install the package with dependencies pip install -e . ``` ### Manual Dependencies If you prefer manual installation: ```bash pip install mcp pyirsdk pydantic aiofiles ``` ## 🎮 Usage ### Running the Server ```bash # Activate virtual environment source .venv/bin/activate # Run the MCP server directly python -m race_mcp_server # Or use the convenient startup script ./start_server.sh # Run with debug logging ./start_server.sh --debug # Run in simulation mode (no iRacing required) ./start_server.sh --simulation ``` ### Mock iRacing Data Generator For development without the simulator, a standalone process can emit realistic iRacing-style telemetry over TCP. ```bash # Start the mock telemetry stream on port 9000 python -m race_mcp_server.mock_iracing_stream --port 9000 ``` Clients can connect to the specified host and port to receive newline-delimited JSON telemetry frames that mimic the structure of a real iRacing stream. ### Launching with a GUI After installation, you can start the server using a small GUI: ```bash race-mcp-gui ``` The GUI offers start/stop controls and displays server logs for quick race prep. ### Testing the Server ```bash # Run comprehensive tests python test_client.py # Or use the startup script with testing ./start_server.sh --test ``` ### 🎙 Voice Interaction Real-time voice communication is supported through optional audio utilities. #### Prerequisites - OpenAI API key set in ``OPENAI_API_KEY`` - Install voice dependencies: ``pip install race-mcp-server[voice]`` #### Example Usage ```python import asyncio from race_mcp_server.openai_client import OpenAIClient from race_mcp_server.voice_interface import VoiceInterface async def main(): client = OpenAIClient() voice = VoiceInterface(client) await voice.chat_once() asyncio.run(main()) ``` This records a short microphone clip, sends it to OpenAI for transcription and speaks the model's response back to the user. ## 🛠 Available Tools ### 1. `get_telemetry` **Purpose**: Retrieve current telemetry data with enhanced analytics ```json { "name": "get_telemetry", "arguments": { "include_analytics": true, "format": "detailed" } } ``` **Returns**: Complete telemetry data including speed, RPM, position, G-forces, and racing line analysis ### 2. `spot_cars` **Purpose**: Identify and analyze nearby cars for situational awareness ```json { "name": "spot_cars", "arguments": { "radius_meters": 100, "include_predictions": true } } ``` **Returns**: List of nearby cars with relative positions, speeds, and trajectory predictions ### 3. `get_racing_advice` **Purpose**: Get AI-powered coaching advice based on current situation ```json { "name": "get_racing_advice", "arguments": { "context": "struggling with turn 3 entry speed", "focus_area": "cornering" } } ``` **Returns**: Personalized advice with priority levels and specific recommendations ### 4. `analyze_lap` **Purpose**: Detailed analysis of lap performance with improvement suggestions ```json { "name": "analyze_lap", "arguments": { "lap_number": 5, "compare_to_best": true } } ``` **Returns**: Sector times, racing line efficiency, consistency ratings, and specific improvement areas ### 5. `track_session` **Purpose**: Monitor overall session progress and performance trends ```json { "name": "track_session", "arguments": { "include_trends": true, "format": "summary" } } ``` **Returns**: Session statistics, pace trends, fuel usage, and tire degradation analysis ## 📊 Live Resources ### 1. `telemetry://live-stream` Continuous telemetry data stream with real-time updates ### 2. `session://current-info` Current session information including track, conditions, and session type ### 3. `track://layout-info` Track-specific information including turn locations and racing line data ## 🤖 AI Prompts ### 1. `racing_coach` **Personality**: Professional racing instructor **Focus**: Technique improvement and strategic advice **Use Case**: General racing improvement and learning ### 2. `car_spotter` **Personality**: Experienced spotter focused on safety and positioning **Focus**: Traffic management and situational awareness **Use Case**: Race situations and traffic navigation ### 3. `setup_analyst` **Personality**: Technical setup engineer **Focus**: Vehicle setup optimization and handling analysis **Use Case**: Car setup tuning and technical adjustments ## 🧪 Testing ### Run the Test Client The test client provides a comprehensive way to interact with all server functionality: ```bash # Test all server functionality python test_client.py # Use the startup script for automated testing ./start_server.sh --test ``` ### Test Client Features - **Tool Testing**: Tests all 5 MCP tools with realistic parameters - **Resource Access**: Validates all 3 live resources - **Prompt Testing**: Exercises all 3 AI coaching prompts - **Error Handling**: Tests server resilience and error responses - **Performance**: Shows response times and data validation ### Manual Server Testing ```bash # Start server manually and test with direct JSON-RPC calls python -m race_mcp_server # In another terminal, you can send JSON-RPC messages via stdin # (Advanced usage - test_client.py is much easier) ``` ## 🔧 Configuration ### Environment Variables ```bash # Enable debug logging export MCP_DEBUG=1 # Force simulation mode export RACE_MCP_SIMULATION=1 # Set custom iRacing data path (if needed) export IRSDK_PATH=/path/to/irsdk ``` ### Server Configuration Modify settings in `src/race_mcp_server/main.py`: - Telemetry update intervals - Simulation mode parameters - Logging levels - Analysis parameters ### Startup Script Options ```bash ./start_server.sh --help # Show all available options ./start_server.sh --check # Verify system requirements ``` ## 🔍 Troubleshooting ### Common Issues 1. **"pyirsdk connection failed"** - Ensure iRacing is running and in a session - Check that iRacing telemetry output is enabled - The server will run in simulation mode if iRacing isn't available 2. **"Tool execution failed"** - Check server logs for detailed error messages - Verify the tool arguments match the expected schema - Try restarting the server 3. **"Resource access failed"** - Resources return simulated data when iRacing isn't running - Check that the server started without errors - Verify the resource URIs are correct ### Debug Mode ```bash # Enable verbose logging python -m race_mcp_server --debug # View detailed telemetry processing export MCP_DEBUG=1 python -m race_mcp_server ``` ### Log Files - Server logs: Written to console (redirect to file if needed) - iRacing connection status: Logged at startup - Tool execution: Logged for each request ## 🏗 Development ### Project Structure ``` race-mcp/ ├── src/race_mcp_server/ │ ├── __init__.py # Package initialization │ ├── __main__.py # CLI entry point │ ├── main.py # Core MCP server (580+ lines) │ └── telemetry_processor.py # Advanced analytics engine ├── start_server.sh # Convenient startup script ├── pyproject.toml # Project configuration ├── test_client.py # Comprehensive test suite └── README.md # This file ``` ### Adding New Features 1. **New Tools**: Add methods to `RaceMCPServer` class in `main.py` 2. **New Resources**: Extend the resource handlers 3. **Enhanced Analytics**: Modify `telemetry_processor.py` 4. **New Prompts**: Add prompt templates to the prompts section ### Testing New Features ```bash # Test after making changes python test_client.py # Test with debug output ./start_server.sh --debug --test ``` ### Contributing 1. Fork the repository 2. Create a feature branch 3. Add tests for new functionality 4. Submit a pull request with detailed description ## 📋 Requirements ### Core Dependencies ```toml mcp = ">=1.0.0" # Model Context Protocol framework pyirsdk = ">=1.3.0" # iRacing SDK integration pydantic = ">=2.0.0" # Data validation and serialization aiofiles = ">=0.8.0" # Async file operations ``` ### System Requirements - **OS**: Windows, macOS, or Linux - **Python**: 3.8+ (tested with 3.10.12) - **Memory**: 100MB+ available - **iRacing**: Any recent version with telemetry enabled (optional - server runs in simulation mode without it) ### Optional Dependencies - **pytest**: For running extended test suites - **MCP Client**: Any MCP-compatible client for integration ## 📜 License This project is licensed under the MIT License - see the LICENSE file for details. ## 🏆 Acknowledgments - **iRacing**: For providing the comprehensive telemetry API - **MCP Community**: For the excellent Model Context Protocol framework - **Racing Community**: For feedback and feature suggestions --- **Ready to improve your lap times? Start the server and run the test client to see it in action! 🏎️💨** ## Configuration The server can be configured via environment variables: - `IRACING_TELEMETRY_INTERVAL` - Telemetry update interval in seconds (default: 1.0) - `RACE_MCP_LOG_LEVEL` - Logging level (default: INFO) - `RACE_MCP_ENABLE_SPOTTING` - Enable car spotting features (default: true) ## Architecture ``` ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ iRacing Sim │───▶│ pyirsdk Stream │───▶│ MCP Server │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ▼ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ Claude/AI │◀───│ MCP Protocol │◀───│ Tool Handlers │ └─────────────────┘ └─────────────────┘ └─────────────────┘ ``` ## Development ```bash # Run tests pytest # Format code black src/ isort src/ # Type checking mypy src/ ``` ## License MIT License