# Dash Robot MCP Server

A Model Context Protocol (MCP) server for controlling Wonder Workshop's Dash robot through Claude. This allows Claude to autonomously control Dash's movements, lights, sounds, and head movements, as well as capture photos using a webcam.

## Features

### Robot Control
- **Movement**: Move forward, turn left/right, turn around (calibrated for accuracy)
- **Sounds**: Play 40+ built-in sounds (animals, vehicles, beeps, custom recordings)
- **Lights**: Control eye brightness and RGB colors for neck and ear LEDs
- **Head Movement**: Control head yaw (-53° to 53°) and pitch (-5° to 10°)
- **Connection Management**: Connect, disconnect, and stop the robot

### Photo Capture
- Capture photos using a webcam via a separate FastAPI server
- Photos are returned to Claude for visual analysis

## Prerequisites

- Python 3.11 or higher
- Wonder Workshop Dash robot
- Bluetooth Low Energy (BLE) support on your computer
- Webcam (optional, for photo capture)

## Installation

### 1. Clone the Repository

```bash
git clone https://github.com/jakesimonds/mcpleasework.git
cd mcpleasework
```

### 2. Install Dependencies

```bash
# Create a virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install the bleak-dash library (Dash robot BLE control)
pip install git+https://github.com/mewmix/bleak-dash.git

# Install project dependencies
pip install -e .
```

### 3. Configure Claude Desktop

Add the following to your Claude Desktop configuration file:

**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

```json
{
  "mcpServers": {
    "Dash Robot": {
      "command": "/path/to/your/venv/bin/uv",
      "args": [
        "run",
        "--with",
        "mcp[cli],requests,opencv-python,pillow",
        "--with",
        "git+https://github.com/mewmix/bleak-dash.git",
        "mcp",
        "run",
        "/path/to/your/mcpleasework/server.py"
      ]
    }
  }
}
```

Replace `/path/to/your/` with the actual paths on your system. To find the `uv` path:

```bash
which uv  # macOS/Linux
where uv  # Windows
```

### 4. Start the Photo Server (Optional)

If you want photo capture capabilities:

```bash
cd photoServer
pip install fastapi uvicorn opencv-python
uvicorn app:app --port 5001
```

Keep this running in a separate terminal.

## Usage

### Testing the Server

Use the MCP development inspector to test the server:

```bash
mcp dev server.py
```

### Available Tools

Once configured in Claude Desktop, you can ask Claude to:

- `connect_to_dash()` - Connect to your Dash robot
- `move_dash_forward(distance)` - Move forward (distance in mm, default 1000)
- `dash_turn_left()` - Turn 90° left
- `dash_turn_right()` - Turn 90° right
- `dash_turn_around()` - Turn 180°
- `dash_say(sound_name)` - Play a sound
- `dash_head_movement(yaw, pitch)` - Move the head
- `dash_change_lights(eye_value, neck_color, left_ear_color, right_ear_color)` - Change LED colors
- `take_photo()` - Capture a photo (requires photo server)
- `get_available_sounds()` - List all available sounds
- `get_sound_descriptions()` - Get descriptions of sounds
- `get_movement_limits()` - Get parameter limits
- `get_color_examples()` - Get available colors
- `disconnect_dash()` - Disconnect from the robot

### Example Prompts

```
"Connect to Dash and make him say hello"
"Move Dash forward 500mm, turn right, and change his lights to blue"
"Take a photo and tell me what you see"
"Make Dash do a little dance with sounds and lights"
```

## Project Structure

```
mcpleasework/
├── server.py              # Main MCP server with Dash control tools
├── photoServer/
│   └── app.py            # FastAPI server for photo capture
├── photo/                 # Directory for captured photos
├── scripts/
│   └── screenshot.py     # Webcam utility script
├── pyproject.toml        # Project configuration and dependencies
├── requirements.txt      # Pinned dependencies
└── README.md            # This file
```

## Development

### Running Tests

```bash
pytest
```

### Code Formatting

This project uses `ruff` and `black` for code formatting:

```bash
ruff check .
black .
```

### Pre-commit Hooks

Install pre-commit hooks:

```bash
pip install pre-commit
pre-commit install
```

## Hardware Notes

### Dash Robot Calibration

The turn functions are calibrated for accurate 90° and 180° turns:
- `dash_turn_left()`: 123° at 72 dps
- `dash_turn_right()`: 270° workaround (hardware issue with right turns)
- `dash_turn_around()`: 185° at 72 dps

These values may need adjustment based on your floor surface and robot's wheel condition.

### BLE Connection

The robot uses Bluetooth Low Energy. Ensure your computer's Bluetooth is enabled and the Dash robot is powered on before attempting to connect.

## Troubleshooting

### Cannot connect to Dash
- Ensure Bluetooth is enabled
- Turn Dash off and on again
- Make sure no other device is connected to Dash

### Photo server not responding
- Check that the photo server is running on port 5001
- Verify your webcam is accessible: `ls /dev/video*` (Linux)

### Import errors
- Ensure `bleak-dash` is installed: `pip install git+https://github.com/mewmix/bleak-dash.git`
- Activate your virtual environment

## Credits

This project was originally forked from [pamelafox's MCP Python demo template](https://github.com/pamelafox/mcp-python-demo) and has been extensively modified for Dash robot control.

- **Dash Robot**: [Wonder Workshop](https://www.makewonder.com/)
- **bleak-dash Library**: [mewmix/bleak-dash](https://github.com/mewmix/bleak-dash)
- **MCP SDK**: [Anthropic](https://github.com/anthropics/anthropic-sdk-python)

## License

MIT License - see LICENSE file for details