Ryan Malloy
ff138c492e
Sort glob results when auto-detecting QEMU binaries to reliably pick the newest version. Previously filesystem ordering could select an older build (8.2.0 instead of 9.0.0), missing ESP32-S3 support. Remove ESP32-S2 from CHIP_MACHINES — the Espressif QEMU fork has no esp32s2 machine type.
116 lines
3.4 KiB
Markdown
116 lines
3.4 KiB
Markdown
# 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
|
|
|
|
## 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. |