# πŸš€ 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.