@pyrokine/mcp-ssh 2.3.2 → 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
@@ -96,7 +96,7 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
96
96
  }
97
97
  ```
98
98
 
99
- ## Available Tools (30 tools)
99
+ ## Available Tools (35 tools)
100
100
 
101
101
  ### Connection Management
102
102
 
@@ -104,10 +104,12 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
104
104
  |---------------------|---------------------------------------------------|
105
105
  | `ssh_connect` | Establish SSH connection (supports ~/.ssh/config) |
106
106
  | `ssh_disconnect` | Close connection |
107
- | `ssh_list_sessions` | List active sessions |
107
+ | `ssh_list_sessions` | List brief sessions; optional detail/field selection |
108
108
  | `ssh_reconnect` | Reconnect a disconnected session |
109
109
  | `ssh_config_list` | List hosts from ~/.ssh/config |
110
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
+
111
113
  ### Command Execution
112
114
 
113
115
  | Tool | Description |
@@ -120,6 +122,16 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
120
122
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
121
123
  | `ssh_exec_script` | Upload and run a temporary remote script |
122
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
+
123
135
  ### File Operations
124
136
 
125
137
  | Tool | Description |
@@ -283,6 +295,24 @@ Timeout errors include the same head/tail fields from output produced before the
283
295
  process-control, service-control, credential-bearing, unbounded `find`, recursive `grep`, long pipelines, background
284
296
  tasks, direct `su - user -c`, or long-running patterns return a `commandRisk` block with `categories` and `signals`.
285
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
+
286
316
  ### Interactive Commands (PTY mode)
287
317
 
288
318
  For commands that need a terminal:
@@ -353,8 +383,9 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180"
353
383
  ```
354
384
 
355
385
  `ssh_upload` returns local path policy diagnostics, remote parent probing, remote target metadata, and optional
356
- verification checks. `atomic=true` uploads to a same-directory temporary file, then renames it to the target path.
357
- `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.
358
389
  Command execution results include `emptyOutputFailure=true` when the remote command exits non-zero without
359
390
  stdout/stderr,
360
391
  with the effective user, cwd, and a suggested follow-up read command when available.
@@ -362,9 +393,9 @@ with the effective user, cwd, and a suggested follow-up read command when availa
362
393
  `read_offset`, `read_bytes`, `remaining_bytes`, `sample_kind`, and `truncated` so callers can distinguish a full read
363
394
  from a head, tail, byte range, or line range sample.
364
395
 
365
- ### Directory Sync (with rsync)
396
+ ### Directory sync with rsync or SFTP
366
397
 
367
- 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:
368
399
 
369
400
  ```
370
401
  // Sync local directory to remote (upload)
@@ -374,7 +405,7 @@ ssh_sync(
374
405
  remotePath="/remote/project",
375
406
  direction="upload"
376
407
  )
377
- // Returns: { method: "rsync", filesTransferred: 42, ... }
408
+ // Returns selectedTransport, decisionReason, stage durations, and transfer counters
378
409
 
379
410
  // Sync with exclude patterns
380
411
  ssh_sync(
@@ -398,16 +429,44 @@ ssh_sync(..., dryRun=true)
398
429
 
399
430
  // Upload one file and verify remote owner/mode after transfer
400
431
  ssh_sync(..., direction="upload", verifyOwner="appuser", verifyMode="0644")
401
- ```
402
432
 
403
- If rsync is not available on remote or local, it automatically falls back to SFTP. Sync responses include `transport`,
404
- `duration`, `dryRun`, `stats`, and `commandSummary`. SFTP single-file transfers include a `verification` object with
405
- local and remote size, mode or permissions, mtime, owner/group, and SHA-256 comparison when the remote has `sha256sum`.
406
- For upload single-file sync, `verifyOwner` and `verifyMode` add an `ownerMode` verification block based on remote file
407
- 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
+ )
408
438
 
409
- **Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
410
- 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.
411
470
 
412
471
  ### Persistent PTY Sessions (top, tmux, etc.)
413
472
 
@@ -447,6 +506,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
447
506
 
448
507
  `ssh_pty_read` and `ssh_pty_list` expose `lastInputAt`, `lastOutputAt`, `lastReadAt`, `unreadRawBytes`,
449
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`).
450
511
 
451
512
  Common control sequences:
452
513
 
@@ -471,10 +532,18 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
471
532
  // List all forwards
472
533
  ssh_forward_list()
473
534
 
474
- // Close forward
475
- 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)
476
540
  ```
477
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
+
478
547
  ## Configuration Options
479
548
 
480
549
  ### Connection Options
@@ -492,6 +561,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
492
561
  | `defaultEnv` | object | - | Default env for this session |
493
562
  | `runAs` | string | - | Default execution user |
494
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`.
495
568
 
496
569
  ### Exec Options
497
570
 
@@ -550,11 +623,12 @@ Files exceeding these limits are rejected before being read.
550
623
 
551
624
  | `followSymlinks` | SFTP path | rsync path |
552
625
  |-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
553
- | `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` |
554
627
  | `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
555
628
 
556
- Both default modes are safe (neither uploads link target contents). The divergence is whether the destination keeps the
557
- 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.
558
632
 
559
633
  ## Project Structure
560
634
 
package/README_zh.md CHANGED
@@ -96,7 +96,7 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
96
96
  }
97
97
  ```
98
98
 
