# Windows-MCP 部署报告（NAS 上的 Windows 被控机）

- 部署日期：2026-10-07
- 被控机：NAS 上自建的 Windows Server 2022 虚拟机（QEMU/KVM）
- 目标：让 NAS 上的 Agent（Hermes / DSH / Codex）通过 MCP 远程控制 Windows 桌面
- 一句话结论：**已完成并通过端到端实测**。NAS 侧 MCP 客户端可以远程调用 Windows-MCP，获取桌面状态、打开应用、读取窗口/UI 元素、鼠标键盘操作、截图回传。

---

## 1. 安装状态

| 项 | 值 |
|---|---|
| 结果 | 成功（端到端已验证） |
| 项目 | CursorTouch/Windows-MCP（官方仓库 github.com/CursorTouch/Windows-MCP） |
| 版本 | windows-mcp **0.8.7**（PyPI 包版本，`uv tool list` 显示 `windows-mcp v0.8.7`） |
| 说明 | MCP 握手时服务自报 `windows-mcp 4.0.11 / proto 2025-11-25`，4.0.11 是底层 FastMCP 的版本号，不是本项目版本 |
| 安装方式 | 官方推荐的 uv 独立工具环境（`uv tool install windows-mcp`），非全局 pip、未改源码 |
| Python | **3.14.8**（uv 自动下载的 CPython；项目要求 `>=3.14`） |
| uv | 0.12.23 |
| 程序入口 | `C:\Users\mc\.local\bin\windows-mcp.exe`（shim） |
| 独立环境目录 | `C:\Users\mc\AppData\Roaming\uv\tools\windows-mcp\` |
| Python 解释器 | `C:\Users\mc\AppData\Roaming\uv\python\cpython-3.14.8-windows-x86_64-none\python.exe` |
| 配置文件 | `C:\Users\mc\.windows-mcp\config.toml`（transport / host / port / stateless_http / auth_key） |
| 启动器 | `C:\Users\mc\.windows-mcp\serve_launcher.py`（用 pythonw 静默运行并保留日志） |
| 服务日志 | `C:\Users\mc\.windows-mcp\server.log`、`server.error.log` |
| 启动命令 | `pythonw.exe C:\Users\mc\.windows-mcp\serve_launcher.py`（等价于 `windows-mcp serve --transport streamable-http --host 0.0.0.0 --port 8000`） |
| 实测依赖 | 92 个包由 uv 解析安装；截屏用 Pillow、UI Automation 用 comtypes + 内置 uia（详见第 5 节） |

前置检查实测结果：Windows Server 2022 Standard Evaluation（build 10.0.20348.1787，中文，桌面体验版）、x86_64、管理员权限可用、处于正常交互式桌面会话（session 1）、可截取桌面、Windows UI Automation 可用。

---

## 2. 被控虚拟机（宿主侧）

| 项 | 值 |
|---|---|
| 宿主 | NAS（fnOS/Linux），局域网 `192.168.1.38` |
| 虚拟机 | Windows Server 2022 中文评估版，桌面体验版（install.wim INDEX 2），计算机名 `mc-34v01h9bkf` |
| 账号 | 用户 `mc`，已配**永久自动登录**（注册表 AutoAdminLogon，非会过期的 AutoLogonCount） |
| 硬件 | 3 vCPU（`-cpu host`）、4096 MB、IDE 磁盘、e1000 网卡、std VGA |
| 显示 | `-vnc 127.0.0.1:8`（本机 5908，仅 127.0.0.1） |
| 磁盘 | `/mnt/ssd/winvm-mcp/win.qcow2`（qcow2，40G 上限，当前实占约 12G） |
| 网络 | QEMU user-mode NAT（客人机 10.0.2.15）；宿主端口转发 **127.0.0.1:18000 → 客人机 :8000**，另有 127.0.0.1:15985 → :5985（WinRM） |
| 开机自启 | `winvm-mcp.service`（systemd，**已 enable**，随 NAS 开机启动） |
| 掉线自恢复 | ①systemd `Restart=on-failure`；②宿主 cron 每分钟检查 `winvm-mcp` 与 `wmcp-netsvc`，掉了就拉起；③VM 内 `wmcp-watchdog` 计划任务每分钟探测 8000 端口，不通就重启 MCP 服务任务 |
| 监控通道 | `wmcp-netsvc.service`（8088 只读文件服务 / 8089 回传接收）+ VM 内 poller（20 秒轮询 `run.ps1` 执行，结果回传 `inbox/`） |

**已实测的自启链路**：2026-10-07 16:57 在客人机内执行干净重启 → 自动登录 → 登录时计划任务跑 bootstrap（`admin=True`）→ 重新注册无窗口服务任务 → 8:17 起 MCP 服务自动监听，全程无人干预，NAS 侧连接成功。

---

## 3. MCP 状态

| 项 | 值 |
|---|---|
| transport | **streamable-http**（本项目原生支持，非自写替代服务器） |
| 模式 | 无状态（`stateless_http = true`）：服务重启后客户端重连不需重新握手 |
| 其它支持的 transport | stdio、sse（本项目 0.8.7 三种都原生支持；本部署只启用了 streamable-http） |
| 服务监听（VM 内） | `0.0.0.0:8000`，MCP 端点 `/mcp/`，另有公开的 `/health` 探测路径 |
| **NAS 应该连的地址** | **`http://127.0.0.1:18000/mcp/`** |
| 认证 | 必须带 `Authorization: Bearer <auth-key>`，密钥 43 字符，由官方 `windows-mcp auth` 生成；无密钥返回 401 |
| 监听边界 | VM 内监听 0.0.0.0，但宿主只把 127.0.0.1:18000 转进去；**未暴露到公网**，也没开任何公网端口 |
| 额外防护 | VM 内 Windows 防火墙只放行来自 QEMU NAT 子网 `10.0.2.0/24`（即只有宿主能连）的 TCP 8000 |
| 启动命令（VM 内） | `pythonw.exe C:\Users\mc\.windows-mcp\serve_launcher.py` |
| 自启方式 | Windows 计划任务 `windows-mcp-server`：**登录时触发 + 交互式主体 + 无窗口（pythonw）**，非 Windows Service（服务模式拿不到交互式桌面，不能用） |

