@pyrokine/mcp-ssh 3.1.0 → 3.3.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,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`, 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`; `auto` detects encoding at the file start, including for later pages. A U+FEFF at
26
- a nonzero offset remains content. A budget too small for the next complete text character returns an error instead of an
27
- empty page; malformed encoding at EOF also fails. Binary reads advance byte by byte. `lineRange` metadata describes only
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. Choose
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`, `Match`,
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`, `masterReused`, `masterPid`, `identityStatus="master_trusted"`, and observed login
55
- metadata. Trust belongs to the user-selected master, as in native OpenSSH multiplexing. Socket ownership, configuration
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`, `stat`, `head`, and `realpath`; missing capabilities fail explicitly.
61
- Bounded directory manifests and streamed SHA-256 checks use the same master and do not require an ssh2 session or a
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,24 @@ 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`, `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`; OpenSSH
167
- entries also include `masterReused` and `identityStatus`. Use `detail=true` for connection details or `fields=[...]` to
168
- select fields. Neither mode returns `keyPath`.
169
-
170
- ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests. Direct,
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
235
+ state, so dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias
236
+ that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and
237
+ an explicitly chosen conflicting alias returns an error.
238
+
239
+ ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
240
+ Direct,
171
241
  jump-host, and replacement connections share this behavior without an additional option.
172
242
 
173
243
  `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
174
244
  the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled
175
245
  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` is
246
+ cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut`
247
+ is
177
248
  pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
178
249
 
179
250
  ### Command Execution
@@ -188,10 +259,22 @@ pending, a channel returned by the delayed callback is destroyed before the conn
188
259
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
189
260
  | `ssh_exec_script` | Upload and run a temporary remote script |
190
261
 
262
+ `ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as
263
+ `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array
264
+ preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and
265
+ retains its cmd or PowerShell script invocation.
266
+
191
267
  For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
192
268
  correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
193
269
  execution. POSIX scripts retain their original content.
194
270
 
271
+ Host cancellation stops subsequent batch commands and queued parallel work, including batches with `stopOnError=false`.
272
+ It also stops later script upload, permission preparation, interpreter dispatch, and password input to a late sudo
273
+ channel.
274
+ Script cleanup uses a separate timeout of at most 30000 ms and removes only this request's temporary file.
275
+ `keepScript=true` retains a script once execution has started; an upload or preparation failure still cleans it up.
276
+ Canceling a request closes its own channels and leaves other requests and any reused OpenSSH master available.
277
+
195
278
  ### Tracked operations
196
279
 
197
280
  | Tool | Description |
@@ -215,6 +298,9 @@ execution. POSIX scripts retain their original content.
215
298
  | `ssh_mkdir` | Create remote directory |
216
299
  | `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
217
300
 
301
+ `ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream
302
+ with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
303
+
218
304
  ### PTY Sessions (Persistent Interactive Terminal)
219
305
 
220
306
  | Tool | Description |
@@ -237,7 +323,8 @@ execution. POSIX scripts retain their original content.
237
323
 
238
324
  ## Windows and cross-platform SSH
239
325
 
240
- Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix`, regardless of the client's OS.
326
+ Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix` , regardless of the client's
327
+ OS.
241
328
  Use `commandShell="powershell"` (default on Windows) or `"cmd"`, and set `remotePathStyle="win32"` (default) or
242
329
  `"sftp-posix"` if the server exposes `/C:/...` paths. `cwd` and `env` are grouped with the command in the selected
243
330
  shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec` also accepts `remotePlatform`,
@@ -245,19 +332,36 @@ shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec
245
332
  `unsupported_remote_platform` before issuing a remote command.
246
333
 
247
334
  ```text
248
- ssh_connect(host="example.com", user="tester", agent="\\\\.\\pipe\\openssh-ssh-agent", remotePlatform="windows", commandShell="powershell", remotePathStyle="win32", rsyncProfile="native-win32")
335
+ ssh_connect(
336
+ host="example.com",
337
+ user="tester",
338
+ agent="\\\\.\\pipe\\openssh-ssh-agent",
339
+ remotePlatform="windows",
340
+ commandShell="powershell",
341
+ remotePathStyle="win32",
342
+ rsyncProfile="native-win32"
343
+ )
249
344
  ssh_exec(alias="tester@example.com:22", command="Get-Location", cwd="C:\\Test Data", env={REGION:"test"})
250
- ssh_read_file(alias="tester@example.com:22", remotePath="C:\\Test Data\\report.txt", lineRange="1-20", encoding="utf16le")
345
+ ssh_read_file(
346
+ alias="tester@example.com:22",
347
+ remotePath="C:\\Test Data\\report.txt",
348
+ lineRange="1-20",
349
+ encoding="utf16le"
350
+ )
251
351
  ```
252
352
 
253
- `ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's `agent="pageant"`
353
+ `ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's
354
+ `agent="pageant"`
254
355
  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 with a
356
+ `IdentityAgent none` (or `agent="none"` ) disables agent authentication and environment socket fallback, including
357
+ with a
256
358
  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 the
