remote-bridge

RemoteBridge 🌉

一款安全、可配置的 MCP 工具，让 AI Agent 能够可靠地访问远程服务。

RemoteBridge 是一个 Rust 命令行工具和 MCP 服务，用于 AI 辅助的远程工作流。它使用 rsync 同步本地代码，通过 SSH 运行远程命令，收集日志和诊断信息、比较环境，并将这些功能通过一组精简的工具直接提供给 AI 使用。

如果你希望 Claude Code、Cursor、Windsurf、Codex 或其他支持 MCP 的工具中的 AI Agent 能够结合实际运行上下文，而不只是面对一个 Shell 提示符来操作远程机器，就可以使用它。

RemoteBridge 不会让模型猜测服务器的配置，而是为它提供一个配置好的运维接口。

RemoteBridge 能帮助 AI 了解什么

AI 在远程机器上调试或部署时，需要的不只是“运行这条命令”。

它还需要了解：

• 应用部署在哪里
• 如何重启服务
• 哪些日志文件很重要
• 安装了哪些运行时
• 服务是否正常
• 正在监听哪些端口
• 是否存在磁盘或内存压力
• 预发布环境与生产环境有何不同
• 允许执行哪些命令，哪些命令有风险

RemoteBridge 会将这些常见的服务器信息保存在 remotebridge.yaml 中，并将实用工作流作为 MCP 工具提供。

这样，AI 就能把远程服务当作一个可以理解的系统来操作，而不只是一个可以运行命令的地方。

这实际上解决了什么问题

如果没有结构化的工具层，AI 执行远程操作通常会变成一连串冗长的 Shell 步骤：

• 找到正确的主机
• 找到部署路径
• 检查运行时
• 找到重启命令
• 找到日志
• 输出过多内容
• 询问更多问题以恢复上下文

RemoteBridge 将这些步骤整合为一组更精简、可复用、意图更明确且默认配置更完善的操作。

AI 可以调用：

• sync_to_remote
• deploy
• preflight_check
• fetch_logs
• diagnose_failure
• compare_targets

这些工具旨在帮助 AI 检查和分析远程系统，而不仅仅是在其上执行命令。

例如，diagnose_failure 可以在一条精简的响应中收集：

• 运行时信息
• 服务管理器状态
• 最近的日志
• 监听端口
• 磁盘状态
• 内存状态
• 可能的故障特征

关于直接使用 SSH 的简要说明

以下情况仍然适合通过 AI 工具直接使用 SSH：

• 你需要完全交互式的 Shell。
• 你已经知道要执行的确切命令。
• 你想临时进行一次性探索。
• 你要紧急执行一次性命令，并且需要原始终端行为。

以下情况更适合使用 RemoteBridge：

• 由 AI 驱动工作流。
• 相同的服务器信息总是被反复查找。
• 你希望部署、重启、诊断和日志工作流可以重复执行。
• 你需要为破坏性命令设置防护措施。
• 你希望获得精简的回答，而不是完整的 Shell 会话记录。
• 你希望执行“比较预发布环境和生产环境”这类了解配置的操作。

RemoteBridge 在实际使用中的不同之处

RemoteBridge 并非通过隐藏 SSH 来提升体验，而是将重复的基础设施分析转化为稳定、可复用的工具行为。

与直接使用 SSH 相比，具体差异如下：

• 服务器路径只需在 remotebridge.yaml 中配置一次，之后每次调用都会复用。
• 重启命令只需配置一次，无需再次查找或重新输入。
• 日志文件只需配置一次，无需让模型四处寻找。
• 模型可以按意图调用 deploy、diagnose_failure 和 compare_targets 等操作。
• 输出经过刻意限制，让模型获取关键信息，而不是被日志淹没。
• 可以要求确认、阻止危险命令，或将其加入允许列表。
• 本地代码变更和远程执行属于同一个工作流，而不是两个互不关联的步骤。

因此，即使 AI Agent 已经支持远程访问，RemoteBridge 通常也比在 AI Agent 中直接使用原始 Shell 更实用。

为什么它在实践中能节省 Token

当 RemoteBridge 减少模型与服务之间低价值的对话时，它就很有用。

它通过几种具体方式节省 Token：

