G1 UART MCP Server

# G1 UART MCP Server A Model Context Protocol (MCP) server that provides tools for communicating with G1 devices over Bluetooth Low Energy (BLE) using the Nordic UART protocol. ## Overview This project implements an MCP server that enables AI assistants and other MCP clients to: - Scan for G1 Bluetooth devices - Connect to G1 devices - Send and receive messages using the Nordic BLE UART protocol - Monitor connection status and device information - **NEW**: Automatically monitor and maintain stable connections - **NEW**: Auto-reconnect on connection loss - **NEW**: Configurable connection monitoring parameters The server is particularly designed for working with Even G1 devices, which appear to be paired left/right devices for audio applications. ## Features - **Device Discovery**: Scan for available G1 devices with automatic side detection (left/right) - **BLE Connection Management**: Connect, disconnect, and monitor connection status - **Nordic UART Protocol**: Full support for the Nordic UART service (6E400001-B5A3-F393-E0A9-E50E24DCCA9E) - **Message Communication**: Send hex-formatted messages and receive responses - **MCP Integration**: Seamless integration with MCP-compatible AI assistants and tools - **🆕 Connection Monitoring**: Automatic heartbeat and health checks to maintain stable connections - **🆕 Auto-Reconnection**: Automatically attempt to reconnect if the connection is lost - **🆕 Configurable Settings**: Adjustable heartbeat intervals, timeouts, and reconnection parameters ## Prerequisites - Python 3.8+ - macOS (tested on darwin 24.3.0) - Bluetooth Low Energy support - Access to G1 devices ## Installation ### Option 1: Quick Start with uvx (Recommended) Run directly from GitHub without installation: ```bash uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp ``` **For MCP Configuration:** Add this to your `mcp.json`: ```json { "mcpServers": { "g1-device-mcp": { "command": "uvx", "args": [ "--from", "git+https://github.com/danroblewis/g1_uart_mcp", "g1-device-mcp" ] } } } ``` ### Option 2: Local Installation 1. Clone the repository: ```bash git clone <repository-url> cd g1_uart_mcp ``` 2. Create a virtual environment: ```bash python3 -m venv venv source venv/bin/activate # On macOS/Linux ``` 3. Install dependencies: ```bash pip install -r requirements.txt ``` ## Configuration The MCP server is configured via `mcp.json`. For the recommended uvx method, use this configuration: ```json { "mcpServers": { "g1-device-mcp": { "command": "uvx", "args": [ "--from", "git+https://github.com/danroblewis/g1_uart_mcp", "g1-device-mcp" ] } } } ``` **Alternative: Local Installation** If you prefer local installation, update the paths to match your system: ```json { "mcpServers": { "g1-device-mcp": { "command": "/path/to/your/venv/bin/python", "args": [ "/path/to/your/g1_uart_mcp/mcp_server.py" ] } } } ``` ## Usage ### Starting the MCP Server The server can be started directly or through an MCP client: #### With uvx (Recommended) ```bash uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp ``` #### Local Installation ```bash python mcp_server.py ``` ### Available Tools #### 1. Scan for G1 Devices ```python scan_g1_devices() ``` Scans for available G1 devices and returns a list with device information including name, ID, side (left/right), and signal strength. #### 2. Connect to G1 Device ```python connect_g1_device(address) ``` Connects to a specific G1 device by its address or UUID. #### 3. Get Connection Status ```python get_g1_connection_status() ``` Returns detailed information about the current connection including device details, UART service availability, and connection monitoring statistics. #### 4. Send Message ```python send_g1_message(hex_data) ``` Sends a hex-formatted message to the connected device and waits for a response. Now includes automatic connection health checks and reconnection attempts. #### 5. Disconnect ```python disconnect_g1_device() ``` Disconnects from the currently connected device. #### 6. 🆕 Configure Connection Settings ```python configure_g1_connection_settings( heartbeat_interval=5.0, connection_timeout=30.0, auto_reconnect_enabled=True, max_reconnect_attempts=3, reconnect_delay=2.0 ) ``` Configures connection monitoring and auto-reconnection parameters. ### Example Workflow 1. **Scan for devices**: ```python devices = scan_g1_devices() # Returns list of available G1 devices ``` 2. **Connect to a device**: ```python result = connect_g1_device("device_uuid_or_address") ``` 3. **Configure connection monitoring (optional)**: ```python configure_g1_connection_settings( heartbeat_interval=3.0, # More frequent heartbeats auto_reconnect_enabled=True ) ``` 4. **Send a message**: ```python response = send_g1_message("2506") # Sends command 0x25 with data 0x06 # Connection is automatically monitored and maintained ``` 5. **Check status**: ```python status = get_g1_connection_status() # Now includes connection duration, last activity, and reconnection info ``` 6. **Disconnect**: ```python disconnect_g1_device() ``` ## Connection Monitoring & Auto-Reconnection ### How It Works The enhanced MCP server now includes robust connection management: 1. **Heartbeat Monitoring**: Sends periodic ping messages (every 5 seconds by default) to keep the connection alive 2. **Health Checks**: Regularly verifies the connection is still responsive 3. **Auto-Detection**: Automatically detects when the connection is lost 4. **Smart Reconnection**: Attempts to reconnect up to 3 times with configurable delays 5. **Background Monitoring**: All monitoring happens in the background without blocking message sending ### Configuration Options - **`heartbeat_interval`**: How often to send heartbeat messages (default: 5 seconds) - **`connection_timeout`**: Maximum connection duration before health check (default: 30 seconds) - **`auto_reconnect_enabled`**: Whether to automatically attempt reconnection (default: True) - **`max_reconnect_attempts`**: Maximum number of reconnection attempts (default: 3) - **`reconnect_delay`**: Delay between reconnection attempts (default: 2 seconds) ### Benefits - **Stable Connections**: Significantly reduces unexpected disconnections - **Automatic Recovery**: No manual intervention needed when connections drop - **Better Reliability**: Especially important for the critical `send_g1_message` command - **Configurable**: Adjust settings based on your specific use case and device behavior ## Example Files - `example_connect.py` - Demonstrates device connection - `example_scan.py` - Shows device scanning functionality - `example_send_message.py` - Example of sending messages - `example_tools.py` - Comprehensive tool usage examples - **🆕 `test_connection_monitoring.py`** - Demonstrates the new connection monitoring features ## Architecture ### Core Components - **`mcp_server.py`**: Main MCP server implementation with tool definitions and connection configuration - **`g1_uart_manager.py`**: Enhanced BLE UART protocol manager with connection monitoring and auto-reconnection - **`mcp.json`**: MCP server configuration ### BLE UART Protocol The server implements the Nordic UART service: - **Service UUID**: `6E400001-B5A3-F393-E0A9-E50E24DCCA9E` - **TX Characteristic**: `6E400002-B5A3-F393-E0A9-E50E24DCCA9E` (Write) - **RX Characteristic**: `6E400003-B5A3-F393-E0A9-E50E24DCCA9E` (Notify) ## Dependencies - **`mcp`**: Model Context Protocol implementation - **`bleak`**: Cross-platform Bluetooth Low Energy library ## Troubleshooting ### Common Issues 1. **Permission Denied**: Ensure Bluetooth permissions are granted to your application 2. **Device Not Found**: Verify the device is in range and discoverable 3. **Connection Failed**: Check if the device is already connected to another client 4. **Message Timeout**: Ensure the device is responsive and supports the Nordic UART protocol 5. **🆕 Frequent Disconnections**: Try adjusting connection monitoring settings or check device power management ### Debug Mode Enable debug logging by modifying the logging level in `mcp_server.py`: ```python logging.basicConfig(level=logging.DEBUG) ``` ### Connection Issues If you're experiencing frequent disconnections: 1. **Check connection monitoring settings**: ```python status = get_g1_connection_status() print(f"Auto-reconnect: {status['auto_reconnect_enabled']}") print(f"Reconnect attempts: {status['reconnect_attempts']}") ``` 2. **Adjust heartbeat frequency**: ```python configure_g1_connection_settings(heartbeat_interval=3.0) ``` 3. **Increase reconnection attempts**: ```python configure_g1_connection_settings(max_reconnect_attempts=5) ``` 4. **Check device power settings**: Some devices may go to sleep mode, causing disconnections ## 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 [Add your license information here] ## Support For issues and questions, please [create an issue](link-to-issues) or contact the maintainers.