@pyrokine/mcp-ssh 2.4.1 → 2.4.2

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,8 +8,7 @@ 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)
12
- ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
11
+ ![Linux](https://img.shields.io/badge/Linux-tested-success) ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
13
12
  ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
14
13
 
15
14
  ## Features
@@ -22,7 +21,7 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
22
21
  - Basic exec with timeout
23
22
  - PTY mode (for interactive commands like `top`, `htop`)
24
23
  - `sudo` execution
25
- - `su` (switch user) execution - *run commands as different user*
24
+ - `su` (switch user) execution - _run commands as different user_
26
25
  - Batch execution
27
26
  - Parallel execution on multiple hosts
28
27
  - **Persistent PTY Sessions**: For long-running interactive commands (top, htop, tmux, vim, etc.)
@@ -32,19 +31,19 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
32
31
  - **File Operations**: Upload, download, read, write, list directory (via SFTP)
33
32
  - **Smart Sync**: Directory sync with rsync (auto-fallback to SFTP if rsync unavailable)
34
33
  - **Environment Configuration**: LANG, LC_ALL, custom env vars
35
- - **Jump Host Support**: Connect through bastion hosts
34
+ - **Bastion Support**: Connect through jump hosts
36
35
 
37
36
  ## Compatible Clients
38
37
 
39
38
  | Client | Status |
40
- |---------------------------|--------|
41
- | Claude Code | ✅ |
42
- | Claude Desktop | ✅ |
43
- | Cursor | ✅ |
44
- | Windsurf | ✅ |
45
- | Continue.dev | ✅ |
46
- | Cline | ✅ |
47
- | Any MCP-compatible client | ✅ |
39
+ | ------------------------- | ------ |
40
+ | Claude Code | ✅ |
41
+ | Claude Desktop | ✅ |
42
+ | Cursor | ✅ |
43
+ | Windsurf | ✅ |
44
+ | Continue.dev | ✅ |
45
+ | Cline | ✅ |
46
+ | Any MCP-compatible client | ✅ |
48
47
 
49
48
  ## Installation
50
49
 
@@ -85,14 +84,12 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
85
84
 
86
85
  ```json
87
86
  {
88
- "mcpServers": {
89
- "ssh": {
90
- "command": "node",
91
- "args": [
92
- "/path/to/mcp-ssh/dist/index.js"
93
- ]
87
+ "mcpServers": {
88
+ "ssh": {
89
+ "command": "node",
90
+ "args": ["/path/to/mcp-ssh/dist/index.js"]
91
+ }
94
92
  }
95
- }
96
93
  }
97
94
  ```
98
95
 
@@ -100,22 +97,27 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
100
97
 
101
98
  ### Connection Management
102
99
 
103
- | Tool | Description |
104
- |---------------------|---------------------------------------------------|
105
- | `ssh_connect` | Establish SSH connection (supports ~/.ssh/config) |
106
- | `ssh_disconnect` | Close connection |
100
+ | Tool | Description |
101
+ | ------------------- | ---------------------------------------------------- |
102
+ | `ssh_connect` | Establish SSH connection (supports ~/.ssh/config) |
103
+ | `ssh_disconnect` | Close connection |
107
104
  | `ssh_list_sessions` | List brief sessions; optional detail/field selection |
108
- | `ssh_reconnect` | Reconnect a disconnected session |
109
- | `ssh_config_list` | List hosts from ~/.ssh/config |
105
+ | `ssh_reconnect` | Reconnect a disconnected session |
106
+ | `ssh_config_list` | List hosts from ~/.ssh/config |
110
107
 
111
- `ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
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`.
112
110
 
113
- `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled them, so an old timer cannot disconnect a newer session with the same alias. A delayed `close` from the old client cannot leave stale resources attached to the alias. If a target connection is cancelled while a jump-host `forwardOut` is pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
111
+ `ssh_reconnect` invalidates operations, PTYs, forwards, and cached transfer capability bound to the old client before
112
+ the replacement connection is published. Automatic reconnect timers are bound to the session and client that scheduled
113
+ them, so an old timer cannot disconnect a newer session with the same alias. A delayed `close` from the old client
114
+ cannot leave stale resources attached to the alias. If a target connection is canceled while a jump-host `forwardOut` is
115
+ pending, a channel returned by the delayed callback is destroyed before the connection attempt fails.
114
116
 
115
117
  ### Command Execution
116
118
 
117
119
  | Tool | Description |
118
- |---------------------|-----------------------------------------------|
120
+ | ------------------- | --------------------------------------------- |
119
121
  | `ssh_exec` | Execute command (supports PTY mode) |
120
122
  | `ssh_exec_as_user` | Execute as different user (via `su`) |
121
123
  | `ssh_exec_sudo` | Execute with `sudo` |
@@ -127,17 +129,17 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
127
129
  ### Tracked operations
128
130
 
129
131
  | Tool | Description |
130
- |------------------------|--------------------------------------------------|
132
+ | ---------------------- | ------------------------------------------------ |
131
133
  | `ssh_operation_start` | Start a tracked long-running remote command |
132
134
  | `ssh_operation_status` | Read status, PID, exit code, and output counters |
133
- | `ssh_operation_read` | Read bounded stdout and stderr by byte offset |
134
- | `ssh_operation_cancel` | Verify the operation marker, then send TERM |
135
- | `ssh_operation_list` | List unexpired operations, optionally by alias |
135
+ | `ssh_operation_read` | Read bounded stdout and stderr by byte offset |
136
+ | `ssh_operation_cancel` | Verify the operation marker, then send TERM |
137
+ | `ssh_operation_list` | List unexpired operations, optionally by alias |
136
138
 
137
139
  ### File Operations
138
140
 
139
141
  | Tool | Description |
140
- |------------------|------------------------------------------|
142
+ | ---------------- | ---------------------------------------- |
141
143
  | `ssh_upload` | Upload local file to remote server |
142
144
  | `ssh_download` | Download remote file to local |
143
145
  | `ssh_read_file` | Read remote file content |
@@ -150,7 +152,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
150
152
  ### PTY Sessions (Persistent Interactive Terminal)
151
153
 
152
154
  | Tool | Description |
153
- |------------------|----------------------------------------------------------------------|
155
+ | ---------------- | -------------------------------------------------------------------- |
154
156
  | `ssh_pty_start` | Start persistent PTY session (for top, htop, tmux, etc.) |
155
157
  | `ssh_pty_write` | Send data to PTY (keystrokes, commands) |
156
158
  | `ssh_pty_read` | Read PTY output (screen mode: current screen, raw mode: ANSI stream) |
@@ -161,7 +163,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
161
163
  ### Port Forwarding
162
164
 
163
165
  | Tool | Description |
164
- |----------------------|--------------------------------------------------------|
166
+ | -------------------- | ------------------------------------------------------ |
165
167
  | `ssh_forward_local` | Local port forwarding (ssh -L): access remote services |
166
168
  | `ssh_forward_remote` | Remote port forwarding (ssh -R): expose local services |
167
169
  | `ssh_forward_close` | Close port forwarding |
@@ -231,7 +233,8 @@ ssh_disconnect(alias="myserver")
231
233
  ### Connection Templates and runAs
232
234
 
233
235
  Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
234
- template values.
236
+ template values. Each selected template is validated before connection. SSH ports must be integers from 1 through 65535;
237
+ an invalid template error identifies its name and field without returning its authentication values.
235
238
 
236
239
  ```json
237
240
  {
@@ -254,13 +257,13 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
254
257
  ```
255
258
 
256
259
  `ssh_connect` returns `identity`, `loginUser`, `runAs`, `reused`, `defaultEnvKeys`, `envKeys`, and `reusableSessions`
257
- from the session that was actually published. Concurrent calls reuse an alias only when the complete session configuration
258
- matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout settings. A conflicting
259
- pending or active connection is rejected even when its `user@host:port` identity is unchanged. Missing templates include
260
- available template names when they can be loaded. Missing `configHost` returns SSH config candidates and suggests
261
- `ssh_config_list`.
260
+ from the session that was actually published. Concurrent calls reuse an alias only when the complete session
261
+ configuration matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
262
+ settings. A conflicting pending or active connection is rejected even when its `user@host:port` identity is unchanged.
263
+ Missing templates include available template names when they can be loaded. Missing `configHost` returns SSH config
264
+ candidates and suggests `ssh_config_list`.
262
265
 
263
- ### Jump Host (Bastion)
266
+ ### Bastion connections (jump hosts)
264
267
 
265
268
  Connect to internal server via jump host:
266
269
 
@@ -288,9 +291,12 @@ Perfect for scenarios where you SSH as root but need to run commands as another
288
291
  // Output: appuser
289
292
  ```
290
293
 
291
- By default, shell profile is loaded to ensure environment variables are available (since `su -c` creates a
292
- non-interactive shell which doesn't execute rc files). Supports bash (`.bashrc`), zsh (`.zshrc`), and other shells (
293
- `.profile`). Disable with `loadProfile=false` if not needed.
294
+ By default, the shell profile is loaded so environment variables are available. Non-interactive `su -c` sessions do not
295
+ execute rc files automatically. Bash (`.bashrc`), zsh (`.zshrc`), and other shells (`.profile`) are supported. Disable
296
+ this behavior with `loadProfile=false`.
297
+
298
+ `ssh_exec`, `ssh_exec_as_user`, and `ssh_exec_sudo` use the same identity precedence: `useLoginUser=true` uses the login
299
+ user; otherwise a per-call `runAs` overrides the session `runAs`; otherwise the session `runAs` applies.
294
300
 
295
301
  `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
296
302
  `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
@@ -310,14 +316,22 @@ ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxByte
310
316
  ssh_operation_cancel(operationId="op_xxx")
311
317
  ```
312
318
 
313
- The start call returns an unpredictable `operationId`. The server creates the record before requesting the SSH channel, keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires terminal records after `retentionMs`. `startTimeoutMs` bounds channel setup, defaults to 30 seconds, and accepts up to 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks another pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes` defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours. `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and PID are verified. Stderr written by a shell profile before the marker is retained as operation output, including an unterminated preamble immediately followed by the marker. A line that uses the operation marker prefix with the wrong token or invalid process metadata ends the
314
- record as `failed`, closes its channel, and starts the configured retention period. Delayed exec, sudo, SFTP, PTY-start,
315
- and operation-start callbacks from a disconnected or replaced SSH session are rejected and their channels are destroyed.
316
- A sudo callback that arrives after timeout is also closed before any password is written. Operation listeners are installed
317
- inside the SSH exec callback before it returns, so a short command that emits its marker and closes immediately still enters
318
- a terminal state with `finishedAt` and `expiresAt` set. If the SSH session disconnects while a tracked command is active,
319
- its status becomes `unknown`; the server does not claim that the remote process stopped. `ssh_exec` keeps its existing
320
- synchronous timeout behavior.
319
+ The start call returns an unpredictable `operationId`. The server creates the record before requesting the SSH channel,
320
+ keeps bounded stdout and stderr buffers, records the remote PID after verifying a per-operation marker, and expires
321
+ terminal records after `retentionMs`. `startTimeoutMs` bounds channel setup, defaults to 30 seconds, and accepts up to
322
+ 10 minutes. A timeout returns the `operationId` in error details, keeps a queryable `unknown` record, and blocks another
323
+ pending start on that alias until the original channel request settles or the alias is disconnected. `maxOutputBytes`
324
+ defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
325
+ `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
326
+ PID are verified. Stderr written by a shell profile before the marker is retained as operation output, including an
327
+ unterminated preamble immediately followed by the marker. A line that uses the operation marker prefix with the wrong
328
+ token or invalid process metadata ends the record as `failed`, closes its channel, and starts the configured retention
329
+ period. Delayed exec, sudo, SFTP, PTY-start, and operation-start callbacks from a disconnected or replaced SSH session
330
+ are rejected and their channels are destroyed. A sudo callback that arrives after timeout is also closed before any
331
+ password is written. Operation listeners are installed inside the SSH exec callback before it returns, so a short
332
+ command that emits its marker and closes immediately still enters a terminal state with `finishedAt` and `expiresAt`
333
+ set. If the SSH session disconnects while a tracked command is active, its status becomes `unknown`; the server does not
334
+ claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
321
335
 
322
336
  ### Interactive Commands (PTY mode)
323
337
 
@@ -335,12 +349,17 @@ ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs=
335
349
 
336
350
  Use `ssh_exec_script` for log discovery and filtering, then use `ssh_read_file` to read large result files in chunks:
337
351
 
352
+ ```bash
353
+ find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' \
354
+ | sort -nr | head -20 > /tmp/mcp-log-files.txt
355
+ grep -n -I -F 'ERROR' /var/log/app/*.log \
356
+ | head -100 > /tmp/mcp-log-errors.txt
338
357
  ```
339
- ssh_exec_script(
340
- alias="server",
341
- script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
342
- timeout=30000
343
- )
358
+
359
+ Run the script above, then read the result:
360
+
361
+ ```
362
+ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
344
363
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
345
364
  ```
346
365
 
@@ -359,7 +378,8 @@ ssh_connect(
359
378
 
360
379
  ### Quick One-shot Execution
361
380
 
362
- No need to manage connections for single commands:
381
+ No need to manage connections for single commands. `ssh_quick_exec` creates a unique temporary alias for each call.
382
+ `readyTimeout` applies only while connecting; `timeout` applies only while the remote command runs.
363
383
 
364
384
  ```
365
385
  ssh_quick_exec(
@@ -375,7 +395,15 @@ ssh_quick_exec(
375
395
  ```
376
396
  // Upload
377
397
  ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
378
- ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
398
+ ssh_upload(
399
+ alias="server",
400
+ localPath="/tmp/config.json",
401
+ remotePath="/etc/app/config.json",
402
+ atomic=true,
403
+ verifySize=true,
404
+ verifyMd5=true,
405
+ verifyMode="0644"
406
+ )
379
407
  // Directories return UPLOAD_PATH_IS_DIRECTORY. Large files complete with a suggestion and recommended ssh_sync call.
380
408
 
381
409
  // Download
@@ -390,18 +418,18 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
390
418
 
391
419
  `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
392
420
  verification checks. `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
393
- returns `diagnostics.tempRemotePath`, verifies the temporary file, and renames it only after every requested check passes.
394
- Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies the path that
395
- was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath` continues to
396
- describe the file that was actually verified, even after that temporary path has been renamed. Interpret the final state
397
- with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
398
- `posix-rename@openssh.com` extension; a new target uses standard SFTP
399
- rename. If the client cannot send the rename request, the response reports `operationStatus="failed"`,
400
- `targetReplaced=false`, and `targetReplacementStatus="not_replaced"`. An error returned after the request was sent cannot
401
- prove whether the server committed it, so the response reports `operationStatus="unknown"`, `targetReplaced=null`, and
421
+ returns `diagnostics.tempRemotePath`, verifies the temporary file, and renames it only after every requested check
422
+ passes. Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies the
423
+ path that was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath`
424
+ continues to describe the file that was actually verified, even after that temporary path has been renamed. Interpret
425
+ the final state with `targetReplaced` and `targetReplacementStatus`. An existing target is replaced with the OpenSSH
426
+ `posix-rename@openssh.com` extension; a new target uses standard SFTP rename. If the client cannot send the rename
427
+ request, the response reports `operationStatus="failed"`, `targetReplaced=false`, and
428
+ `targetReplacementStatus="not_replaced"`. An error returned after the request was sent cannot prove whether the server
429
+ committed it, so the response reports `operationStatus="unknown"`, `targetReplaced=null`, and
402
430
  `targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
403
- cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent and
404
- target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The standard
431
+ cases. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit transfer checks. Parent
432
+ and target probes, recursive directory creation, file hashing, rename, and temporary-file cleanup use SFTP. The standard
405
433
  upload path works on SFTP-only servers and does not require GNU `stat`, `md5sum`, `sha256sum`, `mkdir`, `mv`, or `rm`
406
434
  commands. Explicit directory manifest verification still runs remote shell commands.
407
435
 
@@ -411,14 +439,20 @@ download removes the temporary file and leaves an existing local target unchange
411
439
  names, `.` and `..`, NUL bytes, and path separators before constructing child paths.
412
440
 
413
441
  Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
414
- stdout/stderr, with the effective user, cwd, and a suggested follow-up read command when available.
415
- `ssh_read_file` defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`,
416
- `read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
417
- from a head, tail, byte range, or line range sample.
442
+ stdout/stderr, with the effective user, cwd, and a suggested follow-up read command when available. `ssh_read_file`
443
+ defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`, `read_offset`,
444
+ `requested_offset`, `read_bytes`, `read_end`, `next_offset`, `remaining_bytes`, `sample_kind`, and `truncated` so
445
+ 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.
447
+
448
+ `ssh_upload`, `ssh_download`, `ssh_read_file`, `ssh_write_file`, `ssh_list_dir`, `ssh_file_info`, and `ssh_mkdir` accept
449
+ `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. A timeout returns
450
+ `operationStatus="unknown"` and `retryable=true`; check the affected remote or local path before retrying.
418
451
 
419
452
  ### Directory sync with rsync or SFTP
420
453
 
421
- Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
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:
422
456
 
423
457
  ```
424
458
  // Sync local directory to remote (upload)
@@ -467,29 +501,28 @@ A directory source always means “copy the source directory contents into the d
467
501
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
468
502
  source root; patterns without `/` match each basename.
469
503
 
470
- Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root manifest,
471
- owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the destination
472
- before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently checks every
473
- extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full manifest. The
474
- default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries`,
475
- `verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total.
476
- Symlinks or unsupported filesystem entries that were skipped make verification explicitly `skipped` instead of
477
- reporting a partial match.
504
+ 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.
478
512
 
479
513
  If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
480
514
  `transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
481
- `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size,
482
- mode or permissions, mtime, owner/group, and a streamed SFTP SHA-256 comparison. `verifyOwner` and `verifyMode` apply
483
- to upload single-file sync; use `verify.owner` and `verify.mode` for directory manifests.
515
+ `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size, mode or
516
+ 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.
484
518
 
485
519
  Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
486
520
  jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
487
- `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup, and
488
- the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible for
489
- rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the probe.
490
- Rsync mode sets
491
- `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails explicitly instead of
492
- claiming deletion. If you require strict host key verification and management, use SFTP mode.
521
+ `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup,
522
+ and the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
523
+ for rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
524
+ probe. Rsync mode sets `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails
525
+ explicitly instead of claiming deletion. If you require strict host key verification and management, use SFTP mode.
493
526
 
494
527
  ### Persistent PTY Sessions (top, tmux, etc.)
495
528
 
@@ -531,6 +564,9 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
531
564
  `rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
532
565
  When a finite command exits naturally, its final screen remains readable with `active=false` until explicit close or the
533
566
  closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
567
+ `ssh_pty_write` returns `accepted=true` when the local stream accepts data. `backpressured=true` only reports a full
568
+ buffer and does not mean the input was discarded. `ssh_pty_close` reports `closed`, `not_found`, `failed`, or `unknown`;
569
+ retryable close failures keep the PTY state for a later retry.
534
570
 
535
571
  Common control sequences:
536
572
 
@@ -566,43 +602,51 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
566
602
  ```
567
603
 
568
604
  A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
569
- `listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. Timeout or callback failure
570
- keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful local close, the port
571
- can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port for incoming connection
572
- routing and `unforwardIn`.
573
-
574
- Forward creation is tracked before `listen` or `forwardIn` completes. Disconnect cancels pending creation, closes a local
575
- listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A forward stops
576
- accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward callbacks
577
- check the same lifecycle record before changing state, so a closed forward cannot reappear in `ssh_forward_list`. Each local
578
- connection tracks both the local socket and the SSH `forwardOut` channel. Closing or failing either side destroys the other, and force close returns only after both sides are destroyed and `activeConnections` reaches zero. Pending `forwardOut` requests are limited to 32 per alias, and a close waits for every callback. If the SSH server never answers a channel-open request, close times out, keeps the forward retryable, and rejects another local forward on the same alias so pending ssh2 channels cannot accumulate. Disconnect the alias to release a channel request that never completes.
605
+ `listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. `ssh_forward_list` exposes
606
+ `lifecycle` and `acceptingConnections`; a `closing` forward remains retryable but no longer accepts traffic. Timeout or
607
+ callback failure keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful
608
+ local close, the port can be rebound immediately. `remotePort=0` returns the actual allocated port and uses that port
609
+ for incoming connection routing and `unforwardIn`.
610
+
611
+ Forward creation is tracked before `listen` or `forwardIn` completes. Disconnect cancels pending creation, closes a
612
+ local listener if it appears later, and removes a remotely allocated listener returned by a delayed callback. A forward
613
+ stops accepting new local or remote connections as soon as close begins. Delayed `forwardOut`, close, and unforward
614
+ callbacks check the same lifecycle record before changing state, so a closed forward cannot reappear in
615
+ `ssh_forward_list`. Each local connection tracks both the local socket and the SSH `forwardOut` channel. Closing or
616
+ 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.
579
621
 
580
622
  ## Configuration Options
581
623
 
582
624
  ### Connection Options
583
625
 
584
- | Option | Type | Default | Description |
585
- |---------------------|--------|----------------|--------------------------------|
586
- | `host` | string | *required* | Server address |
587
- | `user` | string | *required* | Username |
588
- | `password` | string | - | Password authentication |
589
- | `keyPath` | string | - | Path to SSH private key |
590
- | `port` | number | 22 | SSH port |
591
- | `alias` | string | auto-generated | Connection alias for reference |
592
- | `template` | string | - | Template name |
593
- | `env` | object | - | Environment variables |
594
- | `defaultEnv` | object | - | Default env for this session |
595
- | `runAs` | string | - | Default execution user |
596
- | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
597
- | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
598
- | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
599
-
600
- Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`, `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
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 |
641
+
642
+ Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`,
643
+ `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include
644
+ `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
601
645
 
602
646
  ### Exec Options
603
647
 
604
648
  | Option | Type | Default | Description |
605
- |-----------------|---------|---------------|--------------------------------------------|
649
+ | --------------- | ------- | ------------- | ------------------------------------------ |
606
650
  | `timeout` | number | 30000 | Command timeout in ms |
607
651
  | `cwd` | string | - | Working directory |
608
652
  | `env` | object | - | Additional environment variables |
@@ -646,9 +690,9 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
646
690
  ```
647
691
 
648
692
  When set, any local path outside the whitelist is rejected and symlinks are resolved via `realpath`.
649
- `ssh_sync(direction="upload", followSymlinks=true)` is rejected before transport selection while the whitelist is active.
650
- A symlink can change between validation and transfer, and rsync cannot bind the validated target to the later `-L` read.
651
- Keep `followSymlinks=false`, or copy regular files into an allowed directory before syncing.
693
+ `ssh_sync(direction="upload", followSymlinks=true)` is rejected before transport selection while the whitelist is
694
+ active. A symlink can change between validation and transfer, and rsync cannot bind the validated target to the later
695
+ `-L` read. Keep `followSymlinks=false`, or copy regular files into an allowed directory before syncing.
652
696
 
653
697
  ### File Size Limits
654
698
 
@@ -661,14 +705,14 @@ Files exceeding these limits are rejected before being read.
661
705
 
662
706
  `ssh_sync(direction="upload", ...)` handles local symlinks differently depending on the underlying transport:
663
707
 
664
- | `followSymlinks` | SFTP path | rsync path |
665
- |-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
666
- | `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Skipped via `--no-links` |
667
- | `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
708
+ | `followSymlinks` | SFTP path | rsync path |
709
+ | ----------------- | ------------------------------------ | --------------------------------- |
710
+ | `false` (default) | Skip and report in `skippedSymlinks` | Skip with `--no-links` |
711
+ | `true` | Upload the link target contents | Follow with `-L` / `--copy-links` |
668
712
 
669
713
  Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
670
- rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries and
671
- does not treat an incomplete manifest as a match.
714
+ rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries
715
+ and does not treat an incomplete manifest as a match.
672
716
 
673
717
  ## Project Structure
674
718