@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 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](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
- [![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
8
+ [![Node](https://img.shields.io/badge/node-%3E%3D20.19-green.svg)](https://nodejs.org/)
9
9
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)
10
10
 
11
11
  ![Linux](https://img.shields.io/badge/Linux-tested-success)
@@ -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 (30 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 active sessions |
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, then renames it to the target path.
349
- `verifySize`, `verifyMd5`, `verifyMode`, `verifyOwner`, and `verifyMtime` add explicit post-transfer checks.
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 Sync (with rsync)
396
+ ### Directory sync with rsync or SFTP
358
397
 
359
- Smart sync automatically detects rsync availability and uses it for efficient incremental transfer:
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: { method: "rsync", filesTransferred: 42, ... }
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
- If rsync is not available on remote or local, it automatically falls back to SFTP. Sync responses include `transport`,
396
- `duration`, `dryRun`, `stats`, and `commandSummary`. SFTP single-file transfers include a `verification` object with
397
- local and remote size, mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`.
398
- For upload single-file sync, `verifyOwner` and `verifyMode` add an `ownerMode` verification block based on remote file
399
- metadata. Directory sync does not recursively scan owner/mode; it returns a skipped verification note instead.
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
- **Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
402
- If you require strict host key verification and management, use SFTP mode instead.
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 forward
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 | Copied as-is (rsync default: preserves the symlink without dereferencing) |
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 default modes are safe (neither uploads link target contents). The divergence is whether the destination keeps the
549
- symlink: SFTP omits it entirely, rsync preserves it as a symlink.
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](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
8
- [![Node](https://img.shields.io/badge/node-%3E%3D18-green.svg)](https://nodejs.org/)
8
+ [![Node](https://img.shields.io/badge/node-%3E%3D20.19-green.svg)](https://nodejs.org/)
9
9
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)
10
10
 
11
11
  ![Linux](https://img.shields.io/badge/Linux-tested-success)
@@ -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
- ## 可用工具(30 个)
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
- ### 目录同步(rsync)
383
+ ### 使用 rsync 或 SFTP 同步目录
351
384
 
352
- 智能同步会自动检测 rsync 可用性,使用 rsync 进行高效增量传输:
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
- // 返回: { method: "rsync", filesTransferred: 42, ... }
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
- 如果远程或本地没有 rsync,会自动回退到 SFTP,同步响应包含 `transport`、`duration`、`dryRun`、`stats`、`commandSummary` 和
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
- **注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
395
- 如需严格的主机密钥验证与管理,请使用 SFTP 模式
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 中提示 | 按 symlink 本身复制(rsync 默认:保留链接,不上传目标内容) |
588
+ | `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 通过 `--no-links` 跳过 |
536
589
  | `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
537
590
 
538
- 两个默认模式都安全(都不会上传链接目标内容),差异仅在于目标端是否保留 symlink:SFTP 完全跳过不传,rsync 保留为 symlink
591
+ 两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用 `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
539
592
 
540
593
  ## 项目结构
541
594
 
@@ -0,0 +1,7 @@
1
+ export type CommandRisk = {
2
+ level: 'medium' | 'high';
3
+ categories: string[];
4
+ signals: string[];
5
+ suggestion: string;
6
+ };
7
+ export declare function classifyCommandRisk(command: string, timeout?: number): CommandRisk | undefined;
@@ -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 {};