@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 +257 -49
- package/README_zh.md +251 -68
- package/dist/command-risk.d.ts +2 -1
- package/dist/command-risk.js +238 -87
- package/dist/directory-verification.d.ts +7 -3
- package/dist/directory-verification.js +302 -208
- package/dist/file-mode.d.ts +6 -0
- package/dist/file-mode.js +71 -0
- package/dist/file-ops.d.ts +38 -7
- package/dist/file-ops.js +822 -293
- package/dist/forward-manager.d.ts +2 -0
- package/dist/forward-manager.js +19 -10
- package/dist/openssh.d.ts +51 -0
- package/dist/openssh.js +528 -0
- package/dist/operation-manager.d.ts +4 -4
- package/dist/operation-manager.js +28 -3
- package/dist/pty-manager.d.ts +5 -13
- package/dist/pty-manager.js +47 -15
- package/dist/remote-platform.d.ts +13 -0
- package/dist/remote-platform.js +132 -0
- package/dist/security.js +12 -2
- package/dist/session-manager.d.ts +31 -15
- package/dist/session-manager.js +483 -120
- package/dist/ssh-config.d.ts +3 -0
- package/dist/ssh-config.js +48 -20
- package/dist/tools/connection.js +132 -3
- package/dist/tools/exec.d.ts +1 -0
- package/dist/tools/exec.js +108 -31
- package/dist/tools/file.js +406 -129
- package/dist/tools/operation.js +1 -1
- package/dist/tools/pty.js +5 -3
- package/dist/tools/utils.js +2 -2
- package/dist/types.d.ts +63 -2
- package/dist/utf8.d.ts +1 -0
- package/dist/utf8.js +10 -0
- package/dist/windows-acl.d.ts +4 -0
- package/dist/windows-acl.js +109 -0
- package/package.json +4 -3
package/README.md
CHANGED
|
@@ -11,6 +11,63 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
11
11
|
 
|
|
12
12
|

|
|
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**:
|
|
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
|
|
109
|
-
`detail=true` for connection details or `fields=[...]` to
|
|
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
|
|
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.
|
|
305
|
-
|
|
306
|
-
|
|
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.
|
|
569
|
+
commands. Directory manifest verification also reads the remote tree through SFTP.
|
|
435
570
|
|
|
436
|
-
`ssh_download` writes to a same-directory temporary file
|
|
437
|
-
stream closes and the transferred byte count matches the size reported by SFTP `stat`. A
|
|
438
|
-
|
|
439
|
-
|
|
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
|
-
|
|
455
|
-
inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use
|
|
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.
|
|
506
|
-
destination before transfer and only checks whether those
|
|
507
|
-
checks every extra destination entry. The response contains
|
|
508
|
-
manifest. The default limits are 10,000 entries, 256 MiB per
|
|
509
|
-
`verify.maxEntries`, `verify.maxFileBytes`, and `verify.maxTotalBytes` to
|
|
510
|
-
file, and 16 GiB total. Symlinks or unsupported filesystem entries that were
|
|
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;
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
|
|
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
|
|
565
|
-
|
|
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.
|
|
618
|
-
|
|
619
|
-
|
|
620
|
-
|
|
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
|
-
| `
|
|
629
|
-
| `
|
|
630
|
-
| `
|
|
631
|
-
| `
|
|
632
|
-
| `
|
|
633
|
-
| `
|
|
634
|
-
| `
|
|
635
|
-
| `
|
|
636
|
-
| `
|
|
637
|
-
| `
|
|
638
|
-
| `
|
|
639
|
-
| `
|
|
640
|
-
| `
|
|
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
|
|
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 |
|