Allows running and interacting with TTY programs on the remote host via tmux sessions, including creating sessions and capturing pane output.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@ssh-remote run the test suite on the remote machine and show me the last 20 lines"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
常驻 SSH 长连接的 MCP server。让 WorkBuddy / Cursor 这类 AI 编码工具直接读写远端机器、执行远端命令，而不是每次调用都新建一次 SSH 连接。
装上之后的效果，和「本地连上远程开发机干活」基本一致：搜代码、读文件、改文件、跑命令、跑长任务、TTY 交互，都在远端原生环境里完成。
Windows 上每次 ssh host "cmd" 的开销拆开看：
环节 | 耗时 |
创建新进程（疑似杀软实时扫描） | ~480ms |
SSH 握手 | ~420ms |
网络往返（局域网 <1ms） | 可忽略 |
也就是说真正的命令执行时间被开销完全淹没了。而 Windows 上两个 ssh 实现都不支持连接复用：
Git-MSYS：mux_client_request_session: read from master failed: Connection reset by peer
Win32-OpenSSH：getsockname failed: Not a socket
所以 ~/.ssh/config 里配 ControlMaster 是没用的。
本项目的解法：绕开 multiplexing，改成一个常驻 Node 进程 hold 住一条 ssh2 连接，通过 MCP 暴露工具。调用时不创建进程、不重新握手。
Related MCP server: remote-shell-mcp
同刻对照，Windows 本机：
方式 | 一次典型四步信息收集¹ |
| 3339ms |
本 MCP（4 次工具调用） | 177ms |
约 19 倍。单次调用：ssh 稳定 825ms，本MCP exec 50ms / search 52ms / list 82ms / read 8ms / stat 3ms。
¹ git 状态 + 代码搜索 + 读文件 + 健康检查
长连接会发心跳（15s × 3 次容错），跑完6 分钟的全量测试后健康检查仍是 14ms。首连含建连226ms，属一次性成本。
npm install在 MCP 客户端的配置里注册（WorkBuddy 是 ~/.workbuddy/mcp.json）：
{
"mcpServers": {
"ssh-remote": {
"command": "node",
"args": ["<绝对路径>/ssh-remote/server.js"],
"env": {
"SSH_REMOTE_HOST": "192.168.0.110",
"SSH_REMOTE_USER": "yourname",
"SSH_REMOTE_BASE": "/home/yourname/work/yourproject"
}
}
}
}必填 SSH_REMOTE_HOST / SSH_REMOTE_USER / SSH_REMOTE_BASE；不填会在启动时直接报错并告诉你怎么配，而不是拿着空主机名去连、报一堆看不懂的 ssh 错误。
新 server 需要在客户端的连接器管理里 Trust，并重启客户端才会加载。
在 Git Bash 里手动跑验证脚本时，MSYS 会把环境变量值里的 Unix 路径改写成 Windows 路径：
# ✗ SSH_REMOTE_BASE 传进 node 后变成了 C:/Program Files/Git/home/... → "No such file"
SSH_REMOTE_BASE=/home/me/proj node smoke-test.js
# ✓
MSYS_NO_PATHCONV=1 SSH_REMOTE_BASE=/home/me/proj node smoke-test.js走 MCP 配置（JSON）启动不受影响——那条路径不经过 shell。
变量 | 必填 | 说明 |
| ✅ | 目标主机地址 |
| SSH 端口，默认 22 | |
| ✅ | 登录用户名 |
| 私钥路径，默认 | |
| ✅ | 远端工作目录，必须是绝对路径 |
|
|
SSH_REMOTE_BASE必须是绝对路径：它会被拼进远端cd "..."，双引号里~不做展开。所有工具的相对路径都基于它。
换机器：改env 段，重启客户端。多台机器并行：复制一份目录，在配置里注册第二个条目、换个名字（工具前缀随之区分，如 mcp__ssh-remote-2__*）。同一台机器不需要多个 server。
免密登录：把公钥放进目标机~/.ssh/authorized_keys（ssh-copy-id）。
工具 | 用途 |
| 执行远端命令。多条命令用 |
| 后台起长任务，立即返回 jobId，不阻塞 |
| 查任务状态（ |
| 列出远端所有任务 |
| 读远端文件（带行号） |
| 写远端文件（整文件覆写） |
| 精确字符串替换，改文件不必整篇重写 |
| 远端全文搜索（rg，跨连接复用） |
| 按名找文件（fd） |
| 列目录 |
| 文件元信息 |
| 连接健康检查 |
长跑的东西（全量测试、构建、大批量迁移）不该占着 MCP 调用不放：
remote_exec_bg({ command: "make test-db", label: "全量测试" })
// → { jobId: "muw9a36u-e6taf", pid: "2523963" } 约 250ms 返回
remote_job_check({ jobId: "muw9a36u-e6taf" })
// → { status: "done", exitCode: 0, durationMs: 226000, log: "..." }状态全放远端 /tmp/ssh-remote-jobs/<jobId>/，所以客户端重启也能继续查（内存状态会随进程消失，进度条就没意义了）。日志不会进 git，也不会被任何目录遍历工具扫到。
没有 GUI diff 视图 / 变更文件面板。原生 Read/Grep 只认本地路径，这是本机侧的限制。但git diff 本身能通过 remote_exec 完整拿到，AI 读文本足够。
改文件是整文件覆写或精确替换，没有「光标停在某行」的细粒度编辑。对 AI 干活够用。
单条 TCP：网络抖动会让正在跑的长命令直接失败（下一跳自动重连，但这一跳会报错）。长任务建议用 remote_exec_bg。
输出有上限：命令 1MB、文件 512KB、目录 500 项，超出截断。
依赖远端有 rg / fd：remote_search / remote_find 需要。没装会明确报错，退回 grep 也行，只是慢。
server 是非交互的，但远端有 tmux，所以 TTY 程序能跑：
tmux new-session -d -s htop htop
tmux capture-pane -pt htop # 抓屏看内容curses 程序、长跑任务中途看进度都适用。
改完代码不必重启客户端就能验——探针会新建子进程加载最新代码：
node mcp-probe.js # 跑通全部工具 + 后台任务三件套
node smoke-test.js # 量化握手开销vs 连接复用
node bg-selftest.js # 拿真实长任务验「起任务不阻塞」目标主机由 CONFIG 固定，工具参数无法指定别的主机——不提供任意目标跳转能力。stdout 专供 MCP 协议，所有日志走 stderr。
在远端服务器执行命令。默认工作目录是 SSH_REMOTE_BASE 指定的目录。把多条命令用 && 串成一次调用更省时间——成本在调用次数，不在命令条数。
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | 工作目录，默认 SSH_REMOTE_BASE 指定的目录；可用绝对路径或相对路径 | |
| command | Yes | 要执行的 shell 命令 | |
| timeout | No | 超时毫秒数，默认 120000 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden for an arbitrary shell execution tool. It discloses the default working directory and the cost model, but says nothing about safety/destructive potential, permission requirements, error behavior, or what happens on timeout — significant gaps for a tool that runs arbitrary commands.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short sentences, front-loaded with the purpose, and the batching hint earns its place as non-obvious cost guidance. No filler.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a high-risk arbitrary-command tool with no annotations and no output schema, the description leaves key operational details unstated: return format, how failures/timeouts are surfaced, and how it relates to remote_exec_bg. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents the default cwd, timeout value, and command argument. The description only restates the default cwd, adding no format, syntax, or interaction detail beyond the schema, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource: executing commands on a remote server. The scope is clear, but it never distinguishes itself from the obvious sibling remote_exec_bg beyond the implicit assumption that this one is synchronous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Offers a cost heuristic (batch commands with && because cost is per call, not per command), which is genuinely useful invocation guidance. However it never states when to prefer remote_exec_bg for long-running or detached work, nor any when-not conditions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
后台起一个远端任务，立即返回不等待。适合编译、全量测试、构建镜像这类几分钟的活——返回 jobId，之后用 remote_job_check 查结果。任务状态存在远端文件系统上，本工具重启、甚至 WorkBuddy 重启后照样能接着查。
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | 工作目录，默认 SSH_REMOTE_BASE 指定的目录 | |
| name | No | 任务标签，便于事后辨认，如 full-test | |
| command | Yes | 要跑的完整命令，会过 shell |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden and delivers: async fire-and-return semantics, a jobId handle, and durable state persisted on the remote filesystem that survives tool and WorkBuddy restarts. It omits auth/precondition and error behavior, but the core async contract is well disclosed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with purpose and immediately followed by usage context, with no wasted sentences. The persistence clause is slightly verbose but earns its place by explaining durability.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With no output schema, the description correctly explains the return value (jobId) and the retrieval path (remote_job_check), which is the key thing an agent needs. Complete enough for an async-launch tool, though it could state what happens on command failure.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the schema already documents command, cwd, and name. The description adds no per-parameter detail beyond noting the jobId result, so the schema does the heavy lifting and baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ("后台起一个远端任务" – starts a remote background task) and the key behavioral differentiator ("立即返回不等待" – returns immediately without waiting). It also routes the agent to the sibling remote_job_check for retrieving results, distinguishing it from the blocking remote_exec.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Gives concrete when-to-use guidance: suitable for compilation, full test suites, and image builds that take several minutes. It names remote_job_check as the follow-up step, but does not explicitly contrast with or exclude the synchronous remote_exec sibling.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在远端按文件名查找（走 fd-find，缺失时回退 find）。比 remote_list 递归快得多。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | 查找起点，默认 SSH_REMOTE_BASE 指定的目录 | |
| type | No | d=只要目录，f=只要文件；不填则不限 | |
| pattern | Yes | 文件名片段或正则，如 "order" 或 "\\.go$" | |
| maxResults | No | 最多返回条数，默认 100 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description must carry the behavioral burden. It usefully discloses backend behavior (fd-find, falling back to find) and a performance characteristic, which is real value beyond the schema. But it says nothing about the read-only nature, permissions/auth requirements, symlink or path traversal behavior, or the shape of results, so key behavioral traits are left unstated.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two tight sentences with no filler, front-loading the core action and then the differentiator. Every clause (find by name, fd-find, find fallback, faster than recursive list) earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a four-parameter lookup tool with full schema coverage and no output schema, the description covers the operation and its performance rationale adequately. The one notable gap is the absence of any contrast with remote_search, which an agent needs in order to choose correctly among siblings.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so all four parameters (path, type, pattern, maxResults) are already documented in the schema, including defaults. The description adds no parameter-level meaning such as regex flavor, matching semantics, or path scoping, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb and resource ('在远端按文件名查找') and even names the implementation (fd-find, with find fallback), so the agent knows exactly what it does. It differentiates from remote_list by noting it is much faster for recursion, but never distinguishes itself from the sibling remote_search, which is a plausible alternative for content-based lookup.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The comparison '比 remote_list 递归快得多' implicitly steers the agent away from recursively listing when hunting for files by name. However, there is no explicit when-to-use/when-not guidance and no mention of remote_search, the sibling most likely to be confused with it, so the routing is only implied.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看 SSH 长连接状态；断线时会自动重连一次。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden, and it does disclose one important behavioral trait: a single automatic reconnect on disconnect (a side effect beyond a pure read). However, it says nothing about timeout behavior, cost, or what state the connection is left in after the reconnect, and gives no sense of the returned status.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence with the core action front-loaded and the reconnect caveat appended; nothing is wasted. It is arguably too terse given that no other structured field supplies the missing detail, but there is no padding.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a zero-parameter probe with no output schema, the description should describe what the returned status looks like and what the caller can act on. It omits the return semantics entirely, leaving the agent unable to interpret results, though the connection behavior it does describe is the key operational fact.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool takes zero parameters and the schema is empty, so there is nothing for the description to disambiguate. Baseline of 4 applies for a parameterless tool.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb and resource ('查看 SSH 长连接状态'), which clearly identifies this as a connection health probe distinct from the exec/read/write siblings. It does not explicitly name or contrast with any sibling, but the purpose is unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: an agent can infer you call this to verify the persistent SSH connection before running other remote_* operations, but the description never states when to use it, when not to, or which sibling to prefer instead. No alternatives or preconditions are named.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查一个后台任务的状态与输出。返回 running / done / failed，终态时带退出码和日志末尾若干行。
| Name | Required | Description | Default |
|---|---|---|---|
| tail | No | 返回日志末尾多少行，默认 40 | |
| jobId | Yes | remote_exec_bg 返回的 id |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It does useful work by disclosing the state machine (running/done/failed) and that terminal states add an exit code and tail of the log, but it says nothing about permissions, whether polling is expected, rate limits, or whether the call blocks.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the purpose and followed by the return contract. Every clause earns its place and nothing is padded.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-parameter polling tool with no output schema, the description covers what matters: the states returned and the terminal-state payload. The only real gap is guidance on repeated polling vs a single check, which keeps it short of a 5.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (jobId origin and tail default of 40) are already fully documented in the schema. The description adds no syntax or unit detail beyond that, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a concrete verb (查/check) and resource (后台任务/background job), plus the exact payload (status and output). It is clearly distinct from the plural sibling remote_job_list and from the launcher remote_exec_bg, but it never names those siblings explicitly, so the differentiation is inferred rather than stated.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is only implied: the jobId schema notes it comes from remote_exec_bg, so an agent can infer this is the follow-up to launching a background job. There is no explicit when-to-use, when-not-to-use, or conditional routing to remote_job_list for enumerating jobs.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出当前所有后台任务，含在跑的和已结束的（按开始时间倒序）。
| Name | Required | Description | Default |
|---|---|---|---|
| all | No | true 连已结束的一起列；默认只列还在跑的 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses the ordering (start time descending) and that both running and finished jobs appear, but omits read-only confirmation, pagination/limits, and output shape for a listing tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single tight sentence front-loads scope and adds ordering; there is no filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a one-parameter, read-only listing tool with no output schema, the description covers scope and sort order, but its running-vs-finished framing conflicts with the parameter default, leaving the actual default result set ambiguous.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3, but the description actively undermines the schema: it says results include finished jobs by default, whereas the 'all' parameter documents that the default is running-only. This contradiction risks the agent reporting wrong scope.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (列出/list) and resource (后台任务/background jobs) with scope (current) and ordering (by start time descending). It is clear what the tool returns, though it does not differentiate itself from sibling tools like remote_job_check, which also deals with jobs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives no explicit when-to-use guidance or alternatives. With siblings remote_job_check and remote_exec_bg in the namespace, an agent gets no signal about which to pick; usage is only loosely implied by 'list current jobs'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
列出远端目录内容，返回类型、大小、修改时间。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | 目录路径，默认 SSH_REMOTE_BASE 指定的目录 | |
| maxEntries | No | 最多返回条目数，默认 300 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the burden. It implies a read-only listing and discloses the returned metadata fields, which is useful since there is no output schema. However, it says nothing about recursion depth, truncation behavior when maxEntries is hit, or permission/error behavior on unreadable directories.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single compact sentence that front-loads the action and appends the return contents. No filler or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers purpose and return fields, which compensates for the missing output schema and annotations. It remains incomplete on truncation/pagination semantics and on the boundary with the many sibling listing/search tools.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both path and maxEntries are already documented in the schema, including defaults. The description adds no syntax, path-form, or default-value detail beyond that, so the baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (列出) and resource (远端目录内容), and adds the return shape (类型、大小、修改时间). It is clearly distinguishable from the search/find siblings in intent, though it never names them explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No when-to-use guidance and no mention of alternatives such as remote_search, remote_find, or remote_stat. The agent must infer that this is for browsing a known directory rather than locating files.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
读取远端文件。支持按行区间读取，返回带行号以便后续精确修改。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 文件路径，相对路径基于 SSH_REMOTE_BASE，也支持 ~ 和绝对路径 | |
| endLine | No | 结束行号（含），不填则到尾 | |
| maxBytes | No | 最大读取字节数，默认 512KB | |
| startLine | No | 起始行号（1 起），不填则从头 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the burden, and it does convey read-only semantics, line-range support, and that output carries line numbers for follow-up edits. However, it omits truncation behavior around maxBytes, error handling for missing/unreadable files, and encoding assumptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short, front-loaded sentences with no filler; the core purpose leads and the line-number behavior follows. Slight overlap with schema-documented line-range params keeps it from a 5.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 4-param read tool with full schema coverage and no output schema, the definition is adequate. Gaps remain around encoding, binary files, and what a maxBytes-truncated result looks like, which an agent could need.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so path, startLine, endLine, and maxBytes are already fully documented in the schema. The description only gestures at line-range reading without adding format or default details beyond what the schema provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource (读取远端文件 / read remote file) and adds scope (line-range reads) plus a distinguishing output trait (line numbers). It clearly reads content, separating it from remote_list/remote_stat/remote_exec, though it does not name the sibling it is not.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Usage is implied by '支持按行区间读取' (line-range reads) and the line-number return for later edits, but there is no explicit when-to-use/when-not or reference to alternatives like remote_search or remote_find for locating content first.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在远端文件里做精确字符串替换，无需传整个文件。old_string 必须唯一匹配，否则报错——这是为了防止改错地方。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 文件路径 | |
| newString | Yes | 替换后的内容 | |
| oldString | Yes | 要被替换的原始片段，需精确匹配（含缩进） | |
| replaceAll | No | 是否替换全部匹配，默认 false（要求唯一匹配） |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full disclosure burden. It usefully explains the failure mode (error on non-unique match) and its rationale (preventing edits in the wrong place), but says nothing about permissions, reversibility, or atomicity—important traits for a remote mutation tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, front-loaded with the core purpose and then the critical uniqueness constraint. No filler; each clause earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 4-parameter mutation tool with no annotations and no output schema, the description covers purpose and the main error condition but omits return behavior and permission/auth requirements. Adequate but with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the baseline is 3. The description reiterates the old_string uniqueness constraint already documented in the replaceAll field, adding rationale but little new parameter semantics beyond what the schema provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (precise string replacement) and resource (remote file), and the phrase '无需传整个文件' implicitly distinguishes it from remote_write by noting the whole file need not be transferred. Clear purpose, though it does not explicitly name a sibling.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the use case (edit a remote file without transferring the whole file) and states the key precondition (old_string must uniquely match), but it never explicitly says when to choose this over remote_write or remote_read. Usage is implied rather than spelled out.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
在远端按内容搜索（优先 ripgrep，远端没装时回退 grep）。适合跨文件找符号、找引用。
| Name | Required | Description | Default |
|---|---|---|---|
| path | No | 搜索起点，默认 SSH_REMOTE_BASE 指定的目录 | |
| type | No | 按文件类型过滤：go / sql / md / yaml 等；与 include 二选一 | |
| context | No | 每个匹配上下各带几行上下文，默认 0 | |
| include | No | 文件名过滤，如 "*.go"；不填则不限 | |
| pattern | Yes | 要搜索的文本或正则 | |
| maxResults | No | 最多返回行数，默认 100 | |
| caseSensitive | No | 大小写敏感，默认 true |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden. It usefully discloses the ripgrep-then-grep fallback and that search happens over SSH on a remote (implying a connection requirement), but says nothing about authentication/permission needs, truncation behavior, or error modes when the remote is unreachable.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact sentences, zero filler. The core capability and the engine fallback are front-loaded, and the use case follows. Nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 7-parameter search tool with no output schema and no annotations, the description leaves the agent guessing about result shape, line truncation relative to maxResults, and failure behavior on an unreachable remote. It is adequate for invocation but thin on the operational context an agent needs.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so path, type, context, include, pattern, maxResults and caseSensitive are all already documented with defaults. The description adds no syntax, format, or precedence detail beyond the schema, so the baseline of 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource: content search on the remote host, plus the implementation detail (ripgrep with grep fallback). The phrase "按内容搜寻" implicitly contrasts with the name-based sibling remote_find, but no sibling is named explicitly, so it stops short of a 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
"适合跨文件找符号、找引用" gives a use case, which is better than nothing, but it is implied guidance rather than explicit when-to-use/when-not guidance. The obvious alternative (remote_find for filename matching, remote_list for listing) is never mentioned, leaving the agent to infer the boundary.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
查看远端文件或目录是否存在及其属性（类型、大小、修改时间、权限）。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 路径 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full behavioral burden, and it partially does so by enumerating the returned attributes, which is valuable given there is no output schema. However, it does not disclose failure semantics (does a nonexistent path return a negative result or an error?), permission requirements, or symlink handling.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
A single front-loaded sentence that states purpose and enumerates returned attributes with no filler. It is appropriately sized for a one-parameter read tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a trivial single-parameter read tool the description is nearly sufficient, and listing the returned fields compensates for the absent output schema. The remaining gap is the undefined behavior when the path does not exist or is inaccessible, which an agent would need to know to interpret results.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% for the single 'path' parameter, so the schema already documents it; the description only implicitly reinforces that the path refers to the remote host. Baseline 3 is appropriate when the schema does the documentation work.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb-plus-resource: checking whether a remote file or directory exists and returning its attributes (type, size, modification time, permissions). This naturally separates it from remote_read (which fetches contents) and remote_list (which enumerates a directory), though no sibling is named explicitly.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
There is no explicit when-to-use guidance, no prerequisites, and no mention of alternatives such as remote_list or remote_read for related metadata needs. The intended use is only inferable from the purpose statement itself.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
整文件写入远端。改大文件前建议先 remote_read 确认内容。
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | 目标路径 | |
| content | Yes | 完整文件内容 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden for a mutation tool. '整文件写入' implies whole-file replacement (thus destroying prior content), but it never states that existing content is overwritten, whether the file is created if absent, permission requirements, or atomicity. The remote_read tip hints at risk but does not disclose the write semantics.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two short sentences, front-loaded with the core purpose and followed by a single actionable tip. No filler; appropriately sized for a simple two-parameter tool.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a destructive write tool with no annotations and no output schema, the description should disclose overwrite semantics and the remote_write vs remote_replace distinction. It covers purpose and one precondition but leaves the risky behavioral details unstated.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both parameters (path, content) are already documented. The description's '整文件' adds only a marginal hint that content must be complete file text, which is already conveyed by the schema. Baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb+resource ('整文件写入远端' = write entire file to remote) with a scope qualifier ('整文件') that implicitly separates it from remote_replace's partial-edit behavior. It lacks explicit sibling naming, but the whole-file scope is enough for an agent to distinguish it from remote_replace.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides a workflow precondition — read large files with remote_read before modifying — which is useful but reactive. It never states when to choose remote_write over remote_replace, so the most important alternative-selection decision is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.1.0remote_execremote_exec_bgremote_findremote_healthremote_job_checkremote_job_listremote_listremote_readremote_replaceremote_searchremote_statremote_writeScored across 12 tools
Tools are largely distinct: remote_list (single dir), remote_find (recursive by name), remote_search (by content), and remote_stat (specific path properties) have clearly different scopes, and exec vs exec_bg vs job_check/list are well separated. There is mild overlap in the cluster of 'inspect the filesystem' tools, but descriptions disambiguate them adequately.
Every tool uses a consistent remote_ prefix followed by a clear verb or verb_noun suffix (remote_list, remote_read, remote_write, remote_exec_bg, remote_job_check). The pattern is predictable throughout with no convention mixing.
12 tools is well within scope for a remote file-and-exec server, and each tool covers a distinct operation (listing, searching, reading, writing, replacing, executing, background jobs, health). No redundancy or padding.
Core file lifecycle (read, write, replace) plus search, exec, and background-job management are covered, but there is no explicit delete, mkdir, or move/rename operation. These gaps are workaround-able via remote_exec shell commands, so they are minor rather than blocking.
Remote shell and detached long-running jobs on your own machines — no SSH, open ports or VPN.
Persistent cloud workspaces for AI agents: run commands, edit files, use git and a browser.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Let AI operate servers without SSH. Choose actions, approve risky changes, and audit every step.