99
- ## 可用工具(30 个)
99
+ ## 可用工具(35 个)
100
100
 
101
101
  ### 连接管理
102
102
 
@@ -104,10 +104,12 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
104
104
  |---------------------|-----------------------------|
105
105
  | `ssh_connect` | 建立 SSH 连接(支持 ~/.ssh/config) |
106
106
  | `ssh_disconnect` | 关闭连接 |
107
- | `ssh_list_sessions` | 列出活跃会话 |
107
+ | `ssh_list_sessions` | 列出精简会话,可选详情或字段筛选 |
108
108
  | `ssh_reconnect` | 重新连接断开的会话 |
109
109
  | `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
110
110
 
111
+ `ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true` 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
112
+
111
113
  ### 命令执行
112
114
 
113
115
  | 工具 | 描述 |
@@ -120,6 +122,16 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
120
122
  | `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
121
123
  | `ssh_exec_script` | 上传并执行远端临时脚本 |
122
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
+
123
135
  ### 文件操作
124
136
 
125
137
  | 工具 | 描述 |
@@ -279,6 +291,19 @@ ssh_connect(
279
291
  destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
280
292
  `su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
281
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
+
282
307
  ### 交互式命令(PTY 模式)
283
308
 
284
309
  用于需要终端的命令:
@@ -348,16 +373,16 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, max
348
373
  ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
349
374
  ```
350
375
 
351
- `ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,再
352
- rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
376
+ `ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,返回
377
+ `diagnostics.tempRemotePath` 后再 rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
353
378
  stdout/stderr 时返回
354
379
  `emptyOutputFailure=true`,同时给出 effective user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过
355
380
  16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
356
381
  `remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
357
382
 
358
- ### 目录同步(rsync)
383
+ ### 使用 rsync 或 SFTP 同步目录
359
384
 
360
- 智能同步会自动检测 rsync 可用性,使用 rsync 进行高效增量传输:
385
+ 智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
361
386
 
362
387
  ```
363
388
  // 同步本地目录到远程(上传)
@@ -367,7 +392,7 @@ ssh_sync(
367
392
  remotePath="/remote/project",
368
393
  direction="upload"
369
394
  )
370
- // 返回: { method: "rsync", filesTransferred: 42, ... }
395
+ // 返回 selectedTransport、decisionReason、各阶段耗时和传输计数
371
396
 
372
397
  // 带排除模式
373
398
  ssh_sync(
@@ -391,16 +416,24 @@ ssh_sync(..., dryRun=true)
391
416
 
392
417
  // 上传单文件后校验远端 owner/mode
393
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})
394
428
  ```
395
429
 
396
- 如果远程或本地没有 rsync,会自动回退到 SFTP,同步响应包含 `transport`、`duration`、`dryRun`、`stats`、`commandSummary` 和
397
- `diagnostics`,其中 `diagnostics` 包含本地路径策略和远端父目录探测结果,SFTP 单文件传输会返回 `verification`,包含本地和远端的
398
- size、mode 或 permissions、mtime、owner/group,以及远端支持 `sha256sum` 时的 SHA-256 对比,upload 单文件同步可用
399
- `verifyOwner` 和 `verifyMode` 追加基于远端元数据的 `ownerMode` 校验,目录同步不递归扫描 owner/mode,会返回 skipped
400
- verification 说明
430
+ 目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false` 会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
431
+
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`,不会报告部分匹配成功
401
433
 
402
- **注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
403
- 如需严格的主机密钥验证与管理,请使用 SFTP 模式
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 模式
404
437
 
405
438
  ### 持久化 PTY 会话(top、tmux 等)
406
439
 
@@ -439,7 +472,8 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
439
472
  ```
440
473
 
441
474
  `ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
442
- `foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流
475
+ `foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回 `active=false`,
476
+ 直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS` 调整
443
477
 
444
478
  常用控制序列:
445
479
 
@@ -464,10 +498,17 @@ ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", local
464
498
  // 列出所有转发
465
499
  ssh_forward_list()
466
500
 
467
- // 关闭转发
468
- 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)
469
506
  ```
470
507
 
508
+ 关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、
509
+ `remoteUnforwarded`、`activeConnections`、`closeMode` 和 `retryable`,超时或 callback 失败时 forward 仍保留在
510
+ `ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind
511
+
471
512
  ## 配置选项
472
513
 
473
514
  ### 连接选项
@@ -485,6 +526,10 @@ ssh_forward_close(forwardId="fwd_1_xxx")
485
526
  | `defaultEnv` | object | - | 连接级默认环境变量 |
486
527
  | `runAs` | string | - | 默认执行用户 |
487
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`
488
533
 
489
534
  ### 执行选项
490
535
 
@@ -540,10 +585,10 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
540
585
 
541
586
  | `followSymlinks` | SFTP 路径 | rsync 路径 |
542
587
  |------------------|----------------------------------------|--------------------------------------------|
543
- | `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 按 symlink 本身复制(rsync 默认:保留链接,不上传目标内容) |
588
+ | `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 通过 `--no-links` 跳过 |
544
589
  | `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
545
590
 
546
- 两个默认模式都安全(都不会上传链接目标内容),差异仅在于目标端是否保留 symlink:SFTP 完全跳过不传,rsync 保留为 symlink
591
+ 两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用 `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
547
592
 
548
593
  ## 项目结构
549
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 {};