mcesptool/FASTMCP_ESPTOOL_SERVER.md

# 🚀 FastMCP Esptool Server Architecture

## Overview

A comprehensive FastMCP server that leverages esptool's Python API to provide AI-powered ESP32/ESP8266 development workflows. This server complements the existing Arduino MCP server by offering direct ESP chip control, advanced flashing capabilities, and production-grade automation.

## 🎯 Core Value Proposition

**Problem**: Current ESP development requires manual Arduino IDE/CLI usage, lacks AI assistance, and provides limited automation for production workflows.

**Solution**: Natural language ESP development with professional-grade chip control, automated workflows, and seamless CI/CD integration.

```
User: "Flash my ESP32 with custom partitions for OTA updates"
Claude: → Detects ESP32 variant automatically
        → Creates optimal partition table
        → Configures OTA bootloader
        → Flashes with production settings
        → Validates flash integrity
        ✓ "ESP32 ready for OTA updates, partition table optimized"
```

## 🏗️ Architecture Design

### Core Components Structure

```python
# FastMCP server structure following Arduino MCP server patterns
src/
├── mcp_esptool_server/
│   ├── __init__.py
│   ├── server.py                    # Main FastMCP server
│   ├── config.py                    # Configuration management
│   └── components/
│       ├── __init__.py
│       ├── chip_control.py          # ESP chip detection & control
│       ├── flash_manager.py         # Flash operations & optimization
│       ├── partition_manager.py     # Partition table management
│       ├── security_manager.py      # eFuse & security operations
│       ├── firmware_builder.py      # ELF→binary conversion
│       ├── ota_manager.py           # OTA update workflows
│       ├── production_tools.py      # Factory programming
│       └── diagnostics.py           # Debug & analysis tools
```

### Component Architecture Patterns

Each component follows FastMCP best practices:

```python
# Example: chip_control.py
from fastmcp import FastMCP
from esptool.cmds import detect_chip, run_stub, reset_chip
import asyncio
from pathlib import Path

class ChipControl:
    def __init__(self, app: FastMCP):
        self.app = app
        self.register_tools()
        self.register_resources()

    def register_tools(self):
        """Register chip control tools"""

        @self.app.tool("esp_detect_chip")
        async def detect_esp_chip(port: str) -> dict:
            """Auto-detect ESP chip and return detailed information"""
            # Implementation using esptool.cmds.detect_chip

        @self.app.tool("esp_connect_optimized")
        async def connect_with_optimization(port: str, enable_stub: bool = True) -> str:
            """Connect to ESP with performance optimizations"""
            # Multi-strategy connection with fallbacks
```

## 🔧 Tool Categories & API Design

### 1. **Chip Control & Detection (8 tools)**

```python
# Chip identification and connection management
esp_detect_chip(port: str) -> dict
esp_connect_advanced(port: str, baud: int = 460800, retries: int = 7) -> str
esp_reset_chip(port: str, reset_mode: str = "hard-reset") -> str
esp_load_ram(port: str, firmware: str) -> str  # Development testing
esp_run_firmware(port: str) -> str
esp_get_chip_info(port: str) -> dict
esp_test_connection(port: str) -> dict
esp_recover_chip(port: str) -> str  # Brick recovery
```

### 2. **Flash Memory Operations (12 tools)**

```python
# Advanced flash management beyond Arduino CLI
esp_flash_firmware(port: str, files: list[dict]) -> str
esp_flash_read(port: str, address: int, size: int, output_file: str) -> str
esp_flash_erase(port: str, region: str = "all") -> str
esp_flash_verify(port: str, files: list[dict]) -> dict
esp_flash_analyze(port: str) -> dict  # Usage analysis
esp_flash_optimize(port: str) -> dict  # Performance tuning
esp_flash_backup(port: str, output_dir: str) -> str
esp_flash_restore(port: str, backup_dir: str) -> str
esp_flash_encrypt(port: str, key_file: str) -> str
esp_flash_status(port: str) -> dict
esp_flash_sfdp_read(port: str) -> dict  # Flash chip details
esp_flash_size_detect(port: str) -> dict
```