• run_remote_command 会将合并后的 stdout 和 stderr 截断到共同的行数上限，让模型获取重要的末尾内容，而不是完整记录。
• preflight_check 通过一次远程调用收集操作系统和运行时信息，而不必让 AI 执行多个单独的 shell 命令。
• fetch_logs 会在一次结构化响应中提取已配置的日志文件，而不必让 AI 反复询问日志位置，再手动逐个查看文件末尾。
• diagnose_failure 会一次性收集服务状态、监听器、磁盘、内存、运行时信息和近期日志，然后总结可能的原因。
• compare_targets 将“SSH 登录 staging、SSH 登录 prod、检查两者、在脑中比较差异”变成一次语义化工具调用。
• deploy 和 restart_service 省去了每次都让 AI 重新陈述 cd /path && ... 之类 shell 命令组合的需要。
• remote_path、restart_cmd、logs、allowed_commands 和 blocked_patterns 等配置值只需保存一次，就能在每次调用时重复使用。

重点不只是“减少 SSH 命令”，还包括：

• 减少围绕相同基础设施信息反复推理
• 减少模型需要阅读的输出
• 减少因 shell 输出嘈杂而产生的后续提示词

为什么这比让 AI 随意编写 Shell 命令更好

原始 SSH 赋予 AI 很多权限，却几乎不提供结构。

RemoteBridge 提供：

• 配置感知：目标主机、部署路径、重启命令和日志路径都保存在 remotebridge.yaml 中。
• 运维语义：deploy、diagnose_failure 和 compare_targets 等工具描述的是意图，而不只是 shell 语法。
• 更安全的默认设置：危险命令可以要求确认、完全禁止，或限制为允许列表中的前缀。
• 更好的输出规范：MCP 接口返回精简且有用的输出，而不是倾倒所有内容。
• 本地与远程协作：将本地文件同步到远程服务属于同一工作流的一部分，而不是单独的手动步骤。

最后一点很重要。单独使用远程 shell 无法查看你本地尚未提交的代码。RemoteBridge 可以准确同步 AI 在本地修改的内容，然后执行依赖这些内容的远程步骤。

核心价值

RemoteBridge 并不打算在 shell 能力上胜过 SSH。

它旨在为 AI Agent 提供比以下流程更好的抽象：

1. 猜测主机
2. 猜测路径
3. 猜测服务管理器
4. 猜测日志位置
5. 倾倒过多输出
6. 再试一次

为什么我们用 Rust 构建它

RemoteBridge 本可以用 Node.js 或 Python 编写。我们选择 Rust，是出于与该工具用途相关的实际考虑。

Rust 在这里很有优势，因为它：

• 可以生成启动速度快的单个原生二进制文件，适用于 CLI 和 stdio MCP 使用场景
• 无需用户在执行时管理 Python 运行时或更庞大的 JS 运行时环境
• 非常适合处理 ssh、rsync、日志流和 MCP stdio 等进程密集型、I/O 密集型工具
• 能在编译时对错误处理和数据流提供强保证，这对部署和远程执行工具很重要
• 在重复工具调用时通常具备可预测的性能和较低的开销

具体到这个项目，这意味着：

• MCP 客户端启动服务时速度更快
• CLI 的打包摩擦更少，用户可以快速安装并立即使用
• 原生二进制文件非常适合封装 ssh 和 rsync 等系统工具
• 与大型脚本运行时环境相比，运行时依赖问题的风险面更小

Node.js 或 Python 也能胜任。对于一款旨在成为 AI 客户端与远程基础设施之间可靠系统桥梁的工具，Rust 是更合适的选择。

功能特性

功能	重要性
Rsync 同步	将本地代码推送到服务端，无需重新上传所有内容
SSH 多路复用	在重复的同步和命令调用中复用 OpenSSH 控制连接
结构化 MCP 工具	让 AI 调用语义化操作，而不是每次都拼接 shell 字符串
输出截断	将命令响应控制在较小范围内，确保在模型上下文中仍然实用
预检	一步收集运行时信息
部署流水线	将同步 → 重启 → 失败日志流程整合为一个操作
故障诊断	将服务状态、运行时信息、监听器、磁盘、内存和日志汇总为一份简洁摘要
目标对比	显示不同环境间的配置差异和运行时差异
安全防护	通过确认、硬性拦截和允许列表，减少破坏性错误
审计日志	记录实际运行的内容及其退出状态
监视模式	在编辑/测试循环中保持远程目标同步
按目标配置 SSH	支持为每个环境单独设置主机、用户、路径、端口和密钥