---

## 4. 已验证功能清单（逐项实测，非"能启动"）

全部通过 NAS 上的真实 MCP 客户端（`mcp` SDK，streamable-http）远程调用完成，工具名与官方一致。

| 工具 / 能力 | 结果 | 实测证据 |
|---|---|---|
| MCP 握手 initialize | ✅ | 服务返回 `windows-mcp / proto 2025-11-25` |
| tools/list | ✅ | 列出 **20** 个工具 |
| **Screenshot（截屏）** | ✅ | 回传真实 PNG（1024×768），肉眼可见记事本/服务器管理器/任务栏 |
| **Snapshot（桌面状态 + UI Automation 信息 + UI 元素）** | ✅ | 返回光标坐标、显示器、前台窗口、已开窗口列表，以及带坐标的可交互元素树（如 `(488,377) 编辑 "文本编辑器" [focused]`、菜单项 `文件(F)`、任务栏 `开始`/`时钟`） |
| **Mouse（鼠标）** | ✅ | `Click(488,377)`→"Single left clicked"；`Move(900,700)`→"Moved the mouse pointer" |
| **Keyboard（键盘）** | ✅ | `Type` 输入后**截图中出现 `HELLO-FROM-NAS-AGENT`**，记事本状态栏显示"第 1 行，第 21 列" |
| **Window（窗口）** | ✅ | `App(mode=switch)`→"Switched to 无标题 - 记事本 window"；Snapshot 能读出前后台窗口与句柄 |
| **Application（应用）** | ✅ | `App(mode=launch_executable)` 启动 `notepad.exe`，返回新进程 pid；随后读到它的完整 UI 树 |
| **PowerShell（命令执行）** | ✅ | 执行 `Get-Process` 并把标准输出回传（含 Status Code） |
| DisplayInventory | ✅ | 返回 `1024x768 / 96 DPI / scale 1.0 / primary` |
| Process | ✅ | `mode=list` 返回进程表（可见我们的 `pythonw.exe` 占 102.6 MB） |
| FileSystem | ✅ | `mode=list` 列出 `C:\Users\mc\.windows-mcp` 目录内容 |
| Clipboard | ✅ | `set` 后 `get` 回环一致（`wmcp-clip-test-123`） |
| 无 CMD 窗口下可用 | ✅ | 重启后服务以 pythonw 运行，桌面/进程列表中**没有任何 cmd.exe**，上述全部调用仍成功 |
| 未单独实测 | ⚠️ | Scroll、Shortcut、Wait、WaitFor、Scrape、MultiSelect、MultiEdit、Notification、Registry、Process(kill)、FileSystem(read/write/copy/move/delete) — 已注册可见，本次未逐个调用（测试中刻意不做危险/删除类操作） |

