📖 English version → README.en.md

---

⚠️ 免责声明：AI 生成

本项目（含 agent.py、server.py、测试与全部文档）由 DeepSeek 生成，属 AI 辅助编写，尚未经过独立的人工安全审查。 使用前请自行审查代码、测试与安全相关逻辑；作者不对其正确性、安全性或适用性作任何保证。

---

remote-mcp

一个 MCP（Model Context Protocol）服务器，用于在远程机器上执行操作。远程机器上只需跑一个零依赖（仅标准库）的 HTTP 守护进程 agent.py。支持 Linux 和 Windows，特别适合没有 SSH / WinRM / SMB 可用的场景——比如一台密码空白的 Windows 机器，账户和注册表都不能动，只能靠用户态 HTTP 守护进程 + 自带 token 来访问。

Claude Code (MCP 客户端)
   │  stdio
   ▼
server.py (本地)  ── HTTP（JSON / NDJSON / 原始字节流，Bearer token 鉴权）──▶  agent.py (远端)

agent.py 是单个自包含 Python 文件，拷到目标机器上直接 python agent.py 就能跑，除标准库外无需任何依赖。它通过一个很小的 REST API 把所有能力暴露给 MCP 服务器：文件读/写/改、一次性命令、持久 PTY shell 会话、带 sha256 端到端校验的大文件流式传输、后台进程管理。

---

工具清单（14 个）

全部以 remote_ 开头：

工具	作用
remote_hosts	列出已配置主机 + 当前 active 主机
remote_read / remote_write	读写远端文本文件（write 上限 8 MiB）
remote_edit	在远端文件上做精确字符串替换
remote_bash	一次性命令（Windows 默认 cmd.exe）
remote_shell_exec	持久 PTY 会话；cd/环境变量/REPL 状态跨调用保留，惰性建会话，agent 重启后自动重连（404/410）
remote_shell	会话管理：list/peek/close/input/interrupt/resize/relabel
remote_upload / remote_download	大文件流式传输，sha256 端到端校验
remote_env	远端平台 / shell / 工具快照——开始干活前先跑这个
remote_spawn / remote_proclist / remote_kill	后台进程管理（spawn 必须给 stdout 文件路径，否则输出丢弃）
remote_shutdown	关掉远端 agent 自身（仅热重载用，慎用）

---

安装与使用

1. 安装 server（在你跑 Claude Code 的那台机器上）：

pip install -r requirements.txt   # 需要 Python 3.10+；mcp 锁在 <2.0（2.0 删了 FastMCP）

2. 在目标机器上跑 agent（只需 Python 3.10+，标准库，不用装任何依赖）：

python agent.py                  # 默认绑定 0.0.0.0:7777；可用 --host/--port 改

它会把自己的 token 写到脚本旁边的 agent.token 文件（或设环境变量 REMOTE_AGENT_TOKEN）。这个 token 要填进下面的配置里。

3. 配置主机（在跑 server 的机器上）：

默认路径：~/.config/remote-agent-mcp/hosts.json

{
  "hosts": {
    "win188": { "url": "http://192.168.88.188:7777", "token": "…", "cwd": "C:\\Users\\me", "platform": "win32" },
    "linux":  { "url": "http://10.0.0.5:7777",       "token": "…", "cwd": "/home/me",  "platform": "linux" }
  },
  "active": "win188"
}

4. 注册到 Claude Code：

claude mcp add --scope user remote-mcp -- python /path/to/server.py
claude mcp list

可选参数 / 环境变量

• --config <路径> — 配置文件（默认 ~/.config/remote-agent-mcp/hosts.json）。此格式与 pi 编码代理的 ~/.pi/remote-hosts.json 兼容，所以 --config ~/.pi/remote-hosts.json 可以让两个工具共享同一份配置。
• --host <别名> — 默认主机，覆盖配置里的 active。
• REMOTE_AGENT_CONFIG — 环境变量覆盖配置路径。
• REMOTE_AGENT_HOST — 环境变量覆盖默认主机（优先级：显式 host= 参数 > 环境变量 > 配置 active）。
• REMOTE_AGENT_TOKEN — 覆盖 agent 的 token（旧名 PI_REMOTE_AGENT_TOKEN 仍兼容）。

---

设计约束

• 显式优先于隐式（explicit over implicit）。 工具都以 remote_* 命名，让模型明确知道这次调用是打到远端去的；本地工具永远不会被偷偷重定向。
• 路径原样直发，不做本地↔远端的路径映射。先用 remote_env 了解远端的 cwd / 平台 / shell。
• Windows 远端默认 cmd.exe，不是 bash。
• 会话缓存在内存里（server 重启即丢）。agent.py 重启后，remote_shell_exec 靠 404/410 重试自动恢复。
• 大文件走 upload/download。 remote_write 上限 8 MiB（JSON 里 base64 膨胀所致）；upload 流式传输并端到端校验 sha256。

---

测试

tests/ 下有一个本地 mock agent（完整镜像 agent.py 的协议），无需真实远端即可跑全套测试：

python tests/test_server.py        # 37 条断言，打本地 mock
python tests/test_mcp_protocol.py  # 真实 MCP stdio 客户端 → server → mock agent 的端到端

mock 复刻了 agent.py 的真实坑，包括 /exec 响应体里手工拼的 HTTP 式 chunk 帧，确保解析器在忠实的输出下也被验证到。

---

安全

• token 以明文存在 hosts 文件里（与 pi agent 同设计）。server 跑在本机、同信任域；agent 默认绑定 0.0.0.0，如果远端暴露在外网请用防火墙或隧道包起来。
• remote_shutdown 会真的停掉远端 agent，只在热重载时用。
• 除 /ping 外，agent.py 对所有端点强制 Bearer token。

---

许可证

MIT。agent.py 是 pi 编码代理项目里 remote-execution agent 的去 pi 化衍生品——来源见 NOTICE。