@pyrokine/mcp-ssh 2.3.1 → 2.4.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 +103 -21
- package/README_zh.md +73 -20
- package/dist/command-risk.d.ts +7 -0
- package/dist/command-risk.js +106 -0
- package/dist/directory-verification.d.ts +43 -0
- package/dist/directory-verification.js +485 -0
- package/dist/file-ops.d.ts +56 -13
- package/dist/file-ops.js +531 -145
- package/dist/forward-manager.d.ts +5 -2
- package/dist/forward-manager.js +133 -19
- package/dist/index.js +2 -1
- package/dist/operation-manager.d.ts +52 -0
- package/dist/operation-manager.js +402 -0
- package/dist/pty-manager.d.ts +1 -0
- package/dist/pty-manager.js +11 -7
- package/dist/session-manager.d.ts +21 -10
- package/dist/session-manager.js +328 -75
- package/dist/tools/connection.js +48 -8
- package/dist/tools/exec.js +7 -66
- package/dist/tools/file.js +455 -81
- package/dist/tools/forward.js +12 -4
- package/dist/tools/index.d.ts +1 -0
- package/dist/tools/index.js +1 -0
- package/dist/tools/operation.d.ts +2 -0
- package/dist/tools/operation.js +126 -0
- package/dist/tools/utils.d.ts +2 -2
- package/dist/transfer-outcome.d.ts +12 -0
- package/dist/transfer-outcome.js +72 -0
- package/dist/types.d.ts +94 -6
- package/package.json +11 -9
package/README.md
CHANGED
|
@@ -5,7 +5,7 @@ English | [中文](README_zh.md)
|
|
|
5
5
|
SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
|
-
[](https://nodejs.org/)
|
|
9
9
|
[](https://modelcontextprotocol.io/)
|
|
10
10
|
|
|
11
11
|

|
|
@@ -48,10 +48,13 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
48
48
|
|
|
49
49
|
## Installation
|
|
50
50
|
|
|
51
|
+
Requires Node.js 20.19 or newer.
|
|
52
|
+
|
|
51
53
|
### npm (Recommended)
|
|
52
54
|
|
|
53
55
|
```bash
|
|
54
56
|
npm install -g @pyrokine/mcp-ssh
|
|
57
|
+
claude mcp add ssh -- mcp-ssh
|
|
55
58
|
```
|
|
56
59
|
|
|
57
60
|
### From Source
|
|
@@ -61,6 +64,7 @@ git clone https://github.com/Pyrokine/claude-tools.git
|
|
|
61
64
|
cd claude-tools/mcp-ssh
|
|
62
65
|
npm install
|
|
63
66
|
npm run build
|
|
67
|
+
claude mcp add ssh -- node "$PWD/dist/index.js"
|
|
64
68
|
```
|
|
65
69
|
|
|
66
70
|
## Configuration
|
|
@@ -68,6 +72,10 @@ npm run build
|
|
|
68
72
|
### Claude Code
|
|
69
73
|
|
|
70
74
|
```bash
|
|
75
|
+
# npm installation
|
|
76
|
+
claude mcp add ssh -- mcp-ssh
|
|
77
|
+
|
|
78
|
+
# source build
|
|
71
79
|
claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
72
80
|
```
|
|
73
81
|
|
|
@@ -88,7 +96,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
88
96
|
}
|
|
89
97
|
```
|
|
90
98
|
|
|
91
|
-
## Available Tools (
|
|
99
|
+
## Available Tools (35 tools)
|
|
92
100
|
|
|
93
101
|
### Connection Management
|
|
94
102
|
|
|
@@ -96,10 +104,12 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
96
104
|
|---------------------|---------------------------------------------------|
|
|
97
105
|
| `ssh_connect` | Establish SSH connection (supports ~/.ssh/config) |
|
|
98
106
|
| `ssh_disconnect` | Close connection |
|
|
99
|
-
| `ssh_list_sessions` | List
|
|
107
|
+
| `ssh_list_sessions` | List brief sessions; optional detail/field selection |
|
|
100
108
|
| `ssh_reconnect` | Reconnect a disconnected session |
|
|
101
109
|
| `ssh_config_list` | List hosts from ~/.ssh/config |
|
|
102
110
|
|
|
111
|
+
`ssh_list_sessions()` returns only `alias`, canonical `identity`, `runAs`, `connected`, and `lastUsedAt`. Use `detail=true` for connection details or `fields=[...]` to select fields. Neither mode returns `keyPath`.
|
|
112
|
+
|
|
103
113
|
### Command Execution
|
|
104
114
|
|
|
105
115
|
| Tool | Description |
|
|
@@ -112,6 +122,16 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
|
|
|
112
122
|
| `ssh_quick_exec` | One-shot: connect, execute, disconnect |
|
|
113
123
|
| `ssh_exec_script` | Upload and run a temporary remote script |
|
|
114
124
|
|
|
125
|
+
### Tracked operations
|
|
126
|
+
|
|
127
|
+
| Tool | Description |
|
|
128
|
+
|------------------------|--------------------------------------------------|
|
|
129
|
+
| `ssh_operation_start` | Start a tracked long-running remote command |
|
|
130
|
+
| `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 |
|
|
134
|
+
|
|
115
135
|
### File Operations
|
|
116
136
|
|
|
117
137
|
| Tool | Description |
|
|
@@ -275,6 +295,24 @@ Timeout errors include the same head/tail fields from output produced before the
|
|
|
275
295
|
process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
|
|
276
296
|
tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
|
|
277
297
|
|
|
298
|
+
### Tracked long-running commands
|
|
299
|
+
|
|
300
|
+
Use tracked operations when a command must continue beyond one synchronous tool call:
|
|
301
|
+
|
|
302
|
+
```
|
|
303
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
304
|
+
ssh_operation_status(operationId="op_xxx")
|
|
305
|
+
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
306
|
+
ssh_operation_cancel(operationId="op_xxx")
|
|
307
|
+
```
|
|
308
|
+
|
|
309
|
+
The start call returns an unpredictable `operationId`. The server keeps bounded stdout and stderr buffers, records the
|
|
310
|
+
remote PID after verifying a per-operation marker, and expires completed records after `retentionMs`. `maxOutputBytes`
|
|
311
|
+
defaults to 1 MiB and accepts up to 8 MiB. `retentionMs` defaults to 1 hour and accepts up to 24 hours.
|
|
312
|
+
`ssh_operation_read.maxBytes` defaults to 64 KiB and accepts up to 1 MiB. Cancellation is refused until the marker and
|
|
313
|
+
PID are verified. If the SSH session disconnects while the command is active, its status becomes `unknown`; the server
|
|
314
|
+
does not claim that the remote process stopped. `ssh_exec` keeps its existing synchronous timeout behavior.
|
|
315
|
+
|
|
278
316
|
### Interactive Commands (PTY mode)
|
|
279
317
|
|
|
280
318
|
For commands that need a terminal:
|
|
@@ -345,8 +383,9 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
|
|
|
345
383
|
```
|
|
346
384
|
|
|
347
385
|
`ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
|
|
348
|
-
verification checks. `atomic=true` uploads to a same-directory temporary file,
|
|
349
|
-
`verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit
|
|
386
|
+
verification checks. `atomic=true` uploads to a same-directory temporary file, returns `diagnostics.tempRemotePath`,
|
|
387
|
+
then renames it to the target path. `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit
|
|
388
|
+
post-transfer checks.
|
|
350
389
|
Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
|
|
351
390
|
stdout/stderr,
|
|
352
391
|
with the effective user, cwd, and a suggested follow-up read command when available.
|
|
@@ -354,9 +393,9 @@ with the effective user, cwd, and a suggested follow-up read command when availa
|
|
|
354
393
|
`read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
|
|
355
394
|
from a head, tail, byte range, or line range sample.
|
|
356
395
|
|
|
357
|
-
### Directory
|
|
396
|
+
### Directory sync with rsync or SFTP
|
|
358
397
|
|
|
359
|
-
Smart sync
|
|
398
|
+
Smart sync selects rsync only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, jump-host, and other routes that cannot be passed safely to OpenSSH use SFTP directly:
|
|
360
399
|
|
|
361
400
|
```
|
|
362
401
|
// Sync local directory to remote (upload)
|
|
@@ -366,7 +405,7 @@ ssh_sync(
|
|
|
366
405
|
remotePath="/remote/project",
|
|
367
406
|
direction="upload"
|
|
368
407
|
)
|
|
369
|
-
// Returns
|
|
408
|
+
// Returns selectedTransport, decisionReason, stage durations, and transfer counters
|
|
370
409
|
|
|
371
410
|
// Sync with exclude patterns
|
|
372
411
|
ssh_sync(
|
|
@@ -390,16 +429,44 @@ ssh_sync(..., dryRun=true)
|
|
|
390
429
|
|
|
391
430
|
// Upload one file and verify remote owner/mode after transfer
|
|
392
431
|
ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
|
|
393
|
-
```
|
|
394
432
|
|
|
395
|
-
|
|
396
|
-
|
|
397
|
-
|
|
398
|
-
|
|
399
|
-
|
|
433
|
+
// Verify a directory with bounded manifests
|
|
434
|
+
ssh_sync(
|
|
435
|
+
...,
|
|
436
|
+
verify={count: true, sha256: true, owner: true, mode: true, staleFiles: true}
|
|
437
|
+
)
|
|
400
438
|
|
|
401
|
-
|
|
402
|
-
|
|
439
|
+
// Verify that entries present before --delete were removed
|
|
440
|
+
ssh_sync(..., delete=true, verify={deletions: true})
|
|
441
|
+
```
|
|
442
|
+
|
|
443
|
+
A directory source always means “copy the source directory contents into the destination root” in both rsync and SFTP
|
|
444
|
+
mode. Directory sources reject `recursive=false`. Relative exclude patterns are evaluated against the path below the
|
|
445
|
+
source root; patterns without `/` match each basename.
|
|
446
|
+
|
|
447
|
+
Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root manifest,
|
|
448
|
+
owner, mode, stale entries, and deletion results. `verify.deletions=true` requires `delete=true`; it records the destination
|
|
449
|
+
before transfer and only checks whether those deletion candidates disappeared. `staleFiles` independently checks every
|
|
450
|
+
extra destination entry. The response contains summaries and at most 20 mismatch samples, not the full manifest. The
|
|
451
|
+
default limits are 10,000 entries, 256 MiB per hashed file, and 1 GiB total hashed bytes. Set `verify.maxEntries`,
|
|
452
|
+
`verify.maxFileBytes`, and `verify.maxTotalBytes` to raise them, up to 50,000 entries, 4 GiB per file, and 16 GiB total.
|
|
453
|
+
Symlinks or unsupported filesystem entries that were skipped make verification explicitly `skipped` instead of
|
|
454
|
+
reporting a partial match.
|
|
455
|
+
|
|
456
|
+
If verification is requested, a mismatch, skipped check, or verification error sets top-level `success=false` while
|
|
457
|
+
`transferSuccess` still reports whether transfer completed. `verificationStatus`, `verificationSuccess`, and
|
|
458
|
+
`failedChecks` describe the verification outcome. SFTP single-file transfers also include local and remote size,
|
|
459
|
+
mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`. `verifyOwner` and
|
|
460
|
+
`verifyMode` apply to upload single-file sync; use `verify.owner` and `verify.mode` for directory manifests.
|
|
461
|
+
|
|
462
|
+
Rsync is selected only for a direct connection with a validated key path or usable SSH agent. Password, inline-key, and
|
|
463
|
+
jump-host sessions use SFTP because their route or credentials cannot be passed safely to a separate OpenSSH process.
|
|
464
|
+
`preflightTimeout`, `connectTimeout`, and `operationTimeout` independently bound capability probing, rsync SSH setup, and
|
|
465
|
+
the overall transfer; their defaults are 10 seconds, 30 seconds, and 10 minutes. When the session is not eligible for
|
|
466
|
+
rsync, the response returns `rsyncProbe.status="skipped"` with the route decision reason instead of omitting the probe.
|
|
467
|
+
Rsync mode sets
|
|
468
|
+
`StrictHostKeyChecking=accept-new`. SFTP does not support `delete=true`; such a request fails explicitly instead of
|
|
469
|
+
claiming deletion. If you require strict host key verification and management, use SFTP mode.
|
|
403
470
|
|
|
404
471
|
### Persistent PTY Sessions (top, tmux, etc.)
|
|
405
472
|
|
|
@@ -439,6 +506,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
439
506
|
|
|
440
507
|
`ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
|
|
441
508
|
`rawBufferLimit`, and `foregroundProcess` so long-running sessions can be monitored without reading the full raw stream.
|
|
509
|
+
When a finite command exits naturally, its final screen remains readable with `active=false` until explicit close or the
|
|
510
|
+
closed-session retention expires (5 minutes by default, configurable with `SSH_MCP_PTY_CLOSED_RETENTION_MS`).
|
|
442
511
|
|
|
443
512
|
Common control sequences:
|
|
444
513
|
|
|
@@ -463,10 +532,18 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
|
|
|
463
532
|
// List all forwards
|
|
464
533
|
ssh_forward_list()
|
|
465
534
|
|
|
466
|
-
// Close
|
|
467
|
-
ssh_forward_close(forwardId="fwd_1_xxx")
|
|
535
|
+
// Close after the listener is released
|
|
536
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
537
|
+
|
|
538
|
+
// Destroy active connections, then release the listener
|
|
539
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
468
540
|
```
|
|
469
541
|
|
|
542
|
+
A successful close means the local `server.close` or remote `unforwardIn` callback completed. The result includes
|
|
543
|
+
`listenerReleased`, `remoteUnforwarded`, `activeConnections`, `closeMode`, and `retryable`. Timeout or callback failure
|
|
544
|
+
keeps the forward in `ssh_forward_list`, so the same `forwardId` can be retried. After a successful local close, the port
|
|
545
|
+
can be rebound immediately.
|
|
546
|
+
|
|
470
547
|
## Configuration Options
|
|
471
548
|
|
|
472
549
|
### Connection Options
|
|
@@ -484,6 +561,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
484
561
|
| `defaultEnv` | object | - | Default env for this session |
|
|
485
562
|
| `runAs` | string | - | Default execution user |
|
|
486
563
|
| `keepaliveInterval` | number | 30000 | Keepalive interval in ms |
|
|
564
|
+
| `readyTimeout` | number | 30000 | Wait for SSH ready in ms, max 600000 |
|
|
565
|
+
| `jumpHost.readyTimeout` | number | top-level value | Jump-host ready timeout, max 600000 |
|
|
566
|
+
|
|
567
|
+
Connection failures return `failureStage`, `retryable`, and a bounded suggestion. `failureStage` is one of `preflight`, `authentication`, `ready_timeout`, `transport_or_handshake`, or `unknown`; multi-hop failures may also include `connectionStep` as `key_read`, `jump_connect`, `jump_forward`, or `target_connect`.
|
|
487
568
|
|
|
488
569
|
### Exec Options
|
|
489
570
|
|
|
@@ -542,11 +623,12 @@ Files exceeding these limits are rejected before being read.
|
|
|
542
623
|
|
|
543
624
|
| `followSymlinks` | SFTP path | rsync path |
|
|
544
625
|
|-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
|
|
545
|
-
| `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning |
|
|
626
|
+
| `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Skipped via `--no-links` |
|
|
546
627
|
| `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
|
|
547
628
|
|
|
548
|
-
Both
|
|
549
|
-
|
|
629
|
+
Both transports skip device and special filesystem entries. SFTP returns `skippedUnsupported` and up to 10 sample paths;
|
|
630
|
+
rsync uses `--no-devices --no-specials`. Directory verification also reports skipped symlinks and unsupported entries and
|
|
631
|
+
does not treat an incomplete manifest as a match.
|
|
550
632
|
|
|
551
633
|
## Project Structure
|
|
552
634
|
|
package/README_zh.md
CHANGED
|
@@ -5,7 +5,7 @@
|
|
|
5
5
|
一个功能完善的 SSH MCP 服务器,适用于 AI 助手(Claude、Cursor、Windsurf 等)
|
|
6
6
|
|
|
7
7
|
[](LICENSE)
|
|
8
|
-
[](https://nodejs.org/)
|
|
9
9
|
[](https://modelcontextprotocol.io/)
|
|
10
10
|
|
|
11
11
|

|
|
@@ -48,10 +48,13 @@
|
|
|
48
48
|
|
|
49
49
|
## 安装
|
|
50
50
|
|
|
51
|
+
需要 Node.js 20.19 或更新版本。
|
|
52
|
+
|
|
51
53
|
### npm(推荐)
|
|
52
54
|
|
|
53
55
|
```bash
|
|
54
56
|
npm install -g @pyrokine/mcp-ssh
|
|
57
|
+
claude mcp add ssh -- mcp-ssh
|
|
55
58
|
```
|
|
56
59
|
|
|
57
60
|
### 从源码安装
|
|
@@ -61,6 +64,7 @@ git clone https://github.com/Pyrokine/claude-tools.git
|
|
|
61
64
|
cd claude-tools/mcp-ssh
|
|
62
65
|
npm install
|
|
63
66
|
npm run build
|
|
67
|
+
claude mcp add ssh -- node "$PWD/dist/index.js"
|
|
64
68
|
```
|
|
65
69
|
|
|
66
70
|
## 配置
|
|
@@ -68,6 +72,10 @@ npm run build
|
|
|
68
72
|
### Claude Code
|
|
69
73
|
|
|
70
74
|
```bash
|
|
75
|
+
# npm 安装
|
|
76
|
+
claude mcp add ssh -- mcp-ssh
|
|
77
|
+
|
|
78
|
+
# 源码构建
|
|
71
79
|
claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
72
80
|
```
|
|
73
81
|
|
|
@@ -88,7 +96,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
88
96
|
}
|
|
89
97
|
```
|
|
90
98
|
|
|
91
|
-
## 可用工具(
|
|
99
|
+
## 可用工具(35 个)
|
|
92
100
|
|
|
93
101
|
### 连接管理
|
|
94
102
|
|
|
@@ -96,10 +104,12 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
96
104
|
|---------------------|-----------------------------|
|
|
97
105
|
| `ssh_connect` | 建立 SSH 连接(支持 ~/.ssh/config) |
|
|
98
106
|
| `ssh_disconnect` | 关闭连接 |
|
|
99
|
-
| `ssh_list_sessions` |
|
|
107
|
+
| `ssh_list_sessions` | 列出精简会话,可选详情或字段筛选 |
|
|
100
108
|
| `ssh_reconnect` | 重新连接断开的会话 |
|
|
101
109
|
| `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
|
|
102
110
|
|
|
111
|
+
`ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true` 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
|
|
112
|
+
|
|
103
113
|
### 命令执行
|
|
104
114
|
|
|
105
115
|
| 工具 | 描述 |
|
|
@@ -112,6 +122,16 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
|
|
|
112
122
|
| `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
|
|
113
123
|
| `ssh_exec_script` | 上传并执行远端临时脚本 |
|
|
114
124
|
|
|
125
|
+
### 可跟踪任务
|
|
126
|
+
|
|
127
|
+
| 工具 | 描述 |
|
|
128
|
+
|------------------------|------------------------------|
|
|
129
|
+
| `ssh_operation_start` | 启动可跟踪的长时间远端命令 |
|
|
130
|
+
| `ssh_operation_status` | 读取状态、PID、退出码和输出计数 |
|
|
131
|
+
| `ssh_operation_read` | 按字节偏移读取有上限的 stdout 和 stderr |
|
|
132
|
+
| `ssh_operation_cancel` | 校验任务 marker 后发送 TERM |
|
|
133
|
+
| `ssh_operation_list` | 列出未过期任务,可按 alias 过滤 |
|
|
134
|
+
|
|
115
135
|
### 文件操作
|
|
116
136
|
|
|
117
137
|
| 工具 | 描述 |
|
|
@@ -271,6 +291,19 @@ ssh_connect(
|
|
|
271
291
|
destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
|
|
272
292
|
`su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
|
|
273
293
|
|
|
294
|
+
### 可跟踪的长时间命令
|
|
295
|
+
|
|
296
|
+
需要命令跨越一次同步工具调用继续执行时,使用 operation 工具组:
|
|
297
|
+
|
|
298
|
+
```
|
|
299
|
+
ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
|
|
300
|
+
ssh_operation_status(operationId="op_xxx")
|
|
301
|
+
ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
|
|
302
|
+
ssh_operation_cancel(operationId="op_xxx")
|
|
303
|
+
```
|
|
304
|
+
|
|
305
|
+
start 返回不可预测的 `operationId`,服务端保存有硬上限的 stdout 和 stderr,在校验每个任务独立的 marker 后记录远端 PID,`maxOutputBytes` 默认 1 MiB、最大 8 MiB,`retentionMs` 默认 1 小时、最大 24 小时,`ssh_operation_read.maxBytes` 默认 64 KiB、最大 1 MiB,marker 和 PID 未完成校验时拒绝取消,SSH 会话在任务运行期间断开后状态变为 `unknown`,不会声称远端进程已经停止,`ssh_exec` 保持原有同步 timeout 行为
|
|
306
|
+
|
|
274
307
|
### 交互式命令(PTY 模式)
|
|
275
308
|
|
|
276
309
|
用于需要终端的命令:
|
|
@@ -340,16 +373,16 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, max
|
|
|
340
373
|
ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
|
|
341
374
|
```
|
|
342
375
|
|
|
343
|
-
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true`
|
|
344
|
-
rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
|
|
376
|
+
`ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,返回
|
|
377
|
+
`diagnostics.tempRemotePath` 后再 rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
|
|
345
378
|
stdout/stderr 时返回
|
|
346
379
|
`emptyOutputFailure=true`,同时给出 effective user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过
|
|
347
380
|
16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
|
|
348
381
|
`remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
|
|
349
382
|
|
|
350
|
-
###
|
|
383
|
+
### 使用 rsync 或 SFTP 同步目录
|
|
351
384
|
|
|
352
|
-
|
|
385
|
+
智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
|
|
353
386
|
|
|
354
387
|
```
|
|
355
388
|
// 同步本地目录到远程(上传)
|
|
@@ -359,7 +392,7 @@ ssh_sync(
|
|
|
359
392
|
remotePath="/remote/project",
|
|
360
393
|
direction="upload"
|
|
361
394
|
)
|
|
362
|
-
//
|
|
395
|
+
// 返回 selectedTransport、decisionReason、各阶段耗时和传输计数
|
|
363
396
|
|
|
364
397
|
// 带排除模式
|
|
365
398
|
ssh_sync(
|
|
@@ -383,16 +416,24 @@ ssh_sync(..., dryRun=true)
|
|
|
383
416
|
|
|
384
417
|
// 上传单文件后校验远端 owner/mode
|
|
385
418
|
ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
|
|
419
|
+
|
|
420
|
+
// 使用有界 manifest 校验目录
|
|
421
|
+
ssh_sync(
|
|
422
|
+
...,
|
|
423
|
+
verify={count: true, sha256: true, owner: true, mode: true, staleFiles: true}
|
|
424
|
+
)
|
|
425
|
+
|
|
426
|
+
// 校验传输前存在且应由 --delete 删除的条目已经消失
|
|
427
|
+
ssh_sync(..., delete=true, verify={deletions: true})
|
|
386
428
|
```
|
|
387
429
|
|
|
388
|
-
|
|
389
|
-
`diagnostics`,其中 `diagnostics` 包含本地路径策略和远端父目录探测结果,SFTP 单文件传输会返回 `verification`,包含本地和远端的
|
|
390
|
-
size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比,upload 单文件同步可用
|
|
391
|
-
`verifyOwner` 和 `verifyMode` 追加基于远端元数据的 `ownerMode` 校验,目录同步不递归扫描 owner/mode,会返回 skipped
|
|
392
|
-
verification 说明
|
|
430
|
+
目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false` 会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
|
|
393
431
|
|
|
394
|
-
|
|
395
|
-
|
|
432
|
+
目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root manifest、owner、mode、旧文件和删除结果,`verify.deletions=true` 必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles` 则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256 MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes` 提高到最多 50000 个条目、单文件 4 GiB、总哈希字节 16 GiB,遇到被跳过的 symlink 或不支持的文件系统条目时,校验会明确返回 `skipped`,不会报告部分匹配成功
|
|
433
|
+
|
|
434
|
+
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,`verificationStatus`、`verificationSuccess` 和 `failedChecks` 描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比,upload 单文件使用 `verifyOwner` 和 `verifyMode`,目录逐项校验使用 `verify.owner` 和 `verify.mode`
|
|
435
|
+
|
|
436
|
+
只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料,`preflightTimeout`、`connectTimeout` 和 `operationTimeout` 分别限制能力预检、rsync SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回 `rsyncProbe.status="skipped"` 和路由判定原因,不再省略 probe,rsync 模式设置 `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
396
437
|
|
|
397
438
|
### 持久化 PTY 会话(top、tmux 等)
|
|
398
439
|
|
|
@@ -431,7 +472,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
431
472
|
```
|
|
432
473
|
|
|
433
474
|
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
|
|
434
|
-
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw
|
|
475
|
+
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回 `active=false`,
|
|
476
|
+
直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS` 调整
|
|
435
477
|
|
|
436
478
|
常用控制序列:
|
|
437
479
|
|
|
@@ -456,10 +498,17 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
|
|
|
456
498
|
// 列出所有转发
|
|
457
499
|
ssh_forward_list()
|
|
458
500
|
|
|
459
|
-
//
|
|
460
|
-
ssh_forward_close(forwardId="fwd_1_xxx")
|
|
501
|
+
// listener 释放后返回成功
|
|
502
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
503
|
+
|
|
504
|
+
// 销毁活跃连接后释放 listener
|
|
505
|
+
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
461
506
|
```
|
|
462
507
|
|
|
508
|
+
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、
|
|
509
|
+
`remoteUnforwarded`、`activeConnections`、`closeMode` 和 `retryable`,超时或 callback 失败时 forward 仍保留在
|
|
510
|
+
`ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind
|
|
511
|
+
|
|
463
512
|
## 配置选项
|
|
464
513
|
|
|
465
514
|
### 连接选项
|
|
@@ -477,6 +526,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
477
526
|
| `defaultEnv` | object | - | 连接级默认环境变量 |
|
|
478
527
|
| `runAs` | string | - | 默认执行用户 |
|
|
479
528
|
| `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
|
|
529
|
+
| `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
530
|
+
| `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
531
|
+
|
|
532
|
+
连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、`transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、`jump_forward` 或 `target_connect`
|
|
480
533
|
|
|
481
534
|
### 执行选项
|
|
482
535
|
|
|
@@ -532,10 +585,10 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
|
532
585
|
|
|
533
586
|
| `followSymlinks` | SFTP 路径 | rsync 路径 |
|
|
534
587
|
|------------------|----------------------------------------|--------------------------------------------|
|
|
535
|
-
| `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 |
|
|
588
|
+
| `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 通过 `--no-links` 跳过 |
|
|
536
589
|
| `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
|
|
537
590
|
|
|
538
|
-
|
|
591
|
+
两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用 `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
|
|
539
592
|
|
|
540
593
|
## 项目结构
|
|
541
594
|
|
|
@@ -0,0 +1,106 @@
|
|
|
1
|
+
function pushRisk(categories, signals, category, signal) {
|
|
2
|
+
categories.add(category);
|
|
3
|
+
signals.push(signal);
|
|
4
|
+
}
|
|
5
|
+
function hasBackgroundOperator(command) {
|
|
6
|
+
let quote;
|
|
7
|
+
let escaped = false;
|
|
8
|
+
for (let index = 0; index < command.length; ++index) {
|
|
9
|
+
const character = command[index];
|
|
10
|
+
if (escaped) {
|
|
11
|
+
escaped = false;
|
|
12
|
+
continue;
|
|
13
|
+
}
|
|
14
|
+
if (character === '\\' && quote !== "'") {
|
|
15
|
+
escaped = true;
|
|
16
|
+
continue;
|
|
17
|
+
}
|
|
18
|
+
if (quote) {
|
|
19
|
+
if (character === quote) {
|
|
20
|
+
quote = undefined;
|
|
21
|
+
}
|
|
22
|
+
continue;
|
|
23
|
+
}
|
|
24
|
+
if (character === "'" || character === '"') {
|
|
25
|
+
quote = character;
|
|
26
|
+
continue;
|
|
27
|
+
}
|
|
28
|
+
if (character !== '&') {
|
|
29
|
+
continue;
|
|
30
|
+
}
|
|
31
|
+
const previous = command[index - 1];
|
|
32
|
+
const next = command[index + 1];
|
|
33
|
+
if (previous === '&' || next === '&' || previous === '>' || previous === '<' || next === '>') {
|
|
34
|
+
continue;
|
|
35
|
+
}
|
|
36
|
+
return true;
|
|
37
|
+
}
|
|
38
|
+
return false;
|
|
39
|
+
}
|
|
40
|
+
export function classifyCommandRisk(command, timeout) {
|
|
41
|
+
const signals = [];
|
|
42
|
+
const categories = new Set();
|
|
43
|
+
const pipeCount = (command.match(/\|/g) ?? []).length;
|
|
44
|
+
const lowerCommand = command.toLowerCase();
|
|
45
|
+
const background = hasBackgroundOperator(command);
|
|
46
|
+
const continuous = /\b(?:tail\s+-f|journalctl\s+-f|watch|top|htop)\b/.test(command);
|
|
47
|
+
const unboundedFind = /\bfind\b/.test(command) && !/\s-maxdepth\s+\d+/.test(command);
|
|
48
|
+
const recursiveGrep = /\bgrep\s+(?:-\S*R|--recursive)\b/.test(command);
|
|
49
|
+
if (command.length > 500) {
|
|
50
|
+
pushRisk(categories, signals, 'complexity-signal', 'long_command');
|
|
51
|
+
}
|
|
52
|
+
if (pipeCount >= 3) {
|
|
53
|
+
pushRisk(categories, signals, 'complexity-signal', 'long_pipeline');
|
|
54
|
+
}
|
|
55
|
+
if (recursiveGrep) {
|
|
56
|
+
pushRisk(categories, signals, 'long-running', 'recursive_grep');
|
|
57
|
+
}
|
|
58
|
+
if (unboundedFind) {
|
|
59
|
+
pushRisk(categories, signals, 'long-running', 'unbounded_find');
|
|
60
|
+
}
|
|
61
|
+
if (/\b(?:python|python3|node|perl|ruby)\b/.test(command)) {
|
|
62
|
+
pushRisk(categories, signals, 'script-execution', 'interpreter_script');
|
|
63
|
+
}
|
|
64
|
+
if (/\bsleep\s+\d{2,}\b/.test(command) || continuous) {
|
|
65
|
+
pushRisk(categories, signals, 'long-running', continuous ? 'continuous_command' : 'long_sleep');
|
|
66
|
+
}
|
|
67
|
+
if (background) {
|
|
68
|
+
pushRisk(categories, signals, 'process-control', 'background_task');
|
|
69
|
+
}
|
|
70
|
+
const recursiveRemove = /\brm\b(?=[^\n;|&]*(?:\s-[a-z]*r[a-z]*\b|\s--recursive\b))/.test(lowerCommand);
|
|
71
|
+
if (recursiveRemove || /\b(?:dd\s+if=|mkfs|fdisk|parted|shutdown|reboot)\b/.test(lowerCommand)) {
|
|
72
|
+
pushRisk(categories, signals, 'destructive', 'destructive_command');
|
|
73
|
+
}
|
|
74
|
+
const processControl = /\b(?:pkill|killall)\b/.test(lowerCommand) || /\bkill\s+(?!-0(?:\s|$))/.test(lowerCommand);
|
|
75
|
+
if (processControl) {
|
|
76
|
+
pushRisk(categories, signals, 'process-control', 'process_control');
|
|
77
|
+
}
|
|
78
|
+
if (/\b(?:systemctl|service|docker|kubectl)\s+(?:restart|stop|kill|delete|rm|down)\b/.test(lowerCommand)) {
|
|
79
|
+
pushRisk(categories, signals, 'service-control', 'service_control');
|
|
80
|
+
}
|
|
81
|
+
if (/\b(?:password|passwd|token|authorization|cookie|secret|private[_-]?key)\b/i.test(command)) {
|
|
82
|
+
pushRisk(categories, signals, 'credential-bearing', 'credential_bearing');
|
|
83
|
+
}
|
|
84
|
+
if (/\bsu\s+-?\s*[a-zA-Z_][a-zA-Z0-9_-]*\s+-c\b/.test(command)) {
|
|
85
|
+
pushRisk(categories, signals, 'user-switch', 'direct_su_command');
|
|
86
|
+
}
|
|
87
|
+
if (signals.length === 0) {
|
|
88
|
+
return undefined;
|
|
89
|
+
}
|
|
90
|
+
const boundedTimeout = timeout !== undefined && timeout > 0 && timeout <= 300_000;
|
|
91
|
+
const high = categories.has('destructive') ||
|
|
92
|
+
categories.has('service-control') ||
|
|
93
|
+
categories.has('process-control') ||
|
|
94
|
+
continuous ||
|
|
95
|
+
((unboundedFind || recursiveGrep) && !boundedTimeout);
|
|
96
|
+
return {
|
|
97
|
+
level: high ? 'high' : 'medium',
|
|
98
|
+
categories: Array.from(categories),
|
|
99
|
+
signals,
|
|
100
|
+
suggestion: signals.includes('direct_su_command')
|
|
101
|
+
? '建议使用 ssh_exec 的 runAs 参数或 ssh_exec_as_user,避免手写 su 命令造成引用和环境加载差异'
|
|
102
|
+
: high
|
|
103
|
+
? '长任务使用 ssh_operation_start,交互命令使用 ssh_pty_start,破坏性操作执行前确认目标范围'
|
|
104
|
+
: '如输出较大,请设置 maxOutputSize 或重定向到远端文件后分块读取',
|
|
105
|
+
};
|
|
106
|
+
}
|
|
@@ -0,0 +1,43 @@
|
|
|
1
|
+
export declare const DIRECTORY_VERIFY_MAX_ENTRIES = 50000;
|
|
2
|
+
export declare const DIRECTORY_VERIFY_MAX_MISMATCHES = 20;
|
|
3
|
+
export declare const DIRECTORY_VERIFY_DEFAULT_MAX_FILE_BYTES: number;
|
|
4
|
+
export declare const DIRECTORY_VERIFY_DEFAULT_MAX_TOTAL_BYTES: number;
|
|
5
|
+
export declare const DIRECTORY_VERIFY_MAX_FILE_BYTES: number;
|
|
6
|
+
export declare const DIRECTORY_VERIFY_MAX_TOTAL_BYTES: number;
|
|
7
|
+
export type DirectoryVerifyRequest = {
|
|
8
|
+
count?: boolean;
|
|
9
|
+
sha256?: boolean;
|
|
10
|
+
owner?: boolean;
|
|
11
|
+
mode?: boolean;
|
|
12
|
+
deletions?: boolean;
|
|
13
|
+
staleFiles?: boolean;
|
|
14
|
+
maxEntries?: number;
|
|
15
|
+
maxFileBytes?: number;
|
|
16
|
+
maxTotalBytes?: number;
|
|
17
|
+
};
|
|
18
|
+
type ManifestEntry = {
|
|
19
|
+
path: string;
|
|
20
|
+
type: 'file' | 'directory';
|
|
21
|
+
size: number;
|
|
22
|
+
mode: string;
|
|
23
|
+
owner: string;
|
|
24
|
+
sha256?: string;
|
|
25
|
+
};
|
|
26
|
+
type DirectoryManifestLimitReason = 'entries' | 'file_bytes' | 'total_bytes';
|
|
27
|
+
export type DirectoryManifest = {
|
|
28
|
+
entries: ManifestEntry[];
|
|
29
|
+
count: number;
|
|
30
|
+
rootSha256: string;
|
|
31
|
+
limited: boolean;
|
|
32
|
+
limitReason?: DirectoryManifestLimitReason;
|
|
33
|
+
skippedSymlinks: number;
|
|
34
|
+
skippedUnsupported: number;
|
|
35
|
+
unsupportedSamples: string[];
|
|
36
|
+
};
|
|
37
|
+
export declare function matchesDirectoryExclude(relativePath: string, patterns: string[] | undefined): boolean;
|
|
38
|
+
export declare function createLocalDirectoryManifest(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): Promise<DirectoryManifest>;
|
|
39
|
+
export declare function createEmptyDirectoryManifest(): DirectoryManifest;
|
|
40
|
+
export declare function buildRemoteDirectoryManifestCommand(rootPath: string, request: DirectoryVerifyRequest, exclude?: string[], followSymlinks?: boolean): string;
|
|
41
|
+
export declare function parseRemoteDirectoryManifest(output: string): DirectoryManifest;
|
|
42
|
+
export declare function compareDirectoryManifests(expected: DirectoryManifest, actual: DirectoryManifest, request: DirectoryVerifyRequest, deletionBaseline?: DirectoryManifest): Record<string, unknown>;
|
|
43
|
+
export {};
|