Metadata-Version: 2.4
Name: sphero-rvr-mcp
Version: 0.1.2
Summary: MCP server for controlling Sphero RVR with Claude AI
Project-URL: Homepage, https://github.com/jsperson/sphero_rvr_mcp
Project-URL: Repository, https://github.com/jsperson/sphero_rvr_mcp
Project-URL: Issues, https://github.com/jsperson/sphero_rvr_mcp/issues
Author-email: Jason Scott Person <jsperson+rvr@gmail.com>
License-Expression: MIT
License-File: LICENSE
Keywords: claude,mcp,model-context-protocol,raspberry-pi,robotics,rvr,sphero
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Education
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.10
Requires-Dist: fastmcp>=2.0.0
Requires-Dist: nest-asyncio>=1.6.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# Sphero RVR MCP Server

An [MCP (Model Context Protocol)](https://modelcontextprotocol.io/) server that enables AI assistants to control a [Sphero RVR](https://sphero.com/collections/rvr) robot. Run this on a Raspberry Pi connected to your RVR, and use any MCP-compatible client to drive, control LEDs, read sensors, and more.

## Features

- **Full RVR Control**: Movement, LEDs, sensors, battery monitoring, IR communication
- **Safety System**: Configurable speed limits, auto-stop timeout, emergency stop
- **Sensor Streaming**: Background streaming with cached data access
- **Natural Language Control**: Let AI drive your robot with conversational commands
- **Client Agnostic**: Works with any MCP-compatible client

## Compatible MCP Clients

- [Claude Code](https://claude.com/claude-code) (CLI)
- [Claude Desktop](https://claude.ai/download)
- [Cursor](https://cursor.sh/)
- [Zed](https://zed.dev/)
- [Continue.dev](https://continue.dev/)
- Any custom client using the [MCP SDK](https://modelcontextprotocol.io/sdks)

## Requirements

- Raspberry Pi 3 or newer (connected to Sphero RVR via serial)
- Python 3.10+ (3.10.x recommended for Sphero SDK compatibility)
- Sphero RVR with serial connection to Pi
- An MCP-compatible client

## Installation

### 1. Clone the Sphero SDK

The Sphero SDK is not available on PyPI and must be installed manually:

```bash
cd ~
git clone https://github.com/sphero-inc/sphero-sdk-raspberrypi-python.git
```

### 2. Install the MCP Server

**Option A: Install from PyPI** (recommended)

```bash
pip install sphero-rvr-mcp

# Add Sphero SDK to Python path (add to ~/.bashrc for persistence)
export PYTHONPATH="${PYTHONPATH}:${HOME}/sphero-sdk-raspberrypi-python"
```

**Option B: Install from source**

```bash
git clone https://github.com/jsperson/sphero_rvr_mcp.git
cd sphero_rvr_mcp

# Install the package in development mode
pip install -e .

# Add Sphero SDK to Python path (add to ~/.bashrc for persistence)
export PYTHONPATH="${PYTHONPATH}:${HOME}/sphero-sdk-raspberrypi-python"
```

### 3. Verify Installation

Run the pre-flight check to verify everything is set up correctly:

```bash
sphero-rvr-mcp --check
```

This will verify:
- Python version (requires 3.10+)
- Sphero SDK is installed
- FastMCP is installed
- Serial port exists and is accessible
- Current configuration settings

### 4. Configure Your MCP Client

The server runs via stdio. Configure your MCP client with:

- **Command**: `python -m sphero_rvr_mcp`
- **Environment**: `PYTHONPATH` must include the Sphero SDK path

#### Claude Code

```bash
claude mcp add sphero-rvr -c "python -m sphero_rvr_mcp"
```

Or edit `~/.claude.json`:

```json
{
  "mcpServers": {
    "sphero-rvr": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "sphero_rvr_mcp"],
      "env": {
        "PYTHONPATH": "<your-home-dir>/sphero-sdk-raspberrypi-python"
      }
    }
  }
}
```

#### Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "sphero-rvr": {
      "command": "python",
      "args": ["-m", "sphero_rvr_mcp"],
      "env": {
        "PYTHONPATH": "<path-to>/sphero-sdk-raspberrypi-python"
      }
    }
  }
}
```

#### Other Clients

Refer to your client's MCP configuration documentation. The server uses stdio transport.

## Configuration

Environment variables (optional):

| Variable | Default | Description |
|----------|---------|-------------|
| `RVR_SERIAL_PORT` | `/dev/ttyS0` | Serial port for RVR |
| `RVR_MAX_SPEED_PERCENT` | `50` | Default speed limit (0-100) |
| `RVR_COMMAND_TIMEOUT` | `5.0` | Auto-stop timeout in seconds |
| `RVR_SENSOR_INTERVAL` | `250` | Sensor streaming interval (ms) |

## Usage

### Example Commands

Once your MCP client is connected to the server:

```
You: Connect to the RVR

You: Drive forward slowly for 2 seconds then stop

You: Set all LEDs to blue

You: What's the battery level?

You: Start streaming the accelerometer and gyroscope sensors

You: Turn left 90 degrees

You: Emergency stop!
```

## Available Tools

### Connection (3 tools)
| Tool | Description |
|------|-------------|
| `connect` | Connect to RVR and wake it up |
| `disconnect` | Safely disconnect |
| `get_connection_status` | Get connection state, uptime, firmware |

### Movement (10 tools)
| Tool | Description |
|------|-------------|
| `drive_with_heading` | Drive at speed toward heading (0-359°) |
| `drive_tank` | Tank drive with left/right velocities (m/s) |
| `drive_rc` | RC-style with linear + yaw velocity |
| `drive_to_position` | Drive to X,Y coordinates |
| `stop` | Normal stop (optional deceleration) |
| `emergency_stop` | Immediate stop, blocks movement |
| `clear_emergency_stop` | Allow movement after e-stop |
| `reset_yaw` | Set current heading as 0° |
| `reset_locator` | Set current position as origin |

### LEDs (3 tools)
| Tool | Description |
|------|-------------|
| `set_all_leds` | Set all LEDs to RGB color |
| `set_led` | Set specific LED group to RGB |
| `turn_leds_off` | Turn off all LEDs |

LED groups: `headlight_left`, `headlight_right`, `brakelight_left`, `brakelight_right`, `status_indication_left`, `status_indication_right`, `battery_door_front`, `battery_door_rear`, `power_button_front`, `power_button_rear`, `undercarriage_white`

### Sensors (5 tools)
| Tool | Description |
|------|-------------|
| `start_sensor_streaming` | Start background sensor streaming |
| `stop_sensor_streaming` | Stop all streaming |
| `get_sensor_data` | Get cached sensor readings |
| `get_ambient_light` | Query light sensor directly |
| `get_color_detection` | Query color sensor directly |

Streamable sensors: `accelerometer`, `gyroscope`, `imu`, `locator`, `velocity`, `speed`, `quaternion`, `color_detection`, `ambient_light`, `encoders`, `core_time`

### Battery & System (3 tools)
| Tool | Description |
|------|-------------|
| `get_battery_status` | Battery percentage, voltage, state |
| `get_motor_temperatures` | Motor thermal status |
| `get_system_info` | MAC, firmware, uptime |

### Safety Controls (3 tools)
| Tool | Description |
|------|-------------|
| `get_safety_status` | Current safety settings |
| `set_speed_limit` | Set max speed (0-100%) |
| `set_command_timeout` | Set auto-stop timeout |

### IR Communication (3 tools)
| Tool | Description |
|------|-------------|
| `send_ir_message` | Send IR code (0-7) |
| `start_ir_broadcasting` | Start robot-to-robot IR |
| `stop_ir_broadcasting` | Stop IR broadcasting |

## Safety Features

### Speed Limiting
All movement commands are limited to a configurable percentage of max speed (default 50%). This prevents accidental high-speed collisions.

```
You: Set the speed limit to 25%
You: Now drive forward at full speed
# RVR will only go at 25% of max speed
```

### Command Timeout
If no movement command is received within the timeout period (default 5 seconds), the RVR automatically stops. This prevents runaway situations if connection is lost.

### Emergency Stop
Immediately stops all movement and blocks further motion until explicitly cleared.

```
You: Emergency stop!
# RVR stops immediately
# All movement commands will fail until:
You: Clear the emergency stop
```

## Troubleshooting

### "Failed to connect to RVR"
- Check serial connection: `ls /dev/ttyS0`
- Ensure RVR is powered on
- Verify baud rate (default 115200)

### "sphero_sdk not found"
- Add SDK to PYTHONPATH: `export PYTHONPATH="${PYTHONPATH}:/path/to/sphero-sdk-raspberrypi-python"`

### Slow response
- Raspberry Pi 3 may be slower than Pi 4/5
- Reduce sensor streaming frequency
- Close unnecessary applications

### RVR not responding to commands
- Check if emergency stop is active: `get_safety_status`
- Verify connection: `get_connection_status`
- Try disconnecting and reconnecting

## Project Structure

```
sphero_rvr_mcp/
├── pyproject.toml              # Package configuration
├── README.md                   # This file
├── LICENSE                     # MIT License
└── src/sphero_rvr_mcp/
    ├── __init__.py
    ├── __main__.py             # Entry point
    ├── config.py               # Configuration dataclasses
    ├── models.py               # Pydantic response models
    ├── rvr_manager.py          # Connection lifecycle
    ├── sensor_manager.py       # Sensor streaming
    ├── safety_controller.py    # Safety system
    └── server.py               # MCP server + tools
```

## License

MIT
