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 规范提供的协议设计思路