84 lines
3.6 KiB
Markdown
84 lines
3.6 KiB
Markdown
# 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 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 ✅/❌、约束核对 ✅/❌。
|