@pyrokine/mcp-ssh 3.1.0 → 3.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +328 -104
- package/README_zh.md +173 -37
- package/dist/command-risk.js +5 -2
- package/dist/directory-verification.d.ts +10 -5
- package/dist/directory-verification.js +153 -66
- package/dist/file-mode.js +25 -13
- package/dist/file-ops.d.ts +13 -6
- package/dist/file-ops.js +477 -208
- package/dist/forward-manager.js +6 -1
- package/dist/known-hosts.d.ts +22 -0
- package/dist/known-hosts.js +553 -0
- package/dist/openssh.js +51 -26
- package/dist/operation-manager.js +13 -4
- package/dist/pty-manager.d.ts +2 -1
- package/dist/pty-manager.js +81 -19
- package/dist/remote-platform.d.ts +1 -1
- package/dist/remote-platform.js +82 -50
- package/dist/security.d.ts +2 -0
- package/dist/security.js +39 -3
- package/dist/session-manager.d.ts +22 -2
- package/dist/session-manager.js +231 -48
- package/dist/sftp-timeout.d.ts +16 -1
- package/dist/sftp-timeout.js +104 -12
- package/dist/ssh-config.js +1 -1
- package/dist/tools/connection.js +17 -3
- package/dist/tools/exec.js +83 -38
- package/dist/tools/file.js +250 -135
- package/dist/tools/operation.js +7 -5
- package/dist/tools/pty.js +16 -13
- package/dist/tools/utils.d.ts +1 -1
- package/dist/tools/utils.js +2 -2
- package/dist/types.d.ts +20 -3
- package/dist/types.js +1 -0
- package/dist/utf8.d.ts +1 -1
- package/dist/utf8.js +2 -2
- package/dist/windows-acl.d.ts +1 -0
- package/dist/windows-acl.js +167 -80
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -8,7 +8,8 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
8
8
|
[](https://nodejs.org/)
|
|
9
9
|
[](https://modelcontextprotocol.io/)
|
|
10
10
|
|
|
11
|
-

|
|
11
|
+

|
|
12
|
+

|
|
12
13
|

|
|
13
14
|
|
|
14
15
|
## Migrating to 3.0
|
|
@@ -17,23 +18,79 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
17
18
|
Recalculate budgets for non-ASCII output and check `stdoutTruncated` / `stderrTruncated`; `maxOutputSize=3` can return
|
|
18
19
|
one Chinese character, not three. Text responses end at a complete character boundary.
|
|
19
20
|
|
|
20
|
-
PTY `bufferSize` and list-result `bufferSize
|
|
21
|
-
|
|
22
|
-
|
|
21
|
+
PTY `bufferSize` and list-result `bufferSize` , together with `unreadRawBytes` and `rawBufferLimit` in read/list
|
|
22
|
+
results,
|
|
23
|
+
now count raw bytes. A raw read with `clear=true` returns the counts and `rawBufferTruncated` state before clearing;
|
|
24
|
+
the
|
|
25
|
+
next read reflects the cleared buffer. Use `dataBase64` for exact ANSI or binary output and `data` for a UTF-8
|
|
26
|
+
preview.
|
|
23
27
|
|
|
24
28
|
File reads accept `encoding` (`auto`, `utf8`, `utf16le`, `utf16be`, `gbk`) and lossless `binary=true`. Keep offsets in
|
|
25
|
-
bytes and continue with `next_offset
|
|
26
|
-
|
|
27
|
-
|
|
29
|
+
bytes and continue with `next_offset` ; `auto` detects encoding at the file start, including for later pages. A U+FEFF
|
|
30
|
+
at
|
|
31
|
+
a nonzero offset remains content. A budget too small for the next complete text character returns an error instead of
|
|
32
|
+
an
|
|
33
|
+
empty page; malformed encoding at EOF also fails. Binary reads advance byte by byte. `lineRange` metadata describes
|
|
34
|
+
only
|
|
28
35
|
the returned prefix, including whether its last line ends with a newline.
|
|
29
36
|
|
|
30
37
|
Windows connections require `remotePlatform="windows"`; local Windows does not change the remote default. Set
|
|
31
38
|
`commandShell` and `remotePathStyle` for the host, and an explicit `rsyncProfile` when using rsync with Windows. The
|
|
32
39
|
Windows behavior and examples below remain available.
|
|
33
40
|
|
|
41
|
+
## Host key trust
|
|
42
|
+
|
|
43
|
+
The default ssh2 backend checks the server key before user authentication, including each bastion, forwarded target,
|
|
44
|
+
and
|
|
45
|
+
reconnect. It also verifies every rekey with a fresh verification budget, while the initial handshake retains its
|
|
46
|
+
original connection deadline. It reads `~/.ssh/known_hosts`, `~/.ssh/known_hosts2`, and standard system
|
|
47
|
+
`ssh_known_hosts` files. An unknown host uses trust on first use (TOFU): its key is saved to `~/.ssh/known_hosts`
|
|
48
|
+
before
|
|
49
|
+
authentication proceeds. Connection results include the target's `hostKey.status` (`added` or `known`) and SHA-256
|
|
50
|
+
fingerprint; `hostKeys` lists the verified host, port, status, and fingerprint for every hop. Preload a verified key
|
|
51
|
+
to
|
|
52
|
+
authenticate the first connection independently of the network path.
|
|
53
|
+
|
|
54
|
+
Existing trusted keys automatically take priority during host-key algorithm negotiation. A saved ECDSA key remains
|
|
55
|
+
usable
|
|
56
|
+
when the server also offers Ed25519; an RSA pin also covers RSA SHA2 signatures. This applies to every hop and
|
|
57
|
+
reconnect,
|
|
58
|
+
with the negotiated key still checked against the saved key bytes before authentication.
|
|
59
|
+
|
|
60
|
+
Changed, revoked, or damaged matching keys stop the connection before authentication or during rekey.
|
|
61
|
+
Key mismatch errors include `details.hostKey`: the negotiated algorithm, presented key type and SHA-256 fingerprint,
|
|
62
|
+
and matching saved fingerprints with their `known_hosts` file and line. Existing trust records remain unchanged.
|
|
63
|
+
A rekey trust failure cancels automatic reconnect for that client and its dependent targets. A target failure
|
|
64
|
+
preserves
|
|
65
|
+
the shared bastion and unrelated aliases. Explicit connect or reconnect verifies trust again; ordinary network loss
|
|
66
|
+
retains automatic reconnect. Hashed hostnames, host/port pairs, IPv6, multiple names, wildcard patterns, and negated
|
|
67
|
+
patterns are supported. Matching CA or host-certificate entries require the OpenSSH backend. Concurrent first-use
|
|
68
|
+
writes
|
|
69
|
+
use an exclusive owner-directory lock with a bounded, cancellable wait. A complete owner record is published before
|
|
70
|
+
writing trust. A confirmed exited owner is recovered automatically within the same verified local process domain:
|
|
71
|
+
Linux uses the `/proc` boot ID and PID namespace, macOS uses `kern.bootsessionuuid`, and Windows queries the kernel's
|
|
72
|
+
`SystemBootEnvironmentInformation.BootIdentifier` through the built-in PowerShell. Live or reused PIDs, denied
|
|
73
|
+
liveness
|
|
74
|
+
checks, and unavailable or mismatched boot/domain identities retain the lock until the wait expires or is canceled.
|
|
75
|
+
Legacy
|
|
76
|
+
empty `.mcp-lock` files have no owner record and remain in place; remove one only after establishing that no older
|
|
77
|
+
writer is still using it.
|
|
78
|
+
|
|
79
|
+
Trust writes append to the existing file, preserving its records, comments, permissions, and Windows DACLs. If
|
|
80
|
+
writing,
|
|
81
|
+
flushing, closing, cancellation, or the deadline fails after append starts, the connection fails before authentication
|
|
82
|
+
and reports an unknown, possibly partial append. Existing bytes are retained without truncation or rollback, including
|
|
83
|
+
records another writer has already saved; inspect the reported partial state before retrying. Trust files may be
|
|
84
|
+
publicly readable, but untrusted writers are rejected. A known read-only record remains usable, while an unknown host
|
|
85
|
+
fails when trust cannot be saved.
|
|
86
|
+
|
|
87
|
+
`ProxyJump none` disables the configured jump. An explicit or template `jumpHost` overrides `ProxyJump` before its
|
|
88
|
+
configuration is validated. OpenSSH master trust remains independent, as described below.
|
|
89
|
+
|
|
34
90
|
## Reusing an existing OpenSSH master
|
|
35
91
|
|
|
36
|
-
The default `backend="ssh2"` retains password/key authentication, bastion connections, SFTP, PTY, and forwarding.
|
|
92
|
+
The default `backend="ssh2"` retains password/key authentication, bastion connections, SFTP, PTY, and forwarding.
|
|
93
|
+
Choose
|
|
37
94
|
`backend="openssh"` to reuse a master already opened by your terminal:
|
|
38
95
|
|
|
39
96
|
```text
|
|
@@ -43,7 +100,8 @@ ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", dir
|
|
|
43
100
|
```
|
|
44
101
|
|
|
45
102
|
`ssh -G` resolves the effective host, user, port, and `ControlPath`; an explicit `controlPath` overrides the socket
|
|
46
|
-
path. Custom `configPath` files retain the existing path and size checks. OpenSSH evaluates its normal `Host
|
|
103
|
+
path. Custom `configPath` files retain the existing path and size checks. OpenSSH evaluates its normal `Host` ,
|
|
104
|
+
`Match` ,
|
|
47
105
|
`Include`, and `ProxyJump` configuration, including user-configured `Match exec` commands. Execution then uses the
|
|
48
106
|
resolved target and socket without rereading that configuration.
|
|
49
107
|
|
|
@@ -51,14 +109,20 @@ This backend only reuses existing connections. A missing, replaced, or disconnec
|
|
|
51
109
|
command and rsync channels use a failing proxy if multiplexing fails, so they cannot start another SSH connection or
|
|
52
110
|
switch to ssh2/SFTP. Do not pass password, key, agent, or `jumpHost` authentication parameters in this mode.
|
|
53
111
|
|
|
54
|
-
Connection results include `backend
|
|
55
|
-
|
|
112
|
+
Connection results include `backend` , `masterReused` , `masterPid` , `identityStatus="master_trusted"` , and observed
|
|
113
|
+
login
|
|
114
|
+
metadata. Trust belongs to the user-selected master, as in native OpenSSH multiplexing. Socket ownership,
|
|
115
|
+
configuration
|
|
56
116
|
conflicts, and login-user mismatches are checked; the response does not claim independent host identity authentication
|
|
57
117
|
from `ssh -G` or `ssh -O check`.
|
|
58
118
|
|
|
59
119
|
Commands, tracked operations, file metadata, and rsync synchronization work on local and remote POSIX systems. Sync
|
|
60
|
-
requires local/remote rsync and remote GNU `find
|
|
61
|
-
|
|
120
|
+
requires local/remote rsync and remote GNU `find` , `stat` , `head` , and `realpath` ; missing capabilities fail
|
|
121
|
+
explicitly.
|
|
122
|
+
The error's `details` preserves `code`, `backend`, `reason`, and `retryable`, such as
|
|
123
|
+
`reason="local_rsync_unavailable"`.
|
|
124
|
+
Bounded directory manifests and streamed SHA-256 checks use the same master and do not require a session using ssh2 or
|
|
125
|
+
a
|
|
62
126
|
remote Python installation. Separate SFTP tools, temporary script uploads, PTY, forwarding, and Windows combinations
|
|
63
127
|
return `unsupported_backend`.
|
|
64
128
|
|
|
@@ -163,17 +227,21 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
163
227
|
| `ssh_reconnect` | Reconnect a disconnected session |
|
|
164
228
|
| `ssh_config_list` | List hosts from ~/.ssh/config |
|
|
165
229
|
|
|
166
|
-
`ssh_list_sessions()` returns `backend
|
|
167
|
-
|
|
168
|
-
|
|
230
|
+
`ssh_list_sessions()` returns `backend` , `alias` , canonical `identity` , `runAs` , `connected` , and `lastUsedAt` ;
|
|
231
|
+
OpenSSH
|
|
232
|
+
entries also include `masterReused` and `identityStatus` . Use `detail=true` for connection details or `fields=[...]`
|
|
233
|
+
to
|
|
234
|
+
select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open state, so a dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and an explicitly chosen conflicting alias returns an error.
|
|
169
235
|
|
|
170
|
-
ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
|
|
236
|
+
ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
|
|
237
|
+
Direct,
|
|
171
238
|
jump-host, and replacement connections share this behavior without an additional option.
|
|
172
239
|
|
|
173
240
|
`ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
|
|
174
241
|
the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled
|
|
175
242
|
them, so an old timer cannot disconnect a newer session with the same alias. A delayed `close` from the old client
|
|
176
|
-
cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut`
|
|
243
|
+
cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut`
|
|
244
|
+
is
|
|
177
245
|
pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
|
|
178
246
|
|
|
179
247
|
### Command Execution
|
|
@@ -188,6 +256,8 @@ pending, a channel returned by the delayed callback is destroyed before the conn
|
|
|
188
256
|
| `ssh_quick_exec` | One-shot: connect, execute, disconnect |
|
|
189
257
|
| `ssh_exec_script` | Upload and run a temporary remote script |
|
|
190
258
|
|
|
259
|
+
`ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and retains its cmd or PowerShell script invocation.
|
|
260
|
+
|
|
191
261
|
For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
|
|
192
262
|
correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
|
|
193
263
|
execution. POSIX scripts retain their original content.
|
|
@@ -215,6 +285,8 @@ execution. POSIX scripts retain their original content.
|
|
|
215
285
|
| `ssh_mkdir` | Create remote directory |
|
|
216
286
|
| `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
|
|
217
287
|
|
|
288
|
+
`ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
|
|
289
|
+
|
|
218
290
|
### PTY Sessions (Persistent Interactive Terminal)
|
|
219
291
|
|
|
220
292
|
| Tool | Description |
|
|
@@ -237,7 +309,8 @@ execution. POSIX scripts retain their original content.
|
|
|
237
309
|
|
|
238
310
|
## Windows and cross-platform SSH
|
|
239
311
|
|
|
240
|
-
Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix
|
|
312
|
+
Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix` , regardless of the client's
|
|
313
|
+
OS.
|
|
241
314
|
Use `commandShell="powershell"` (default on Windows) or `"cmd"`, and set `remotePathStyle="win32"` (default) or
|
|
242
315
|
`"sftp-posix"` if the server exposes `/C:/...` paths. `cwd` and `env` are grouped with the command in the selected
|
|
243
316
|
shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec` also accepts `remotePlatform`,
|
|
@@ -245,19 +318,36 @@ shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec
|
|
|
245
318
|
`unsupported_remote_platform` before issuing a remote command.
|
|
246
319
|
|
|
247
320
|
```text
|
|
248
|
-
ssh_connect(
|
|
321
|
+
ssh_connect(
|
|
322
|
+
host="example.com",
|
|
323
|
+
user="tester",
|
|
324
|
+
agent="\\\\.\\pipe\\openssh-ssh-agent",
|
|
325
|
+
remotePlatform="windows",
|
|
326
|
+
commandShell="powershell",
|
|
327
|
+
remotePathStyle="win32",
|
|
328
|
+
rsyncProfile="native-win32"
|
|
329
|
+
)
|
|
249
330
|
ssh_exec(alias="tester@example.com:22", command="Get-Location", cwd="C:\\Test Data", env={REGION:"test"})
|
|
250
|
-
ssh_read_file(
|
|
331
|
+
ssh_read_file(
|
|
332
|
+
alias="tester@example.com:22",
|
|
333
|
+
remotePath="C:\\Test Data\\report.txt",
|
|
334
|
+
lineRange="1-20",
|
|
335
|
+
encoding="utf16le"
|
|
336
|
+
)
|
|
251
337
|
```
|
|
252
338
|
|
|
253
|
-
`ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's
|
|
339
|
+
`ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's
|
|
340
|
+
`agent="pageant"`
|
|
254
341
|
on Windows. SSH config `IdentityAgent` supplies a socket when there is no explicit agent or private key.
|
|
255
|
-
`IdentityAgent none` (or `agent="none"`) disables agent authentication and environment socket fallback, including
|
|
342
|
+
`IdentityAgent none` (or `agent="none"` ) disables agent authentication and environment socket fallback, including
|
|
343
|
+
with a
|
|
256
344
|
private key and on ProxyJump hosts; password and key authentication remain available. An explicit argument or template
|
|
257
|
-
`agent` takes precedence over SSH config. Reconnect preserves this choice, and external OpenSSH/rsync also disables
|
|
345
|
+
`agent` takes precedence over SSH config. Reconnect preserves this choice, and external OpenSSH/rsync also disables
|
|
346
|
+
the
|
|
258
347
|
environment agent when `none` is selected. The connection result reports `remotePlatform`, `commandShell`,
|
|
259
348
|
`remotePathStyle`, and `keyAclStatus` for Windows private keys. Existing private keys are checked but never modified:
|
|
260
|
-
`key_acl_insecure` and `key_acl_unverified` reject authentication. Windows session files and temporary downloads
|
|
349
|
+
`key_acl_insecure` and `key_acl_unverified` reject authentication. Windows session files and temporary downloads
|
|
350
|
+
receive
|
|
261
351
|
and verify private DACLs before they contain data. Windows scripts and atomic uploads create an empty temporary file
|
|
262
352
|
through SFTP, verify its DACL, then write content; cleanup uses SFTP. Windows tracked operations report the PID and
|
|
263
353
|
creation time. Cancellation checks the process command line for its random marker and creation time before
|
|
@@ -265,15 +355,20 @@ creation time. Cancellation checks the process command line for its random marke
|
|
|
265
355
|
channel as proof of cancellation. Windows ACL and process behavior need a native Windows or Windows SSH host for
|
|
266
356
|
end-to-end verification.
|
|
267
357
|
|
|
268
|
-
`ssh_read_file` reads `lineRange` through SFTP, including CRLF and UTF-8, UTF-16LE/BE, or GBK (`encoding="auto"`
|
|
269
|
-
|
|
270
|
-
|
|
358
|
+
`ssh_read_file` reads `lineRange` through SFTP, including CRLF and UTF-8, UTF-16LE/BE, or GBK (`encoding="auto"`
|
|
359
|
+
detects
|
|
360
|
+
a BOM at the start). `binary=true` returns the bytes as base64 in `content` and `content_base64` . Byte offsets apply
|
|
361
|
+
to
|
|
362
|
+
the remote file. GBK byte-offset reads and tails are rejected because a random byte offset cannot prove a GBK
|
|
363
|
+
character
|
|
271
364
|
boundary; use `lineRange` or `binary=true`. Use an explicit UTF-16 encoding for nonzero offsets. `maxOutputSize` for
|
|
272
365
|
exec caps each stdout/stderr text body by UTF-8 bytes; `stdoutTruncated` and `stderrTruncated` signal truncation
|
|
273
|
-
separately. PTY raw reads include `dataBase64` containing the unmodified buffered bytes; `data` remains a text
|
|
366
|
+
separately. PTY raw reads include `dataBase64` containing the unmodified buffered bytes; `data` remains a text
|
|
367
|
+
preview.
|
|
274
368
|
|
|
275
369
|
Directory verification traverses SFTP with entry, depth, file-size, and total-hash budgets; POSIX `verify.owner` and
|
|
276
|
-
`verify.mode` are rejected on Windows. For a Windows directory, `verify.aclSddl` compares the expected DACL SDDL of
|
|
370
|
+
`verify.mode` are rejected on Windows. For a Windows directory, `verify.aclSddl` compares the expected DACL SDDL of
|
|
371
|
+
the
|
|
277
372
|
remote root separately. `ssh_upload(atomic=true)` checks the SFTP `posix-rename@openssh.com` capability before
|
|
278
373
|
transferring data to replace an existing target; unsupported or unverified replacement leaves that target untouched.
|
|
279
374
|
`ssh_sync` uses `rsyncProfile` (`posix`, `native-win32`, `msys2`, `cygwin`) and optional `rsyncExecutable` on the
|
|
@@ -285,7 +380,8 @@ Before either upload transport starts, Windows directory sync checks source name
|
|
|
285
380
|
are applied. Potential collisions are compared using Windows ordinal case rules and the existing destination parent
|
|
286
381
|
directory's case-sensitive flag. A confirmed collision returns `windows_filename_collision`; a missing parent,
|
|
287
382
|
unavailable shell, timeout, or incomplete query returns `case_semantics_unverified` before any upload or directory
|
|
288
|
-
creation, including in dry-run mode. Already-existing case-sensitive directories can keep case-distinct names. The
|
|
383
|
+
creation, including in dry-run mode. Already-existing case-sensitive directories can keep case-distinct names. The
|
|
384
|
+
check
|
|
289
385
|
does not infer rules for new directories from their ancestors. No candidate means no additional PowerShell or exec
|
|
290
386
|
requirement, so SFTP-only uploads remain supported; POSIX uploads retain their name semantics.
|
|
291
387
|
|
|
@@ -339,8 +435,21 @@ Execute the same command on multiple connected hosts:
|
|
|
339
435
|
```
|
|
340
436
|
|
|
341
437
|
Each host result keeps the same execution metadata as `ssh_exec`, including `failureKind`, `effectiveUser`, `cwd`,
|
|
342
|
-
truncation fields, and diagnostic suggestions. `ssh_exec_parallel` limits one call to 32 aliases, runs up to 4 hosts
|
|
343
|
-
|
|
438
|
+
truncation fields, and diagnostic suggestions. `ssh_exec_parallel` limits one call to 32 aliases, runs up to 4 hosts
|
|
439
|
+
at
|
|
440
|
+
a time by default (configurable with `maxConcurrency` , max 8), and accepts `maxOutputSize` to cap each host result.
|
|
441
|
+
Both
|
|
442
|
+
parallel and batch calls share a 16 MiB request budget for stdout/stderr and head/tail previews. `outputBytes`,
|
|
443
|
+
`maxOutputBytes` , and `outputTruncated` describe that budget; each command retains its byte counts and truncation
|
|
444
|
+
flags.
|
|
445
|
+
Exhausting the budget truncates text while preserving every command's actual success, exit status, and batch
|
|
446
|
+
`executed`
|
|
447
|
+
count. A later disconnect or failed diagnostic preserves results already returned by completed commands.
|
|
448
|
+
|
|
449
|
+
A channel closed without an exit status returns `exitCode=null`, `failureKind="ssh_transport"`,
|
|
450
|
+
`operationStatus="unknown"` , and `retryable=false` , with any captured output. Inspect the remote state before
|
|
451
|
+
repeating
|
|
452
|
+
that command. A reported exit signal is retained as `exitSignal` and classified as a known remote command failure.
|
|
344
453
|
|
|
345
454
|
### Basic: Connect and Execute
|
|
346
455
|
|
|
@@ -353,8 +462,11 @@ ssh_disconnect(alias="myserver")
|
|
|
353
462
|
### Connection Templates and runAs
|
|
354
463
|
|
|
355
464
|
Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
|
|
356
|
-
template values. Each selected template is validated before connection. SSH ports must be integers from 1 through
|
|
357
|
-
|
|
465
|
+
template values. Each selected template is validated before connection. SSH ports must be integers from 1 through
|
|
466
|
+
65535;
|
|
467
|
+
an invalid template error identifies its name and field without returning its authentication values. Invalid JSON
|
|
468
|
+
errors
|
|
469
|
+
report only the source and available numeric position or line/column, never source-text excerpts.
|
|
358
470
|
|
|
359
471
|
```json
|
|
360
472
|
{
|
|
@@ -411,25 +523,33 @@ Perfect for scenarios where you SSH as root but need to run commands as another
|
|
|
411
523
|
// Output: appuser
|
|
412
524
|
```
|
|
413
525
|
|
|
414
|
-
By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do
|
|
526
|
+
By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do
|
|
527
|
+
not
|
|
415
528
|
execute rc files automatically. Bash (`.bashrc`), zsh (`.zshrc`), and other shells (`.profile`) are supported. Disable
|
|
416
529
|
this behavior with `loadProfile=false`.
|
|
417
530
|
|
|
418
|
-
`ssh_exec
|
|
531
|
+
`ssh_exec` , `ssh_exec_as_user` , and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the
|
|
532
|
+
login
|
|
419
533
|
user; otherwise a per-call `runAs` overrides the session `runAs`; otherwise the session `runAs` applies.
|
|
420
534
|
|
|
421
535
|
`ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
|
|
422
|
-
`resolvedCwd
|
|
536
|
+
`resolvedCwd` , `shell` , `profileLoaded` , `envInjectedKeys` , `failureKind` , `stdoutBytes` , `stderrBytes` , and
|
|
537
|
+
truncation
|
|
423
538
|
hints. Large output returns `stdoutHead`, `stdoutTail`, `stderrHead`, `stderrTail`, and `recommendedReadCommand`.
|
|
424
|
-
Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are
|
|
539
|
+
Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are
|
|
540
|
+
decoded
|
|
425
541
|
incrementally, so a UTF-8 character split across SSH data chunks is returned intact. `commandRisk` reports
|
|
426
542
|
shell-specific destructive, privilege, credential-argument, process-control, and resource-use signals; read-only
|
|
427
543
|
searches containing a credential word and ordinary Python/Node commands are not flagged solely for those words.
|
|
428
544
|
|
|
429
|
-
`commandRisk` is diagnostic metadata and does not change command execution or its result.
|
|
545
|
+
`commandRisk` is diagnostic metadata and does not change command execution or its result.
|
|
546
|
+
Search risk uses the execution timeout, including the default 30 seconds. Searches with timeouts at most five minutes
|
|
547
|
+
and `find` commands with a numeric `-maxdepth` are treated as bounded; separate unbounded searches and continuous
|
|
548
|
+
commands such as `tail -f` retain their risk signals. POSIX classification treats
|
|
430
549
|
here-doc bodies as input, supports quoted and partially quoted delimiters, backslash quoting, `<<-`, and multiple
|
|
431
550
|
here-docs, and resumes after an exact, case-sensitive delimiter. Unquoted here-docs and double-quoted arguments still
|
|
432
|
-
expose active command substitutions. A Shell background `&` at EOF is reported;
|
|
551
|
+
expose active command substitutions. A Shell background `&` at EOF is reported; `&&` , redirections, escaped
|
|
552
|
+
ampersands,
|
|
433
553
|
and quoted input are not background operators.
|
|
434
554
|
|
|
435
555
|
### Tracked long-running commands
|
|
@@ -443,10 +563,12 @@ ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxByte
|
|
|
443
563
|
ssh_operation_cancel(operationId="op_xxx")
|
|
444
564
|
```
|
|
445
565
|
|
|
446
|
-
The start call returns an unpredictable `operationId
|
|
566
|
+
The start call returns an unpredictable `operationId` . The server creates the record before requesting the SSH
|
|
567
|
+
channel,
|
|
447
568
|
keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires
|
|
448
569
|
terminal records after `retentionMs`. `startTimeoutMs` bounds channel setup, defaults to 30 seconds, and accepts up to
|
|
449
|
-
10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks
|
|
570
|
+
10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks
|
|
571
|
+
another
|
|
450
572
|
pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes`
|
|
451
573
|
defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
|
|
452
574
|
`ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
|
|
@@ -457,8 +579,13 @@ period. Delayed exec, sudo, SFTP, PTY-start, and operation-start callbacks from
|
|
|
457
579
|
are rejected and their channels are destroyed. A sudo callback that arrives after timeout is also closed before any
|
|
458
580
|
password is written. Operation listeners are installed inside the SSH exec callback before it returns, so a short
|
|
459
581
|
command that emits its marker and closes immediately still enters a terminal state with `finishedAt` and `expiresAt`
|
|
460
|
-
set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown
|
|
461
|
-
|
|
582
|
+
set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown` ; the server does
|
|
583
|
+
not
|
|
584
|
+
claim that the remote process stopped. A channel that closes without an exit status or signal also becomes `unknown`,
|
|
585
|
+
with `exitCode=null` and retained output, marker, PID and retention metadata. Inspect the remote command before
|
|
586
|
+
repeating
|
|
587
|
+
it. Known exit codes, signals and confirmed cancellation keep their respective terminal states. `ssh_exec` keeps its
|
|
588
|
+
existing synchronous timeout behavior.
|
|
462
589
|
|
|
463
590
|
Tracked POSIX commands use `setsid -w` when available to wait for the command, including when `setsid` forks. Nonzero
|
|
464
591
|
command exits produce `failed`; a zero exit can still have stderr output. Commands execute under `sh`, so Bash-only
|
|
@@ -496,8 +623,10 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
|
|
|
496
623
|
ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
|
|
497
624
|
```
|
|
498
625
|
|
|
499
|
-
This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
|
|
500
|
-
|
|
626
|
+
This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
|
|
627
|
+
The
|
|
628
|
+
`ssh_exec_script.timeout` value applies while uploading the temporary script, preparing its permissions, and running
|
|
629
|
+
it.
|
|
501
630
|
A stalled SFTP upload therefore ends on the requested timeout instead of using the default SFTP budget.
|
|
502
631
|
|
|
503
632
|
### With Environment Variables
|
|
@@ -552,24 +681,30 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
|
|
|
552
681
|
```
|
|
553
682
|
|
|
554
683
|
`ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
|
|
555
|
-
verification checks.
|
|
684
|
+
verification checks. Default uploads omit `verification`; requesting a check, such as `verifySize=true`, adds it.
|
|
685
|
+
`atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
|
|
556
686
|
returns `diagnostics.tempRemotePath`, verifies the temporary file, and renames it only after every requested check
|
|
557
|
-
passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies
|
|
687
|
+
passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies
|
|
688
|
+
the
|
|
558
689
|
path that was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath`
|
|
559
690
|
continues to describe the file that was actually verified, even after that temporary path has been renamed. Interpret
|
|
560
691
|
the final state with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
|
|
561
692
|
`posix-rename@openssh.com` extension; a new target uses standard SFTP rename. If the client cannot send the rename
|
|
562
|
-
request, the response reports `operationStatus="failed"
|
|
563
|
-
|
|
564
|
-
|
|
693
|
+
request or the server explicitly rejects it, the response reports `operationStatus="failed"` , `targetReplaced=false`
|
|
694
|
+
, and
|
|
695
|
+
`targetReplacementStatus="not_replaced"` . A lost completion reply after dispatch leaves the replacement unconfirmed;
|
|
696
|
+
the response reports `operationStatus="unknown"` , `targetReplaced=null` , and
|
|
565
697
|
`targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
|
|
566
698
|
cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent
|
|
567
|
-
and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The
|
|
699
|
+
and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The
|
|
700
|
+
standard
|
|
568
701
|
upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
|
|
569
702
|
commands. Directory manifest verification also reads the remote tree through SFTP.
|
|
570
703
|
|
|
571
|
-
`ssh_download` writes to a same-directory temporary file with mode `0600
|
|
572
|
-
|
|
704
|
+
`ssh_download` writes to a same-directory temporary file with mode `0600` , then renames it over the requested local
|
|
705
|
+
path
|
|
706
|
+
after the SFTP stream closes and the transferred byte count matches the size reported by SFTP `stat` . A new target
|
|
707
|
+
keeps
|
|
573
708
|
mode `0600`. Replacing a regular file preserves its `rwx` bits but does not copy setuid, setgid, or sticky bits. A
|
|
574
709
|
symlink, directory, or other non-regular target is rejected before the remote read starts. A failed, truncated, or
|
|
575
710
|
aborted download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings
|
|
@@ -580,11 +715,21 @@ stdout/stderr, with the effective user, cwd, and a suggested follow-up read comm
|
|
|
580
715
|
defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`, `read_offset`,
|
|
581
716
|
`requested_offset`, `read_bytes`, `read_end`, `next_offset`, `remaining_bytes`, `sample_kind`, and `truncated` so
|
|
582
717
|
callers can distinguish a full read, head, tail, byte-range, or line-range sample. Text reads never split a UTF-8
|
|
583
|
-
character. Use `next_offset` for the next range request. `lineRange` scans via SFTP without running remote shell
|
|
584
|
-
|
|
585
|
-
|
|
586
|
-
`
|
|
587
|
-
`
|
|
718
|
+
character. Use `next_offset` for the next range request. `lineRange` scans via SFTP without running remote shell
|
|
719
|
+
tools.
|
|
720
|
+
|
|
721
|
+
`ssh_upload` , `ssh_download` , `ssh_read_file` , `ssh_write_file` , `ssh_list_dir` , `ssh_file_info` , and
|
|
722
|
+
`ssh_mkdir` accept
|
|
723
|
+
`timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. Timeouts retain local and
|
|
724
|
+
remote probe diagnostics. Uploads and writes report `operationStatus="unknown"` when an
|
|
725
|
+
OPEN, WRITE, or CLOSE request was dispatched without a completion reply. Explicit server refusal returns `failed` .
|
|
726
|
+
Read-only upload preflight failures also return `failed` ,
|
|
727
|
+
with `failureStage="preflight"` and zero acknowledged bytes.
|
|
728
|
+
`failureStage`, the affected path, and `acknowledgedBytes` preserve the confirmed progress; `retryable=false` prevents
|
|
729
|
+
automatic replay of writes. Inspect that path before another write. Atomic upload errors identify the temporary path
|
|
730
|
+
separately from `finalRemotePath`; a failed temporary upload leaves the final target unchanged.
|
|
731
|
+
Download errors report `failed` and distinguish temporary transfer from `local_rename` ; an existing target remains
|
|
732
|
+
intact.
|
|
588
733
|
|
|
589
734
|
`ssh_list_dir` and `ssh_file_info` return `mode` as the numeric `07777` permission mask and `permissions` as display
|
|
590
735
|
text. The text uses `s`/`S` for setuid and setgid and `t`/`T` for sticky. `verifyMode` accepts four-digit octal values
|
|
@@ -597,14 +742,20 @@ from the display text.
|
|
|
597
742
|
Entries retain directory-first, name-based ordering, and `showHidden=false` excludes dot-prefixed names. Supplying any
|
|
598
743
|
filter or pagination parameter enables bounded responses, with defaults of 100 entries and 64 KiB per page.
|
|
599
744
|
|
|
600
|
-
| Parameter | Type
|
|
601
|
-
| ---------------- |
|
|
602
|
-
| `namePattern` | string
|
|
603
|
-
| `modifiedAfter` | ISO 8601
|
|
604
|
-
| `modifiedBefore` | ISO 8601
|
|
605
|
-
| `offset` |
|
|
606
|
-
| `limit` |
|
|
607
|
-
| `maxBytes` |
|
|
745
|
+
| Parameter | Type | Default |
|
|
746
|
+
| ---------------- | ---------------------- | ----------------------- |
|
|
747
|
+
| `namePattern` | string | None |
|
|
748
|
+
| `modifiedAfter` | ISO 8601 with timezone | None |
|
|
749
|
+
| `modifiedBefore` | ISO 8601 with timezone | None |
|
|
750
|
+
| `offset` | Nonnegative integer | `0` |
|
|
751
|
+
| `limit` | Positive integer | `100` in bounded mode |
|
|
752
|
+
| `maxBytes` | Positive integer | `65536` in bounded mode |
|
|
753
|
+
|
|
754
|
+
`namePattern` is case-sensitive and uses sync exclusions' `*` and `?`; other characters match literally.
|
|
755
|
+
`modifiedAfter` is inclusive, for example `2026-01-01T00:00:00Z` . `modifiedBefore` is exclusive and must be at or
|
|
756
|
+
after
|
|
757
|
+
`modifiedAfter`. `offset` selects the position in the filtered, sorted entries; `limit` bounds the returned count.
|
|
758
|
+
`maxBytes` counts emitted UTF-8 JSON, including metadata and formatting.
|
|
608
759
|
|
|
609
760
|
Name, time, and hidden-file conditions are combined with AND. The time interval is `[modifiedAfter, modifiedBefore)`;
|
|
610
761
|
equal bounds return an empty result. Bounded results include `count` for this page, `total_count` for all matching
|
|
@@ -619,20 +770,25 @@ ssh_list_dir(
|
|
|
619
770
|
)
|
|
620
771
|
```
|
|
621
772
|
|
|
622
|
-
The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete
|
|
773
|
+
The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete
|
|
774
|
+
entry
|
|
623
775
|
cannot fit, the tool returns `LIST_DIR_MAX_BYTES_TOO_SMALL`, `requiredBytes`, and an unchanged `offset`/`next_offset`;
|
|
624
776
|
raise `maxBytes` and retry that offset. Error diagnostics can exceed the requested budget. Entries are never split or
|
|
625
777
|
silently skipped to fit a page.
|
|
626
778
|
|
|
627
|
-
Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination,
|
|
779
|
+
Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination,
|
|
780
|
+
not
|
|
628
781
|
incremental remote enumeration or a frozen snapshot; directory changes between calls can shift offsets. Internal
|
|
629
|
-
listing, recursive downloads, sync, and directory verification retain their existing enumeration contracts. The
|
|
782
|
+
listing, recursive downloads, sync, and directory verification retain their existing enumeration contracts. The
|
|
783
|
+
default
|
|
630
784
|
ssh2/SFTP backend is unchanged; OpenSSH master mode still rejects standalone SFTP directory listing.
|
|
631
785
|
|
|
632
786
|
### Directory sync with rsync or SFTP
|
|
633
787
|
|
|
634
|
-
With the default ssh2 backend, smart sync selects rsync for a direct connection with a validated key path or usable
|
|
635
|
-
|
|
788
|
+
With the default ssh2 backend, smart sync selects rsync for a direct connection with a validated key path or usable
|
|
789
|
+
SSH
|
|
790
|
+
agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to a separate OpenSSH process
|
|
791
|
+
use
|
|
636
792
|
SFTP directly. The OpenSSH master backend always uses its selected master and requires rsync:
|
|
637
793
|
|
|
638
794
|
```
|
|
@@ -683,27 +839,44 @@ ssh_sync(..., delete=true, verify={deletions: true})
|
|
|
683
839
|
|
|
684
840
|
A directory source always means “copy the source directory contents into the destination root” in both rsync and SFTP
|
|
685
841
|
mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
|
|
686
|
-
source root; patterns without `/` match each basename.
|
|
842
|
+
source root; patterns without `/` match each basename. A trailing `/` restricts a pattern to directories:
|
|
843
|
+
`provider/` skips directories with that basename and their contents while retaining regular files named `provider`.
|
|
687
844
|
|
|
688
|
-
|
|
689
|
-
|
|
690
|
-
|
|
691
|
-
before transfer for a file. A known source file larger than the requested hash budget is also rejected before transfer.
|
|
845
|
+
A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation behavior. Downloads create missing local parents; an rsync parent-preparation failure returns `failureStage="local_prepare"` before the transfer process starts.
|
|
846
|
+
|
|
847
|
+
Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning, with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the client's absolute request deadline remain separate from progress-driven idle-timeout resets.
|
|
692
848
|
|
|
693
|
-
|
|
849
|
+
For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
|
|
850
|
+
transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a
|
|
851
|
+
directory
|
|
852
|
+
root hash. Set `verify.sha256=true` to compute and compare digests; omitting it or setting it to `false` skips both
|
|
853
|
+
local and remote hashing, including the SFTP transport check. `verify.count`, `verify.deletions`, and
|
|
854
|
+
`verify.staleFiles`
|
|
855
|
+
require a directory source and are rejected before transfer for a file. A known source file larger than the requested
|
|
856
|
+
hash budget is also rejected before transfer.
|
|
857
|
+
|
|
858
|
+
Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root
|
|
859
|
+
manifest,
|
|
694
860
|
owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
|
|
695
|
-
`verify.deletions=true` requires `delete=true
|
|
696
|
-
|
|
861
|
+
`verify.deletions=true` requires `delete=true` ; it records the destination before transfer and only checks whether
|
|
862
|
+
those
|
|
863
|
+
deletion candidates disappeared. `staleFiles` independently checks every extra destination entry. The response
|
|
864
|
+
contains
|
|
697
865
|
summaries and at most 20 mismatch samples, not the full manifest. The default limits are 10,000 entries, 256 MiB per
|
|
698
|
-
hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries
|
|
699
|
-
|
|
866
|
+
hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries` , `verify.maxFileBytes` , and
|
|
867
|
+
`verify.maxTotalBytes` to
|
|
868
|
+
raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total. Symlinks or unsupported filesystem entries that
|
|
869
|
+
were
|
|
700
870
|
skipped make verification explicitly `skipped` instead of reporting a partial match.
|
|
701
871
|
|
|
702
872
|
If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
|
|
703
873
|
`transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
|
|
704
|
-
`failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode
|
|
705
|
-
|
|
706
|
-
|
|
874
|
+
`failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode
|
|
875
|
+
or
|
|
876
|
+
permissions, mtime, and owner/group, plus a streamed SFTP SHA-256 comparison when `verify.sha256=true`.
|
|
877
|
+
`verifyOwner` and `verifyMode` apply to upload
|
|
878
|
+
single-file sync; directory, download, or dry-run requests using these scalar fields are rejected before transfer.
|
|
879
|
+
Use `verify.owner` and `verify.mode` for files and directory manifests. Verification does not run
|
|
707
880
|
`chown` or `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`;
|
|
708
881
|
replacing an existing local regular file preserves its `rwx` bits. These permissions can differ from the source even
|
|
709
882
|
when content and owner match, so a requested mode check can fail after a completed transfer.
|
|
@@ -714,15 +887,49 @@ OpenSSH process. OpenSSH master sessions bypass this credential selection and do
|
|
|
714
887
|
`preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
|
|
715
888
|
and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
|
|
716
889
|
for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
|
|
717
|
-
probe.
|
|
718
|
-
|
|
719
|
-
|
|
720
|
-
|
|
890
|
+
probe. The sync deadline also covers parent metadata probes, SFTP acquisition, per-file transfer, and verification;
|
|
891
|
+
parent probes outside sync retain their 10-second default. Canceling or exhausting the deadline blocks subsequent
|
|
892
|
+
OPEN,
|
|
893
|
+
MKDIR, and rename requests. Requests already sent can remain `unknown`. Local and remote directory traversal, content
|
|
894
|
+
hashing, deletion baselines and post-transfer ACL checks share that absolute deadline. Verification timeout closes
|
|
895
|
+
owned
|
|
896
|
+
hash streams and stops later checks, while preserving completed file and byte counters and `transferSuccess` ; the
|
|
897
|
+
result
|
|
898
|
+
has `success=false` and a timed-out verification outcome.
|
|
899
|
+
|
|
900
|
+
Directory root digests sort paths by their UTF-8 bytes, independent of enumeration order or locale. Case-distinct and
|
|
901
|
+
Unicode NFC/NFD-distinct names remain separate entries; file names are not normalized.
|
|
902
|
+
|
|
903
|
+
Rsync mode sets `StrictHostKeyChecking=accept-new` ; SFTP uses the established ssh2 connection's known_hosts policy.
|
|
904
|
+
For
|
|
905
|
+
the full OpenSSH host-certificate and configuration policy, reuse an existing OpenSSH master. SFTP does not support
|
|
906
|
+
`delete=true`; such a request fails explicitly instead of claiming deletion. Rsync statistics count complete itemized
|
|
907
|
+
lines from the entire stdout stream in both directions, independently of the bounded output preview; `outputTruncated`
|
|
908
|
+
indicates an omitted preview suffix.
|
|
909
|
+
|
|
910
|
+
When symlinks are skipped, verification describes the incomplete tree. For downloads, exclude those links and repeat
|
|
911
|
+
the
|
|
721
912
|
sync and verification; `followSymlinks` only controls uploads. Directory transfer failures retain known successful
|
|
722
|
-
file/byte counts and failure counters.
|
|
913
|
+
file/byte counts and failure counters. Single-file transfers register their file and byte counts as soon as upload
|
|
914
|
+
finishes or an atomic download is published, before hash verification. A verification timeout retains those counts and
|
|
915
|
+
reports verification as `unknown`; completed bytes do not establish a hash match. A timeout can leave remote state
|
|
916
|
+
`unknown` even when some files completed.
|
|
917
|
+
|
|
918
|
+
SFTP counts an upload only after all WRITE replies and the server CLOSE reply succeed. A WRITE failure or an early
|
|
919
|
+
close fails the
|
|
920
|
+
transfer, including when no error event is emitted. Concurrent directory uploads settle requests already issued before
|
|
921
|
+
returning the partial file, byte, and failure counters.
|
|
922
|
+
|
|
923
|
+
Recursive downloads check the real local destination against the allow-list before each directory side effect,
|
|
924
|
+
including
|
|
925
|
+
existing symlink ancestors. Symlinks resolving inside the allowed range remain usable. On Windows, each sibling-name
|
|
926
|
+
check uses the target directory's native case flag and ordinal comparison, preserves exact-name updates, and reports
|
|
927
|
+
an
|
|
928
|
+
error when native name semantics cannot be queried.
|
|
723
929
|
|
|
724
930
|
`ssh_upload(timeout=...)` applies that timeout to each metadata, digest, transfer, verification, rename, and cleanup
|
|
725
|
-
operation. A cleanup failure is reported separately. Tracked output ending with an incomplete UTF-8 character returns
|
|
931
|
+
operation. A cleanup failure is reported separately. Tracked output ending with an incomplete UTF-8 character returns
|
|
932
|
+
an
|
|
726
933
|
explicit encoding error once the operation is terminal; pending partial characters can still complete while running.
|
|
727
934
|
|
|
728
935
|
### Persistent PTY Sessions (top, tmux, etc.)
|
|
@@ -763,15 +970,24 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
763
970
|
|
|
764
971
|
`ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
|
|
765
972
|
`rawBufferLimit`, `rawBufferTruncated`, and `foregroundProcess`. List entries also expose `bufferSize`. These size
|
|
766
|
-
fields count bytes. PTY screen output is decoded incrementally. Raw output preserves the original bytes in
|
|
767
|
-
|
|
768
|
-
|
|
769
|
-
|
|
973
|
+
fields count bytes. PTY screen output is decoded incrementally. Raw output preserves the original bytes in
|
|
974
|
+
`dataBase64` ,
|
|
975
|
+
including invalid or partial UTF-8; `data` is a text preview. `rawBufferTruncated=true` means older raw output since
|
|
976
|
+
the
|
|
977
|
+
last clear was discarded at the byte limit. A raw read uses `clear=true` by default: its response reports the
|
|
978
|
+
pre-clear
|
|
979
|
+
byte count and truncation flag, then resets the raw buffer and flag. Screen reads do not clear raw state. When a
|
|
980
|
+
finite
|
|
770
981
|
command exits naturally, its final screen remains readable with `active=false` until explicit close or the
|
|
771
982
|
closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
|
|
772
983
|
`ssh_pty_write` returns `accepted=true` when the local stream accepts data. `backpressured=true` only reports a full
|
|
773
|
-
buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed
|
|
774
|
-
|
|
984
|
+
buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed` , `not_found` , `failed` , or
|
|
985
|
+
`unknown` ;
|
|
986
|
+
retryable close failures keep the PTY state for a later retry. Screen reads wait until previously queued xterm writes
|
|
987
|
+
have been parsed, including the final output before `active=false`. The output channel pauses at 1,048,576 unparsed
|
|
988
|
+
UTF-16 code units and resumes at 262,144 units; this parser backpressure is separate from the raw byte limit and
|
|
989
|
+
input-side `backpressured` flag. Parser failures close the output channel and return `parserError` alongside retained
|
|
990
|
+
raw output.
|
|
775
991
|
|
|
776
992
|
Common control sequences:
|
|
777
993
|
|
|
@@ -808,13 +1024,15 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
|
808
1024
|
|
|
809
1025
|
A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
|
|
810
1026
|
`listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. `ssh_forward_list` exposes
|
|
811
|
-
`lifecycle` and `acceptingConnections
|
|
1027
|
+
`lifecycle` and `acceptingConnections` ; a `closing` forward remains retryable but no longer accepts traffic. Timeout
|
|
1028
|
+
or
|
|
812
1029
|
callback failure keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful
|
|
813
1030
|
local close, the port can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port
|
|
814
1031
|
for incoming connection routing and `unforwardIn`.
|
|
815
1032
|
|
|
816
1033
|
Forward creation is tracked before `listen` or `forwardIn` completes. Disconnect cancels pending creation, closes a
|
|
817
|
-
local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A
|
|
1034
|
+
local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A
|
|
1035
|
+
forward
|
|
818
1036
|
stops accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward
|
|
819
1037
|
callbacks check the same lifecycle record before changing state, so a closed forward cannot reappear in
|
|
820
1038
|
`ssh_forward_list`. Each local connection tracks both the local socket and the SSH `forwardOut` channel. Closing or
|
|
@@ -847,8 +1065,10 @@ accumulate. Disconnect the alias to release a channel request that never complet
|
|
|
847
1065
|
| `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
|
|
848
1066
|
| `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
|
|
849
1067
|
|
|
850
|
-
Connection failures return `failureStage
|
|
851
|
-
`
|
|
1068
|
+
Connection failures return `failureStage` , `retryable` , and a bounded suggestion. `failureStage` is one of
|
|
1069
|
+
`preflight` ,
|
|
1070
|
+
`authentication` , `ready_timeout` , `transport_or_handshake` , `host_key` , or `unknown` ; multi-hop failures may
|
|
1071
|
+
also include
|
|
852
1072
|
`connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
|
|
853
1073
|
|
|
854
1074
|
### Exec Options
|
|
@@ -864,7 +1084,8 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
|
|
|
864
1084
|
| `useLoginUser` | boolean | false | Skip session-level runAs |
|
|
865
1085
|
| `loadProfile` | boolean | true | Load target user's shell profile for runAs |
|
|
866
1086
|
|
|
867
|
-
When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with
|
|
1087
|
+
When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&` , then runs
|
|
1088
|
+
the
|
|
868
1089
|
entire requested command as one escaped `eval` argument in the active login shell. A failed directory change or export
|
|
869
1090
|
prevents every part of the requested command from running, including text after `;`, newlines, or `||`, while Bash/Zsh
|
|
870
1091
|
syntax keeps the same interpreter semantics as a direct SSH command.
|
|
@@ -885,6 +1106,8 @@ Linux/macOS or `;` on Windows:
|
|
|
885
1106
|
export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
|
|
886
1107
|
```
|
|
887
1108
|
|
|
1109
|
+
Trusted root directories are resolved through filesystem aliases, including macOS system paths. Both the requested
|
|
1110
|
+
path and its resolved file must remain under an allowed root; descendant links outside allowed roots are rejected.
|
|
888
1111
|
Files outside the whitelist are rejected with `Invalid private key path: ...` or `Invalid config path: ...`.
|
|
889
1112
|
|
|
890
1113
|
### Optional File-Ops Path Whitelist
|
|
@@ -918,7 +1141,8 @@ Files exceeding these limits are rejected before being read.
|
|
|
918
1141
|
| `false` (default) | Skip and report in `skippedSymlinks` | Skip with `--no-links` |
|
|
919
1142
|
| `true` | Upload the link target contents | Follow with `-L` / `--copy-links` |
|
|
920
1143
|
|
|
921
|
-
Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample
|
|
1144
|
+
Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample
|
|
1145
|
+
paths;
|
|
922
1146
|
rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries
|
|
923
1147
|
and does not treat an incomplete manifest as a match.
|
|
924
1148
|
|