> 说明：`App(mode=launch, name="notepad")`（按开始菜单名启动）在中文系统下返回 `Notepad not found in start menu`——官方 README 已声明 App-Tool 依赖英文界面。改用 `launch_executable` 传完整路径即稳定可用。

---

## 5. 截屏后端说明（dxcam / DXGI 在本机不可用，已走官方内置等价实现）

本项目截屏是**自动降级链**：`dxcam(优先级10) → mss(20) → pillow(100)`。在被控机内实测：

```
dxcam_imported: True
backend dxcam    priority=10   available=False
backend mss      priority=20   available=False
backend pillow   priority=100  available=True
CAPTURE backend_used=pillow size=(1024, 768) mode=RGB
luminance min=0 max=255 mean=209.5 distinct=252
```

- **dxcam 的 DXGI 桌面复制在纯 QEMU 下不可用**（std VGA 走"Microsoft 基本显示适配器"，没有 WDDM/DXGI 桌面复制能力），`is_available()` 直接返回 False。
- mss 同样不可用。
- 实际生效的是**项目自带的 Pillow（ImageGrab / GDI BitBlt）后端**——这是官方内置的等价实现，**没有改源码、没有外挂替代方案**。
- 真实性校验：截到的帧灰度 0–255、252 个不同灰阶（不是黑帧/空帧），肉眼可见真实窗口内容；`_degraded_backends` 为空，服务端无任何截屏告警。
- 影响：GDI 截屏对普通窗口/控件完全够用；纯 QEMU 无 GPU 仍不适合视频/3D 画面（官方本身也声明不能用来玩游戏）。

---

## 6. NAS 侧 Agent 怎么接（详细可复制配置见 `NAS接入配置.md`）

- **连接地址**：`http://127.0.0.1:18000/mcp/`
- **认证**：HTTP 头 `Authorization: Bearer <key>`；密钥存放在 `/vol1/ai/windows-mcp/.mcp-key`（权限 600）
- **MCP JSON（streamable-http / 官方称 type:"http"）**：

```json
{
  "mcpServers": {
    "windows-mcp": {
      "type": "http",
      "url": "http://127.0.0.1:18000/mcp/",
      "headers": { "Authorization": "Bearer <见 .mcp-key>" }
    }
  }
}
```

- 支持 stdio 但**不支持**远程 HTTP 的客户端：用标准桥接（如 `npx -y mcp-remote http://127.0.0.1:18000/mcp/ --header "Authorization: Bearer <key>"`）即可，不必自写服务器。
- 自测命令（NAS 上现成可用）：

```bash
/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/windows-mcp/mcp_smoke.py list   # 列工具
/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/windows-mcp/mcp_smoke.py e2e    # 端到端演示
/vol1/ai/windows-mcp/.venv/bin/python /vol1/ai/windows-mcp/mcp_smoke.py input  # 鼠标键盘剪贴板
```

- 若以后要给别的机器用：优先走 Tailscale（NAS `100.114.191.104`）——把 QEMU hostfwd 的 hostaddr 从 127.0.0.1 换成该地址即可；**不要**为此开公网端口。

---

## 7. 遇到的问题

**已解决**

