金大哥 - esp-cyd-mcp MCP 详情

article

README

🚀 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 - 控制音量
预定义旋律（如马里奥、星球大战等）

📦 安装指南

安装 PlatformIO 或 Arduino IDE
克隆本仓库
在 PlatformIO 中打开项目
构建并上传到你的 ESP32 CYD 开发板

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

📚 详细文档

配置

编辑 include/config.h 以进行自定义设置：

WiFi 凭证
引脚分配
服务器端口
显示设置
传感器校准

使用方法

连接到 MCP 服务器

为 ESP32 CYD 开发板通电
连接到 WiFi 或使用接入点模式
在显示屏上找到设备 IP 地址
通过 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 中断事件

开发

添加新工具

在 include/tools/ 目录下创建头文件
在 src/tools/ 目录下实现功能
在 registerTools() 方法中注册工具
在 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 规范提供的协议设计思路

esp-cyd-mcp