Easycon MCP Service

EasyCon MCP服务

EasyCon MCP服务：用于Nintendo Switch通过串行（USB/UART）控制EasyCon协议的HTTP/JSON API。

此服务实现：

• 串行生命周期：列出端口、连接/断开连接、状态
• EasyCon握手：发送\[A5，A5，81\]并期待\[80\]
• 开关控制：按钮、D-Pad（HAT）、摇杆和重置
• 新：组合按钮、序列、宏、LED控制、控制器设置
• 新：批处理操作、健康监测
• 用于调试/扩展的原始发送/接收

需求

• Python 3.9+
• 一种使用EasyCon协议（115200 8N1）的串行设备

安装

pip install -r requirements.txt

跑

uvicorn mcp_service.server:app --host 0.0.0.0 --port 8000

api参考

连接管理

• 获取 /ports -列出可用串行端口
• 发布 /connect -连接到串行端口
• 发布 /disconnect -断开与串行端口的连接
• 获取 /status -获取连接状态
• 发布 /init -初始化设备（握手）

基本控制

• 发布 /press/button -按下一个按钮
• 发布 /press/hat -按D-Pad方向
• 发布 /stick -控制模拟棒
• 发布 /reset -发送重置命令

高级控制（新）

• 发布 /press/combo -同时按下多个按钮
• 发布 /sequence -重复执行一系列操作
• 发布 /batch -批量执行多个命令

宏观系统（新）

• 发布 /macro/save -保存宏
• 获取 /macro/list -列出所有已保存的宏
• 获取 /macro/{name} -获取宏详细信息
• 删除 /macro/{name} -删除宏
• 发布 /macro/execute -执行已保存的宏

设备控制（新）

• 发布 /led -控制装置LED（开/关）
• 获取 /version -获取固件版本
• 发布 /controller/mode -更改控制器模式（Pro/JoyCon）
• 发布 /controller/color -更改控制器颜色
• 发布 /unpair -从控制台上拔下控制器

公用事业

• 获取 /health -健康检查端点
• 获取 /buttons -列出所有可用按钮
• 获取 /directions -列出所有可用的HAT路线
• 发布 /raw/send -发送原始字节

例子

基本用法

# 1) List ports
curl http://localhost:8000/ports

# 2) Connect
curl -X POST http://localhost:8000/connect -H "Content-Type: application/json" \
     -d '{"port":"/dev/ttyUSB0","baud":115200}'

# 3) Handshake
curl -X POST http://localhost:8000/init

# 4) Press A for 50ms
curl -X POST http://localhost:8000/press/button -H "Content-Type: application/json" \
     -d '{"button":"A","durationMs":50}'

# 5) Reset
curl -X POST http://localhost:8000/reset

# 6) Disconnect
curl -X POST http://localhost:8000/disconnect

组合按钮

# Press A+B simultaneously for 100ms
curl -X POST http://localhost:8000/press/combo -H "Content-Type: application/json" \
     -d '{"buttons":["A","B"],"durationMs":100}'

# Press L+R (screenshot combo)
curl -X POST http://localhost:8000/press/combo -H "Content-Type: application/json" \
     -d '{"buttons":["L","R"],"durationMs":50}'

序列

# Execute a sequence: press A, wait, press B, repeat 3 times
curl -X POST http://localhost:8000/sequence -H "Content-Type: application/json" \
     -d '{
  "steps": [
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":100},
    {"type":"button","button":"B","durationMs":50}
  ],
  "repeatCount": 3
}'

宏

# Save a macro
curl -X POST http://localhost:8000/macro/save -H "Content-Type: application/json" \
     -d '{
  "name": "farm_berries",
  "steps": [
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":500},
    {"type":"button","button":"A","durationMs":50},
    {"type":"wait","durationMs":1000}
  ]
}'

# List macros
curl http://localhost:8000/macro/list

# Execute macro 10 times
curl -X POST http://localhost:8000/macro/execute -H "Content-Type: application/json" \
     -d '{"name":"farm_berries","repeatCount":10}'

# Delete macro
curl -X DELETE http://localhost:8000/macro/farm_berries

批量操作

# Execute multiple commands in one request
curl -X POST http://localhost:8000/batch -H "Content-Type: application/json" \
     -d '{
  "commands": [
    {"type":"button","button":"HOME","durationMs":100},
    {"type":"wait","durationMs":1000},
    {"type":"button","button":"A","durationMs":50},
    {"type":"combo","buttons":["A","B"],"durationMs":100}
  ]
}'

设备控制

# Turn LED on
curl -X POST http://localhost:8000/led -H "Content-Type: application/json" \
     -d '{"state":true}'

# Get firmware version
curl http://localhost:8000/version

# Change to Pro Controller mode
curl -X POST http://localhost:8000/controller/mode -H "Content-Type: application/json" \
     -d '{"mode":0}'

# Change controller color (red body, white buttons)
curl -X POST http://localhost:8000/controller/color -H "Content-Type: application/json" \
     -d '{"body_r":255,"body_g":0,"body_b":0,"button_r":255,"button_g":255,"button_b":255}'

公用事业

# Health check
curl http://localhost:8000/health

# List available buttons
curl http://localhost:8000/buttons

# List available directions
curl http://localhost:8000/directions

API文档

服务器运行后，请访问：

• Swagger用户界面: http://localhost:8000/docs
• ReDoc: http://localhost:8000/redoc

动作步骤类型

使用时 /sequence, /macro/save，或批处理操作，支持以下操作类型：

按钮名称

A、 B、X、Y、L、R、ZL、ZR、加号、减号、LCLICK、RCLICK、HOME、CAPTURE

方向名称

顶部、右顶部、右侧、右底部、底部、左底部、左侧、左顶部、中央

控制器模式

• 0：Pro控制器
• 1：Joy Con（左）
• 2：乔伊康（右）

备注

• 串行设置固定为115200 8N1。
• 每个媒体都会发出行动→ 等待 durationMs → 发送RESET。
• 握手将在发送之前清除过时的字节。
• 宏存储在内存中，将在服务器重新启动时丢失。
• 对于持久宏，可以考虑将它们保存到文件或数据库中。

许可证

麻省理工学院