1. **uv 工具安装被中断后卡死**：上一轮被外部 SIGTERM 打断，留下 uv 锁 + 两个 uv 进程互相等锁（`Timeout (300s) when waiting for lock`），首次安装耗时约 12 分钟。→ 清理进程后重跑，`uv tool install exit=0`。
2. **config.toml 被写成带 BOM 的 UTF-8**：我最初用 `[IO.File]::WriteAllText` 注入 `stateless_http`，.NET 会写入 UTF-8 BOM，TOML 解析器把 BOM 当成语句的一部分 → 服务启动即退出（日志里只有一句 `Error: Invalid statement (at line 1, column 1)`）。→ 改用显式 `UTF8Encoding($false)` 重写，并把校验写进 bootstrap（用项目自带 Python 的 `tomllib` 验证通过）。
3. **宿主机 → 客人机连不通 8000**：服务确实在监听，但 NAS 侧超时。真因是 **Windows 防火墙丢弃了 NAT 进来的 SYN**（WinRM 5985 能通是因为系统自带放行规则）。→ 加放行规则，且限定源网段 `10.0.2.0/24`。
4. **管理通道（poller）会"假死"**：原 poller 的心跳 POST 没有超时、且脚本里有 `uv python list` 这种几分钟的慢命令，导致看起来像挂了。→ 重写 poller：每步都有超时、全程 try/catch、单实例保护、心跳先写后跑，并加了一个每分钟的兜底 tick 任务（实测这个兜底真的把通道救回来过）。
5. **脚本中文乱码**：给客人机的 PowerShell 脚本里写中文，PS 5.1 会把无 BOM 的 UTF-8 当 ANSI 读 → 匹配中文窗口标题失败。→ 客人机脚本一律纯 ASCII（并加了自动检查）。
6. **无窗口运行**：默认 `windows-mcp install` 生成的是 .cmd 包装，计划任务拉起会留一个 cmd 控制台窗口。→ 改成 `pythonw.exe + serve_launcher.py`（启动器先把 stdout/stderr 接到日志文件再进主程序），既无窗口又保留日志。
7. **干净重启被"关闭事件跟踪程序"拦住**：Windows Server 会拦无理由的关机/重启（早前发的 ACPI 关机请求就是被这个对话框挡住的）。→ 带原因执行 `shutdown /r /t 25 /f /d p:4:1 /c "..."`。

**临时方案 / 变通**

8. **请客机机没有 sudo 式提权**：客人机内的自动化脚本是非提权身份，改防火墙、注册计划任务这类操作会 `拒绝访问`。→ 用已注册的"最高权限"计划任务（wmcp-watchdog）当提权通道：把要执行的脚本放进 `%USERPROFILE%\wmcp\admin_req.ps1`，它每分钟会以管理员身份执行一次。
9. **键入长命令**：QEMU 监视器往"运行"框注入长命令会丢开头字符。→ 先用 Win+R 打开 cmd，再在控制台里输入；且所有复杂逻辑都放脚本、只敲一条短命令。

**未解决 / 官方项目限制**

10. `App` 工具"按开始菜单名启动"**依赖英文系统界面**（本项目 README 明说），中文 Windows 下会找不到。用 `launch_executable` 规避；若必须用 start-menu 名，官方给的路子是禁用 App-Tool 或改英文界面。
11. `dxcam`（DXGI 桌面复制）与 `mss` 在纯 QEMU std VGA 下**不可用**，只能用 Pillow/GDI 截屏（功能等价，已实测有效，见第 5 节）。
12. 无 3D 加速：不适合视频/游戏类画面（官方亦声明不能用于玩游戏）。
13. **WinRM（5985）**在客人机里是监听状态、宿主也能连到，但 `pywinrm` 用 NTLM 认证一直被服务端拒绝（`credentials were rejected`），没有深究——已有 poller 通道替代，不影响交付。留作以后可选的第二条管理通道。
14. `windows-mcp` 的 MCP 服务自报版本 4.0.11 与其 PyPI 包版本 0.8.7 不一致（前者是 FastMCP 的版本），排查时容易误判，已在此注明。

---

## 8. 运维手册（怎么用 / 怎么查 / 怎么安全关掉）

**先看它是否活着**

```bash
curl -s -o /dev/null -w '%{http_code}\n' http://127.0.0.1:18000/mcp/
# 401 = 在线（需要鉴权，正常）   000 = 不通
```

**看日志**