实用示例

如果没有 RemoteBridge，AI 在调试失败的部署时，通常会这样做：

1. 通过 SSH 登录。
2. 查询 pwd。
3. 查询 ls。
4. 尝试查找应用路径。
5. 猜测如何重启服务。
6. 查询日志。
7. 拉取过多输出。
8. 因为输出杂乱而继续追问。

使用 RemoteBridge 后，可以这样提出同样的请求：

你：“暂存环境的部署出了问题。请诊断。”

AI 可以调用 diagnose_failure，并获取：

• 目标身份
• 推断出的服务管理器
• 服务健康状态
• 运行时版本
• 磁盘或内存压力信号
• 相关日志摘录
• 可能的原因
• 后续步骤建议

相比多轮 shell 对话记录，这样能更好地利用上下文。

快速开始

1. 安装

前置条件：Rust、rsync 和 ssh 均可在 PATH 中使用。

npm install -g remote-bridge-cli

2. 将 MCP 服务添加到你的 AI 工具中

claude mcp add remote-bridge --scope user -- remote-bridge mcp

其他工具请参阅下文的 MCP 支持。

3. 初始化项目配置

remote-bridge init --name my-app -H your-server.com --user ubuntu --path /var/www/app

这会创建 remotebridge.yaml，作为 AI 工作流的共享事实来源。

配置示例

project_name: "my-app"
targets:
  staging:
    host: "13.234.xx.xx"
    user: "ubuntu"
    remote_path: "/var/www/html/app"
    port: 22
    ssh_key: "~/.ssh/id_rsa"
    restart_cmd: "pm2 restart app"
    logs:
      - "/var/www/html/app/logs/error.log"
      - "/var/log/nginx/error.log"
    require_confirmation: false
    exclude:
      - "node_modules/"
      - "*.log"
    blocked_patterns:
      - "rm -rf"
      - "drop table"
    allowed_commands:
      - "npm"
      - "pm2"
    audit_log: "~/.remote-bridge-staging.log"
  production:
    host: "prod.example.com"
    user: "ubuntu"
    remote_path: "/opt/app"
    ssh_key: "~/keys/prod.pem"
    restart_cmd: "systemctl restart myapp"
    logs:
      - "/opt/app/logs/error.log"
    require_confirmation: true

remotebridge.yaml 的重要性

这个文件正是 MCP 工具比原始 SSH 更实用的原因。

它会存储 AI 无需重新发现的信息：

• 应用所在位置
• 重启方式
• 需要关注的日志
• 安全的命令
• 需要更严格确认的环境

这些信息只需编码一次，之后每次工具调用都会更简单、更省力。

CLI 命令

命令	描述
init	创建新的 remotebridge.yaml
sync	将本地文件同步到远程服务
sync --dry-run	预览 rsync 变更，不会触及服务
run <cmd>	执行一条远程命令
preflight	收集远程操作系统和运行时版本
logs	获取最近的已配置日志
logs --follow	实时流式传输已配置日志
restart	重启已配置的服务
deploy	同步、重启；若重启失败，则获取故障上下文
watch	监视本地文件，并在变更时自动同步
apply	解析 AI 输出中的 Markdown，并应用文件变更和 shell 命令

与 AI CLI 集成

RemoteBridge 也支持管道操作。

Claude Code

claude "Fix the database connection in src/db.ts and restart the app" --non-interactive \
  | remote-bridge apply --target staging

Gemini CLI

gemini "Add rate limiting to the Express API" \
  | remote-bridge apply --target staging

Aider

aider --message "Refactor the login logic" --apply \
  | remote-bridge apply --target staging

MCP 支持

RemoteBridge 是原生 MCP 服务。任何兼容 MCP 的 AI IDE 都可以使用它。

可用的 MCP 工具

工具	实际价值
sync_to_remote	从同一 AI 会话将本地代码推送到服务器
run_remote_command	运行输出受限的远程 Shell 命令
preflight_check	在一条简洁的响应中获取运行时信息
fetch_logs	拉取已配置的日志，无需重新查找路径
restart_service	安全地复用已配置的重启命令
deploy	一次性运行标准远程部署流程
diagnose_failure	收集并概述故障上下文，而不是直接输出原始 Shell 调试信息
compare_targets	使用配置和实时运行时信息比较环境

这些工具如何帮助 AI 做得比直接使用 SSH 更好

