@pyrokine/mcp-ssh 3.2.0 → 3.3.1

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
@@ -10,7 +10,7 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
10
10
 
11
11
  ![Linux](https://img.shields.io/badge/Linux-tested-success)
12
12
  ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
13
- ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
13
+ [![Windows](https://img.shields.io/badge/Windows-native%20regressions-success)](TESTING.md)
14
14
 
15
15
  ## Migrating to 3.0
16
16
 
@@ -36,7 +36,9 @@ the returned prefix, including whether its last line ends with a newline.
36
36
 
37
37
  Windows connections require `remotePlatform="windows"`; local Windows does not change the remote default. Set
38
38
  `commandShell` and `remotePathStyle` for the host, and an explicit `rsyncProfile` when using rsync with Windows. The
39
- Windows behavior and examples below remain available.
39
+ Windows behavior and examples below remain available. Local permission, boot-identity, and filename checks ignore
40
+ inherited `PSModulePath`, allowing MCP to start under PowerShell 7 while using Windows PowerShell 5.1. Remote commands
41
+ and user scripts retain their configured environment.
40
42
 
41
43
  ## Host key trust
42
44
 
@@ -66,8 +68,9 @@ the shared bastion and unrelated aliases. Explicit connect or reconnect verifies
66
68
  retains automatic reconnect. Hashed hostnames, host/port pairs, IPv6, multiple names, wildcard patterns, and negated
67
69
  patterns are supported. Matching CA or host-certificate entries require the OpenSSH backend. Concurrent first-use
68
70
  writes
69
- use an exclusive owner-directory lock with a bounded, cancellable wait. A complete owner record is published before
70
- writing trust. A confirmed exited owner is recovered automatically within the same verified local process domain:
71
+ use an exclusive owner-directory lock with a bounded, cancellable wait. Preparation and permission checks share the
72
+ connection deadline; the five-second lock-contention budget starts after preparation and stays within that deadline.
73
+ A complete owner record is published before writing trust. A confirmed exited owner is recovered automatically within the same verified local process domain:
71
74
  Linux uses the `/proc` boot ID and PID namespace, macOS uses `kern.bootsessionuuid`, and Windows queries the kernel's
72
75
  `SystemBootEnvironmentInformation.BootIdentifier` through the built-in PowerShell. Live or reused PIDs, denied
73
76
  liveness
@@ -231,7 +234,10 @@ Add to your MCP settings (e.g., `~/.claude/settings.json` or client-specific con
231
234
  OpenSSH
232
235
  entries also include `masterReused` and `identityStatus` . Use `detail=true` for connection details or `fields=[...]`
233
236
  to
234
- select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open state, so a dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and an explicitly chosen conflicting alias returns an error.
237
+ select fields. Neither mode returns `keyPath`. For ssh2, `connected` checks the underlying socket's writable/open
238
+ state, so dead transport is reported disconnected before a delayed close event arrives. An implicit bastion alias
239
+ that conflicts with another live connection uses a target-scoped alias; compatible bastions are still shared, and
240
+ an explicitly chosen conflicting alias returns an error.
235
241
 
236
242
  ssh2 connections enable TCP_NODELAY to reduce waiting between interactive commands and small-file SFTP requests.
237
243
  Direct,
@@ -256,12 +262,22 @@ pending, a channel returned by the delayed callback is destroyed before the conn
256
262
  | `ssh_quick_exec` | One-shot: connect, execute, disconnect |
257
263
  | `ssh_exec_script` | Upload and run a temporary remote script |
258
264
 
259
- `ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and retains its cmd or PowerShell script invocation.
265
+ `ssh_exec_script.interpreter` is an executable name or path. Pass flags separately as `interpreterArgs`, such as
266
+ `interpreter="python3", interpreterArgs=["-I"]`. Each array entry is one escaped argument; omitting the array
267
+ preserves the default empty argument list. POSIX defaults to bash; Windows defaults to the connection shell and
268
+ retains its cmd or PowerShell script invocation.
260
269
 
261
270
  For a Windows remote, `ssh_exec_script` saves PowerShell scripts as UTF-8 with BOM so Windows PowerShell reads Unicode
262
271
  correctly. CMD scripts switch to code page 65001 before running UTF-8 commands; an unavailable code page stops
263
272
  execution. POSIX scripts retain their original content.
264
273
 
274
+ Host cancellation stops subsequent batch commands and queued parallel work, including batches with `stopOnError=false`.
275
+ It also stops later script upload, permission preparation, interpreter dispatch, and password input to a late sudo
276
+ channel.
277
+ Script cleanup uses a separate timeout of at most 30000 ms and removes only this request's temporary file.
278
+ `keepScript=true` retains a script once execution has started; an upload or preparation failure still cleans it up.
279
+ Canceling a request closes its own channels and leaves other requests and any reused OpenSSH master available.
280
+
265
281
  ### Tracked operations
266
282
 
267
283
  | Tool | Description |
@@ -285,7 +301,8 @@ execution. POSIX scripts retain their original content.
285
301
  | `ssh_mkdir` | Create remote directory |
286
302
  | `ssh_sync` | Smart sync with rsync (fallback to SFTP) |
287
303
 
288
- `ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
304
+ `ssh_read_file` accepts regular files, including empty files. A directory is rejected before opening a read stream
305
+ with guidance to use `ssh_list_dir`; other non-regular targets return a type error.
289
306
 
290
307
  ### PTY Sessions (Persistent Interactive Terminal)
291
308
 
@@ -454,7 +471,7 @@ that command. A reported exit signal is retained as `exitSignal` and classified
454
471
  ### Basic: Connect and Execute
455
472
 
456
473
  ```
457
- ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
474
+ ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
458
475
  ssh_exec(alias="myserver", command="ls -la /home")
459
476
  ssh_disconnect(alias="myserver")
460
477
  ```
@@ -492,6 +509,11 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
492
509
  from the session that was actually published. Concurrent calls reuse an alias only when the complete session
493
510
  configuration matches, including endpoint, authentication, `runAs`, environment, jump host, keepalive, and timeout
494
511
  settings. A conflicting pending or active connection is rejected even when its `user@host:port` identity is unchanged.
512
+ Conflict errors include `details.differingFields` with configuration field names only. OpenSSH configuration preparation
513
+ registers the requested alias, `configHost`, or initial endpoint. Disconnect cancels its owned `ssh -G` process and
514
+ prevents a later connection, including the preparation-to-connect handoff. A later connection can reuse the resolved
515
+ alias when `ssh -G` changes the hostname, user, or port.
516
+
495
517
  Missing templates include available template names when they can be loaded. Missing `configHost` returns SSH config
496
518
  candidates and suggests `ssh_config_list`.
497
519
 
@@ -503,12 +525,12 @@ Connect to internal server via jump host:
503
525
  ssh_connect(
504
526
  host="<internal-host>",
505
527
  user="root",
506
- keyPath="/home/.ssh/id_rsa",
528
+ keyPath="~/.ssh/id_rsa",
507
529
  alias="internal",
508
530
  jumpHost={
509
531
  host: "bastion.example.com",
510
532
  user: "admin",
511
- keyPath: "/home/.ssh/bastion_key"
533
+ keyPath: "~/.ssh/bastion_key"
512
534
  }
513
535
  )
514
536
  ```
@@ -518,7 +540,7 @@ ssh_connect(
518
540
  Perfect for scenarios where you SSH as root but need to run commands as another user:
519
541
 
520
542
  ```
521
- 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
543
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
522
544
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
523
545
  // Output: appuser
524
546
  ```
@@ -623,11 +645,12 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
623
645
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
624
646
  ```
625
647
 
626
- This keeps log querying in the general command and file tools instead of adding a separate log-specific MCP surface.
627
- The
628
- `ssh_exec_script.timeout` value applies while uploading the temporary script, preparing its permissions, and running
629
- it.
630
- A stalled SFTP upload therefore ends on the requested timeout instead of using the default SFTP budget.
648
+ Log querying uses the general command and file tools. `ssh_exec_script.timeout` independently limits temporary script
649
+ upload, permission preparation, and execution. Explicit values use positive integer milliseconds, up to 3600000. Cleanup
650
+ has its own timeout: the smaller of the requested value and 30000 ms, or 30000 ms when omitted. Without an explicit
651
+ timeout, commands retain their 30000 ms default and SFTP retains 600000 ms. Host request deadlines apply separately.
652
+ Use `ssh_operation_start/status/read/cancel` for long observations: a host abort of synchronous exec leaves the remote
653
+ process's stop state unknown.
631
654
 
632
655
  ### With Environment Variables
633
656
 
@@ -635,7 +658,7 @@ A stalled SFTP upload therefore ends on the requested timeout instead of using t
635
658
  ssh_connect(
636
659
  host="<server-host>",
637
660
  user="root",
638
- keyPath="/home/.ssh/id_rsa",
661
+ keyPath="~/.ssh/id_rsa",
639
662
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
640
663
  )
641
664
  ```
@@ -649,7 +672,7 @@ No need to manage connections for single commands. `ssh_quick_exec` creates a un
649
672
  ssh_quick_exec(
650
673
  host="<server-host>",
651
674
  user="root",
652
- keyPath="/home/.ssh/id_rsa",
675
+ keyPath="~/.ssh/id_rsa",
653
676
  command="uptime"
654
677
  )
655
678
  ```
@@ -720,7 +743,9 @@ tools.
720
743
 
721
744
  `ssh_upload` , `ssh_download` , `ssh_read_file` , `ssh_write_file` , `ssh_list_dir` , `ssh_file_info` , and
722
745
  `ssh_mkdir` accept
723
- `timeout` for one SFTP operation. It defaults to 10 minutes and accepts up to one hour. Timeouts retain local and
746
+ `timeout` for one SFTP operation. Downloads use one total deadline for transfer and failure diagnostics;
747
+ when time expires or the host cancels, remote probing stops and local diagnostics remain available. It defaults to
748
+ 10 minutes and accepts up to one hour. Timeouts retain local and
724
749
  remote probe diagnostics. Uploads and writes report `operationStatus="unknown"` when an
725
750
  OPEN, WRITE, or CLOSE request was dispatched without a completion reply. Explicit server refusal returns `failed` .
726
751
  Read-only upload preflight failures also return `failed` ,
@@ -842,9 +867,18 @@ mode. Directory sources reject `recursive=false`. Relative exclude patterns are
842
867
  source root; patterns without `/` match each basename. A trailing `/` restricts a pattern to directories:
843
868
  `provider/` skips directories with that basename and their contents while retaining regular files named `provider`.
844
869
 
845
- A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation behavior. Downloads create missing local parents; an rsync parent-preparation failure returns `failureStage="local_prepare"` before the transfer process starts.
870
+ A single-file upload requires an existing remote parent directory. A known missing parent or a parent that is a
871
+ file fails before upload with `failureStage="remote_prepare"` and `REMOTE_PARENT_NOT_FOUND` or
872
+ `REMOTE_PARENT_NOT_DIRECTORY`; use `ssh_mkdir` for a missing parent. Directory sync retains its recursive creation
873
+ behavior. Downloads create missing local parents; a failure during rsync parent preparation returns
874
+ `failureStage="local_prepare"` before the transfer process starts.
846
875
 
847
- Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning, with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the client's absolute request deadline remain separate from progress-driven idle-timeout resets.
876
+ Clients requesting `_meta.progressToken` receive `notifications/progress` from SFTP and rsync transfers, including
877
+ recursive sync, at most once per second while transfer bytes advance. `progress` is an increasing notification
878
+ sequence; `message` reports the current file's bytes and percentage, with its total when known. Calls without a
879
+ token keep the same transfer result. Cancellation stops later notifications. Notification errors produce a warning,
880
+ with `progressWarning` when available, while the transfer retains its own outcome. The operation deadline and the
881
+ client's absolute request deadline remain separate from progress-driven idle-timeout resets.
848
882
 
849
883
  For a regular file, `verify.sha256`, `verify.owner`, `verify.mode`, and Windows `verify.aclSddl` apply to the actual
850
884
  transferred file in either direction. The result uses `kind="single_file"` and includes the file digest, not a
@@ -855,7 +889,7 @@ local and remote hashing, including the SFTP transport check. `verify.count`, `v
855
889
  require a directory source and are rejected before transfer for a file. A known source file larger than the requested
856
890
  hash budget is also rejected before transfer.
857
891
 
858
- Directory verification builds bounded local and remote manifests. It can compare entry count, an SHA-256 root
892
+ Directory verification builds bounded local and remote manifests. It can compare entry count, a SHA-256 root
859
893
  manifest,
860
894
  owner, all four octal mode digits (including setuid, setgid, and sticky), stale entries, and deletion results.
861
895
  `verify.deletions=true` requires `delete=true` ; it records the destination before transfer and only checks whether
@@ -897,6 +931,29 @@ hash streams and stops later checks, while preserving completed file and byte co
897
931
  result
898
932
  has `success=false` and a timed-out verification outcome.
899
933
 
934
+ `bandwidthLimitKiBps` optionally limits aggregate transfer payload to KiB/s (1 KiB = 1024 bytes), for rsync and
935
+ SFTP, in either direction. Omit it for the existing unrestricted speed. Concurrent and recursive SFTP file
936
+ transfers share one limit; metadata and explicitly requested verification reads have separate costs. For example,
937
+ `ssh_sync(..., bandwidthLimitKiBps=1024)` requests 1 MiB/s.
938
+
939
+ Canceling a running rsync request terminates and waits for its own local process group, retaining reported
940
+ itemization/deletion counts and `lastProgress`. The result is `cancelled=true`, `operationStatus="unknown"`: remote
941
+ writes or deletions already dispatched require inspection. The alias, other requests, and the reused OpenSSH master
942
+ remain available.
943
+
944
+ Directory `checks` uses `null` for unrequested checks, `true` for an executed match, and `false` for a mismatch.
945
+ Top-level `verificationStatus` distinguishes unrequested, skipped, matched, mismatched, and error outcomes.
946
+ Explicit single-file SHA-256 verification reads each endpoint once and shares its digest with
947
+ `transportVerification`; byte limits and metadata stability checks still apply.
948
+
949
+ `ssh_mkdir` uses the SFTP login identity, independently of command `runAs`. Its response includes `loginUser`,
950
+ `runAs`, `creationIdentity="sftp_login"`, and actual numeric `owner`, `group`, `mode`, and `permissions`. Directory
951
+ access follows those returned permissions; the tool preserves ownership and permission policy. Once creation is
952
+ acknowledged, a later metadata read failure returns `success=true`, `operationStatus="completed"`, `retryable=false`,
953
+ and `metadataStatus="unavailable"`. `metadataError` contains the metadata failure in the existing error format,
954
+ including any timeout details; unavailable `owner`, `group`, `mode`, and `permissions` are omitted. Use `ssh_file_info`
955
+ to read metadata again. Directory creation failures retain their original error response.
956
+
900
957
  Directory root digests sort paths by their UTF-8 bytes, independent of enumeration order or locale. Case-distinct and
901
958
  Unicode NFC/NFD-distinct names remain separate entries; file names are not normalized.
902
959
 
@@ -1073,6 +1130,11 @@ also include
1073
1130
 
1074
1131
  ### Exec Options
1075
1132
 
1133
+ `ssh_exec(..., stdin="text")` sends UTF-8 input followed by EOF through ssh2 or the reused OpenSSH channel. Empty
1134
+ input sends EOF; omitting `stdin` retains existing behavior. Input stays out of the command string and
1135
+ input-delivery errors. A canceled request closes its own channel and returns remote state `unknown`, while the
1136
+ alias and master remain available. Commands that intentionally print their input still control their own output.
1137
+
1076
1138
  | Option | Type | Default | Description |
1077
1139
  | --------------- | ------- | ------------- | ------------------------------------------ |
1078
1140
  | `timeout` | number | 30000 | Command timeout in ms |
package/README_zh.md CHANGED
@@ -10,7 +10,7 @@
10
10
 
11
11
  ![Linux](https://img.shields.io/badge/Linux-tested-success)
12
12
  ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
13
- ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
13
+ [![Windows](https://img.shields.io/badge/Windows-native%20regressions-success)](TESTING.md)
14
14
 
15
15
  ## 迁移到 3.0
16
16
 
@@ -30,6 +30,7 @@ PTY 的 `bufferSize` 参数与列表结果中的 `bufferSize`,以及 read/list
30
30
 
31
31
  连接 Windows 主机须设置 `remotePlatform="windows"`,本机为 Windows 不会改变远端默认值;按主机设置 `commandShell` 和
32
32
  `remotePathStyle`,使用 Windows rsync 时显式设置 `rsyncProfile`;下文 Windows 功能和示例继续适用
33
+ 本机权限、启动身份与文件名检查忽略继承的 `PSModulePath`,从 PowerShell 7 启动 MCP 时仍可使用 Windows PowerShell 5.1,远端命令和用户脚本沿用各自配置的环境
33
34
 
34
35
  ## 主机密钥信任
35
36
 
@@ -48,7 +49,9 @@ SHA2 签名
48
49
  目标失败保留共享跳板和无关 alias;显式 connect/reconnect 重新验证信任,普通网络断线仍自动重连
49
50
  支持哈希主机名、host/port、IPv6、多名称、通配和否定模式,匹配
50
51
  CA 或主机证书记录时使用 OpenSSH
51
- 后端;首次信任写入使用持有者目录排他锁,等待有期限且可取消,完整持有者记录发布后才开始写入信任;在同一可核实的本地进程域内,自动恢复已核实退出的持有者
52
+ 后端;首次信任写入使用持有者目录排他锁,等待有期限且可取消
53
+ 准备与权限检查共用连接总期限,五秒锁竞争预算从准备完成后开始,并受该总期限约束
54
+ 完整持有者记录发布后才开始写入信任;在同一可核实的本地进程域内,自动恢复已核实退出的持有者
52
55
  Linux 使用 `/proc` 启动标识与 PID 命名空间,macOS 使用 `kern.bootsessionuuid`,Windows 通过系统自带 PowerShell 查询内核的
53
56
  `SystemBootEnvironmentInformation.BootIdentifier`
54
57
  存活或已复用的 PID、存活探测被拒绝、启动标识或进程域无法取得或不匹配时,保留锁并等待至期限或取消
@@ -401,7 +404,7 @@ channel 关闭且没有收到退出状态时,返回 `exitCode=null`、`failure
401
404
  ### 基础:连接和执行
402
405
 
403
406
  ```
404
- ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="myserver")
407
+ ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="myserver")
405
408
  ssh_exec(alias="myserver", command="ls -la /home")
406
409
  ssh_disconnect(alias="myserver")
407
410
  ```
@@ -438,6 +441,19 @@ ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
438
441
  host、keepalive 和 timeout;pending 或 active 连接的配置冲突时会被拒绝,即使 `user@host:port`
439
442
  identity 相同,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
440
443
 
444
+ 配置冲突通过 `details.differingFields` 返回不同的配置字段名,字段值和凭证保持私有
445
+ OpenSSH 配置准备按请求 alias、`configHost` 或初始连接地址登记,disconnect 会终止本次自有 `ssh -G` 进程
446
+ 准备结束与连接登记之间发生的取消同样生效,`ssh -G` 改变主机名、用户或端口后,后续请求仍可重新连接解析后的 alias
447
+
448
+ `ssh_exec(..., stdin="text")` 经 ssh2 或复用的 OpenSSH 通道写入 UTF-8 内容并发送 EOF,空字符串只发送 EOF,省略时保持原输入行为,输入不写入命令字符串或输入发送错误,
449
+ 请求取消会关闭本次通道并返回远端状态 `unknown`,alias 与 master 继续可用,命令主动输出输入内容时按实际命令输出返回
450
+
451
+ 宿主取消请求后,批量命令与排队中的并行任务停止派发,`stopOnError=false` 同样生效
452
+ 脚本停止后续上传、权限准备和解释器执行,迟到的 sudo 通道不再接收密码
453
+ 脚本清理使用独立期限,最长 30000 ms,仅删除本次创建的临时文件
454
+ `keepScript=true` 在开始执行后保留脚本,上传或准备失败时仍执行清理
455
+ 取消仅关闭本次通道,其他请求及复用的 OpenSSH master 继续可用
456
+
441
457
  ### 跳板机
442
458
 
443
459
  通过跳板机连接内网服务器:
@@ -446,12 +462,12 @@ identity 相同,template 缺失时返回可用模板名,`configHost` 缺失
446
462
  ssh_connect(
447
463
  host="<internal-host>",
448
464
  user="root",
449
- keyPath="/home/.ssh/id_rsa",
465
+ keyPath="~/.ssh/id_rsa",
450
466
  alias="internal",
451
467
  jumpHost={
452
468
  host: "bastion.example.com",
453
469
  user: "admin",
454
- keyPath: "/home/.ssh/bastion_key"
470
+ keyPath: "~/.ssh/bastion_key"
455
471
  }
456
472
  )
457
473
  ```
@@ -461,7 +477,7 @@ ssh_connect(
461
477
  适用于 SSH 以 root 登录,但需要以其他用户执行命令的场景:
462
478
 
463
479
  ```
464
- 1. ssh_connect(host="<server-host>", user="root", keyPath="/home/.ssh/id_rsa", alias="server")
480
+ 1. ssh_connect(host="<server-host>", user="root", keyPath="~/.ssh/id_rsa", alias="server")
465
481
  2. ssh_exec_as_user(alias="server", command="whoami", targetUser="appuser")
466
482
  // 输出: appuser
467
483
  ```
@@ -554,8 +570,9 @@ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
554
570
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
555
571
  ```
556
572
 
557
- 日志查询由通用命令和文件工具组合完成,不再提供独立的日志专用 MCP 工具;`ssh_exec_script.timeout`
558
- 同时用于临时脚本上传、权限准备和执行阶段;SFTP 上传停滞时按请求的 timeout 结束,不再使用默认 SFTP 预算
573
+ 日志查询由通用命令和文件工具组合完成;`ssh_exec_script.timeout` 分别限制临时脚本上传、权限准备和执行阶段,每阶段独立计时,显式值为正整数,最大 3600000 ms;清理阶段独立计时,使用请求值与 30000 ms 中的较小值,省略参数时为 30000 ms
574
+
575
+ 未传显式超时时,命令保持 30000 ms 默认值,SFTP 保持 600000 ms 默认值,宿主请求期限独立生效;长时间观察使用 `ssh_operation_start/status/read/cancel`,同步 exec 被宿主中止时远端进程停止状态仍为未知
559
576
 
560
577
  ### 设置环境变量
561
578
 
@@ -563,7 +580,7 @@ ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=655
563
580
  ssh_connect(
564
581
  host="<server-host>",
565
582
  user="root",
566
- keyPath="/home/.ssh/id_rsa",
583
+ keyPath="~/.ssh/id_rsa",
567
584
  env={"LANG": "en_US.UTF-8", "LC_ALL": "en_US.UTF-8"}
568
585
  )
569
586
  ```
@@ -577,7 +594,7 @@ ssh_connect(
577
594
  ssh_quick_exec(
578
595
  host="<server-host>",
579
596
  user="root",
580
- keyPath="/home/.ssh/id_rsa",
597
+ keyPath="~/.ssh/id_rsa",
581
598
  command="uptime"
582
599
  )
583
600
  ```
@@ -638,7 +655,8 @@ user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB
638
655
  `next_offset`;行范围读取不执行远端 shell 工具
639
656
 
640
657
  `ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
641
- 支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时,超时保留本地与远端探测诊断
658
+ 支持 `timeout`,默认 10 分钟,最大 1 小时,下载与失败诊断共用一次总期限
659
+ 取消或超期后停止远端探测,保留原错误与本地详情,其他文件工具仍按单个 SFTP 操作计时
642
660
  上传和写入已派发 OPEN、WRITE 或 CLOSE 且丢失完成应答时,返回 `operationStatus="unknown"`;服务端明确拒绝返回 `failed`
643
661
  上传前只读探测失败也返回 `failed`,`failureStage="preflight"`,已确认写入字节为 0
644
662
  `failureStage`、受影响路径与 `acknowledgedBytes` 保留已确认进度,`retryable=false` 表示写入不会自动重放,重写前检查路径状态
@@ -751,7 +769,8 @@ ssh_sync(..., delete=true, verify={deletions: true})
751
769
  会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
752
770
  尾部 `/` 将模式限定为目录,`provider/` 排除每一级同名目录及其内容,保留名为 `provider` 的普通文件
753
771
 
754
- 单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或 `REMOTE_PARENT_NOT_DIRECTORY`
772
+ 单文件上传要求远端父目录存在,已知父目录缺失或父路径为文件时,在上传前返回 `failureStage="remote_prepare"` 和 `REMOTE_PARENT_NOT_FOUND` 或
773
+ `REMOTE_PARENT_NOT_DIRECTORY`
755
774
  缺失目录使用 `ssh_mkdir` 创建,目录同步仍按递归创建规则执行
756
775
  下载自动创建缺失的本地父目录,rsync 的本地准备失败在传输进程启动前返回 `failureStage="local_prepare"`
757
776
 
@@ -797,6 +816,20 @@ session 不经过这项凭证选择,也不回退到 SFTP,`preflightTimeout`
797
816
  校验超期会关闭本次持有的哈希流并停止后续检查,保留已完成的文件数、字节数与 `transferSuccess`,整体返回 `success=false`
798
817
  并明确报告校验超期
799
818
 
819
+ `bandwidthLimitKiBps` 为可选总传输限速,单位 KiB/s(1 KiB = 1024 bytes),适用于双向 rsync 和 SFTP,省略时保持原不限速行为,SFTP 并发文件和递归子目录共用本次限速,
820
+ 元数据和显式校验读取单独消耗资源,例如 `ssh_sync(..., bandwidthLimitKiBps=1024)` 请求 1 MiB/s
821
+
822
+ 取消运行中的 rsync 请求时,工具终止并等待本次自有本地进程组,保留已报告的文件明细、删除计数和 `lastProgress`,返回 `cancelled=true`、`operationStatus="unknown"`,
823
+ 已派发的远端写入和删除需要检查实际状态,alias、其他请求和复用的 OpenSSH master 保持可用
824
+
825
+ 目录 `checks` 使用 `null` 表示未请求,`true` 表示已执行且匹配,`false` 表示不匹配,顶层 `verificationStatus` 区分未请求、跳过、匹配、不匹配和错误,
826
+ 显式单文件 SHA-256 校验只完整读取每端一次,并将摘要共享给 `transportVerification`,保留字节预算及元数据稳定性检查
827
+
828
+ `ssh_mkdir` 使用 SFTP 登录身份,命令 `runAs` 单独生效,响应包含 `loginUser`、`runAs`、`creationIdentity="sftp_login"` 和实际数值 `owner`、
829
+ `group`、`mode` 及 `permissions`,后续目录访问由返回的权限决定,工具保持既有属主和权限策略
830
+ 创建已确认后,后续元信息读取失败时返回 `success=true`、`operationStatus="completed"`、`retryable=false` 和 `metadataStatus="unavailable"`,
831
+ `metadataError` 按既有错误格式保留元信息读取错误及超时详情,未取得的 `owner`、`group`、`mode` 和 `permissions` 省略,使用 `ssh_file_info` 重新读取元信息,目录创建自身失败时保留原错误响应
832
+
800
833
  目录根摘要按路径的 UTF-8 字节排序,不依赖枚举顺序或 locale,大小写不同与 NFC/NFD 不同的名称保持独立,不归一化文件名
801
834
 
802
835
  rsync 模式设置
@@ -123,7 +123,7 @@ function withoutQuotedText(command, shell) {
123
123
  const bodyStart = index;
124
124
  let bodyEnd = limit;
125
125
  let afterDelimiter = limit;
126
- // Delimiters are case-sensitive; input quotes never change shell quote state.
126
+ // Delimiters are case-sensitive; quoted input leaves the command parser quote state unchanged.
127
127
  for (let lineStart = index; lineStart < limit;) {
128
128
  let lineEnd = lineStart;
129
129
  let line = '';
@@ -512,15 +512,15 @@ export async function createOpenSshDirectoryManifest(connection, rootPath, reque
512
512
  throw new Error('OpenSSH manifest field exceeded its byte budget');
513
513
  }
514
514
  }, remaining());
515
- if (pending.length || fields.length) {
516
- throw new Error('OpenSSH manifest ended with incomplete metadata');
517
- }
518
515
  }
519
516
  catch (error) {
520
517
  if (error !== limit) {
521
518
  throw error;
522
519
  }
523
520
  }
521
+ if (!limitReason && (pending.length || fields.length)) {
522
+ throw new Error('OpenSSH manifest ended with incomplete metadata');
523
+ }
524
524
  if (!limitReason && request.sha256) {
525
525
  let hashedBytes = 0;
526
526
  for (const entry of entries) {
@@ -658,18 +658,18 @@ export function compareDirectoryManifests(expected, actual, request, deletionBas
658
658
  }
659
659
  const checks = {
660
660
  entries: missing === 0 && typeMismatch === 0,
661
- count: request.count ? expected.count === actual.count : true,
662
- sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : true,
663
- owner: request.owner ? ownerMismatch === 0 : true,
664
- mode: request.mode ? modeMismatch === 0 : true,
661
+ count: request.count ? expected.count === actual.count : null,
662
+ sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 : null,
663
+ owner: request.owner ? ownerMismatch === 0 : null,
664
+ mode: request.mode ? modeMismatch === 0 : null,
665
665
  deletions: request.deletions
666
666
  ? deletionBaseline !== undefined && remainingDeletionCandidates.length === 0
667
- : true,
668
- staleFiles: request.staleFiles ? stale === 0 : true,
667
+ : null,
668
+ staleFiles: request.staleFiles ? stale === 0 : null,
669
669
  };
670
670
  return {
671
671
  kind: 'directory',
672
- matched: Object.values(checks).every(Boolean),
672
+ matched: Object.values(checks).every((value) => value !== false),
673
673
  checks,
674
674
  expected: { count: expected.count, rootSha256: request.sha256 ? expected.rootSha256 : undefined },
675
675
  actual: { count: actual.count, rootSha256: request.sha256 ? actual.rootSha256 : undefined },
@@ -91,7 +91,7 @@ export declare class UploadFileError extends Error {
91
91
  /**
92
92
  * 上传文件
93
93
  */
94
- export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number): Promise<{
94
+ export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, createMode?: number, signal?: AbortSignal, followSymlinks?: boolean, exclusive?: boolean, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
95
95
  success: boolean;
96
96
  size: number;
97
97
  createMode: string;
@@ -99,7 +99,7 @@ export declare function uploadFile(alias: string, localPath: string, remotePath:
99
99
  /**
100
100
  * 下载文件
101
101
  */
102
- export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number): Promise<{
102
+ export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper, signal?: AbortSignal, timeout?: number, throttle?: (bytes: number) => Promise<void>): Promise<{
103
103
  success: boolean;
104
104
  size: number;
105
105
  atomic: true;
@@ -141,12 +141,12 @@ type ReadFileResult = {
141
141
  * 读取远程文件内容
142
142
  */
143
143
  export declare function readFile(alias: string, remotePath: string, options?: number | ReadFileOptions): Promise<ReadFileResult>;
144
- export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number): Promise<void>;
145
- export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string): Promise<void>;
144
+ export declare function createEmptyRemoteFile(alias: string, remotePath: string, timeout?: number, signal?: AbortSignal): Promise<void>;
145
+ export declare function prepareWindowsRemotePrivateFile(alias: string, remotePath: string, timeout?: number, shellPath?: string, signal?: AbortSignal): Promise<void>;
146
146
  /**
147
147
  * 写入远程文件
148
148
  */
149
- export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number): Promise<{
149
+ export declare function writeFile(alias: string, remotePath: string, content: string, append?: boolean, timeout?: number, signal?: AbortSignal): Promise<{
150
150
  success: boolean;
151
151
  size: number;
152
152
  }>;
@@ -173,6 +173,8 @@ type SyncOptions = {
173
173
  recursive?: boolean;
174
174
  followSymlinks?: boolean;
175
175
  verifySha256?: boolean;
176
+ bandwidthLimitKiBps?: number;
177
+ throttle?: (bytes: number) => Promise<void>;
176
178
  preflightTimeout?: number;
177
179
  connectTimeout?: number;
178
180
  operationTimeout?: number;
@@ -225,6 +227,8 @@ type SyncResult = {
225
227
  connectStatus?: 'completed' | 'failed' | 'not_applicable';
226
228
  operationStatus?: 'completed' | 'failed' | 'unknown';
227
229
  failureStage?: string;
230
+ cancelled?: boolean;
231
+ lastProgress?: TransferProgress;
228
232
  timedOut?: boolean;
229
233
  retryable?: boolean;
230
234
  direction?: 'upload' | 'download';