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:

uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp

For MCP Configuration: Add this to your mcp.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:

git clone <repository-url>
cd g1_uart_mcp

2. Create a virtual environment:

python3 -m venv venv
source venv/bin/activate  # On macOS/Linux

3. Install dependencies:

pip install -r requirements.txt

Configuration

The MCP server is configured via mcp.json. For the recommended uvx method, use this configuration:

{
  "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:

{
  "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)

uvx --from git+https://github.com/danroblewis/g1_uart_mcp g1-device-mcp

Local Installation

python mcp_server.py

Available Tools

1. Scan for G1 Devices

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

connect_g1_device(address)

Connects to a specific G1 device by its address or UUID.

3. Get Connection Status

get_g1_connection_status()

Returns detailed information about the current connection including device details, UART service availability, and connection monitoring statistics.

4. Send Message

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

disconnect_g1_device()

Disconnects from the currently connected device.

6. 🆕 Configure Connection Settings

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:

   devices = scan_g1_devices()
   # Returns list of available G1 devices

2. Connect to a device:

   result = connect_g1_device("device_uuid_or_address")

3. Configure connection monitoring (optional):

   configure_g1_connection_settings(
       heartbeat_interval=3.0,  # More frequent heartbeats
       auto_reconnect_enabled=True
   )

4. Send a message:

   response = send_g1_message("2506")
   # Sends command 0x25 with data 0x06
   # Connection is automatically monitored and maintained

5. Check status:

   status = get_g1_connection_status()
   # Now includes connection duration, last activity, and reconnection info

6. Disconnect:

   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:

logging.basicConfig(level=logging.DEBUG)

Connection Issues

If you're experiencing frequent disconnections:

1. Check connection monitoring settings:

   status = get_g1_connection_status()
   print(f"Auto-reconnect: {status['auto_reconnect_enabled']}")
   print(f"Reconnect attempts: {status['reconnect_attempts']}")

2. Adjust heartbeat frequency:

   configure_g1_connection_settings(heartbeat_interval=3.0)

3. Increase reconnection attempts:

   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 or contact the maintainers.