diagnose_failure 是最明显的例子。

使用原始 SSH 的 Agent 必须判断：

• 存在哪种服务管理器
• 如何检查它
• 要读取哪些日志
• 要查看多少行
• 磁盘、内存或端口状态是否可能相关
• 哪些行可能是关键信息，哪些只是噪声

diagnose_failure 将这套调查流程整合为一次操作。

compare_targets 是另一个例子。SSH 一次只能检查一台服务器。此工具会比较：

• 主机、路径和配置差异
• 确认策略偏差
• 服务管理器差异
• 运行时版本差异
• 高层兼容性风险

使用 SSH 并非无法做到这些，只是对 AI 来说成本高，而且重复繁琐。

请求示例

在启用了 MCP 的 IDE 中，你可以说：

• “将我当前的项目同步到 staging。”
• “将最新的本地更改部署到 staging。”
• “检查 production 上安装了哪些运行时。”
• “部署后应用出现故障。诊断 staging。”
• “比较 staging 和 production，并告诉我运行时偏差是否可能导致这个 Bug。”
• “显示 production 最近 100 行日志。”

MCP 配置示例

Claude Desktop

文件：~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Cursor

文件：~/.cursor/mcp.json 或 .cursor/mcp.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

VS Code / Cline / Continue / Copilot 兼容的 MCP 客户端

{
  "servers": {
    "remote-bridge": {
      "type": "stdio",
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

Codex CLI

文件：~/.codex/config.json

{
  "mcpServers": {
    "remote-bridge": {
      "command": "remote-bridge",
      "args": ["mcp"]
    }
  }
}

或者以内联方式配置：

codex --mcp-server "remote-bridge mcp" "Diagnose the staging deploy failure"

通用 MCP 模式

{
  "command": "remote-bridge",
  "args": ["mcp"],
  "transport": "stdio"
}

SSH 身份验证

RemoteBridge 使用你现有的 SSH 配置。

1. 将密钥复制到服务器：

   ssh-copy-id -i ~/.ssh/id_rsa.pub [email protected]
   

2. 或在配置中指定密钥和端口：

   targets:
     staging:
       host: "13.234.xx.xx"
       user: "ubuntu"
       port: 2222
       ssh_key: "~/keys/staging.pem"
   

3. 或使用 ~/.ssh/config 中的别名：

   Host staging-server
       HostName 13.234.xx.xx
       User ubuntu
       IdentityFile ~/keys/my-key.pem
       Port 22
   

   然后将 host 指向该别名：

   targets:
     staging:
       host: "staging-server"
       user: "ubuntu"
   

安全模型

RemoteBridge 专为 AI 驱动的执行而设计，因此安全性不可或缺。

确认关卡

包含 sudo、rm、drop、delete、shutdown、reboot、killall、curl | bash 等风险模式及类似破坏性序列的命令，必须在执行前确认。

硬性拦截

blocked_patterns 中的任何内容都会被拒绝：

targets:
  production:
    blocked_patterns:
      - "rm -rf"
      - "drop table"
      - "truncate"

允许列表

如果设置了 allowed_commands，则只允许匹配的前缀：

targets:
  production:
    allowed_commands:
      - "npm"
      - "pm2"
      - "systemctl restart myapp"

审计日志

每条命令都会自动记录：

[1742660591] host=your-server.com path=/var/www/app exit=0 cmd=npm install
[1742660612] host=your-server.com path=/var/www/app exit=-2 cmd=rm -rf /var/data

退出代码：

• 0+ 实际进程退出代码
• -1 用户跳过
• -2 被硬性拦截
• -3 不在允许列表中

其他保护措施

• 对于敏感目标，require_confirmation: true 可强制要求每条命令都经过确认。
• sync --dry-run 会预览同步前后的更改。
• RemoteBridge 不存储密码。
• 无需将机密信息放在 remotebridge.yaml 中。
• MCP 输出长度受到限制，避免单条嘈杂的命令淹没模型上下文。

坦诚说明取舍

如果你需要原始终端，请使用 SSH。

如果你希望 AI 能可靠地处理远程基础设施，避免反复耗费令牌来重新发现信息、拼接 Shell 命令和处理嘈杂输出，请使用 RemoteBridge。

这就是它的价值所在。

参与贡献

欢迎通过 GitHub Issues 提交贡献和问题。

许可证

MIT 许可证。