@pyrokine/mcp-ssh 2.4.0 → 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,20 +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`.
110
+
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.
112
116
 
113
117
  ### Command Execution
114
118
 
115
119
  | Tool | Description |
116
- |---------------------|-----------------------------------------------|
120
+ | ------------------- | --------------------------------------------- |
117
121
  | `ssh_exec` | Execute command (supports PTY mode) |
118
122
  | `ssh_exec_as_user` | Execute as different user (via `su`) |
119
123
  | `ssh_exec_sudo` | Execute with `sudo` |
@@ -125,17 +129,17 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
125
129
  ### Tracked operations
126
130
 
127
131
  | Tool | Description |
128
- |------------------------|--------------------------------------------------|
132
+ | ---------------------- | ------------------------------------------------ |
129
133
  | `ssh_operation_start` | Start a tracked long-running remote command |
130
134
  | `ssh_operation_status` | Read status, PID, exit code, and output counters |
131
- | `ssh_operation_read` | Read bounded stdout and stderr by byte offset |
132
- | `ssh_operation_cancel` | Verify the operation marker, then send TERM |
133
- | `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 |
134
138
 
135
139
  ### File Operations
136
140
 
137
141
  | Tool | Description |
138
- |------------------|------------------------------------------|
142
+ | ---------------- | ---------------------------------------- |
139
143
  | `ssh_upload` | Upload local file to remote server |
140
144
  | `ssh_download` | Download remote file to local |
141
145
  | `ssh_read_file` | Read remote file content |
@@ -148,7 +152,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
148
152
  ### PTY Sessions (Persistent Interactive Terminal)
149
153
 
150
154
  | Tool | Description |
151
- |------------------|----------------------------------------------------------------------|
155
+ | ---------------- | -------------------------------------------------------------------- |
152
156
  | `ssh_pty_start` | Start persistent PTY session (for top, htop, tmux, etc.) |
153
157
  | `ssh_pty_write` | Send data to PTY (keystrokes, commands) |
154
158
  | `ssh_pty_read` | Read PTY output (screen mode: current screen, raw mode: ANSI stream) |
@@ -159,7 +163,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
159
163
  ### Port Forwarding
160
164
 
161
165
  | Tool | Description |
162
- |----------------------|--------------------------------------------------------|
166
+ | -------------------- | ------------------------------------------------------ |
163
167
  | `ssh_forward_local` | Local port forwarding (ssh -L): access remote services |
164
168
  | `ssh_forward_remote` | Remote port forwarding (ssh -R): expose local services |
165
169
  | `ssh_forward_close` | Close port forwarding |
@@ -229,7 +233,8 @@ ssh_disconnect(alias="myserver")
229
233
  ### Connection Templates and runAs
230
234
 
231
235
  Templates can be provided through `SSH_MCP_TEMPLATES` or `~/.mcp-ssh/templates.json`. Explicit tool arguments override
232
- 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.
233
238
 
234
239
  ```json
235
240
  {
@@ -252,11 +257,13 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
252
257
  ```
253
258
 
254
259
  `ssh_connect` returns `identity`, `loginUser`, `runAs`, `reused`, `defaultEnvKeys`, `envKeys`, and `reusableSessions`
255
- for already connected aliases with the same `user@host:port` identity. Reusing an alias for a different identity is
256
- rejected with the existing and requested identities. Missing templates include available template names when they can be
257
- loaded. Missing `configHost` returns SSH config candidates and suggests `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`.
258
265
 
259
- ### Jump Host (Bastion)
266
+ ### Bastion connections (jump hosts)
260
267
 
261
268
  Connect to internal server via jump host:
262
269
 
@@ -284,9 +291,12 @@ Perfect for scenarios where you SSH as root but need to run commands as another
284
291
  // Output: appuser
285
292
  ```
286
293
 
287
- By default, shell profile is loaded to ensure environment variables are available (since `su -c` creates a
288
- non-interactive shell which doesn't execute rc files). Supports bash (`.bashrc`), zsh (`.zshrc`), and other shells (
289
- `.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.
290
300
 
