Esp Cyd MCP

🚀 ESP32 CYD MCP 服務器

這是一個為 ESP32 CYD（廉價黃色顯示屏）開發板打造的全面的模型上下文協議（MCP）服務器實現方案。本項目藉助基於 WebSocket 的 MCP 接口，為 ESP32 - 2432S028R 開發板提供了強大的遠程控制功能。

✨ 主要特性

MCP 服務器核心

• 基於 WebSocket 的 MCP 協議實現
• 符合 JSON - RPC 2.0 標準
• 支持即時雙向通信
• 可同時支持多個客戶端
• 具備事件通知功能

工具類別

顯示工具（20 多種工具）

• display.clear - 用指定顏色清屏
• display.text - 定位並設置樣式繪製文本
• display.line - 繪製指定粗細的線條
• display.rectangle - 繪製矩形輪廓
• display.fillRectangle - 繪製填充矩形
• display.circle - 繪製圓形輪廓
• display.fillCircle - 繪製填充圓形
• display.pixel - 繪製單個像素
• display.backlight - 控制背光燈開關
• display.brightness - 設置顯示屏亮度（範圍 0 - 255）
• display.rotation - 設置顯示屏旋轉角度（範圍 0 - 3）
• display.progressBar - 繪製進度條
• display.info - 獲取顯示屏信息

觸摸工具（10 多種工具）

• touch.getState - 獲取當前觸摸狀態
• touch.enable - 啟用/禁用觸摸輸入
• touch.calibrate - 校準觸摸屏
• touch.getHistory - 獲取最近的觸摸事件
• touch.simulate - 模擬觸摸事件
• touch.getCalibration - 獲取校準值
• touch.saveCalibration - 將校準值保存到文件
• 支持手勢檢測（支持滑動操作）

GPIO 工具（15 多種工具）

• gpio.pinMode - 設置引腳模式（輸入/輸出/PWM）
• gpio.digitalWrite - 寫入數字值
• gpio.digitalRead - 讀取數字值
• gpio.analogWrite - 進行 PWM 輸出
• gpio.analogRead - 讀取模擬值
• gpio.attachInterrupt - 附加中斷
• gpio.setPWM - 配置帶頻率的 PWM
• gpio.tone - 生成音調
• gpio.pulseIn - 測量脈衝持續時間

傳感器工具（10 多種工具）

• sensor.readTemperature - 讀取溫度傳感器數據
• sensor.readLight - 讀取光線傳感器數據
• sensor.readInternalTemp - 讀取 ESP32 內部溫度
• sensor.readHallSensor - 讀取內置霍爾傳感器數據
• sensor.readBatteryVoltage - 讀取電源電壓
• sensor.readAll - 一次性讀取所有傳感器數據
• sensor.calibrate - 校準傳感器
• sensor.getEnvironment - 獲取環境概要信息

網絡工具（15 多種工具）

• network.status - 獲取網絡狀態
• network.connect - 連接到 WiFi
• network.scan - 掃描可用網絡
• network.startAP - 開啟接入點
• network.httpRequest - 發起 HTTP 請求
• network.ping - 對主機進行 Ping 操作
• network.getTime - 獲取 NTP 時間
• network.setMDNS - 配置 mDNS

系統工具（20 多種工具）

• system.info - 獲取全面的系統信息
• system.restart - 重啟 ESP32
• system.sleep - 進入深度/輕度睡眠模式
• system.memory - 獲取內存統計信息
• system.tasks - 獲取 FreeRTOS 任務信息
• system.setCPUFrequency - 控制 CPU 速度
• system.performanceMode - 進行性能優化
• system.factoryReset - 恢復出廠設置

文件工具（15 多種工具）

• file.list - 列出文件/目錄
• file.read - 讀取文件內容
• file.write - 寫入文件
• file.delete - 刪除文件
• file.mkdir - 創建目錄
• file.copy - 複製文件
• file.storage - 獲取存儲統計信息
• 支持 SPIFFS 和 SD 卡

音頻工具（15 多種工具）

• audio.tone - 播放單音
• audio.playMelody - 播放旋律
• audio.beep - 播放簡單的蜂鳴聲
• audio.playPattern - 播放自定義音調模式
• audio.notification - 播放通知音
• audio.alarm - 播放警報模式
• audio.setVolume - 控制音量
• 預定義旋律（如馬里奧、星球大戰等）

📦 安裝指南

1. 安裝 PlatformIO 或 Arduino IDE
2. 克隆本倉庫
3. 在 PlatformIO 中打開項目
4. 構建並上傳到你的 ESP32 CYD 開發板

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

📚 詳細文檔

配置

編輯 include/config.h 以進行自定義設置：

• WiFi 憑證
• 引腳分配
• 服務器端口
• 顯示設置
• 傳感器校準

使用方法

連接到 MCP 服務器

1. 為 ESP32 CYD 開發板通電
2. 連接到 WiFi 或使用接入點模式
3. 在顯示屏上找到設備 IP 地址
4. 通過 WebSocket 連接到 ws://[IP]:3001

MCP 請求示例

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

與 Claude Desktop 配合使用

將以下內容添加到你的 Claude Desktop 配置中：

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

API 文檔

工具調用

所有工具都使用標準的 MCP tools/invoke 方法進行調用：

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

事件通知

服務器會針對各種事件發送通知：

• touch.event - 觸摸輸入事件
• sensor.update - 定期的傳感器更新事件
• network.event - 網絡狀態變化事件
• gpio.interrupt - GPIO 中斷事件

開發

添加新工具

1. 在 include/tools/ 目錄下創建頭文件
2. 在 src/tools/ 目錄下實現功能
3. 在 registerTools() 方法中註冊工具
4. 在 main.cpp 中添加初始化代碼

項目結構

esp32-cyd-mcp/
├── include/
│   ├── config.h           # 配置文件
│   ├── mcp_server.h       # MCP 服務器核心
│   └── tools/            # 工具頭文件
├── src/
│   ├── main.cpp          # 主應用程序
│   ├── mcp_server.cpp    # MCP 實現
│   └── tools/           # 工具實現
├── platformio.ini        # PlatformIO 配置文件
└── README.md

故障排除

• WiFi 連接問題：檢查 config.h 中的憑證信息
• 觸摸功能異常：運行觸摸校準工具
• 顯示問題：驗證顯示屏旋轉設置
• 內存問題：監控空閒堆內存，減少工具使用

📄 許可證

本項目為開源項目，採用 MIT 許可證。

貢獻說明

歡迎貢獻代碼！請提交拉取請求，或針對漏洞和功能需求提交問題。

致謝

• 感謝 ESP32 社區提供的硬件支持
• 感謝 TFT_eSPI 庫提供的顯示驅動
• 感謝 MCP 規範提供的協議設計思路