docs: Windows 部署执行清单（熠管家协作）

Co-Authored-By: Claude <noreply@anthropic.com>

tools/mcp_windows_deploy.md

@@ -0,0 +1,82 @@
+# ppclock-mcp · Windows 部署执行清单（熠管家协作版）
+
+目标：把 ppclock-mcp 部署到**蓝牙物理所在的 Windows 服务器**，跑通 stdio 与 HTTP 两种接入实测。
+约束：**不动** 8971 bridge 与该机任何既有服务；8972 防火墙仅局域网放行；测试期手动启动，不注册系统服务。
+
+> 每步含验证命令与预期输出。全部步骤的文本输出/截图请留存，随回报发回。
+
+## 0. 前置核对
+
+```powershell
+python --version          # 需 ≥3.10
+```
+- 蓝牙适配器在位（设备管理器可见）；NRF- 墨水屏设备在蓝牙范围内
+- 记录设备 MAC（若已知，形如 `18:BC:5A:5D:BF:28`；不知也可，后续 scan 得到）
+
+## 1. 取码
+
+二选一：
+```powershell
+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. 环境
+
+```powershell
+python -m venv .venv
+.\.venv\Scripts\pip install -e ".[mcp]"
+```
+预期： bleak/pillow/mcp 1.x（<2）安装成功，无编译错误。
+
+## 3. 冒烟（无设备）
+
+```powershell
+.\.venv\Scripts\ppclock-mcp --help
+```
+预期：打印参数表，含 `--transport/--host/--port/--mac/--connect-timeout/--idle-timeout`。
+
+## 4. stdio 实测（本机 agent 直挂）
+
+```powershell
+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 平台）
+
+```powershell
+$env:PPCLOCK_MCP_TOKEN = "<随机长串>"
+.\.venv\Scripts\ppclock-mcp --transport http --host 0.0.0.0 --port 8972 --mac <MAC>
+```
+另开终端：
+```powershell
+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 ✅/❌、约束核对 ✅/❌。