359
+ `agent` takes precedence over SSH config. Reconnect preserves this choice, and external OpenSSH/rsync also disables
360
+ the
258
361
  environment agent when `none` is selected. The connection result reports `remotePlatform`, `commandShell`,
259
362
  `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 receive
363
+ `key_acl_insecure` and `key_acl_unverified` reject authentication. Windows session files and temporary downloads
364
+ receive
261
365
  and verify private DACLs before they contain data. Windows scripts and atomic uploads create an empty temporary file
262
366
  through SFTP, verify its DACL, then write content; cleanup uses SFTP. Windows tracked operations report the PID and
263
367
  creation time. Cancellation checks the process command line for its random marker and creation time before
@@ -265,15 +369,20 @@ creation time. Cancellation checks the process command line for its random marke
265
369
  channel as proof of cancellation. Windows ACL and process behavior need a native Windows or Windows SSH host for
266
370
  end-to-end verification.
267
371
 
268
- `ssh_read_file` reads `lineRange` through SFTP, including CRLF and UTF-8, UTF-16LE/BE, or GBK (`encoding="auto"` detects
269
- a BOM at the start). `binary=true` returns the bytes as base64 in `content` and `content_base64`. Byte offsets apply to
270
- the remote file. GBK byte-offset reads and tails are rejected because a random byte offset cannot prove a GBK character
372
+ `ssh_read_file` reads `lineRange` through SFTP, including CRLF and UTF-8, UTF-16LE/BE, or GBK (`encoding="auto"`
373
+ detects
374
+ a BOM at the start). `binary=true` returns the bytes as base64 in `content` and `content_base64` . Byte offsets apply
375
+ to
376
+ the remote file. GBK byte-offset reads and tails are rejected because a random byte offset cannot prove a GBK
377
+ character
271
378
  boundary; use `lineRange` or `binary=true`. Use an explicit UTF-16 encoding for nonzero offsets. `maxOutputSize` for
272
379
  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 preview.
380
+ separately. PTY raw reads include `dataBase64` containing the unmodified buffered bytes; `data` remains a text
381
+ preview.
274
382
 
275
383
  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 the
384
+ `verify.mode` are rejected on Windows. For a Windows directory, `verify.aclSddl` compares the expected DACL SDDL of
385
+ the
277
386
  remote root separately. `ssh_upload(atomic=true)` checks the SFTP `posix-rename@openssh.com` capability before
278
387
  transferring data to replace an existing target; unsupported or unverified replacement leaves that target untouched.
279
388
  `ssh_sync` uses `rsyncProfile` (`posix`, `native-win32`, `msys2`, `cygwin`) and optional `rsyncExecutable` on the
@@ -285,7 +394,8 @@ Before either upload transport starts, Windows directory sync checks source name
285
394
  are applied. Potential collisions are compared using Windows ordinal case rules and the existing destination parent
286
395
  directory's case-sensitive flag. A confirmed collision returns `windows_filename_collision`; a missing parent,
287
396
  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 check
397
+ creation, including in dry-run mode. Already-existing case-sensitive directories can keep case-distinct names. The
398
+ check
289
399
  does not infer rules for new directories from their ancestors. No candidate means no additional PowerShell or exec
290
400
  requirement, so SFTP-only uploads remain supported; POSIX uploads retain their name semantics.
291
401
 
@@ -339,13 +449,26 @@ Execute the same command on multiple connected hosts:
339
449
  ```
340
450
 
341
451
  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 at
343
- a time by default (configurable with `maxConcurrency`, max 8), and accepts `maxOutputSize` to cap each host result.
452
+ truncation fields, and diagnostic suggestions. `ssh_exec_parallel` limits one call to 32 aliases, runs up to 4 hosts
453
+ at
454
+ a time by default (configurable with `maxConcurrency` , max 8), and accepts `maxOutputSize` to cap each host result.
455
+ Both
456
+ parallel and batch calls share a 16 MiB request budget for stdout/stderr and head/tail previews. `outputBytes`,
457
+ `maxOutputBytes` , and `outputTruncated` describe that budget; each command retains its byte counts and truncation
458
+ flags.
459
+ Exhausting the budget truncates text while preserving every command's actual success, exit status, and batch
460
+ `executed`
461
+ count. A later disconnect or failed diagnostic preserves results already returned by completed commands.
462
+
463
+ A channel closed without an exit status returns `exitCode=null`, `failureKind="ssh_transport"`,
464
+ `operationStatus="unknown"` , and `retryable=false` , with any captured output. Inspect the remote state before
465
+ repeating
466
+ that command. A reported exit signal is retained as `exitSignal` and classified as a known remote command failure.
344
467
 
345
468
  ### Basic: Connect and Execute
346
469
 
347
470
  ```
348
- ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
471
+ ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
349
472
  ssh_exec(alias="myserver", command="ls -la /home")
350
473
  ssh_disconnect(alias="myserver")
351
474
  ```
@@ -353,8 +476,11 @@ ssh_disconnect(alias="myserver")
353
476
  ### Connection Templates and runAs