### 3. **Partition Management (6 tools)**

```python
# Custom partition table creation and management
esp_partition_create(layout: dict, output_file: str) -> str
esp_partition_flash(port: str, partition_file: str) -> str
esp_partition_read(port: str) -> dict
esp_partition_analyze(port: str) -> dict
esp_ota_partition_setup(port: str, app_size: str) -> str
esp_nvs_partition_create(data: dict, output_file: str) -> str
```

### 4. **Security & eFuse Operations (8 tools)**

```python
# Production security configuration
esp_efuse_read(port: str, efuse_name: str = None) -> dict
esp_efuse_burn(port: str, efuse_name: str, value: str) -> str
esp_security_info(port: str) -> dict
esp_encryption_enable(port: str, key_file: str) -> str
esp_secure_boot_enable(port: str, key_file: str) -> str
esp_flash_encryption_configure(port: str) -> str
esp_mac_address_read(port: str) -> str
esp_security_audit(port: str) -> dict
```

### 5. **Firmware Building & Analysis (7 tools)**

```python
# ELF processing and binary preparation
esp_elf_to_binary(elf_file: str, chip_type: str, output_file: str = None) -> str
esp_binary_merge(files: list[dict], output_file: str) -> str
esp_firmware_analyze(binary_file: str) -> dict
esp_bootloader_build(chip_type: str, config: dict) -> str
esp_app_prepare(elf_file: str, chip_type: str) -> dict
esp_binary_optimize(binary_file: str) -> str
esp_size_analysis(elf_file: str) -> dict
```

### 6. **OTA & Production Workflows (10 tools)**

```python
# Over-the-air updates and factory programming
esp_ota_package_create(firmware_file: str, version: str) -> str
esp_ota_flash_prepare(port: str) -> str
esp_factory_program(port: str, config: dict) -> str
esp_production_test(port: str, test_suite: str) -> dict
esp_batch_program(ports: list[str], firmware: str) -> dict
esp_quality_control(port: str) -> dict
esp_calibration_data_write(port: str, cal_data: dict) -> str
esp_manufacturing_data_write(port: str, mfg_data: dict) -> str
esp_provision_device(port: str, config: dict) -> str
esp_factory_reset(port: str) -> str
```

### 7. **Diagnostics & Debug (8 tools)**

```python
# Advanced debugging and analysis
esp_memory_dump(port: str, address: int, size: int) -> str
esp_register_dump(port: str) -> dict
esp_core_dump_analyze(dump_file: str) -> dict
esp_performance_profile(port: str, duration: int) -> dict
esp_power_analysis(port: str) -> dict
esp_rf_calibration_check(port: str) -> dict
esp_thermal_status(port: str) -> dict
esp_diagnostic_report(port: str) -> dict
```

## 📋 MCP Resources (6 resources)

Real-time information resources for Claude to understand ESP development environment:

```python
# Resource URLs following MCP patterns
esp://chips          # Connected ESP devices with capabilities
esp://flash/status    # Flash memory status and layout
esp://security/info   # Security configuration and eFuse status
esp://partitions      # Partition table information
esp://firmware/info   # Loaded firmware details
esp://diagnostics     # Real-time diagnostic information
```

## 🎨 Natural Language Workflows

### Development Workflows

```
User: "I need to test my new ESP32 firmware without wearing out the flash"
Claude: → esp_detect_chip to identify ESP32 variant
        → esp_load_ram with firmware binary
        → esp_run_firmware to execute from RAM
        ✓ "Firmware running from RAM, flash cycles preserved"

User: "Create an OTA-ready ESP32 with 2MB app partitions"
Claude: → esp_partition_create with OTA layout (2x2MB app + OTA data)
        → esp_bootloader_build with OTA support
        → esp_flash_firmware with bootloader + partition table
        ✓ "ESP32 configured for OTA updates, ready for deployment"
```

