# ppclock-mcp · Windows 部署执行清单（熠管家协作版）

> 时点件（2026-07-30 测试期清单）。现行部署形态以 docs/sdk/MCP.md §常驻部署 为准。

目标：把 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 main                    # 对应 tag v0.2.0-beta
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/--allowed-hosts`。

## 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> `
    --allowed-hosts "192.168.61.35:8972,localhost:8972,127.0.0.1:8972"   # 换成本机局域网地址；缺了 LAN Host 请求被 DNS 重绑定防护 421
```
另开终端：
```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 ✅/❌、约束核对 ✅/❌。