@superpms/jarvis-remote-hand-mcp

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

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

前提

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

配置

在你的 MCP client 配置中加入：

{
  "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