@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 +84 -22
- package/README_zh.md +45 -12
- package/dist/command-risk.js +1 -1
- package/dist/directory-verification.js +10 -10
- package/dist/file-ops.d.ts +9 -5
- package/dist/file-ops.js +165 -58
- package/dist/known-hosts.d.ts +2 -2
- package/dist/known-hosts.js +110 -59
- package/dist/openssh.d.ts +5 -5
- package/dist/openssh.js +92 -38
- package/dist/remote-platform.js +2 -2
- package/dist/session-manager.d.ts +7 -1
- package/dist/session-manager.js +140 -23
- package/dist/sftp-timeout.d.ts +1 -1
- package/dist/sftp-timeout.js +12 -2
- package/dist/tools/connection.js +14 -10
- package/dist/tools/exec.js +66 -35
- package/dist/tools/file.js +93 -21
- package/dist/transfer-outcome.js +1 -1
- package/dist/types.d.ts +4 -1
- package/dist/windows-acl.d.ts +3 -2
- package/dist/windows-acl.js +23 -10
- package/package.json +5 -5
package/README.md
CHANGED
|
@@ -10,7 +10,7 @@ SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.)
|
|
|
10
10
|
|
|
11
11
|

|
|
12
12
|

|
|
13
|
-
](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.
|
|
70
|
-
|
|
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
|
|
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
|
|
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
|
|
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="
|
|
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="
|
|
528
|
+
keyPath="~/.ssh/id_rsa",
|
|
507
529
|
alias="internal",
|
|
508
530
|
jumpHost={
|
|
509
531
|
host: "bastion.example.com",
|
|
510
532
|
user: "admin",
|
|
511
|
-
keyPath: "
|
|
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="
|
|
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
|
-
|
|
627
|
-
|
|
628
|
-
|
|
629
|
-
|
|
630
|
-
|
|
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="
|
|
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="
|
|
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.
|
|
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
|
|
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
|
|
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,
|
|
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
|

|
|
12
12
|

|
|
13
|
-
](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="
|
|
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="
|
|
465
|
+
keyPath="~/.ssh/id_rsa",
|
|
450
466
|
alias="internal",
|
|
451
467
|
jumpHost={
|
|
452
468
|
host: "bastion.example.com",
|
|
453
469
|
user: "admin",
|
|
454
|
-
keyPath: "
|
|
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="
|
|
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
|
-
|
|
558
|
-
|
|
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="
|
|
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="
|
|
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
|
-
|
|
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` 或
|
|
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 模式设置
|
package/dist/command-risk.js
CHANGED
|
@@ -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
|
|
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 :
|
|
662
|
-
sha256: request.sha256 ? expected.rootSha256 === actual.rootSha256 :
|
|
663
|
-
owner: request.owner ? ownerMismatch === 0 :
|
|
664
|
-
mode: request.mode ? modeMismatch === 0 :
|
|
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
|
-
:
|
|
668
|
-
staleFiles: request.staleFiles ? stale === 0 :
|
|
667
|
+
: null,
|
|
668
|
+
staleFiles: request.staleFiles ? stale === 0 : null,
|
|
669
669
|
};
|
|
670
670
|
return {
|
|
671
671
|
kind: 'directory',
|
|
672
|
-
matched: Object.values(checks).every(
|
|
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 },
|
package/dist/file-ops.d.ts
CHANGED
|
@@ -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';
|