qianbian/tools/mcp_windows_deploy.md

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 feat/ppclock-mcp        # 分支合并 main 后此步改为 git checkout main
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。

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>

另开终端：

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 ✅/❌、约束核对 ✅/❌。