354
477
 
355
478
  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 65535;
357
- an invalid template error identifies its name and field without returning its authentication values.
479
+ template values. Each selected template is validated before connection. SSH ports must be integers from 1 through
480
+ 65535;
481
+ an invalid template error identifies its name and field without returning its authentication values. Invalid JSON
482
+ errors
483
+ report only the source and available numeric position or line/column, never source-text excerpts.
358
484
 
359
485
  ```json
360
486
  {
@@ -380,6 +506,11 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
380
506
  from the session that was actually published. Concurrent calls reuse an alias only when the complete session
381
507
  configuration matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
382
508
  settings. A conflicting pending or active connection is rejected even when its `user@host:port` identity is unchanged.
509
+ Conflict errors include `details.differingFields` with configuration field names only. OpenSSH configuration preparation
510
+ registers the requested alias, `configHost`, or initial endpoint. Disconnect cancels its owned `ssh -G` process and
511
+ prevents a later connection, including the preparation-to-connect handoff. A later connection can reuse the resolved
512
+ alias when `ssh -G` changes the hostname, user, or port.
513
+
383
514
  Missing templates include available template names when they can be loaded. Missing `configHost` returns SSH config
384
515
  candidates and suggests `ssh_config_list`.
385
516
 
@@ -391,12 +522,12 @@ Connect to internal server via jump host:
391
522
  ssh_connect(
392
523
  host="<internal-host>",
393
524
  user="root",
394
- keyPath="/home/.ssh/id_rsa",
525
+ keyPath="~/.ssh/id_rsa",
395
526
  alias="internal",
396
527
  jumpHost={
397
528
  host: "bastion.example.com",
398
529
  user: "admin",
399
- keyPath: "/home/.ssh/bastion_key"
530
+ keyPath: "~/.ssh/bastion_key"
400
531
  }
401
532
  )
402
533
  ```