| 位置 | 内容 |
|---|---|
| VM 内 `C:\Users\mc\.windows-mcp\server.log` / `server.error.log` | MCP 服务自身日志（NAS 上可经 runner 或 VNC 读） |
| `journalctl -u winvm-mcp` | QEMU 虚拟机进程 |
| `journalctl -u wmcp-netsvc` | 文件/回传通道 |
| `/mnt/ssd/winvm-mcp/inbox/` | VM 回传的诊断/日志文件 |
| `/mnt/ssd/winvm-mcp/shots/` | 桌面截图（QEMU monitor） |

**给 VM 下发一次性脚本（不用碰鼠标键盘）**
把脚本写到 `/mnt/ssd/winvm-mcp/serve/run.ps1`（注意：客人机脚本要纯 ASCII），VM 内 poller 20 秒内拉取执行，输出 POST 到 `/mnt/ssd/winvm-mcp/inbox/`。心跳：`inbox/hb.log`。

**看受控机桌面**

```bash
/mnt/ssd/winvm-mcp/venv/bin/python /mnt/ssd/winvm-mcp/vmctl.py shot demo
# 截图落在 /mnt/ssd/winvm-mcp/shots/demo.png
```

**怎么安全关掉它（内存 4G）**

1. 先在 VM 内干净关机（否则下次开机 Windows 会弹"关闭事件跟踪程序"）：
   - 有 poller 通道时：在 `serve/run.ps1` 里写 `shutdown /s /t 10 /f /d p:4:1 /c "maintenance"`，等它执行；
   - 或直接在 VNC（127.0.0.1:5908）桌面上操作。
2. 再停宿主服务（**顺序不能反**，否则 cron 会在 1 分钟内把它拉起来）：

```bash
sudo systemctl stop winvm-mcp            # 停虚拟机
```

3. 若要长期停用（不再自动拉起），把 cron 里两行注释掉 / 删除，再 disable：

```bash
crontab -l             # 会看到 winvm-mcp / wmcp-netsvc 的两行保活
sudo systemctl disable --now winvm-mcp wmcp-netsvc
```

4. 只想省内存、又不想丢配置：`sudo systemctl stop winvm-mcp` 即可，配置全在 `win.qcow2` 里，下次 `start` 原样回来。

**重启虚拟机**

```bash
sudo systemctl restart winvm-mcp         # 需管理员权限；约 1~2 分钟自启完成
```

**磁盘/内存占用**：`win.qcow2` 实占约 12 G（上限 40 G）；运行时占 4 G 内存。NAS 内存 15 G，Minecraft 服务端已占约 3.3 G —— **不要再同时开第二台虚拟机**。

---

## 9. 交付物与工作目录

| 路径 | 说明 |
|---|---|
| `/vol1/ai/windows-mcp/部署报告.md` | 本文件 |
| `/vol1/ai/windows-mcp/NAS接入配置.md` | 可直接复制的接入配置（含真实密钥，权限 600） |
| `/vol1/ai/windows-mcp/.mcp-key` | MCP 鉴权密钥（权限 600，勿外传） |
| `/vol1/ai/windows-mcp/mcp_smoke.py` | NAS 侧 MCP 客户端自测脚本（list / e2e / input / call） |
| `/vol1/ai/windows-mcp/.venv/` | 自测用 Python 环境（含 `mcp` SDK） |
| `/vol1/ai/windows-mcp/evidence/` | 实测截图证据 |
| `/mnt/ssd/winvm-mcp/` | 宿主侧工作目录：`win.qcow2`、ISO、`vmctl.py`（监视器操作）、`netsvc.py`（文件通道）、`serve/`（下发给 VM 的脚本）、`inbox/`（VM 回传）、`shots/`（截图） |
| `/etc/systemd/system/winvm-mcp.service` | 虚拟机自启单元 |
| `/etc/systemd/system/wmcp-netsvc.service` | 文件通道单元 |

**硬约束遵守情况**：未改动/未停用 `minecraft-fc6`、`minecraft-dl`、`cloudflared-*`、`hermes-gateway`、`dsh`；未触碰 `/vol1` 存储池相关；未同时开第二台 QEMU；未把任何服务暴露到公网。
