@superpms/jarvis-remote-hand-mcp

AI 에이전트가 귀하 명의의 여러 대의 컴퓨터를 원격으로 제어하여 시스템 명령을 실행할 수 있게 해주는 MCP 서비스입니다. 대표적인 용도는 여러 대의 머신에서 네트워크 등 시스템 문제를 동시에 진단하고 복구하는 것입니다.

본 서비스는 자체적으로 로그인하지 않습니다. 「원격 제어 도우미」 데스크톱 클라이언트의 기존 로그인 상태를 활용합니다: agent → 본 서비스 → 데스크톱 클라이언트 → MQTT → 대상 장치.

전제 조건

1. 한 대의 머신에서 「원격 제어 도우미」 데스크톱 클라이언트가 실행 중이고 로그인되어 있어야 합니다

2. 대상 장치도 데스크톱 클라이언트가 실행 중이고, 동일한 계정으로 로그인되어 있으며, 온라인 상태여야 합니다

3. Node.js >= 20.19

Related MCP server: mcp-windows-server

구성

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 服务配置」页复制"
      }
    }
  }
}

환경 변수

액세스 토큰 정보

브리지 인터페이스는 로그인된 장치의 셸 프록시와 동일하며, LAN을 통해 크로스 머신 사용이 가능하도록 수신 대기하므로 서버는 토큰 검증을 강제합니다. 토큰은 데스크톱 클라이언트의 애플리케이션 데이터 디렉터리에 저장되며 재시작해도 변경되지 않습니다. 기존 토큰을 폐기하려면 「MCP 서비스 구성」 페이지에서 「재설정」을 클릭하면 되며, 이후 모든 agent의 구성을 새 값으로 변경해야 합니다.

health는 토큰 검증이 없는 유일한 인터페이스입니다. 토큰이 아직 페어링되지 않은 상태에서도 "브리지가 실제로 실행 중인지"에 답할 수 있도록 존재하며, 고정된 {"ok":true}만 반환하고 다른 정보는 포함하지 않습니다.

크로스 머신 접근을 위해서는 대상 머신의 방화벽에서 47890 포트를 허용해야 합니다.

도구

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