@pyrokine/mcp-ssh 3.0.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 CHANGED
@@ -8,7 +8,8 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
8
8
  [![Node](https://img.shields.io/badge/node-%3E%3D20.19-green.svg)](https://nodejs.org/)
9
9
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)
10
10
 
11
- ![Linux](https://img.shields.io/badge/Linux-tested-success) ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
11
+ ![Linux](https://img.shields.io/badge/Linux-tested-success)
12
+ ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
12
13
  ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
13
14
 
14
15
  ## Migrating to 3.0
@@ -17,20 +18,120 @@ 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`, together with `unreadRawBytes` and `rawBufferLimit` in read/list results,
21
- now count raw bytes. A raw read with `clear=true` returns the counts and `rawBufferTruncated` state before clearing; the
22
- next read reflects the cleared buffer. Use `dataBase64` for exact ANSI or binary output and `data` for a UTF-8 preview.
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`; choose an explicit UTF-16 encoding for nonzero offsets. A budget too small for
26
- the next complete text character returns an error instead of an empty page; malformed encoding at EOF also fails. Binary
27
- reads advance byte by byte. `lineRange` metadata describes only the returned prefix, including whether its last line
28
- ends with a newline.
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
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
+
90
+ ## Reusing an existing OpenSSH master
91
+
92
+ The default `backend="ssh2"` retains password/key authentication, bastion connections, SFTP, PTY, and forwarding.
93
+ Choose
94
+ `backend="openssh"` to reuse a master already opened by your terminal:
95
+
96
+ ```text
97
+ ssh_connect(backend="openssh", configHost="myserver", alias="shared")
98
+ ssh_exec(alias="shared", command="pwd", cwd="/tmp", env={TASK: "inspect"})
99
+ ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", direction="upload", verify={sha256: true})
100
+ ```
101
+
102
+ `ssh -G` resolves the effective host, user, port, and `ControlPath`; an explicit `controlPath` overrides the socket
103
+ path. Custom `configPath` files retain the existing path and size checks. OpenSSH evaluates its normal `Host` ,
104
+ `Match` ,
105
+ `Include`, and `ProxyJump` configuration, including user-configured `Match exec` commands. Execution then uses the
106
+ resolved target and socket without rereading that configuration.
107
+
108
+ This backend only reuses existing connections. A missing, replaced, or disconnected master returns an error; actual
109
+ command and rsync channels use a failing proxy if multiplexing fails, so they cannot start another SSH connection or
110
+ switch to ssh2/SFTP. Do not pass password, key, agent, or `jumpHost` authentication parameters in this mode.
111
+
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
116
+ conflicts, and login-user mismatches are checked; the response does not claim independent host identity authentication
117
+ from `ssh -G` or `ssh -O check`.
118
+
119
+ Commands, tracked operations, file metadata, and rsync synchronization work on local and remote POSIX systems. Sync
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
126
+ remote Python installation. Separate SFTP tools, temporary script uploads, PTY, forwarding, and Windows combinations
127
+ return `unsupported_backend`.
128
+
129
+ Each command uses an independent shell. `runAs`, `cwd`, and `env` remain explicit; a terminal's `su` or exported
130
+ variables do not carry over. Canceling an operation only targets its verified process. Disconnecting an alias closes
131
+ that alias's own channels; MCP shutdown closes its own channels and subprocesses. The user's master and terminal
132
+ connections remain open. Interrupted operations retain `unknown` when their remote exit cannot be verified.
133
+ `ssh_reconnect` binds the alias to the existing configured master again and never creates a replacement master.
134
+
34
135
  ## Features
35
136
 
36
137
  - **Multiple Authentication**: Password, SSH key
@@ -49,7 +150,8 @@ Windows behavior and examples below remain available.
49
150
  - Send keystrokes and commands
50
151
  - Window resize support
51
152
  - **File Operations**: Upload, download, read, write, list directory (via SFTP)
52
- - **Smart Sync**: Directory sync with rsync (auto-fallback to SFTP if rsync unavailable)
153
+ - **Smart Sync**: File and directory synchronization; default ssh2 can use SFTP when rsync is unavailable, while the
154
+ OpenSSH backend requires rsync
53
155
  - **Environment Configuration**: LANG, LC_ALL, custom env vars
54
156
  - **Bastion Support**: Connect through jump hosts
55
157
 
@@ -125,16 +227,21 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
125
227
  | `ssh_reconnect` | Reconnect a disconnected session |
126
228
  | `ssh_config_list` | List hosts from ~/.ssh/config |
127
229
 
128
- `ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use
129
- `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
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.
130
235
 
131
- Connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests. Direct,
236
+ ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
237
+ Direct,
132
238
  jump-host, and replacement connections share this behavior without an additional option.
133
239
 
134
240
  `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
135
241
  the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled
136
242
  them, so an old timer cannot disconnect a newer session with the same alias. A delayed `close` from the old client
137
- cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut` is
243
+ cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut`
244
+ is
138
245
  pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
139
246
 
140
247
  ### Command Execution
@@ -149,6 +256,8 @@ pending, a channel returned by the delayed callback is destroyed before the conn
149
256
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
150
257
  | `ssh_exec_script` | Upload and run a temporary remote script |
151
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
+
152
261
  For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
153
262
  correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
154
263
  execution. POSIX scripts retain their original content.
@@ -176,6 +285,8 @@ execution. POSIX scripts retain their original content.
176
285
  | `ssh_mkdir` | Create remote directory |
177
286
  | `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
178
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
+
179
290
  ### PTY Sessions (Persistent Interactive Terminal)
180
291
 
181
292
  | Tool | Description |
@@ -198,7 +309,8 @@ execution. POSIX scripts retain their original content.
198
309
 
199
310
  ## Windows and cross-platform SSH
200
311
 
201
- Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix`, regardless of the client's OS.
312
+ Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix` , regardless of the client's
313
+ OS.
202
314
  Use `commandShell="powershell"` (default on Windows) or `"cmd"`, and set `remotePathStyle="win32"` (default) or
203
315
  `"sftp-posix"` if the server exposes `/C:/...` paths. `cwd` and `env` are grouped with the command in the selected
204
316
  shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec` also accepts `remotePlatform`,
@@ -206,19 +318,36 @@ shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec
206
318
  `unsupported_remote_platform` before issuing a remote command.
207
319
 
208
320
  ```text
209
- ssh_connect(host="example.com", user="tester", agent="\\\\.\\pipe\\openssh-ssh-agent", remotePlatform="windows", commandShell="powershell", remotePathStyle="win32", rsyncProfile="native-win32")
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
+ )
210
330
  ssh_exec(alias="tester@example.com:22", command="Get-Location", cwd="C:\\Test Data", env={REGION:"test"})
211
- ssh_read_file(alias="tester@example.com:22", remotePath="C:\\Test Data\\report.txt", lineRange="1-20", encoding="utf16le")
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
+ )
212
337
  ```
213
338
 
214
- `ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's `agent="pageant"`
339
+ `ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's
340
+ `agent="pageant"`
215
341
  on Windows. SSH config `IdentityAgent` supplies a socket when there is no explicit agent or private key.
216
- `IdentityAgent none` (or `agent="none"`) disables agent authentication and environment socket fallback, including with a
342
+ `IdentityAgent none` (or `agent="none"` ) disables agent authentication and environment socket fallback, including
343
+ with a
217
344
  private key and on ProxyJump hosts; password and key authentication remain available. An explicit argument or template
218
- `agent` takes precedence over SSH config. Reconnect preserves this choice, and external OpenSSH/rsync also disables the
345
+ `agent` takes precedence over SSH config. Reconnect preserves this choice, and external OpenSSH/rsync also disables
346
+ the
219
347
  environment agent when `none` is selected. The connection result reports `remotePlatform`, `commandShell`,
220
348
  `remotePathStyle`, and `keyAclStatus` for Windows private keys. Existing private keys are checked but never modified:
221
- `key_acl_insecure` and `key_acl_unverified` reject authentication. Windows session files and temporary downloads receive
349
+ `key_acl_insecure` and `key_acl_unverified` reject authentication. Windows session files and temporary downloads
350
+ receive
222
351
  and verify private DACLs before they contain data. Windows scripts and atomic uploads create an empty temporary file
223
352
  through SFTP, verify its DACL, then write content; cleanup uses SFTP. Windows tracked operations report the PID and
224
353
  creation time. Cancellation checks the process command line for its random marker and creation time before
@@ -226,15 +355,20 @@ creation time. Cancellation checks the process command line for its random marke
226
355
  channel as proof of cancellation. Windows ACL and process behavior need a native Windows or Windows SSH host for
227
356
  end-to-end verification.
228
357
 
229
- `ssh_read_file` reads `lineRange` through SFTP, including CRLF and UTF-8, UTF-16LE/BE, or GBK (`encoding="auto"` detects
230
- a BOM at the start). `binary=true` returns the bytes as base64 in `content` and `content_base64`. Byte offsets apply to
231
- the remote file. GBK byte-offset reads and tails are rejected because a random byte offset cannot prove a GBK character
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
232
364
  boundary; use `lineRange` or `binary=true`. Use an explicit UTF-16 encoding for nonzero offsets. `maxOutputSize` for
233
365
  exec caps each stdout/stderr text body by UTF-8 bytes; `stdoutTruncated` and `stderrTruncated` signal truncation
234
- separately. PTY raw reads include `dataBase64` containing the unmodified buffered bytes; `data` remains a text preview.
366
+ separately. PTY raw reads include `dataBase64` containing the unmodified buffered bytes; `data` remains a text
367
+ preview.
235
368
 
236
369
  Directory verification traverses SFTP with entry, depth, file-size, and total-hash budgets; POSIX `verify.owner` and
237
- `verify.mode` are rejected on Windows. For a Windows directory, `verify.aclSddl` compares the expected DACL SDDL of the
370
+ `verify.mode` are rejected on Windows. For a Windows directory, `verify.aclSddl` compares the expected DACL SDDL of
371
+ the
238
372
  remote root separately. `ssh_upload(atomic=true)` checks the SFTP `posix-rename@openssh.com` capability before
239
373
  transferring data to replace an existing target; unsupported or unverified replacement leaves that target untouched.
240
374
  `ssh_sync` uses `rsyncProfile` (`posix`, `native-win32`, `msys2`, `cygwin`) and optional `rsyncExecutable` on the
@@ -246,7 +380,8 @@ Before either upload transport starts, Windows directory sync checks source name
246
380
  are applied. Potential collisions are compared using Windows ordinal case rules and the existing destination parent
247
381
  directory's case-sensitive flag. A confirmed collision returns `windows_filename_collision`; a missing parent,
248
382
  unavailable shell, timeout, or incomplete query returns `case_semantics_unverified` before any upload or directory
249
- creation, including in dry-run mode. Already-existing case-sensitive directories can keep case-distinct names. The check
383
+ creation, including in dry-run mode. Already-existing case-sensitive directories can keep case-distinct names. The
384
+ check
250
385
  does not infer rules for new directories from their ancestors. No candidate means no additional PowerShell or exec
251
386
  requirement, so SFTP-only uploads remain supported; POSIX uploads retain their name semantics.
252
387
 
@@ -300,8 +435,21 @@ Execute the same command on multiple connected hosts:
300
435
  ```
301
436
 
302
437
  Each host result keeps the same execution metadata as `ssh_exec`, including `failureKind`, `effectiveUser`, `cwd`,
303
- truncation fields, and diagnostic suggestions. `ssh_exec_parallel` limits one call to 32 aliases, runs up to 4 hosts at
304
- a time by default (configurable with `maxConcurrency`, max 8), and accepts `maxOutputSize` to cap each host result.
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.
305
453
 
306
454
  ### Basic: Connect and Execute
307
455
 
@@ -314,8 +462,11 @@ ssh_disconnect(alias="myserver")
314
462
  ### Connection Templates and runAs
315
463
 
316
464
  Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
317
- template values. Each selected template is validated before connection. SSH ports must be integers from 1 through 65535;
318
- an invalid template error identifies its name and field without returning its authentication values.
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.
319
470
 
320
471
  ```json
321
472
  {
@@ -372,25 +523,33 @@ Perfect for scenarios where you SSH as root but need to run commands as another
372
523
  // Output: appuser
373
524
  ```
374
525
 
375
- By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do not
526
+ By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do
527
+ not
376
528
  execute rc files automatically. Bash (`.bashrc`), zsh (`.zshrc`), and other shells (`.profile`) are supported. Disable
377
529
  this behavior with `loadProfile=false`.
378
530
 
379
- `ssh_exec`, `ssh_exec_as_user`, and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the login
531
+ `ssh_exec` , `ssh_exec_as_user` , and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the
532
+ login
380
533
  user; otherwise a per-call `runAs` overrides the session `runAs`; otherwise the session `runAs` applies.
381
534
 
382
535
  `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
383
- `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
536
+ `resolvedCwd` , `shell` , `profileLoaded` , `envInjectedKeys` , `failureKind` , `stdoutBytes` , `stderrBytes` , and
537
+ truncation
384
538
  hints. Large output returns `stdoutHead`, `stdoutTail`, `stderrHead`, `stderrTail`, and `recommendedReadCommand`.
385
- Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are decoded
539
+ Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are
540
+ decoded
386
541
  incrementally, so a UTF-8 character split across SSH data chunks is returned intact. `commandRisk` reports
387
542
  shell-specific destructive, privilege, credential-argument, process-control, and resource-use signals; read-only
388
543
  searches containing a credential word and ordinary Python/Node commands are not flagged solely for those words.
389
544
 
390
- `commandRisk` is diagnostic metadata and does not change command execution or its result. POSIX classification treats
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
391
549
  here-doc bodies as input, supports quoted and partially quoted delimiters, backslash quoting, `<<-`, and multiple
392
550
  here-docs, and resumes after an exact, case-sensitive delimiter. Unquoted here-docs and double-quoted arguments still
393
- expose active command substitutions. A Shell background `&` at EOF is reported; `&&`, redirections, escaped ampersands,
551
+ expose active command substitutions. A Shell background `&` at EOF is reported; `&&` , redirections, escaped
552
+ ampersands,
394
553
  and quoted input are not background operators.
395
554
 
396
555
  ### Tracked long-running commands
@@ -404,10 +563,12 @@ ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxByte
404
563
  ssh_operation_cancel(operationId="op_xxx")
405
564
  ```
406
565
 
407
- The start call returns an unpredictable `operationId`. The server creates the record before requesting the SSH channel,
566
+ The start call returns an unpredictable `operationId` . The server creates the record before requesting the SSH
567
+ channel,
408
568
  keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires
409
569
  terminal records after `retentionMs`. `startTimeoutMs` bounds channel setup, defaults to 30 seconds, and accepts up to
410
- 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks another
570
+ 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks
571
+ another
411
572
  pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes`
412
573
  defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
413
574
  `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
@@ -418,8 +579,13 @@ period. Delayed exec, sudo, SFTP, PTY-start, and operation-start callbacks from
418
579
  are rejected and their channels are destroyed. A sudo callback that arrives after timeout is also closed before any
419
580
  password is written. Operation listeners are installed inside the SSH exec callback before it returns, so a short
420
581
  command that emits its marker and closes immediately still enters a terminal state with `finishedAt` and `expiresAt`
421
- set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown`; the server does not
422
- claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
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.
423
589
 
424
590
  Tracked POSIX commands use `setsid -w` when available to wait for the command, including when `setsid` forks. Nonzero
425
591
  command exits produce `failed`; a zero exit can still have stderr output. Commands execute under `sh`, so Bash-only
@@ -457,8 +623,10 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
457
623
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
458
624
  ```
459
625
 
460
- This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface. The
461
- `ssh_exec_script.timeout` value applies while uploading the temporary script, preparing its permissions, and running it.
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.
462
630
  A stalled SFTP upload therefore ends on the requested timeout instead of using the default SFTP budget.
463
631
 
464
632
  ### With Environment Variables
@@ -513,24 +681,30 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
513
681
  ```
514
682
 
515
683
  `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
516
- verification checks. `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
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,
517
686
  returns `diagnostics.tempRemotePath`, verifies the temporary file, and renames it only after every requested check
518
- passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies the
687
+ passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies
688
+ the
519
689
  path that was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath`
520
690
  continues to describe the file that was actually verified, even after that temporary path has been renamed. Interpret
521
691
  the final state with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
522
692
  `posix-rename@openssh.com` extension; a new target uses standard SFTP rename. If the client cannot send the rename
523
- request, the response reports `operationStatus="failed"`, `targetReplaced=false`, and
524
- `targetReplacementStatus="not_replaced"`. An error returned after the request was sent cannot prove whether the server
525
- committed it, so the response reports `operationStatus="unknown"`, `targetReplaced=null`, and
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
526
697
  `targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
527
698
  cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent
528
- and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The standard
699
+ and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The
700
+ standard
529
701
  upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
530
702
  commands. Directory manifest verification also reads the remote tree through SFTP.
531
703
 
532
- `ssh_download` writes to a same-directory temporary file with mode `0600`, then renames it over the requested local path
533
- after the SFTP stream closes and the transferred byte count matches the size reported by SFTP `stat`. A new target keeps
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
534
708
  mode `0600`. Replacing a regular file preserves its `rwx` bits but does not copy setuid, setgid, or sticky bits. A
535
709
  symlink, directory, or other non-regular target is rejected before the remote read starts. A failed, truncated, or
536
710
  aborted download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings
@@ -541,21 +715,81 @@ stdout/stderr, with the effective user, cwd, and a suggested follow-up read comm
541
715
  defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`, `read_offset`,
542
716
  `requested_offset`, `read_bytes`, `read_end`, `next_offset`, `remaining_bytes`, `sample_kind`, and `truncated` so
543
717
  callers can distinguish a full read, head, tail, byte-range, or line-range sample. Text reads never split a UTF-8
544
- character. Use `next_offset` for the next range request. `lineRange` scans via SFTP without running remote shell tools.
545
-
546
- `ssh_upload`, `ssh_download`, `ssh_read_file`, `ssh_write_file`, `ssh_list_dir`, `ssh_file_info`, and `ssh_mkdir` accept
547
- `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. A timeout returns
548
- `operationStatus="unknown"` and `retryable=true`; check the affected remote or local path before retrying.
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.
549
733
 
550
734
  `ssh_list_dir` and `ssh_file_info` return `mode` as the numeric `07777` permission mask and `permissions` as display
551
735
  text. The text uses `s`/`S` for setuid and setgid and `t`/`T` for sticky. `verifyMode` accepts four-digit octal values
552
736
  such as `4755` and permission text such as `-rwsr-xr-x`; checks compare the numeric mask rather than reconstructing it
553
737
  from the display text.
554
738
 
739
+ ### Directory filters and pages
740
+
741
+ `ssh_list_dir` returns the complete `{success, path, count, files}` result when all six parameters below are omitted.
742
+ Entries retain directory-first, name-based ordering, and `showHidden=false` excludes dot-prefixed names. Supplying any
743
+ filter or pagination parameter enables bounded responses, with defaults of 100 entries and 64 KiB per page.
744
+
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.
759
+
760
+ Name, time, and hidden-file conditions are combined with AND. The time interval is `[modifiedAfter, modifiedBefore)`;
761
+ equal bounds return an empty result. Bounded results include `count` for this page, `total_count` for all matching
762
+ entries, `offset`, `has_more`, and `next_offset`. Continue with `next_offset` and the same conditions until
763
+ `has_more=false`. An offset at or beyond the end returns an empty page and retains that offset.
764
+
765
+ ```text
766
+ ssh_list_dir(
767
+ alias="server", remotePath="/var/log/app", namePattern="*.log",
768
+ modifiedAfter="2026-01-01T00:00:00Z", modifiedBefore="2026-01-02T00:00:00Z",
769
+ offset=0, limit=100, maxBytes=65536
770
+ )
771
+ ```
772
+
773
+ The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete
774
+ entry
775
+ cannot fit, the tool returns `LIST_DIR_MAX_BYTES_TOO_SMALL`, `requiredBytes`, and an unchanged `offset`/`next_offset`;
776
+ raise `maxBytes` and retry that offset. Error diagnostics can exceed the requested budget. Entries are never split or
777
+ silently skipped to fit a page.
778
+
779
+ Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination,
780
+ not
781
+ incremental remote enumeration or a frozen snapshot; directory changes between calls can shift offsets. Internal
782
+ listing, recursive downloads, sync, and directory verification retain their existing enumeration contracts. The
783
+ default
784
+ ssh2/SFTP backend is unchanged; OpenSSH master mode still rejects standalone SFTP directory listing.
785
+
555
786
  ### Directory sync with rsync or SFTP
556
787
 
557
- Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password,
558
- inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
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
792
+ SFTP directly. The OpenSSH master backend always uses its selected master and requires rsync:
559
793
 
560
794
  ```
561
795
  // Sync local directory to remote (upload)
@@ -590,6 +824,9 @@ ssh_sync(..., dryRun=true)
590
824
  // Upload one file and verify remote owner/mode after transfer
591
825
  ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
592
826
 
827
+ // Verify one file after upload or download, including a directory destination
828
+ ssh_sync(..., verify={sha256: true, owner: true, mode: true, maxFileBytes: 268435456})
829
+
593
830
  // Verify a directory with bounded manifests
594
831
  ssh_sync(
595
832
  ...,
@@ -602,33 +839,98 @@ ssh_sync(..., delete=true, verify={deletions: true})
602
839
 
603
840
  A directory source always means “copy the source directory contents into the destination root” in both rsync and SFTP
604
841
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
605
- 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`.
844
+
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.
848
+
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.
606
857
 
607
- Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root manifest,
858
+ Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root
859
+ manifest,
608
860
  owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
609
- `verify.deletions=true` requires `delete=true`; it records the destination before transfer and only checks whether those
610
- deletion candidates disappeared. `staleFiles` independently checks every extra destination entry. The response contains
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
611
865
  summaries and at most 20 mismatch samples, not the full manifest. The default limits are 10,000 entries, 256 MiB per
612
- hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries`, `verify.maxFileBytes`, and `verify.maxTotalBytes` to
613
- raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total. Symlinks or unsupported filesystem entries that were
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
614
870
  skipped make verification explicitly `skipped` instead of reporting a partial match.
615
871
 
616
872
  If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
617
873
  `transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
618
- `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode or
619
- permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply to upload
620
- single-file sync; use `verify.owner` and `verify.mode` for directory manifests. Verification does not run `chown` or
621
- `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`; replacing an
622
- existing local regular file preserves its `rwx` bits. These permissions can differ from the source even when content and
623
- owner match, so a requested mode check can fail after a completed transfer.
624
-
625
- Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
626
- jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
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
880
+ `chown` or `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`;
881
+ replacing an existing local regular file preserves its `rwx` bits. These permissions can differ from the source even
882
+ when content and owner match, so a requested mode check can fail after a completed transfer.
883
+
884
+ For ssh2 sessions, rsync is selected for a direct connection with a validated key path or usable SSH agent. Password,
885
+ inline-key, and jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate
886
+ OpenSSH process. OpenSSH master sessions bypass this credential selection and do not fall back to SFTP.
627
887
  `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
628
888
  and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
629
889
  for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
630
- probe. Rsync mode sets `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails
631
- explicitly instead of claiming deletion. If you require strict host key verification and management, use SFTP mode.
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
912
+ sync and verification; `followSymlinks` only controls uploads. Directory transfer failures retain known successful
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.
929
+
930
+ `ssh_upload(timeout=...)` applies that timeout to each metadata, digest, transfer, verification, rename, and cleanup
931
+ operation. A cleanup failure is reported separately. Tracked output ending with an incomplete UTF-8 character returns
932
+ an
933
+ explicit encoding error once the operation is terminal; pending partial characters can still complete while running.
632
934
 
633
935
  ### Persistent PTY Sessions (top, tmux, etc.)
634
936
 
@@ -668,15 +970,24 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
668
970
 
669
971
  `ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
670
972
  `rawBufferLimit`, `rawBufferTruncated`, and `foregroundProcess`. List entries also expose `bufferSize`. These size
671
- fields count bytes. PTY screen output is decoded incrementally. Raw output preserves the original bytes in `dataBase64`,
672
- including invalid or partial UTF-8; `data` is a text preview. `rawBufferTruncated=true` means older raw output since the
673
- last clear was discarded at the byte limit. A raw read uses `clear=true` by default: its response reports the pre-clear
674
- byte count and truncation flag, then resets the raw buffer and flag. Screen reads do not clear raw state. When a finite
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
675
981
  command exits naturally, its final screen remains readable with `active=false` until explicit close or the
676
982
  closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
677
983
  `ssh_pty_write` returns `accepted=true` when the local stream accepts data. `backpressured=true` only reports a full
678
- buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed`, `not_found`, `failed`, or `unknown`;
679
- retryable close failures keep the PTY state for a later retry.
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.
680
991
 
681
992
  Common control sequences:
682
993
 
@@ -713,13 +1024,15 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
713
1024
 
714
1025
  A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
715
1026
  `listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. `ssh_forward_list` exposes
716
- `lifecycle` and `acceptingConnections`; a `closing` forward remains retryable but no longer accepts traffic. Timeout or
1027
+ `lifecycle` and `acceptingConnections` ; a `closing` forward remains retryable but no longer accepts traffic. Timeout
1028
+ or
717
1029
  callback failure keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful
718
1030
  local close, the port can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port
719
1031
  for incoming connection routing and `unforwardIn`.
720
1032
 
721
1033
  Forward creation is tracked before `listen` or `forwardIn` completes. Disconnect cancels pending creation, closes a
722
- local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A forward
1034
+ local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A
1035
+ forward
723
1036
  stops accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward
724
1037
  callbacks check the same lifecycle record before changing state, so a closed forward cannot reappear in
725
1038
  `ssh_forward_list`. Each local connection tracks both the local socket and the SSH `forwardOut` channel. Closing or
@@ -734,24 +1047,28 @@ accumulate. Disconnect the alias to release a channel request that never complet
734
1047
 
735
1048
  ### Connection Options
736
1049
 
737
- | Option | Type | Default | Description |
738
- | ----------------------- | ------ | --------------- | ------------------------------------ |
739
- | `host` | string | _required_ | Server address |
740
- | `user` | string | _required_ | Username |
741
- | `password` | string | - | Password authentication |
742
- | `keyPath` | string | - | Path to SSH private key |
743
- | `port` | number | 22 | SSH port |
744
- | `alias` | string | auto-generated | Connection alias for reference |
745
- | `template` | string | - | Template name |
746
- | `env` | object | - | Environment variables |
747
- | `defaultEnv` | object | - | Default env for this session |
748
- | `runAs` | string | - | Default execution user |
749
- | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
750
- | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
751
- | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
752
-
753
- Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`,
754
- `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include
1050
+ | Option | Type | Default | Description |
1051
+ | ----------------------- | ------ | --------------- | ---------------------------------------- |
1052
+ | `backend` | string | `ssh2` | `ssh2` or existing-master-only `openssh` |
1053
+ | `controlPath` | string | `ssh -G` value | Existing OpenSSH control socket |
1054
+ | `host` | string | _required_ | Server address |
1055
+ | `user` | string | _required_ | Username |
1056
+ | `password` | string | - | Password authentication |
1057
+ | `keyPath` | string | - | Path to SSH private key |
1058
+ | `port` | number | 22 | SSH port |
1059
+ | `alias` | string | auto-generated | Connection alias for reference |
1060
+ | `template` | string | - | Template name |
1061
+ | `env` | object | - | Environment variables |
1062
+ | `defaultEnv` | object | - | Default env for this session |
1063
+ | `runAs` | string | - | Default execution user |
1064
+ | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
1065
+ | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
1066
+ | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
1067
+
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
755
1072
  `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
756
1073
 
757
1074
  ### Exec Options
@@ -767,7 +1084,8 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
767
1084
  | `useLoginUser` | boolean | false | Skip session-level runAs |
768
1085
  | `loadProfile` | boolean | true | Load target user's shell profile for runAs |
769
1086
 
770
- When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&`, then runs the
1087
+ When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&` , then runs
1088
+ the
771
1089
  entire requested command as one escaped `eval` argument in the active login shell. A failed directory change or export
772
1090
  prevents every part of the requested command from running, including text after `;`, newlines, or `||`, while Bash/Zsh
773
1091
  syntax keeps the same interpreter semantics as a direct SSH command.
@@ -788,6 +1106,8 @@ Linux/macOS or `;` on Windows:
788
1106
  export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
789
1107
  ```
790
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.
791
1111
  Files outside the whitelist are rejected with `Invalid private key path: ...` or `Invalid config path: ...`.
792
1112
 
793
1113
  ### Optional File-Ops Path Whitelist
@@ -821,7 +1141,8 @@ Files exceeding these limits are rejected before being read.
821
1141
  | `false` (default) | Skip and report in `skippedSymlinks` | Skip with `--no-links` |
822
1142
  | `true` | Upload the link target contents | Follow with `-L` / `--copy-links` |
823
1143
 
824
- Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
1144
+ Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample
1145
+ paths;
825
1146
  rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries
826
1147
  and does not treat an incomplete manifest as a match.
827
1148