### Production Workflows

```
User: "Program 50 ESP32 devices for production with unique MAC addresses"
Claude: → esp_detect_chip for each device
        → esp_factory_program with base firmware
        → esp_manufacturing_data_write with unique identifiers
        → esp_quality_control validation
        → esp_production_test suite execution
        ✓ "Batch programming completed, all devices validated"
```

### Security Workflows

```
User: "Enable flash encryption and secure boot on this ESP32"
Claude: → esp_security_audit to check current state
        → esp_secure_boot_enable with key generation
        → esp_flash_encryption_configure
        → esp_efuse_burn for permanent security settings
        ✓ "ESP32 secured with flash encryption and secure boot"
```

## 🔗 Integration with Existing Arduino MCP Server

### Complementary Capabilities

```python
# Integration patterns
class ESPToolIntegration:
    """Bridge between Arduino MCP and ESPTool MCP servers"""

    async def arduino_to_esptool_workflow(self, sketch_path: str, board_type: str):
        """Convert Arduino sketch to ESP-optimized firmware"""
        # 1. Use Arduino MCP to compile sketch
        # 2. Use ESPTool MCP to optimize binary
        # 3. Use ESPTool MCP for advanced flashing

    async def unified_esp_development(self, project_config: dict):
        """Complete ESP development pipeline"""
        # 1. Arduino MCP: Sketch development and compilation
        # 2. ESPTool MCP: Binary optimization and security
        # 3. ESPTool MCP: Production flashing and validation
```

### Shared Resources

```python
# Shared configuration between servers
class UnifiedESPConfig:
    arduino_cli_path: str
    esptool_path: str
    sketch_directories: list[Path]
    esp_tools_directory: Path
    shared_project_roots: list[Path]
```

## 🚀 Implementation Roadmap

### Phase 1: Core Infrastructure (Week 1-2)
- [ ] FastMCP server setup with modern uv/pyproject.toml
- [ ] Basic chip control component (detect, connect, reset)
- [ ] Flash operations component (read, write, erase)
- [ ] Configuration management and MCP roots integration

### Phase 2: Advanced Features (Week 3-4)
- [ ] Partition management tools
- [ ] Security and eFuse operations
- [ ] Firmware building and analysis
- [ ] Custom logger integration

### Phase 3: Production Features (Week 5-6)
- [ ] OTA workflow automation
- [ ] Factory programming tools
- [ ] Batch operations and CI/CD integration
- [ ] Comprehensive diagnostics

### Phase 4: Integration & Polish (Week 7-8)
- [ ] Arduino MCP server integration
- [ ] Documentation and examples
- [ ] Performance optimization
- [ ] Production deployment tooling

## 📚 Configuration Example

```toml
# pyproject.toml
[project]
name = "mcp-esptool-server"
version = "2025.09.27.1"
description = "FastMCP server for ESP32/ESP8266 development with esptool integration"
requires-python = ">=3.10"

dependencies = [
    "fastmcp>=2.12.4",
    "esptool>=5.0.0",
    "pyserial>=3.5",
    "pyserial-asyncio>=0.6",
    "thefuzz[speedup]>=0.22.1"
]

[project.scripts]
mcp-esptool = "mcp_esptool_server.server:main"

# Docker compose integration
services:
  mcp-esptool:
    build: .
    environment:
      - ESPTOOL_PATH=/usr/local/bin/esptool
      - ESP_DEVICE_TIMEOUT=30
      - MCP_ESP_PROJECT_DIR=/workspace/esp_projects
    volumes:
      - esp-firmware:/workspace/firmware
      - esp-tools:/workspace/tools
    labels:
      caddy: esp-tools.local
      caddy.reverse_proxy: "{{upstreams 8080}}"
```

This FastMCP esptool server will provide enterprise-grade ESP development capabilities through natural language interaction, complementing the existing Arduino ecosystem while enabling advanced production workflows.