What is Esp32mcpserver

ESP32MCPServer is an implementation of the Model Context Protocol (MCP) for ESP32 microcontrollers, providing a WebSocket-based interface for resource discovery and monitoring.

Use cases

Use cases include connecting AI models to ESP32 interfaces, monitoring sensor data in real-time, and enabling remote control of devices through a WebSocket interface.

How to use

To use ESP32MCPServer, power on the ESP32, connect to the created access point, navigate to the web interface to configure WiFi credentials, and then connect to the MCP server using WebSocket on port 9000.

Key features

Key features include MCP protocol implementation, WebSocket server for real-time updates, resource discovery and monitoring, WiFi configuration via web interface, thread-safe request handling, and support for LittleFS configuration storage.

Where to use

ESP32MCPServer can be used in IoT applications, smart home devices, and any project requiring real-time communication and resource management over a network.

ESP32 MCP Server

A Model Context Protocol (MCP) implementation for ESP32 microcontrollers, providing a WebSocket-based interface for resource discovery and monitoring.

Status: Not Compiling, initial commit as is from the model

Created with Claude 3.5 Sonet on the commit date (with minor obvioud fixes with automatic formating, etc.)

Features

• MCP protocol implementation (v0.1.0)
• WebSocket server for real-time updates
• Resource discovery and monitoring
• WiFi configuration via web interface
• Thread-safe request handling
• Comprehensive test suite
• AsyncWebServer integration
• LittleFS support for configuration storage

Prerequisites

Hardware

• ESP32 S3 DevKitC-1 board
• USB cable for programming

Software

• PlatformIO Core (CLI) or PlatformIO IDE
• Python 3.7 or higher
• Git

Architecture

flowchart TD
    Start[Start Application] --> Setup[Setup]
    Setup -->|Initialize Filesystem| InitFS[Initialize LittleFS]
    Setup -->|Start Network| StartNetwork[Initialize Network Manager]
    Setup -->|Create Tasks| CreateTasks[Create and Assign Tasks]

    subgraph Network
        StartNetwork --> APCheck[Check AP or Connect Mode]
        APCheck -->|Credentials Exist| Connect[Connect to WiFi]
        APCheck -->|No Credentials| StartAP[Start Access Point]
        Connect --> NetworkReady[Network Ready]
        StartAP --> NetworkReady
    end

    subgraph MCP_Server
        MCP[Start MCP Server] --> HandleClient[Handle Client Connections]
        HandleClient --> HandleRequest[Handle Requests]
        HandleRequest -->|WebSocket Events| WebSocket[Handle WebSocket]
        HandleRequest -->|HTTP Endpoints| HTTP[Process HTTP Requests]
    end

    subgraph Metrics
        self[Start Metrics System] --> InitMetrics[Initialize System Metrics]
        InitMetrics --> CollectMetrics[Collect Metrics Periodically]
        CollectMetrics --> SaveMetrics[Save Metrics to Filesystem]
    end

    subgraph Logger
        self[Start uLogger] --> LogMetrics[Log Metrics Data]
        LogMetrics --> CompactLogs[Compact Logs if Necessary]
        CompactLogs -->|Rotates Logs| LogRotation
    end

    CreateTasks -->|Network Task| NetworkTask[Run Network Task on Core]
    CreateTasks -->|MCP Task| MCPTask[Run MCP Server Task on Core]
    NetworkTask --> Network
    MCPTask --> MCP_Server
    MCP_Server --> Metrics
    Metrics --> Logger

Installation

1. Clone the repository:

git clone https://github.com/yourusername/esp32-mcp-server.git
cd esp32-mcp-server

2. Install dependencies:

pio pkg install

3. Build and upload the filesystem:

pio run -t uploadfs

4. Build and upload the firmware:

pio run -t upload

Usage

Initial Setup

1. Power on the ESP32. It will create an access point named “ESP32_XXXXXX”
2. Connect to the access point
3. Navigate to http://192.168.4.1
4. Configure your WiFi credentials
5. The device will connect to your network

MCP Connection

Connect to the MCP server using WebSocket on port 9000:

const ws = new WebSocket('ws://YOUR_ESP32_IP:9000');

// Initialize connection
ws.send(JSON.stringify({
    jsonrpc: "2.0",
    method: "initialize",
    id: 1
}));

// List available resources
ws.send(JSON.stringify({
    jsonrpc: "2.0",
    method: "resources/list",
    id: 2
}));

Testing

Run the test suite:

# Run all tests
pio test -e native

# Run specific test
pio test -e native -f test_request_queue

# Run with coverage
pio test -e native --coverage

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.