3.6 KiB
3.6 KiB
ppclock-mcp · Windows 部署执行清单（熠管家协作版）
目标：把 ppclock-mcp 部署到蓝牙物理所在的 Windows 服务器，跑通 stdio 与 HTTP 两种接入实测。 约束：不动 8971 bridge 与该机任何既有服务；8972 防火墙仅局域网放行；测试期手动启动，不注册系统服务。
每步含验证命令与预期输出。全部步骤的文本输出/截图请留存，随回报发回。
0. 前置核对
python --version # 需 ≥3.10
- 蓝牙适配器在位（设备管理器可见）；NRF- 墨水屏设备在蓝牙范围内
- 记录设备 MAC（若已知，形如
18:BC:5A:5D:BF:28；不知也可，后续 scan 得到）
1. 取码
二选一：
git clone <仓库地址> C:\ppclock # 或把 Linux 侧源码压缩包拷贝解压到 C:\ppclock
cd C:\ppclock
git checkout main # 对应 tag v0.2.0-beta
git log --oneline -1 # 记录 commit，回报用
2. 环境
python -m venv .venv
.\.venv\Scripts\pip install -e ".[mcp]"
预期： bleak/pillow/mcp 1.x（<2）安装成功，无编译错误。
3. 冒烟（无设备）
.\.venv\Scripts\ppclock-mcp --help
预期：打印参数表，含 --transport/--host/--port/--mac/--connect-timeout/--idle-timeout/--allowed-hosts。
4. stdio 实测（本机 agent 直挂）
claude mcp add ppclock -- C:\ppclock\.venv\Scripts\ppclock-mcp.exe --mac <MAC>
（无 claude CLI 时可用任何支持 stdio MCP 的 agent；MAC 缺省则去掉 --mac，靠 scan。）
逐个调用并记录：
| 工具 | 参数 | 预期 |
|---|---|---|
| scan_devices | {} | ok=true，devices 含 NRF- 项 |
| device_status | {} | ok=true，connected=true，有 device_id |
| set_time | {"tz": 8} | ok=true |
| upload_image | {"source": "<一张图的路径>", "slot": 0} | ok=true，bytes_bw=15000 |
| set_mode | {"mode": "image0"} | ok=true，目视屏幕上屏 |
注意：设备长睡眠，首次调用可能守候至 90s（--connect-timeout）；连续调用应秒回（连接保持）。
5. HTTP 实测（局域网 agent 平台）
$env:PPCLOCK_MCP_TOKEN = "<随机长串>"
.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac <MAC> `
--allowed-hosts "192.168.61.35:8972,localhost:8972,127.0.0.1:8972" # 换成本机局域网地址；缺了 LAN Host 请求被 DNS 重绑定防护 421
另开终端：
curl -i -X POST http://127.0.0.1:8972/mcp -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-03-26","capabilities":{},"clientInfo":{"name":"t","version":"0"}}}'
# 预期：401 unauthorized（无 token）
curl -i -X POST http://127.0.0.1:8972/mcp -H "Authorization: Bearer <随机长串>" -H "Content-Type: application/json" -H "Accept: application/json, text/event-stream" -d '<同上 initialize>'
# 预期：200，body 含 serverInfo ppclock
从局域网另一台机重复带 token 的 initialize（确认 0.0.0.0 绑定与防火墙）。
6. 约束核对
- 8971 bridge 进程与端口未受影响：
netstat -ano | findstr 8971前后一致 - 既有服务清单未变；ppclock-mcp 仅占用 8972
- Windows 防火墙：8972 仅允许局域网子网（或暂不开 inbound，仅本机验证亦可，记录选择）
7. 回报格式
按步骤编号回报：每步实际命令输出（文本）、目视结果（上屏与否）、异常原文；结尾给结论：stdio ✅/❌、HTTP ✅/❌、约束核对 ✅/❌。