# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
Reachy Mini MCP Server - A Model Context Protocol (MCP) server that enables AI assistants (like Claude Desktop) to control Reachy Mini humanoid robots through natural language.
## Common Commands
```bash
# Install
uv venv --python 3.10 && source .venv/bin/activate
uv pip install -e . # Core package
uv pip install -e ".[camera]" # With camera support
uv pip install -e ".[speech]" # With text-to-speech support
uv pip install -e ".[dev]" # With dev tools
# Run the server
reachy-mini-mcp
# Lint and type check
ruff check .
mypy src/
# Run tests
pytest
pytest tests/test_specific.py -k "test_name" # Single test
```
## Architecture
```
src/reachy_mini_mcp/
├── server.py # FastMCP server with lifespan context manager
├── config.py # Environment variable configuration
├── context.py # AppContext dataclass for shared state
├── robot_manager.py # Core 100Hz control loop and move queue
├── moves.py # Move implementations (dance, emotion, goto, breathing)
└── tools/ # MCP tool implementations
├── dance.py # Dance choreography
├── emotion.py # Pre-recorded emotions
├── move_head.py # Directional head movement
├── camera.py # Image capture (requires opencv)
├── speaker.py # Text-to-speech with head animation (requires pocket-tts)
├── head_tracking.py
├── stop_motion.py
└── get_status.py
```
### Key Design Patterns
1. **Move Queue System**: All robot actions are queued as `Move` objects and executed sequentially by the control loop.
2. **100Hz Control Loop** (`robot_manager.py`): A dedicated thread runs at 100Hz to:
- Process commands from a thread-safe queue
- Manage move execution and queue
- Activate breathing animation when idle
- Apply head tracking offsets
- Send poses to the robot via Zenoh
3. **Tool Registration Pattern**: Each tool in `tools/` exports a `register_*_tool(mcp)` function that registers handlers with the FastMCP server.
4. **Lifespan Management**: Server startup connects to the robot and starts the control loop; shutdown stops the loop and disconnects cleanly.
5. **ReachyMiniApp Integration**: The `ReachyMiniMCPApp` class allows the server to be launched from the Reachy Mini dashboard with automatic robot connection management.
### Threading Model
- Main thread: FastMCP async handlers
- Control thread: 100Hz movement loop (robot_manager._control_loop)
- Communication: Queue-based commands for thread safety
## Configuration
Environment variables (or `.env` file):
**Robot Settings:**
- `REACHY_MINI_ROBOT_NAME` - Robot name for Zenoh discovery (default: `reachy-mini`)
- `REACHY_MINI_ENABLE_CAMERA` - Enable camera capture (default: `false`)
- `REACHY_MINI_HEAD_TRACKING_ENABLED` - Start with head tracking (default: `false`)
**MCP Transport Settings:**
- `REACHY_MINI_MCP_TRANSPORT` - Transport mode: `stdio` or `sse` (default: `stdio`)
- `REACHY_MINI_MCP_HOST` - SSE server host (default: `0.0.0.0`)
- `REACHY_MINI_MCP_PORT` - SSE server port (default: `8000`)
**Running in SSE mode:**
```bash
# Via environment variable
REACHY_MINI_MCP_TRANSPORT=sse reachy-mini-mcp
# Server will be available at http://localhost:8000/sse
# With custom host/port
REACHY_MINI_MCP_TRANSPORT=sse REACHY_MINI_MCP_PORT=9000 reachy-mini-mcp
```
## Dependencies
- **mcp**: MCP server framework (FastMCP)
- **reachy_mini**: Official Reachy Mini robot SDK
- **reachy_mini_dances_library**: Pre-choreographed dance moves
- **eclipse-zenoh**: Robot communication protocol
- **opencv-python**: Optional, for camera frame encoding
- **pocket-tts**: Optional, for text-to-speech functionality (speak tool)