291
301
  `ssh_exec` and `ssh_exec_as_user` return execution metadata: `loginUser`, `effectiveUser`, `identity`, `cwd`,
292
302
  `resolvedCwd`, `shell`, `profileLoaded`, `envInjectedKeys`, `failureKind`, `stdoutBytes`, `stderrBytes`, and truncation
@@ -300,18 +310,28 @@ tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` bl
300
310
  Use tracked operations when a command must continue beyond one synchronous tool call:
301
311
 
302
312
  ```
303
- ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
313
+ ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576, startTimeoutMs=30000)
304
314
  ssh_operation_status(operationId="op_xxx")
305
315
  ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
306
316
  ssh_operation_cancel(operationId="op_xxx")
307
317
  ```
308
318
 
309
- The start call returns an unpredictable `operationId`. The server keeps bounded stdout and stderr buffers, records the
310
- remote PID after verifying a per-operation marker, and expires completed records after `retentionMs`. `maxOutputBytes`
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`
311
324
  defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
312
325
  `ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
313
- PID are verified. If the SSH session disconnects while the command is active, its status becomes `unknown`; the server
314
- does not claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
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.
315
335
 
316
336
  ### Interactive Commands (PTY mode)
317
337
 
@@ -329,12 +349,17 @@ ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs=
329
349
 
330
350
  Use `ssh_exec_script` for log discovery and filtering, then use `ssh_read_file` to read large result files in chunks:
331
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
332
357
  ```
333
- ssh_exec_script(
334
- alias="server",
335
- 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",
336
- timeout=30000
337
- )
358
+
359
+ Run the script above, then read the result:
360
+
361
+ ```
362
+ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
338
363
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
339
364
  ```
340
365
 
@@ -353,7 +378,8 @@ ssh_connect(
353
378
 
354
379
  ### Quick One-shot Execution
355
380
 
356
- 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.
357
383
 
358
384
  ```
359
385
  ssh_quick_exec(
@@ -369,7 +395,15 @@ ssh_quick_exec(
369
395
  ```
370
396
  // Upload
371
397
  ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
372
- 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
+ )
373
407
  // Directories return UPLOAD_PATH_IS_DIRECTORY. Large files complete with a suggestion and recommended ssh_sync call.
374
408
 
375
409
  // Download
@@ -383,19 +417,42 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
383
417
  ```
384
418
 
385
419
  `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
386
- verification checks. `atomic=true` uploads to a same-directory temporary file, returns `diagnostics.tempRemotePath`,
387
- then renames it to the target path. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit
388
- post-transfer checks.
420
+ verification checks. `atomic=true` writes an unpredictable same-directory temporary path with exclusive SFTP creation,
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
430
+ `targetReplacementStatus="unknown"`; inspect the target before retrying. Temporary-file cleanup is attempted in both
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
433
+ 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.
435
+
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.
440
+
389
441
  Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
390
- stdout/stderr,
391
- with the effective user, cwd, and a suggested follow-up read command when available.
392
- `ssh_read_file` defaults to 1 MiB and rejects `maxBytes` above 16 MiB before remote transfer. It returns `total_size`,
393
- `read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
394
- 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.
395
451
 
396
452
  ### Directory sync with rsync or SFTP
397
453
 
398
- 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:
399
456
 
400
457
  ```
401
458
  // Sync local directory to remote (upload)
@@ -444,29 +501,28 @@ A directory source always means “copy the source directory contents into the d
444
501
  mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
445
502
  source root; patterns without `/` match each basename.
446
503
 
447
- Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root manifest,
448
- owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the destination
449
- before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently checks every
450
- extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full manifest. The
451
- default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries`,
452
- `verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total.
453
- Symlinks or unsupported filesystem entries that were skipped make verification explicitly `skipped` instead of
454
- 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.
455
512
 
456
513
  If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
457
514
  `transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
458
- `failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size,
459
- mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`. `verifyOwner` and
460
- `verifyMode` apply 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.
461
518
 
462
519
  Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
463
520
  jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
464
- `preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup, and
465
- the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible for
466
- rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the probe.
467
- Rsync mode sets
468
- `StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails explicitly instead of
469
- 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.
470
526
 
471
527
  ### Persistent PTY Sessions (top, tmux, etc.)
472
528
 
@@ -508,6 +564,9 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
508
564
  `rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