@@ -406,30 +537,38 @@ ssh_connect(
406
537
  Perfect for scenarios where you SSH as root but need to run commands as another user:
407
538
 
408
539
  ```
409
- 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
540
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
410
541
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
411
542
  // Output: appuser
412
543
  ```
413
544
 
414
- By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do not
545
+ By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do
546
+ not
415
547
  execute rc files automatically. Bash (`.bashrc`), zsh (`.zshrc`), and other shells (`.profile`) are supported. Disable
416
548
  this behavior with `loadProfile=false`.
417
549
 
418
- `ssh_exec`, `ssh_exec_as_user`, and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the login
550
+ `ssh_exec` , `ssh_exec_as_user` , and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the
551
+ login
419
552
  user; otherwise a per-call `runAs` overrides the session `runAs`; otherwise the session `runAs` applies.
420
553
 
421
554
  `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
422
- `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
555
+ `resolvedCwd` , `shell` , `profileLoaded` , `envInjectedKeys` , `failureKind` , `stdoutBytes` , `stderrBytes` , and
556
+ truncation
423
557
  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 decoded
558
+ Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are
559
+ decoded
425
560
  incrementally, so a UTF-8 character split across SSH data chunks is returned intact. `commandRisk` reports
426
561
  shell-specific destructive, privilege, credential-argument, process-control, and resource-use signals; read-only
427
562
  searches containing a credential word and ordinary Python/Node commands are not flagged solely for those words.
428
563
 
429
- `commandRisk` is diagnostic metadata and does not change command execution or its result. POSIX classification treats
564
+ `commandRisk` is diagnostic metadata and does not change command execution or its result.
565
+ Search risk uses the execution timeout, including the default 30 seconds. Searches with timeouts at most five minutes
566
+ and `find` commands with a numeric `-maxdepth` are treated as bounded; separate unbounded searches and continuous
567
+ commands such as `tail -f` retain their risk signals. POSIX classification treats
430
568
  here-doc bodies as input, supports quoted and partially quoted delimiters, backslash quoting, `<<-`, and multiple
431
569
  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; `&&`, redirections, escaped ampersands,
570
+ expose active command substitutions. A Shell background `&` at EOF is reported; `&&` , redirections, escaped
571
+ ampersands,
433
572
  and quoted input are not background operators.
434
573
 
435
574
  ### Tracked long-running commands
@@ -443,10 +582,12 @@ ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxByte
443
582
  ssh_operation_cancel(operationId="op_xxx")
444
583
  ```
445
584
 
446
- The start call returns an unpredictable `operationId`. The server creates the record before requesting the SSH channel,
585
+ The start call returns an unpredictable `operationId` . The server creates the record before requesting the SSH
586
+ channel,
447
587
  keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires
448
588
  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 another
589
+ 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks
590
+ another
450
591
  pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes`
451
592
  defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
452
593
  `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
@@ -457,8 +598,13 @@ period. Delayed exec, sudo, SFTP, PTY-start, and operation-start callbacks from
457
598
  are rejected and their channels are destroyed. A sudo callback that arrives after timeout is also closed before any
458
599
  password is written. Operation listeners are installed inside the SSH exec callback before it returns, so a short
459
600
  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`; the server does not
461
- claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
601
+ set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown` ; the server does
602
+ not
603
+ claim that the remote process stopped. A channel that closes without an exit status or signal also becomes `unknown`,
604
+ with `exitCode=null` and retained output, marker, PID and retention metadata. Inspect the remote command before
605
+ repeating
606
+ it. Known exit codes, signals and confirmed cancellation keep their respective terminal states. `ssh_exec` keeps its
607
+ existing synchronous timeout behavior.
462
608
 
463
609
  Tracked POSIX commands use `setsid -w` when available to wait for the command, including when `setsid` forks. Nonzero
464
610
  command exits produce `failed`; a zero exit can still have stderr output. Commands execute under `sh`, so Bash-only
@@ -496,9 +642,12 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
496
642
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
497
643
  ```
498
644
 
499
- This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface. The
500
- `ssh_exec_script.timeout` value applies while uploading the temporary script, preparing its permissions, and running it.
501
- A stalled SFTP upload therefore ends on the requested timeout instead of using the default SFTP budget.
645
+ Log querying uses the general command and file tools. `ssh_exec_script.timeout` independently limits temporary script
646
+ upload, permission preparation, and execution. Explicit values use positive integer milliseconds, up to 3600000. Cleanup
647
+ has its own timeout: the smaller of the requested value and 30000 ms, or 30000 ms when omitted. Without an explicit
648
+ timeout, commands retain their 30000 ms default and SFTP retains 600000 ms. Host request deadlines apply separately.
649
+ Use `ssh_operation_start/status/read/cancel` for long observations: a host abort of synchronous exec leaves the remote
650
+ process's stop state unknown.
502
651
 
503
652
  ### With Environment Variables
504
653
 
@@ -506,7 +655,7 @@ A stalled SFTP upload therefore ends on the requested timeout instead of using t
506
655
  ssh_connect(
507
656
  host="<server-host>",
508
657
  user="root",
509
- keyPath="/home/.ssh/id_rsa",
658
+ keyPath="~/.ssh/id_rsa",
510
659
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
511
660
  )
512
661
  ```
@@ -520,7 +669,7 @@ No need to manage connections for single commands. `ssh_quick_exec` creates a un
520
669
  ssh_quick_exec(
521
670
  host="<server-host>",
522
671
  user="root",
523
- keyPath="/home/.ssh/id_rsa",
672
+ keyPath="~/.ssh/id_rsa",
524
673
  command="uptime"
525
674
  )
526
675
  ```
@@ -552,24 +701,30 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
552
701
  ```
553
702
 
554
703
  `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
555
- verification checks. `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
704
+ verification checks. Default uploads omit `verification`; requesting a check, such as `verifySize=true`, adds it.
705
+ `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
556
706
  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 the
707
+ passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies
708
+ the
558
709
  path that was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath`
559
710
  continues to describe the file that was actually verified, even after that temporary path has been renamed. Interpret
560
711
  the final state with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
561
712
  `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"`, `targetReplaced=false`, and
563
- `targetReplacementStatus="not_replaced"`. An error returned after the request was sent cannot prove whether the server
564
- committed it, so the response reports `operationStatus="unknown"`, `targetReplaced=null`, and
713
+ request or the server explicitly rejects it, the response reports `operationStatus="failed"` , `targetReplaced=false`
714
+ , and
715
+ `targetReplacementStatus="not_replaced"` . A lost completion reply after dispatch leaves the replacement unconfirmed;
716
+ the response reports `operationStatus="unknown"` , `targetReplaced=null` , and
565
717
  `targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
566
718
  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 standard
719
+ and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The
720
+ standard
568
721
  upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
569
722
  commands. Directory manifest verification also reads the remote tree through SFTP.
570
723
 
571
- `ssh_download` writes to a same-directory temporary file with mode `0600`, then renames it over the requested local path
572
- after the SFTP stream closes and the transferred byte count matches the size reported by SFTP `stat`. A new target keeps
724
+ `ssh_download` writes to a same-directory temporary file with mode `0600` , then renames it over the requested local
725
+ path
726
+ after the SFTP stream closes and the transferred byte count matches the size reported by SFTP `stat` . A new target
727
+ keeps
573
728
  mode `0600`. Replacing a regular file preserves its `rwx` bits but does not copy setuid, setgid, or sticky bits. A
574
729
  symlink, directory, or other non-regular target is rejected before the remote read starts. A failed, truncated, or
575
730
  aborted download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings
@@ -580,11 +735,23 @@ stdout/stderr, with the effective user, cwd, and a suggested follow-up read comm
580
735
  defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`, `read_offset`,
581
736
  `requested_offset`, `read_bytes`, `read_end`, `next_offset`, `remaining_bytes`, `sample_kind`, and `truncated` so
582
737
  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 tools.
584
-
585
- `ssh_upload`, `ssh_download`, `ssh_read_file`, `ssh_write_file`, `ssh_list_dir`, `ssh_file_info`, and `ssh_mkdir` accept
586
- `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. A timeout returns
587
- `operationStatus="unknown"` and `retryable=true`; check the affected remote or local path before retrying.
738
+ character. Use `next_offset` for the next range request. `lineRange` scans via SFTP without running remote shell
739
+ tools.
740
+
741
+ `ssh_upload` , `ssh_download` , `ssh_read_file` , `ssh_write_file` , `ssh_list_dir` , `ssh_file_info` , and
742
+ `ssh_mkdir` accept
743
+ `timeout` for one SFTP operation. Downloads use one total deadline for transfer and failure diagnostics;
744
+ when time expires or the host cancels, remote probing stops and local diagnostics remain available. It defaults to
745
+ 10 minutes and accepts up to one hour. Timeouts retain local and
746
+ remote probe diagnostics. Uploads and writes report `operationStatus="unknown"` when an
747
+ OPEN, WRITE, or CLOSE request was dispatched without a completion reply. Explicit server refusal returns `failed` .
748
+ Read-only upload preflight failures also return `failed` ,
749
+ with `failureStage="preflight"` and zero acknowledged bytes.
750
+ `failureStage`, the affected path, and `acknowledgedBytes` preserve the confirmed progress; `retryable=false` prevents
751
+ automatic replay of writes. Inspect that path before another write. Atomic upload errors identify the temporary path
752
+ separately from `finalRemotePath`; a failed temporary upload leaves the final target unchanged.
753
+ Download errors report `failed` and distinguish temporary transfer from `local_rename` ; an existing target remains
754
+ intact.
588
755
 
589
756
  `ssh_list_dir` and `ssh_file_info` return `mode` as the numeric `07777` permission mask and `permissions` as display
590
757
  text. The text uses `s`/`S` for setuid and setgid and `t`/`T` for sticky. `verifyMode` accepts four-digit octal values
@@ -597,14 +764,20 @@ from the display text.
597
764
  Entries retain directory-first, name-based ordering, and `showHidden=false` excludes dot-prefixed names. Supplying any
598
765
  filter or pagination parameter enables bounded responses, with defaults of 100 entries and 64 KiB per page.
599
766
 
600
- | Parameter | Type | Contract |
601
- | ---------------- | ----------------------------- | -------------------------------------------------------------------------------------------------------------------- |
602
- | `namePattern` | string | Case-sensitive name match using the same `*` and `?` wildcard rules as sync exclusions; other characters are literal |
603
- | `modifiedAfter` | ISO 8601 string with timezone | Inclusive modification-time lower bound, such as `2026-01-01T00:00:00Z` |
604
- | `modifiedBefore` | ISO 8601 string with timezone | Exclusive modification-time upper bound; it must be at or after `modifiedAfter` |
605
- | `offset` | nonnegative integer | Position in the filtered, sorted entries; default `0` |
606
- | `limit` | positive integer | Maximum returned entries; default `100` in bounded mode |
607
- | `maxBytes` | positive integer | UTF-8 byte budget for the emitted JSON text, including metadata and formatting; default `65536` in bounded mode |
767
+ | Parameter | Type | Default |
768
+ | ---------------- | ---------------------- | ----------------------- |
769
+ | `namePattern` | string | None |
770
+ | `modifiedAfter` | ISO 8601 with timezone | None |
771
+ | `modifiedBefore` | ISO 8601 with timezone | None |
772
+ | `offset` | Nonnegative integer | `0` |
773
+ | `limit` | Positive integer | `100` in bounded mode |
774
+ | `maxBytes` | Positive integer | `65536` in bounded mode |
775
+
776
+ `namePattern` is case-sensitive and uses sync exclusions' `*` and `?`; other characters match literally.
777
+ `modifiedAfter` is inclusive, for example `2026-01-01T00:00:00Z` . `modifiedBefore` is exclusive and must be at or
778
+ after
779
+ `modifiedAfter`. `offset` selects the position in the filtered, sorted entries; `limit` bounds the returned count.
780
+ `maxBytes` counts emitted UTF-8 JSON, including metadata and formatting.
608
781
 
609
782
  Name, time, and hidden-file conditions are combined with AND. The time interval is `[modifiedAfter, modifiedBefore)`;
610
783
  equal bounds return an empty result. Bounded results include `count` for this page, `total_count` for all matching
@@ -619,20 +792,25 @@ ssh_list_dir(
619
792
  )
620
793
  ```
621
794
 
622
- The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete entry
795
+ The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete
796
+ entry
623
797
  cannot fit, the tool returns `LIST_DIR_MAX_BYTES_TOO_SMALL`, `requiredBytes`, and an unchanged `offset`/`next_offset`;
624
798
  raise `maxBytes` and retry that offset. Error diagnostics can exceed the requested budget. Entries are never split or
625
799
  silently skipped to fit a page.
626
800
 
627
- Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination, not
801
+ Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination,
802
+ not
628
803
  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 default
804
+ listing, recursive downloads, sync, and directory verification retain their existing enumeration contracts. The
805
+ default
630
806
  ssh2/SFTP backend is unchanged; OpenSSH master mode still rejects standalone SFTP directory listing.
631
807
 
632
808
  ### Directory sync with rsync or SFTP
633
809
 
634
- With the default ssh2 backend, smart sync selects rsync for a direct connection with a validated key path or usable SSH
635
- agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to a separate OpenSSH process use
810
+ With the default ssh2 backend, smart sync selects rsync for a direct connection with a validated key path or usable
811
+ SSH
812
+ agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to a separate OpenSSH process
813
+ use
636
814
  SFTP directly. The OpenSSH master backend always uses its selected master and requires rsync:
637
815
 
638
816
  ```
@@ -683,27 +861,53 @@ ssh_sync(..., delete=true, verify={deletions: true})
683
861
 
684
862
  A directory source always means “copy the source directory contents into the destination root” in both rsync and SFTP
685
863
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
686
- source root; patterns without `/` match each basename.
864
+ source root; patterns without `/` match each basename. A trailing `/` restricts a pattern to directories:
865
+ `provider/` skips directories with that basename and their contents while retaining regular files named `provider`.
866
+
867
+ A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a
868
+ file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or
869
+ `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation
870
+ behavior. Downloads create missing local parents; a failure during rsync parent preparation returns
871
+ `failureStage="local_prepare"` before the transfer process starts.
872
+
873
+ Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including
874
+ recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification
875
+ sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a
876
+ token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning,
877
+ with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the
878
+ client's absolute request deadline remain separate from progress-driven idle-timeout resets.
687
879
 
688
880
  For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
689
- transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a directory
690
- root hash. `verify.count`, `verify.deletions`, and `verify.staleFiles` require a directory source and are rejected
691
- before transfer for a file. A known source file larger than the requested hash budget is also rejected before transfer.
692
-
693
- Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root manifest,
881
+ transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a
882
+ directory
883
+ root hash. Set `verify.sha256=true` to compute and compare digests; omitting it or setting it to `false` skips both
884
+ local and remote hashing, including the SFTP transport check. `verify.count`, `verify.deletions`, and
885
+ `verify.staleFiles`
886
+ require a directory source and are rejected before transfer for a file. A known source file larger than the requested
887
+ hash budget is also rejected before transfer.
888
+
889
+ Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root
890
+ manifest,
694
891
  owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
695
- `verify.deletions=true` requires `delete=true`; it records the destination before transfer and only checks whether those
696
- deletion candidates disappeared. `staleFiles` independently checks every extra destination entry. The response contains
892
+ `verify.deletions=true` requires `delete=true` ; it records the destination before transfer and only checks whether
893
+ those
894
+ deletion candidates disappeared. `staleFiles` independently checks every extra destination entry. The response
895
+ contains
697
896
  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`, `verify.maxFileBytes`, and `verify.maxTotalBytes` to
699
- raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total. Symlinks or unsupported filesystem entries that were
897
+ hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries` , `verify.maxFileBytes` , and
898
+ `verify.maxTotalBytes` to
899
+ raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total. Symlinks or unsupported filesystem entries that
900
+ were
700
901
  skipped make verification explicitly `skipped` instead of reporting a partial match.
701
902
 
702
903
  If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
703
904
  `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 or
705
- permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply to upload
706
- single-file sync; `verify.owner` and `verify.mode` work for files and directory manifests. Verification does not run
905
+ `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode
906
+ or
907
+ permissions, mtime, and owner/group, plus a streamed SFTP SHA-256 comparison when `verify.sha256=true`.
908
+ `verifyOwner` and `verifyMode` apply to upload
909
+ single-file sync; directory, download, or dry-run requests using these scalar fields are rejected before transfer.
910
+ Use `verify.owner` and `verify.mode` for files and directory manifests. Verification does not run
707
911
  `chown` or `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`;
708
912
  replacing an existing local regular file preserves its `rwx` bits. These permissions can differ from the source even
709
913
  when content and owner match, so a requested mode check can fail after a completed transfer.
@@ -714,15 +918,72 @@ OpenSSH process. OpenSSH master sessions bypass this credential selection and do
714
918
  `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
715
919
  and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
716
920
  for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
717
- probe. Rsync mode sets `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails
718
- explicitly instead of claiming deletion. If you require strict host key verification and management, use SFTP mode.
719
-
720
- When symlinks are skipped, verification describes the incomplete tree. For downloads, exclude those links and repeat the
921
+ probe. The sync deadline also covers parent metadata probes, SFTP acquisition, per-file transfer, and verification;
922
+ parent probes outside sync retain their 10-second default. Canceling or exhausting the deadline blocks subsequent
923
+ OPEN,
924
+ MKDIR, and rename requests. Requests already sent can remain `unknown`. Local and remote directory traversal, content
925
+ hashing, deletion baselines and post-transfer ACL checks share that absolute deadline. Verification timeout closes
926
+ owned
927
+ hash streams and stops later checks, while preserving completed file and byte counters and `transferSuccess` ; the
928
+ result
929
+ has `success=false` and a timed-out verification outcome.
930
+
931
+ `bandwidthLimitKiBps` optionally limits aggregate transfer payload to KiB/s (1 KiB = 1024 bytes), for rsync and
932
+ SFTP, in either direction. Omit it for the existing unrestricted speed. Concurrent and recursive SFTP file
933
+ transfers share one limit; metadata and explicitly requested verification reads have separate costs. For example,
934
+ `ssh_sync(..., bandwidthLimitKiBps=1024)` requests 1 MiB/s.
935
+
936
+ Canceling a running rsync request terminates and waits for its own local process group, retaining reported
937
+ itemization/deletion counts and `lastProgress`. The result is `cancelled=true`, `operationStatus="unknown"`: remote
938
+ writes or deletions already dispatched require inspection. The alias, other requests, and the reused OpenSSH master
939
+ remain available.
940
+
941
+ Directory `checks` uses `null` for unrequested checks, `true` for an executed match, and `false` for a mismatch.
942
+ Top-level `verificationStatus` distinguishes unrequested, skipped, matched, mismatched, and error outcomes.
943
+ Explicit single-file SHA-256 verification reads each endpoint once and shares its digest with
944
+ `transportVerification`; byte limits and metadata stability checks still apply.
945
+
946
+ `ssh_mkdir` uses the SFTP login identity, independently of command `runAs`. Its response includes `loginUser`,
947
+ `runAs`, `creationIdentity="sftp_login"`, and actual numeric `owner`, `group`, `mode`, and `permissions`. Directory
948
+ access follows those returned permissions; the tool preserves ownership and permission policy. Once creation is
949
+ acknowledged, a later metadata read failure returns `success=true`, `operationStatus="completed"`, `retryable=false`,
950
+ and `metadataStatus="unavailable"`. `metadataError` contains the metadata failure in the existing error format,
951
+ including any timeout details; unavailable `owner`, `group`, `mode`, and `permissions` are omitted. Use `ssh_file_info`
952
+ to read metadata again. Directory creation failures retain their original error response.
953
+
954
+ Directory root digests sort paths by their UTF-8 bytes, independent of enumeration order or locale. Case-distinct and
955
+ Unicode NFC/NFD-distinct names remain separate entries; file names are not normalized.
956
+
957
+ Rsync mode sets `StrictHostKeyChecking=accept-new` ; SFTP uses the established ssh2 connection's known_hosts policy.
958
+ For
959
+ the full OpenSSH host-certificate and configuration policy, reuse an existing OpenSSH master. SFTP does not support
960
+ `delete=true`; such a request fails explicitly instead of claiming deletion. Rsync statistics count complete itemized
961
+ lines from the entire stdout stream in both directions, independently of the bounded output preview; `outputTruncated`
962
+ indicates an omitted preview suffix.
963
+
964
+ When symlinks are skipped, verification describes the incomplete tree. For downloads, exclude those links and repeat
965
+ the
721
966
  sync and verification; `followSymlinks` only controls uploads. Directory transfer failures retain known successful
722
- file/byte counts and failure counters. A timeout can leave remote state `unknown` even when some files completed.
967
+ file/byte counts and failure counters. Single-file transfers register their file and byte counts as soon as upload
968
+ finishes or an atomic download is published, before hash verification. A verification timeout retains those counts and
969
+ reports verification as `unknown`; completed bytes do not establish a hash match. A timeout can leave remote state
970
+ `unknown` even when some files completed.
971
+
972
+ SFTP counts an upload only after all WRITE replies and the server CLOSE reply succeed. A WRITE failure or an early
973
+ close fails the
974
+ transfer, including when no error event is emitted. Concurrent directory uploads settle requests already issued before
975
+ returning the partial file, byte, and failure counters.
976
+
977
+ Recursive downloads check the real local destination against the allow-list before each directory side effect,
978
+ including
979
+ existing symlink ancestors. Symlinks resolving inside the allowed range remain usable. On Windows, each sibling-name
980
+ check uses the target directory's native case flag and ordinal comparison, preserves exact-name updates, and reports
981
+ an
982
+ error when native name semantics cannot be queried.
723
983
 
724
984
  `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 an
985
+ operation. A cleanup failure is reported separately. Tracked output ending with an incomplete UTF-8 character returns
986
+ an
726
987
  explicit encoding error once the operation is terminal; pending partial characters can still complete while running.
727
988
 
728
989
  ### Persistent PTY Sessions (top, tmux, etc.)
@@ -763,15 +1024,24 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
763
1024
 
764
1025
  `ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
765
1026
  `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 `dataBase64`,
767
- including invalid or partial UTF-8; `data` is a text preview. `rawBufferTruncated=true` means older raw output since the
768
- last clear was discarded at the byte limit. A raw read uses `clear=true` by default: its response reports the pre-clear
769
- byte count and truncation flag, then resets the raw buffer and flag. Screen reads do not clear raw state. When a finite
1027
+ fields count bytes. PTY screen output is decoded incrementally. Raw output preserves the original bytes in
1028
+ `dataBase64` ,
1029
+ including invalid or partial UTF-8; `data` is a text preview. `rawBufferTruncated=true` means older raw output since
1030
+ the
1031
+ last clear was discarded at the byte limit. A raw read uses `clear=true` by default: its response reports the
1032
+ pre-clear
1033
+ byte count and truncation flag, then resets the raw buffer and flag. Screen reads do not clear raw state. When a
1034
+ finite
770
1035
  command exits naturally, its final screen remains readable with `active=false` until explicit close or the
771
1036
  closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
772
1037
  `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`, `not_found`, `failed`, or `unknown`;
774
- retryable close failures keep the PTY state for a later retry.
1038
+ buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed` , `not_found` , `failed` , or
1039
+ `unknown` ;
1040
+ retryable close failures keep the PTY state for a later retry. Screen reads wait until previously queued xterm writes
1041
+ have been parsed, including the final output before `active=false`. The output channel pauses at 1,048,576 unparsed
1042
+ UTF-16 code units and resumes at 262,144 units; this parser backpressure is separate from the raw byte limit and
1043
+ input-side `backpressured` flag. Parser failures close the output channel and return `parserError` alongside retained
1044
+ raw output.
775
1045
 
776
1046
  Common control sequences:
777
1047
 
@@ -808,13 +1078,15 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
808
1078
 
809
1079
  A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
810
1080
  `listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. `ssh_forward_list` exposes
811
- `lifecycle` and `acceptingConnections`; a `closing` forward remains retryable but no longer accepts traffic. Timeout or
1081
+ `lifecycle` and `acceptingConnections` ; a `closing` forward remains retryable but no longer accepts traffic. Timeout
1082
+ or
812
1083
  callback failure keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful
813
1084
  local close, the port can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port
814
1085
  for incoming connection routing and `unforwardIn`.
815
1086
 
816
1087
  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 forward
1088
+ local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A
1089
+ forward
818
1090
  stops accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward
819
1091
  callbacks check the same lifecycle record before changing state, so a closed forward cannot reappear in
820
1092
  `ssh_forward_list`. Each local connection tracks both the local socket and the SSH `forwardOut` channel. Closing or
@@ -847,12 +1119,19 @@ accumulate. Disconnect the alias to release a channel request that never complet
847
1119
  | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
848
1120
  | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
849
1121
 
850
- Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`,
851
- `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include
1122
+ Connection failures return `failureStage` , `retryable` , and a bounded suggestion. `failureStage` is one of
1123
+ `preflight` ,
1124
+ `authentication` , `ready_timeout` , `transport_or_handshake` , `host_key` , or `unknown` ; multi-hop failures may
1125
+ also include
852
1126
  `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
853
1127
 
854
1128
  ### Exec Options
855
1129
 
1130
+ `ssh_exec(..., stdin="text")` sends UTF-8 input followed by EOF through ssh2 or the reused OpenSSH channel. Empty
1131
+ input sends EOF; omitting `stdin` retains existing behavior. Input stays out of the command string and
1132
+ input-delivery errors. A canceled request closes its own channel and returns remote state `unknown`, while the
1133
+ alias and master remain available. Commands that intentionally print their input still control their own output.
1134
+
856
1135
  | Option | Type | Default | Description |
857
1136
  | --------------- | ------- | ------------- | ------------------------------------------ |
858
1137
  | `timeout` | number | 30000 | Command timeout in ms |
@@ -864,7 +1143,8 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
864
1143
  | `useLoginUser` | boolean | false | Skip session-level runAs |
865
1144
  | `loadProfile` | boolean | true | Load target user's shell profile for runAs |
866
1145
 
867
- When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&`, then runs the
1146
+ When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&` , then runs
1147
+ the
868
1148
  entire requested command as one escaped `eval` argument in the active login shell. A failed directory change or export
869
1149
  prevents every part of the requested command from running, including text after `;`, newlines, or `||`, while Bash/Zsh
870
1150
  syntax keeps the same interpreter semantics as a direct SSH command.
@@ -885,6 +1165,8 @@ Linux/macOS or `;` on Windows:
885
1165
  export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
886
1166
  ```
887
1167
 
1168
+ Trusted root directories are resolved through filesystem aliases, including macOS system paths. Both the requested
1169
+ path and its resolved file must remain under an allowed root; descendant links outside allowed roots are rejected.
888
1170
  Files outside the whitelist are rejected with `Invalid private key path: ...` or `Invalid config path: ...`.
889
1171
 
890
1172
  ### Optional File-Ops Path Whitelist
@@ -918,7 +1200,8 @@ Files exceeding these limits are rejected before being read.
918
1200
  | `false` (default) | Skip and report in `skippedSymlinks` | Skip with `--no-links` |
919
1201
  | `true` | Upload the link target contents | Follow with `-L` / `--copy-links` |
920
1202
 
921
- Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
1203
+ Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample
1204
+ paths;
922
1205
  rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries
923
1206
  and does not treat an incomplete manifest as a match.
924
1207