mcesptool/README.md

# MCP ESPTool Server

FastMCP server providing AI-powered ESP32/ESP8266 development workflows through natural language interfaces.

## Features

- **Chip Control**: Advanced ESP device detection, connection, and control
- **Flash Operations**: Comprehensive flash memory management with safety features
- **Security Management**: ESP security features including secure boot and flash encryption
- **Production Tools**: Factory programming and batch operations
- **Middleware System**: Universal CLI tool integration with bidirectional MCP communication
- **ESP-IDF Integration**: Host application support for hardware-free development
- **QEMU Emulation**: Virtual ESP32 devices for testing without physical hardware

## Quick Start

### Installation

```bash
# Install with uvx (recommended)
uvx mcp-esptool-server

# Or install in project
uv add mcp-esptool-server
```

### Claude Code Integration

```bash
# Add to Claude Code
claude mcp add mcp-esptool-server "uvx mcp-esptool-server"
```

### Development Setup

```bash
# Clone and setup
git clone <repository>
cd mcp-esptool
make dev

# Run development server
make run-debug

# Run tests
make test
```

## Architecture

The server implements a component-based architecture with middleware for CLI tool integration:

- **Components**: Specialized modules for different ESP development workflows
- **Middleware**: Universal pattern for intercepting and redirecting CLI tool output to MCP context
- **Configuration**: Environment-based configuration with auto-detection
- **Production Ready**: Docker support with development and production modes

## Components

- `ChipControl`: Device detection, connection management, reset operations
- `FlashManager`: Flash operations with verification and backup
- `PartitionManager`: Partition table management and OTA support
- `SecurityManager`: Security features and eFuse management
- `FirmwareBuilder`: ESP-IDF integration and binary operations
- `OTAManager`: Over-the-air update workflows
- `ProductionTools`: Factory programming and quality control
- `Diagnostics`: Memory dumps and performance profiling
- `QemuManager`: QEMU-based ESP32 emulation with download mode, efuse, and flash support

## Flash Operations

Advanced flash management tools for efficient firmware deployment:

| Tool | Description |
|------|-------------|
| `esp_flash_firmware` | Flash a single binary to device |
| `esp_flash_multi` | Flash multiple binaries at different addresses in one operation |
| `esp_verify_flash` | Verify flash contents match a file without re-flashing |
| `esp_flash_read` | Read flash memory to a file |
| `esp_flash_erase` | Erase flash regions |
| `esp_flash_backup` | Create complete flash backup |

### Multi-File Flashing

Flash bootloader, partition table, and app in a single operation:

```python
esp_flash_multi(
    files=[
        {"address": "0x0", "path": "bootloader.bin"},
        {"address": "0x8000", "path": "partitions.bin"},
        {"address": "0x10000", "path": "app.bin"}
    ],
    port="/dev/ttyUSB0",
    verify=True
)
```

## RAM Loading (Development Iteration)

Test firmware changes without wearing out flash:

| Tool | Description |
|------|-------------|
| `esp_elf_to_ram_binary` | Convert ELF to RAM-loadable binary |
| `esp_load_ram` | Load and execute binary in RAM |
| `esp_serial_monitor` | Capture serial output from device |

### Workflow

```bash
# 1. Build your ESP-IDF project
idf.py build

# 2. Convert ELF to RAM binary
esp_elf_to_ram_binary(elf_path="build/my_app.elf", chip="esp32s3")

# 3. Load to RAM and execute (no flash wear!)
esp_load_ram(binary_path="my_app-ram.bin", port="/dev/ttyUSB0")

# 4. Capture output
esp_serial_monitor(port="/dev/ttyUSB0", duration_seconds=10)
```

**Note:** RAM loading requires ELFs built without secure boot (`CONFIG_SECURE_BOOT=n`). Some PlatformIO defaults may be incompatible.

## QEMU Emulation

Run virtual ESP32 devices without physical hardware. Requires [Espressif's QEMU fork](https://github.com/espressif/qemu):

```bash
# Install via ESP-IDF tools
source /path/to/esp-idf/export.sh
python3 $IDF_PATH/tools/idf_tools.py install qemu-xtensa qemu-riscv32
```

The server auto-detects QEMU binaries from `~/.espressif/tools/`. Once available, five tools are exposed:

| Tool | Description |
|------|-------------|
| `esp_qemu_start` | Launch a virtual ESP device (supports esp32, esp32s3, esp32c3) |
| `esp_qemu_stop` | Stop a running instance |
| `esp_qemu_list` | List all running instances |
| `esp_qemu_status` | Detailed instance info |
| `esp_qemu_flash` | Write firmware to a virtual device's flash |

Virtual devices appear in `esp_scan_ports` alongside physical hardware, connected via `socket://localhost:<port>`.

## Configuration

Configure via environment variables or `.env` file:

```bash
ESPTOOL_PATH=esptool
ESP_DEFAULT_BAUD_RATE=460800
ESP_IDF_PATH=/path/to/esp-idf
MCP_ENABLE_PROGRESS=true
PRODUCTION_MODE=false
```

## Docker

```bash
# Development with hot reload
make docker-up

# Production deployment
DOCKER_TARGET=production make docker-up
```

## License

MIT License - see LICENSE file for details.