509
565
  When a finite command exits naturally, its final screen remains readable with `active=false` until explicit close or the
510
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.
511
570
 
512
571
  Common control sequences:
513
572
 
@@ -529,6 +588,9 @@ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>",
529
588
  // Remote forward: expose local dev server (3000) to remote port 8080
530
589
  ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
531
590
 
591
+ // Ask the SSH server to allocate a remote port; use remotePort from the result
592
+ ssh_forward_remote(alias="server", remotePort=0, localHost="127.0.0.1", localPort=3000)
593
+
532
594
  // List all forwards
533
595
  ssh_forward_list()
534
596
 
@@ -540,36 +602,51 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
540
602
  ```
541
603
 
542
604
  A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
543
- `listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. Timeout or callback failure
544
- keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful local close, the port
545
- can be rebound immediately.
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.
546
621
 
547
622
  ## Configuration Options
548
623
 
549
624
  ### Connection Options
550
625
 
551
- | Option | Type | Default | Description |
552
- |---------------------|--------|----------------|--------------------------------|
553
- | `host` | string | *required* | Server address |
554
- | `user` | string | *required* | Username |
555
- | `password` | string | - | Password authentication |
556
- | `keyPath` | string | - | Path to SSH private key |
557
- | `port` | number | 22 | SSH port |
558
- | `alias` | string | auto-generated | Connection alias for reference |
559
- | `template` | string | - | Template name |
560
- | `env` | object | - | Environment variables |
561
- | `defaultEnv` | object | - | Default env for this session |
562
- | `runAs` | string | - | Default execution user |
563
- | `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
564
- | `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
565
- | `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
566
-
567
- 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`.
568
645
 
569
646
  ### Exec Options
570
647
 
571
648
  | Option | Type | Default | Description |
572
- |-----------------|---------|---------------|--------------------------------------------|
649
+ | --------------- | ------- | ------------- | ------------------------------------------ |
573
650
  | `timeout` | number | 30000 | Command timeout in ms |
574
651
  | `cwd` | string | - | Working directory |
575
652
  | `env` | object | - | Additional environment variables |
@@ -579,6 +656,11 @@ Connection failures return `failureStage`, `retryable`, and a bounded suggestion
579
656
  | `useLoginUser` | boolean | false | Skip session-level runAs |
580
657
  | `loadProfile` | boolean | true | Load target user's shell profile for runAs |
581
658
 
659
+ When `cwd` or `env` is set, the generated shell command chains `cd` and each validated `export` with `&&`, then runs the
660
+ entire requested command as one escaped `eval` argument in the active login shell. A failed directory change or export
661
+ prevents every part of the requested command from running, including text after `;`, newlines, or `||`, while Bash/Zsh
662
+ syntax keeps the same interpreter semantics as a direct SSH command.
663
+
582
664
  ## Security
583
665
 
584
666
  ### Path Whitelist for Key/Config Files
@@ -607,8 +689,10 @@ directories (recommended for shared environments), set `SSH_MCP_FILE_OPS_ALLOW_D
607
689
  export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
608
690
  ```
609
691
 
610
- When set, any local path outside the whitelist is rejected. Symlinks are resolved via `realpath` to prevent escape.
611
- When unset, no restriction is applied (preserves flexibility).
692
+ When set, any local path outside the whitelist is rejected and symlinks are resolved via `realpath`.
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.
612
696
 
613
697
  ### File Size Limits
614
698
 
@@ -621,14 +705,14 @@ Files exceeding these limits are rejected before being read.
621
705
 
622
706
  `ssh_sync(direction="upload", ...)` handles local symlinks differently depending on the underlying transport:
623
707
 
624
- | `followSymlinks` | SFTP path | rsync path |
625
- |-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
626
- | `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Skipped via `--no-links` |
627
- | `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` |
628
712
 
629
713
  Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
630
- rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries and
631
- 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.
632
716
 
633
717
  ## Project Structure
634
718