# @superpms/jarvis-remote-hand-mcp

让 AI agent 远程控制你名下的多台电脑执行系统命令的 MCP 服务。典型用途是同时排查、修复多台机器的网络等系统问题。

本服务**不自己登录**，它借用「远程控制助手」桌面端已有的登录态：agent → 本服务 → 桌面端 → MQTT → 目标设备。

## 前提

1. 一台机器运行着「远程控制助手」桌面端并已登录
2. 目标设备也运行着桌面端、登录**同一账号**、且在线
3. Node.js >= 20.19

## 配置

在你的 MCP client 配置中加入：

```json
{
  "mcpServers": {
    "jarvis-remote-hand": {
      "command": "npx",
      "args": ["-y", "@superpms/jarvis-remote-hand-mcp"],
      "env": {
        "ARH_BRIDGE_URL": "http://127.0.0.1:47890",
        "ARH_BRIDGE_TOKEN": "在桌面端「MCP 服务配置」页复制"
      }
    }
  }
}
```

### 环境变量

| 变量 | 必填 | 说明 |
|---|---|---|
| `ARH_BRIDGE_TOKEN` | 是 | 访问令牌，在桌面端「MCP 服务配置」页复制。**持久有效，重启桌面端不变**，只在该页点「重置」后需重新填写 |
| `ARH_BRIDGE_URL` | 否 | 桌面端地址，默认 `http://127.0.0.1:47890`。桌面端在局域网另一台机器上时改成那台的地址，如 `http://192.168.1.20:47890` |

### 关于访问令牌

桥接接口等同于已登录设备的 shell 代理，且监听局域网以便跨机使用，因此服务端强制校验令牌。令牌存在桌面端的应用数据目录里，重启不变；要作废旧令牌就在「MCP 服务配置」页点「重置」，之后所有 agent 的配置都要改成新值。

`health` 是唯一不校验令牌的接口 —— 它存在的意义就是在令牌还没配对时也能回答"桥接到底在不在跑"，因此只回一个固定的 `{"ok":true}`，不带任何其他信息。

跨机访问还需目标机器的防火墙放通 `47890` 端口。

## 工具

| 工具 | 说明 |
|---|---|
| `health` | 检查桥接服务是否可用，不需要令牌。排查连接问题时先用它 |
| `list_devices` | 列出同账号设备及在线状态，取得 `device_uuid` |
| `send_command` | 下发命令，**立即返回 `mid`，不等执行完** |
| `query_mid` | 按 `mid` 查状态与结果 |
| `query_device_status` | 查某台设备的实时在线状态 |

`send_command` 的 `tool` 参数按目标设备平台选择：`bash`（macOS/Linux）、`cmd` 或 `pws`（Windows）。

## 使用流程

1. `list_devices` 取得在线设备的 `device_uuid`
2. `send_command` 下发，拿到 `mid`
3. `query_mid` 轮询直到 `state` 为「已完成」，读 `result`

`state` 依次经过 `发送中 → 排队中 → 运行中 → 已完成`。被控端按收到顺序逐条执行，同一时刻只跑一条。

终态只有 `已完成` 与 `已中断` 两个，见到任一个即停止轮询。`已中断` 表示目标设备在执行期间离线，命令结果无法确认 —— 可能没跑、跑了一半、也可能跑完了只是结果传不回来。这是**唯一**不依赖被控端回报的状态推进途径：没有它，被控端进程被杀、断网或假死后，任务会永久停在 `运行中`，调用方只能无下限轮询一个永远不变的状态。

判定依据是设备离线，不是执行时长 —— 按时长判失败会误杀正常的长命令。

**命令执行不设超时**，几分钟到十几分钟都属正常（如网络重置、批量安装）。轮询到「运行中」请间隔几秒继续，不要判定失败或重复下发。

设备离线或不属于当前账号时，`send_command` 直接报错说明原因，不会返回一个永远没有结果的 `mid`。

## 安全说明

本服务转发的请求可在你已登录的设备上执行任意系统命令。请仅在可信网络中使用，不要将 `47890` 端口暴露到公网，也不要把访问令牌贴到公开位置。

## License

MIT