@pyrokine/mcp-ssh 2.4.3 → 3.1.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
@@ -11,6 +11,63 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
11
11
  ![Linux](https://img.shields.io/badge/Linux-tested-success) ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
12
12
  ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
13
13
 
14
+ ## Migrating to 3.0
15
+
16
+ `maxOutputSize` now limits each exec stdout/stderr response by UTF-8 bytes instead of JavaScript string length.
17
+ Recalculate budgets for non-ASCII output and check `stdoutTruncated` / `stderrTruncated`; `maxOutputSize=3` can return
18
+ one Chinese character, not three. Text responses end at a complete character boundary.
19
+
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.
23
+
24
+ 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
28
+ the returned prefix, including whether its last line ends with a newline.
29
+
30
+ Windows connections require `remotePlatform="windows"`; local Windows does not change the remote default. Set
31
+ `commandShell` and `remotePathStyle` for the host, and an explicit `rsyncProfile` when using rsync with Windows. The
32
+ Windows behavior and examples below remain available.
33
+
34
+ ## Reusing an existing OpenSSH master
35
+
36
+ The default `backend="ssh2"` retains password/key authentication, bastion connections, SFTP, PTY, and forwarding. Choose
37
+ `backend="openssh"` to reuse a master already opened by your terminal:
38
+
39
+ ```text
40
+ ssh_connect(backend="openssh", configHost="myserver", alias="shared")
41
+ ssh_exec(alias="shared", command="pwd", cwd="/tmp", env={TASK: "inspect"})
42
+ ssh_sync(alias="shared", localPath="/local/data", remotePath="/remote/data", direction="upload", verify={sha256: true})
43
+ ```
44
+
45
+ `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`,
47
+ `Include`, and `ProxyJump` configuration, including user-configured `Match exec` commands. Execution then uses the
48
+ resolved target and socket without rereading that configuration.
49
+
50
+ This backend only reuses existing connections. A missing, replaced, or disconnected master returns an error; actual
51
+ command and rsync channels use a failing proxy if multiplexing fails, so they cannot start another SSH connection or
52
+ switch to ssh2/SFTP. Do not pass password, key, agent, or `jumpHost` authentication parameters in this mode.
53
+
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
56
+ conflicts, and login-user mismatches are checked; the response does not claim independent host identity authentication
57
+ from `ssh -G` or `ssh -O check`.
58
+
59
+ 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
62
+ remote Python installation. Separate SFTP tools, temporary script uploads, PTY, forwarding, and Windows combinations
63
+ return `unsupported_backend`.
64
+
65
+ Each command uses an independent shell. `runAs`, `cwd`, and `env` remain explicit; a terminal's `su` or exported
66
+ variables do not carry over. Canceling an operation only targets its verified process. Disconnecting an alias closes
67
+ that alias's own channels; MCP shutdown closes its own channels and subprocesses. The user's master and terminal
68
+ connections remain open. Interrupted operations retain `unknown` when their remote exit cannot be verified.
69
+ `ssh_reconnect` binds the alias to the existing configured master again and never creates a replacement master.
70
+
14
71
  ## Features
15
72
 
16
73
  - **Multiple Authentication**: Password, SSH key
@@ -29,7 +86,8 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
29
86
  - Send keystrokes and commands
30
87
  - Window resize support
31
88
  - **File Operations**: Upload, download, read, write, list directory (via SFTP)
32
- - **Smart Sync**: Directory sync with rsync (auto-fallback to SFTP if rsync unavailable)
89
+ - **Smart Sync**: File and directory synchronization; default ssh2 can use SFTP when rsync is unavailable, while the
90
+ OpenSSH backend requires rsync
33
91
  - **Environment Configuration**: LANG, LC_ALL, custom env vars
34
92
  - **Bastion Support**: Connect through jump hosts
35
93
 
@@ -105,8 +163,12 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
105
163
  | `ssh_reconnect` | Reconnect a disconnected session |
106
164
  | `ssh_config_list` | List hosts from ~/.ssh/config |
107
165
 
108
- `ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use
109
- `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
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,
171
+ jump-host, and replacement connections share this behavior without an additional option.
110
172
 
111
173
  `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
112
174
  the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled
@@ -126,6 +188,10 @@ pending, a channel returned by the delayed callback is destroyed before the conn
126
188
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
127
189
  | `ssh_exec_script` | Upload and run a temporary remote script |
128
190
 
191
+ For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
192
+ correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
193
+ execution. POSIX scripts retain their original content.
194
+
129
195
  ### Tracked operations
130
196
 
131
197
  | Tool | Description |
@@ -133,7 +199,7 @@ pending, a channel returned by the delayed callback is destroyed before the conn
133
199
  | `ssh_operation_start` | Start a tracked long-running remote command |
134
200
  | `ssh_operation_status` | Read status, PID, exit code, and output counters |
135
201
  | `ssh_operation_read` | Read bounded stdout and stderr by byte offset |
136
- | `ssh_operation_cancel` | Verify the operation marker, then send TERM |
202
+ | `ssh_operation_cancel` | Verify process identity before cancellation |
137
203
  | `ssh_operation_list` | List unexpired operations, optionally by alias |
138
204
 
139
205
  ### File Operations
@@ -169,6 +235,60 @@ pending, a channel returned by the delayed callback is destroyed before the conn
169
235
  | `ssh_forward_close` | Close port forwarding |
170
236
  | `ssh_forward_list` | List all port forwards |
171
237
 
238
+ ## Windows and cross-platform SSH
239
+
240
+ Set `remotePlatform="windows"` on connections to a Windows host. The default is `posix`, regardless of the client's OS.
241
+ Use `commandShell="powershell"` (default on Windows) or `"cmd"`, and set `remotePathStyle="win32"` (default) or
242
+ `"sftp-posix"` if the server exposes `/C:/...` paths. `cwd` and `env` are grouped with the command in the selected
243
+ shell; unsupported cmd expansion in injected values is rejected. `ssh_quick_exec` also accepts `remotePlatform`,
244
+ `commandShell`, and `agent`. Windows `runAs`, `ssh_exec_as_user`, and `ssh_exec_sudo` return
245
+ `unsupported_remote_platform` before issuing a remote command.
246
+
247
+ ```text
248
+ ssh_connect(host="example.com", user="tester", agent="\\\\.\\pipe\\openssh-ssh-agent", remotePlatform="windows", commandShell="powershell", remotePathStyle="win32", rsyncProfile="native-win32")
249
+ 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")
251
+ ```
252
+
253
+ `ssh_connect(agent="...")` passes the socket or pipe to ssh2, including OpenSSH named pipes and ssh2's `agent="pageant"`
254
+ 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
256
+ 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
258
+ environment agent when `none` is selected. The connection result reports `remotePlatform`, `commandShell`,
259
+ `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
261
+ and verify private DACLs before they contain data. Windows scripts and atomic uploads create an empty temporary file
262
+ through SFTP, verify its DACL, then write content; cleanup uses SFTP. Windows tracked operations report the PID and
263
+ creation time. Cancellation checks the process command line for its random marker and creation time before
264
+ `taskkill /T /F`; `cancellationStatus` reports `requested`, `unknown`, or `unsupported` without treating a closed SSH
265
+ channel as proof of cancellation. Windows ACL and process behavior need a native Windows or Windows SSH host for
266
+ end-to-end verification.
267
+
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
271
+ boundary; use `lineRange` or `binary=true`. Use an explicit UTF-16 encoding for nonzero offsets. `maxOutputSize` for
272
+ 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.
274
+
275
+ 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
277
+ remote root separately. `ssh_upload(atomic=true)` checks the SFTP `posix-rename@openssh.com` capability before
278
+ transferring data to replace an existing target; unsupported or unverified replacement leaves that target untouched.
279
+ `ssh_sync` uses `rsyncProfile` (`posix`, `native-win32`, `msys2`, `cygwin`) and optional `rsyncExecutable` on the
280
+ remote. A Windows local client or remote host requires an explicit profile for rsync; unavailable probes use SFTP with
281
+ `selectedTransport` and `decisionReason` reported. Transfer errors after rsync starts do not imply the remote state is
282
+ known.
283
+
284
+ Before either upload transport starts, Windows directory sync checks source names after `exclude` and `followSymlinks`
285
+ are applied. Potential collisions are compared using Windows ordinal case rules and the existing destination parent
286
+ directory's case-sensitive flag. A confirmed collision returns `windows_filename_collision`; a missing parent,
287
+ 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
289
+ does not infer rules for new directories from their ancestors. No candidate means no additional PowerShell or exec
290
+ requirement, so SFTP-only uploads remain supported; POSIX uploads retain their name semantics.
291
+
172
292
  ## Usage Examples
173
293
 
174
294
  ### Using SSH Config (Recommended)
@@ -301,9 +421,16 @@ user; otherwise a per-call `runAs` overrides the session `runAs`; otherwise the
301
421
  `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
302
422
  `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
303
423
  hints. Large output returns `stdoutHead`, `stdoutTail`, `stderrHead`, `stderrTail`, and `recommendedReadCommand`.
304
- Timeout errors include the same head/tail fields from output produced before the timeout. Commands with destructive,
305
- process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
306
- tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
424
+ Timeout errors include the same head/tail fields from output produced before the timeout. Stdout and stderr are decoded
425
+ incrementally, so a UTF-8 character split across SSH data chunks is returned intact. `commandRisk` reports
426
+ shell-specific destructive, privilege, credential-argument, process-control, and resource-use signals; read-only
427
+ searches containing a credential word and ordinary Python/Node commands are not flagged solely for those words.
428
+
429
+ `commandRisk` is diagnostic metadata and does not change command execution or its result. POSIX classification treats
430
+ here-doc bodies as input, supports quoted and partially quoted delimiters, backslash quoting, `<<-`, and multiple
431
+ 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,
433
+ and quoted input are not background operators.
307
434
 
308
435
  ### Tracked long-running commands
309
436
 
@@ -333,6 +460,12 @@ command that emits its marker and closes immediately still enters a terminal sta
333
460
  set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown`; the server does not
334
461
  claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
335
462
 
463
+ Tracked POSIX commands use `setsid -w` when available to wait for the command, including when `setsid` forks. Nonzero
464
+ command exits produce `failed`; a zero exit can still have stderr output. Commands execute under `sh`, so Bash-only
465
+ options such as `pipefail` require an explicit `bash -lc` command. Without `setsid`, `processGroup` is false and
466
+ cancellation targets the PID. POSIX cancellation validates the marker before sending TERM with signal syntax supported
467
+ by `sh` and Bash. System diagnostics produced during termination are retained as stderr output.
468
+
336
469
  ### Interactive Commands (PTY mode)
337
470
 
338
471
  For commands that need a terminal:
@@ -363,7 +496,9 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
363
496
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
364
497
  ```
365
498
 
366
- This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
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.
367
502
 
368
503
  ### With Environment Variables
369
504
 
@@ -431,28 +566,74 @@ committed it, so the response reports `operationStatus="unknown"`, `targetReplac
431
566
  cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent
432
567
  and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The standard
433
568
  upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
434
- commands. Explicit directory manifest verification still runs remote shell commands.
569
+ commands. Directory manifest verification also reads the remote tree through SFTP.
435
570
 
436
- `ssh_download` writes to a same-directory temporary file and renames it over the requested local path after the SFTP
437
- stream closes and the transferred byte count matches the size reported by SFTP `stat`. A failed, truncated, or aborted
438
- download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings reject empty
439
- names, `.` and `..`, NUL bytes, and path separators before constructing child paths.
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
573
+ mode `0600`. Replacing a regular file preserves its `rwx` bits but does not copy setuid, setgid, or sticky bits. A
574
+ symlink, directory, or other non-regular target is rejected before the remote read starts. A failed, truncated, or
575
+ aborted download removes the temporary file and leaves an existing local target unchanged. SFTP directory listings
576
+ reject empty names, `.` and `..`, NUL bytes, and path separators before constructing child paths.
440
577
 
441
578
  Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
442
579
  stdout/stderr, with the effective user, cwd, and a suggested follow-up read command when available. `ssh_read_file`
443
580
  defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`, `read_offset`,
444
581
  `requested_offset`, `read_bytes`, `read_end`, `next_offset`, `remaining_bytes`, `sample_kind`, and `truncated` so
445
582
  callers can distinguish a full read, head, tail, byte-range, or line-range sample. Text reads never split a UTF-8
446
- character. Use `next_offset` for the next range request.
583
+ character. Use `next_offset` for the next range request. `lineRange` scans via SFTP without running remote shell tools.
447
584
 
448
585
  `ssh_upload`, `ssh_download`, `ssh_read_file`, `ssh_write_file`, `ssh_list_dir`, `ssh_file_info`, and `ssh_mkdir` accept
449
586
  `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. A timeout returns
450
587
  `operationStatus="unknown"` and `retryable=true`; check the affected remote or local path before retrying.
451
588
 
589
+ `ssh_list_dir` and `ssh_file_info` return `mode` as the numeric `07777` permission mask and `permissions` as display
590
+ text. The text uses `s`/`S` for setuid and setgid and `t`/`T` for sticky. `verifyMode` accepts four-digit octal values
591
+ such as `4755` and permission text such as `-rwsr-xr-x`; checks compare the numeric mask rather than reconstructing it
592
+ from the display text.
593
+
594
+ ### Directory filters and pages
595
+
596
+ `ssh_list_dir` returns the complete `{success, path, count, files}` result when all six parameters below are omitted.
597
+ Entries retain directory-first, name-based ordering, and `showHidden=false` excludes dot-prefixed names. Supplying any
598
+ filter or pagination parameter enables bounded responses, with defaults of 100 entries and 64 KiB per page.
599
+
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 |
608
+
609
+ Name, time, and hidden-file conditions are combined with AND. The time interval is `[modifiedAfter, modifiedBefore)`;
610
+ equal bounds return an empty result. Bounded results include `count` for this page, `total_count` for all matching
611
+ entries, `offset`, `has_more`, and `next_offset`. Continue with `next_offset` and the same conditions until
612
+ `has_more=false`. An offset at or beyond the end returns an empty page and retains that offset.
613
+
614
+ ```text
615
+ ssh_list_dir(
616
+ alias="server", remotePath="/var/log/app", namePattern="*.log",
617
+ modifiedAfter="2026-01-01T00:00:00Z", modifiedBefore="2026-01-02T00:00:00Z",
618
+ offset=0, limit=100, maxBytes=65536
619
+ )
620
+ ```
621
+
622
+ The byte budget covers successful JSON text, not the MCP protocol envelope. If page metadata or the next complete entry
623
+ cannot fit, the tool returns `LIST_DIR_MAX_BYTES_TOO_SMALL`, `requiredBytes`, and an unchanged `offset`/`next_offset`;
624
+ raise `maxBytes` and retry that offset. Error diagnostics can exceed the requested budget. Entries are never split or
625
+ silently skipped to fit a page.
626
+
627
+ Each call performs a complete SFTP `readdir` before filtering and paging the response. This is response pagination, not
628
+ 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
630
+ ssh2/SFTP backend is unchanged; OpenSSH master mode still rejects standalone SFTP directory listing.
631
+
452
632
  ### Directory sync with rsync or SFTP
453
633
 
454
- Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password,
455
- inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
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
636
+ SFTP directly. The OpenSSH master backend always uses its selected master and requires rsync:
456
637
 
457
638
  ```
458
639
  // Sync local directory to remote (upload)
@@ -487,6 +668,9 @@ ssh_sync(..., dryRun=true)
487
668
  // Upload one file and verify remote owner/mode after transfer
488
669
  ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
489
670
 
671
+ // Verify one file after upload or download, including a directory destination
672
+ ssh_sync(..., verify={sha256: true, owner: true, mode: true, maxFileBytes: 268435456})
673
+
490
674
  // Verify a directory with bounded manifests
491
675
  ssh_sync(
492
676
  ...,
@@ -501,29 +685,46 @@ A directory source always means “copy the source directory contents into the d
501
685
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
502
686
  source root; patterns without `/` match each basename.
503
687
 
688
+ 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
+
504
693
  Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root manifest,
505
- owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the
506
- destination before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently
507
- checks every extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full
508
- manifest. The default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set
509
- `verify.maxEntries`, `verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per
510
- file, and 16 GiB total. Symlinks or unsupported filesystem entries that were skipped make verification explicitly
511
- `skipped` instead of reporting a partial match.
694
+ 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
697
+ 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
700
+ skipped make verification explicitly `skipped` instead of reporting a partial match.
512
701
 
513
702
  If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
514
703
  `transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
515
704
  `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode or
516
705
  permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply to upload
517
- single-file sync; use `verify.owner` and `verify.mode` for directory manifests.
518
-
519
- Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
520
- jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
706
+ single-file sync; `verify.owner` and `verify.mode` work for files and directory manifests. Verification does not run
707
+ `chown` or `chmod`. New SFTP directories use destination-side default permissions, and new SFTP downloads use `0600`;
708
+ replacing an existing local regular file preserves its `rwx` bits. These permissions can differ from the source even
709
+ when content and owner match, so a requested mode check can fail after a completed transfer.
710
+
711
+ For ssh2 sessions, rsync is selected for a direct connection with a validated key path or usable SSH agent. Password,
712
+ inline-key, and jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate
713
+ OpenSSH process. OpenSSH master sessions bypass this credential selection and do not fall back to SFTP.
521
714
  `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
522
715
  and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
523
716
  for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
524
717
  probe. Rsync mode sets `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails
525
718
  explicitly instead of claiming deletion. If you require strict host key verification and management, use SFTP mode.
526
719
 
720
+ When symlinks are skipped, verification describes the incomplete tree. For downloads, exclude those links and repeat the
721
+ 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.
723
+
724
+ `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
726
+ explicit encoding error once the operation is terminal; pending partial characters can still complete while running.
727
+
527
728
  ### Persistent PTY Sessions (top, tmux, etc.)
528
729
 
529
730
  For interactive commands that continuously refresh or require ongoing interaction:
@@ -561,8 +762,12 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
561
762
  ```
562
763
 
563
764
  `ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
564
- `rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
565
- When a finite command exits naturally, its final screen remains readable with `active=false` until explicit close or the
765
+ `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
770
+ command exits naturally, its final screen remains readable with `active=false` until explicit close or the
566
771
  closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
567
772
  `ssh_pty_write` returns `accepted=true` when the local stream accepts data. `backpressured=true` only reports a full
568
773
  buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed`, `not_found`, `failed`, or `unknown`;
@@ -614,30 +819,33 @@ stops accepting new local or remote connections as soon as close begins. Delayed
614
819
  callbacks check the same lifecycle record before changing state, so a closed forward cannot reappear in
615
820
  `ssh_forward_list`. Each local connection tracks both the local socket and the SSH `forwardOut` channel. Closing or
616
821
  failing either side destroys the other, and force close returns only after both sides are destroyed and
617
- `activeConnections` reaches zero. Pending `forwardOut` requests are limited to 32 per alias, and a close waits for every
618
- callback. If the SSH server never answers a channel-open request, close times out, keeps the forward retryable, and
619
- rejects another local forward on the same alias so pending ssh2 channels cannot accumulate. Disconnect the alias to
620
- release a channel request that never completes.
822
+ `activeConnections` reaches zero. Remote force close uses the same drain rule after `unforwardIn`; close and error
823
+ events from both ends of one connection decrement the count only once. Pending `forwardOut` requests are limited to 32
824
+ per alias, and a close waits for every callback. If the SSH server never answers a channel-open request, close times
825
+ out, keeps the forward retryable, and rejects another local forward on the same alias so pending ssh2 channels cannot
826
+ accumulate. Disconnect the alias to release a channel request that never completes.
621
827
 
622
828
  ## Configuration Options
623
829
 
624
830
  ### Connection Options
625
831
 
626
- | Option | Type | Default | Description |
627
- | ----------------------- | ------ | --------------- | ------------------------------------ |
628
- | `host` | string | _required_ | Server address |
629
- | `user` | string | _required_ | Username |
630
- | `password` | string | - | Password authentication |
631
- | `keyPath` | string | - | Path to SSH private key |
632
- | `port` | number | 22 | SSH port |
633
- | `alias` | string | auto-generated | Connection alias for reference |
634
- | `template` | string | - | Template name |
635
- | `env` | object | - | Environment variables |
636
- | `defaultEnv` | object | - | Default env for this session |
637
- | `runAs` | string | - | Default execution user |
638
- | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
639
- | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
640
- | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
832
+ | Option | Type | Default | Description |
833
+ | ----------------------- | ------ | --------------- | ---------------------------------------- |
834
+ | `backend` | string | `ssh2` | `ssh2` or existing-master-only `openssh` |
835
+ | `controlPath` | string | `ssh -G` value | Existing OpenSSH control socket |
836
+ | `host` | string | _required_ | Server address |
837
+ | `user` | string | _required_ | Username |
838
+ | `password` | string | - | Password authentication |
839
+ | `keyPath` | string | - | Path to SSH private key |
840
+ | `port` | number | 22 | SSH port |
841
+ | `alias` | string | auto-generated | Connection alias for reference |
842
+ | `template` | string | - | Template name |
843
+ | `env` | object | - | Environment variables |
844
+ | `defaultEnv` | object | - | Default env for this session |
845
+ | `runAs` | string | - | Default execution user |
846
+ | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
847
+ | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
848
+ | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
641
849
 
642
850
  Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`,
643
851
  `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include
@@ -651,7 +859,7 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
651
859
  | `cwd` | string | - | Working directory |
652
860
  | `env` | object | - | Additional environment variables |
653
861
  | `pty` | boolean | false | Enable PTY mode for interactive commands |
654
- | `maxOutputSize` | number | 10 MB chars | Output truncation limit |
862
+ | `maxOutputSize` | number | 10 MiB bytes | UTF-8 byte limit for each output stream |
655
863
  | `runAs` | string | session runAs | Per-command execution user |
656
864
  | `useLoginUser` | boolean | false | Skip session-level runAs |
657
865
  | `loadProfile` | boolean | true | Load target user's shell profile for runAs |