# Webots MCP Server

Generic MCP (Model Context Protocol) bridge for **any** Webots robot simulation. Provides Claude Code and Cursor with real-time access to robot state, sensors, camera, and simulation control.

## Quick Start (3 Lines)

```python
from mcp_bridge import MCPBridge

bridge = MCPBridge(robot)  # Auto-detects Supervisor
bridge.publish({"pose": [x, y, theta], "mode": "navigate"})
```

That's it! Claude Code now has full visibility into your simulation.

## Installation

### Option 1: Clone (Recommended)

```bash
git clone https://github.com/luisfelipesena/webots-youbot-mcp.git
pip install mcp pydantic
```

### Option 2: Copy Files

Copy `mcp_bridge.py` to your controller directory.

## Claude Code Integration

Add to your project's `.mcp.json`:

```json
{
  "mcpServers": {
    "webots": {
      "command": "python",
      "args": ["/path/to/webots-youbot-mcp/webots_youbot_mcp_server.py"],
      "cwd": "/path/to/webots-youbot-mcp"
    }
  }
}
```

## Cursor Integration

Same configuration - Cursor reads `.mcp.json` automatically.

## Controller Integration

### Minimal Example

```python
import sys
sys.path.insert(0, "/path/to/webots-youbot-mcp")
from mcp_bridge import MCPBridge

class MyController:
    def __init__(self):
        self.robot = Robot()  # or Supervisor()
        self.mcp = MCPBridge(self.robot)

    def run(self):
        while self.robot.step(32) != -1:
            # Your logic here
            self.mcp.publish({
                "pose": [x, y, theta],
                "mode": self.mode,
                "sensors": {"front": 1.2, "left": 0.8},
            })
            self.mcp.get_command()  # Handle simulation control
```

### Advanced: World Reload Detection

```python
def reset_state():
    """Called automatically when world reloads"""
    self.mode = "search"
    self.collected = 0

bridge = MCPBridge(robot)
bridge.on_reload(reset_state)

# In main loop:
bridge.detect_reload()  # Triggers callback if reload detected
```

### Advanced: Custom Commands

```python
def handle_custom(cmd):
    if cmd.get("action") == "my_action":
        print(f"Custom command: {cmd}")

bridge.register_command("my_action", handle_custom)
```

## Available MCP Tools

| Tool | Description |
|------|-------------|
| `webots_get_robot_state` | Get current robot state (pose, mode, etc.) |
| `webots_get_sensors` | Get sensor data from status |
| `webots_get_camera` | Get latest camera frame path |
| `webots_get_logs` | Get controller logs |
| `webots_simulation_control` | Pause/resume/reset/reload/step/fast |
| `webots_world_reload` | Force reload world (macOS: osascript) |
| `webots_world_reset` | Reset simulation to initial state |
| `webots_reset_controller_state` | Reset controller internal state |
| `webots_take_screenshot` | Capture simulation view |
| `webots_monitor` | Monitor robot for N seconds |
| `webots_get_full_state` | Complete state dump |

### Force Reload (macOS)

When controller is stuck, use force reload via osascript:

```python
# From MCP:
webots_world_reload(force=True)  # Sends Ctrl+Shift+R to Webots
webots_world_reset(force=True)   # Sends Ctrl+Shift+T to Webots
```

Requires accessibility permissions for Terminal/IDE in System Preferences.

## Data Directory Structure

```
data/
├── status.json      # Robot state (written by controller)
├── commands.json    # Commands from MCP
├── camera/          # Camera frames
├── screenshots/     # Simulation screenshots
└── logs/            # Controller logs
```

## MCPBridge API Reference

```python
bridge = MCPBridge(robot, data_dir=None, throttle_interval=5)

# Core
bridge.publish(state_dict)          # Publish state (throttled)
bridge.publish(state, force=True)   # Publish immediately
bridge.get_command()                # Check for MCP commands

# Reload Detection
bridge.on_reload(callback)          # Register reload callback
bridge.detect_reload()              # Check if world reloaded

# Custom Commands
bridge.register_command(action, handler)

# Utilities
bridge.log(message)                 # Write to log file
bridge.save_camera_frame(camera)    # Save camera image
```

## Global Installation (All Projects)

Add to `~/.config/claude/mcp.json` (Claude Code) or global Cursor settings:

```json
{
  "mcpServers": {
    "webots": {
      "command": "python",
      "args": ["/absolute/path/to/webots_youbot_mcp_server.py"],
      "cwd": "/absolute/path/to/webots-youbot-mcp"
    }
  }
}
```

## Requirements

- Python 3.10+
- `mcp` >= 1.0.0
- `pydantic` >= 2.0.0
- `Pillow` (optional, for camera frames)

## License

MIT