@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 +193 -109
- package/README_zh.md +238 -130
- package/dist/directory-verification.js +29 -4
- package/dist/file-ops.d.ts +31 -6
- package/dist/file-ops.js +493 -169
- package/dist/forward-manager.d.ts +17 -1
- package/dist/forward-manager.js +397 -89
- package/dist/operation-manager.d.ts +13 -6
- package/dist/operation-manager.js +200 -99
- package/dist/pty-manager.d.ts +3 -3
- package/dist/pty-manager.js +61 -15
- package/dist/session-manager.d.ts +29 -4
- package/dist/session-manager.js +288 -67
- package/dist/sftp-timeout.d.ts +9 -0
- package/dist/sftp-timeout.js +49 -0
- package/dist/tools/connection.js +85 -38
- package/dist/tools/exec.js +16 -6
- package/dist/tools/file.d.ts +1 -0
- package/dist/tools/file.js +276 -148
- package/dist/tools/forward.js +11 -8
- package/dist/tools/operation.js +12 -3
- 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 +16 -0
- package/dist/utf8.d.ts +3 -0
- package/dist/utf8.js +44 -0
- package/package.json +6 -6
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,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
|
|
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
|
-
|
|
256
|
-
|
|
257
|
-
|
|
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
|
-
###
|
|
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
|
|
288
|
-
|
|
289
|
-
|
|
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
|
|
310
|
-
remote PID after verifying a per-operation marker, and expires
|
|
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.
|
|
314
|
-
|
|
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
|
-
|
|
334
|
-
|
|
335
|
-
|
|
336
|
-
|
|
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(
|
|
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`
|
|
387
|
-
|
|
388
|
-
|
|
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
|
-
|
|
392
|
-
`
|
|
393
|
-
|
|
394
|
-
|
|
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,
|
|
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,
|
|
448
|
-
owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the
|
|
449
|
-
before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently
|
|
450
|
-
extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full
|
|
451
|
-
default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set
|
|
452
|
-
`verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per
|
|
453
|
-
Symlinks or unsupported filesystem entries that were skipped make verification explicitly
|
|
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
|
-
|
|
460
|
-
|
|
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,
|
|
465
|
-
the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible
|
|
466
|
-
rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the
|
|
467
|
-
Rsync mode sets
|
|
468
|
-
|
|
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`.
|
|
544
|
-
|
|
545
|
-
can be
|
|
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
|
|
552
|
-
|
|
553
|
-
| `host`
|
|
554
|
-
| `user`
|
|
555
|
-
| `password`
|
|
556
|
-
| `keyPath`
|
|
557
|
-
| `port`
|
|
558
|
-
| `alias`
|
|
559
|
-
| `template`
|
|
560
|
-
| `env`
|
|
561
|
-
| `defaultEnv`
|
|
562
|
-
| `runAs`
|
|
563
|
-
| `keepaliveInterval`
|
|
564
|
-
| `readyTimeout`
|
|
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`,
|
|
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
|
|
611
|
-
|
|
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
|
|
625
|
-
|
|
626
|
-
| `false` (default) |
|
|
627
|
-
| `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` |
|
|
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
|
|
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
|
|