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