# ESP32 CYD MCP Server

A comprehensive Model Context Protocol (MCP) server implementation for the ESP32 CYD (Cheap Yellow Display) board. This project provides extensive remote control capabilities for the ESP32-2432S028R board through a WebSocket-based MCP interface.

## Features

### MCP Server Core
- WebSocket-based MCP protocol implementation
- JSON-RPC 2.0 compliant
- Real-time bidirectional communication
- Multiple client support
- Event notifications

### Tool Categories

#### Display Tools (20+ tools)
- `display.clear` - Clear screen with color
- `display.text` - Draw text with positioning and styling
- `display.line` - Draw lines with thickness
- `display.rectangle` - Draw rectangle outlines
- `display.fillRectangle` - Draw filled rectangles
- `display.circle` - Draw circle outlines
- `display.fillCircle` - Draw filled circles
- `display.pixel` - Draw individual pixels
- `display.backlight` - Control backlight on/off
- `display.brightness` - Set display brightness (0-255)
- `display.rotation` - Set display rotation (0-3)
- `display.progressBar` - Draw progress bars
- `display.info` - Get display information

#### Touch Tools (10+ tools)
- `touch.getState` - Get current touch state
- `touch.enable` - Enable/disable touch input
- `touch.calibrate` - Calibrate touch screen
- `touch.getHistory` - Get recent touch events
- `touch.simulate` - Simulate touch events
- `touch.getCalibration` - Get calibration values
- `touch.saveCalibration` - Save calibration to file
- Gesture detection (swipe support)

#### GPIO Tools (15+ tools)
- `gpio.pinMode` - Set pin mode (input/output/PWM)
- `gpio.digitalWrite` - Write digital value
- `gpio.digitalRead` - Read digital value
- `gpio.analogWrite` - PWM output
- `gpio.analogRead` - Read analog value
- `gpio.attachInterrupt` - Attach interrupts
- `gpio.setPWM` - Configure PWM with frequency
- `gpio.tone` - Generate tones
- `gpio.pulseIn` - Measure pulse duration

#### Sensor Tools (10+ tools)
- `sensor.readTemperature` - Read temperature sensor
- `sensor.readLight` - Read light sensor
- `sensor.readInternalTemp` - ESP32 internal temperature
- `sensor.readHallSensor` - Built-in hall sensor
- `sensor.readBatteryVoltage` - Power supply voltage
- `sensor.readAll` - Read all sensors at once
- `sensor.calibrate` - Calibrate sensors
- `sensor.getEnvironment` - Environmental summary

#### Network Tools (15+ tools)
- `network.status` - Get network status
- `network.connect` - Connect to WiFi
- `network.scan` - Scan for networks
- `network.startAP` - Start access point
- `network.httpRequest` - Make HTTP requests
- `network.ping` - Ping hosts
- `network.getTime` - Get NTP time
- `network.setMDNS` - Configure mDNS

#### System Tools (20+ tools)
- `system.info` - Comprehensive system information
- `system.restart` - Restart ESP32
- `system.sleep` - Deep/light sleep modes
- `system.memory` - Memory statistics
- `system.tasks` - FreeRTOS task info
- `system.setCPUFrequency` - CPU speed control
- `system.performanceMode` - Performance optimization
- `system.factoryReset` - Factory reset

#### File Tools (15+ tools)
- `file.list` - List files/directories
- `file.read` - Read file contents
- `file.write` - Write to file
- `file.delete` - Delete files
- `file.mkdir` - Create directories
- `file.copy` - Copy files
- `file.storage` - Storage statistics
- Support for SPIFFS and SD card

#### Audio Tools (15+ tools)
- `audio.tone` - Play single tone
- `audio.playMelody` - Play melodies
- `audio.beep` - Simple beep sounds
- `audio.playPattern` - Custom tone patterns
- `audio.notification` - Notification sounds
- `audio.alarm` - Alarm patterns
- `audio.setVolume` - Volume control
- Predefined melodies (Mario, Star Wars, etc.)

## Hardware Requirements

- ESP32-2432S028R (CYD) board
- 2.8" ILI9341 TFT display (240x320)
- XPT2046 resistive touch controller
- Optional: SD card for file storage
- Optional: External sensors (temperature, light)

## Installation

1. Install PlatformIO or Arduino IDE
2. Clone this repository
3. Open the project in PlatformIO
4. Build and upload to your ESP32 CYD board

```bash
git clone https://github.com/yourusername/esp32-cyd-mcp
cd esp32-cyd-mcp
pio run -t upload
```

## Configuration

Edit `include/config.h` to customize:
- WiFi credentials
- Pin assignments
- Server ports
- Display settings
- Sensor calibration

## Usage

### Connecting to the MCP Server

1. Power on the ESP32 CYD board
2. Connect to WiFi or use the AP mode
3. Find the device IP address on the display
4. Connect via WebSocket to `ws://[IP]:3001`

### Example MCP Request

```json
{
  "jsonrpc": "2.0",
  "id": "1",
  "method": "tools/invoke",
  "params": {
    "name": "display.text",
    "arguments": {
      "text": "Hello MCP!",
      "x": 50,
      "y": 100,
      "color": "white",
      "size": 2
    }
  }
}
```

### Using with Claude Desktop

Add to your Claude Desktop configuration:

```json
{
  "mcpServers": {
    "esp32-cyd": {
      "command": "websocat",
      "args": ["ws://192.168.1.100:3001"]
    }
  }
}
```

## API Documentation

### Tool Invocation

All tools are invoked using the standard MCP `tools/invoke` method:

```json
{
  "method": "tools/invoke",
  "params": {
    "name": "tool.name",
    "arguments": { ... }
  }
}
```

### Event Notifications

The server sends notifications for various events:

- `touch.event` - Touch input events
- `sensor.update` - Periodic sensor updates
- `network.event` - Network state changes
- `gpio.interrupt` - GPIO interrupt events

## Development

### Adding New Tools

1. Create header file in `include/tools/`
2. Implement in `src/tools/`
3. Register tools in the `registerTools()` method
4. Add initialization in `main.cpp`

### Project Structure

```
esp32-cyd-mcp/
├── include/
│   ├── config.h           # Configuration
│   ├── mcp_server.h       # MCP server core
│   └── tools/            # Tool headers
├── src/
│   ├── main.cpp          # Main application
│   ├── mcp_server.cpp    # MCP implementation
│   └── tools/           # Tool implementations
├── platformio.ini        # PlatformIO config
└── README.md
```

## Troubleshooting

- **WiFi Connection Issues**: Check credentials in config.h
- **Touch Not Working**: Run touch calibration tool
- **Display Issues**: Verify display rotation setting
- **Memory Issues**: Monitor free heap, reduce tool usage

## License

This project is open source and available under the MIT License.

## Contributing

Contributions are welcome! Please submit pull requests or open issues for bugs and feature requests.

## Acknowledgments

- ESP32 community for hardware support
- TFT_eSPI library for display drivers
- MCP specification for protocol design