@pyrokine/mcp-ssh 2.4.1 → 2.4.3
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 +174 -130
- package/README_zh.md +232 -128
- package/dist/directory-verification.js +29 -4
- package/dist/file-ops.d.ts +13 -8
- package/dist/file-ops.js +191 -115
- package/dist/forward-manager.js +9 -3
- package/dist/operation-manager.d.ts +0 -5
- package/dist/operation-manager.js +13 -55
- package/dist/pty-manager.d.ts +3 -3
- package/dist/pty-manager.js +61 -15
- package/dist/session-manager.d.ts +3 -3
- package/dist/session-manager.js +44 -20
- package/dist/sftp-timeout.d.ts +9 -0
- package/dist/sftp-timeout.js +49 -0
- package/dist/tools/connection.js +75 -29
- package/dist/tools/exec.js +16 -6
- package/dist/tools/file.js +101 -55
- package/dist/tools/forward.js +6 -5
- package/dist/tools/operation.js +2 -1
- package/dist/tools/pty.js +17 -13
- package/dist/tools/schema.d.ts +4 -0
- package/dist/tools/schema.js +9 -0
- package/dist/types.d.ts +15 -0
- package/dist/utf8.d.ts +3 -0
- package/dist/utf8.js +44 -0
- package/package.json +8 -8
package/README.md
CHANGED
|
@@ -8,8 +8,7 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
8
8
|
[](https://nodejs.org/)
|
|
9
9
|
[](https://modelcontextprotocol.io/)
|
|
10
10
|
|
|
11
|
-

|
|
12
|
-

|
|
11
|
+
 
|
|
13
12
|

|
|
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 -
|
|
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
|
-
- **
|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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
|
|
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
|
|
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
|
|
258
|
-
matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
|
|
259
|
-
pending or active connection is rejected even when its `user@host:port` identity is unchanged.
|
|
260
|
-
available template names when they can be loaded. Missing `configHost` returns SSH config
|
|
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
|
-
###
|
|
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
|
|
292
|
-
|
|
293
|
-
|
|
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,
|
|
314
|
-
|
|
315
|
-
|
|
316
|
-
|
|
317
|
-
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
|
|
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
|
-
|
|
340
|
-
|
|
341
|
-
|
|
342
|
-
|
|
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(
|
|
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
|
|
394
|
-
Responses distinguish `finalRemotePath` from the actual verification target: `verifiedRemotePath` identifies the
|
|
395
|
-
was probed, and atomic verification also returns `verifiedTempRemotePath`. `verification.actual.remotePath`
|
|
396
|
-
describe the file that was actually verified, even after that temporary path has been renamed. Interpret
|
|
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
|
-
|
|
400
|
-
`
|
|
401
|
-
|
|
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
|
|
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
|
-
|
|
416
|
-
`
|
|
417
|
-
|
|
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,
|
|
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,
|
|
471
|
-
owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the
|
|
472
|
-
before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently
|
|
473
|
-
extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full
|
|
474
|
-
default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set
|
|
475
|
-
`verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per
|
|
476
|
-
Symlinks or unsupported filesystem entries that were skipped make verification explicitly
|
|
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
|
-
|
|
483
|
-
|
|
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,
|
|
488
|
-
the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
|
|
489
|
-
rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
|
|
490
|
-
Rsync mode sets
|
|
491
|
-
|
|
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`.
|
|
570
|
-
|
|
571
|
-
|
|
572
|
-
|
|
573
|
-
|
|
574
|
-
|
|
575
|
-
|
|
576
|
-
|
|
577
|
-
|
|
578
|
-
|
|
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
|
|
585
|
-
|
|
586
|
-
| `host`
|
|
587
|
-
| `user`
|
|
588
|
-
| `password`
|
|
589
|
-
| `keyPath`
|
|
590
|
-
| `port`
|
|
591
|
-
| `alias`
|
|
592
|
-
| `template`
|
|
593
|
-
| `env`
|
|
594
|
-
| `defaultEnv`
|
|
595
|
-
| `runAs`
|
|
596
|
-
| `keepaliveInterval`
|
|
597
|
-
| `readyTimeout`
|
|
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`,
|
|
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
|
|
650
|
-
A symlink can change between validation and transfer, and rsync cannot bind the validated target to the later
|
|
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
|
|
665
|
-
|
|
666
|
-
| `false` (default) |
|
|
667
|
-
| `true` |
|
|
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
|
|
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
|
|