@pyrokine/mcp-ssh 2.4.0 → 2.4.2

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_zh.md CHANGED
@@ -8,8 +8,7 @@
8
8
  [![Node](https://img.shields.io/badge/node-%3E%3D20.19-green.svg)](https://nodejs.org/)
9
9
  [![MCP](https://img.shields.io/badge/MCP-compatible-purple.svg)](https://modelcontextprotocol.io/)
10
10
 
11
- ![Linux](https://img.shields.io/badge/Linux-tested-success)
12
- ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
11
+ ![Linux](https://img.shields.io/badge/Linux-tested-success) ![macOS](https://img.shields.io/badge/macOS-untested-yellow)
13
12
  ![Windows](https://img.shields.io/badge/Windows-untested-yellow)
14
13
 
15
14
  ## 功能特性
@@ -36,15 +35,15 @@
36
35
 
37
36
  ## 兼容客户端
38
37
 
39
- | 客户端 | 状态 |
40
- |----------------|----|
41
- | Claude Code | ✅ |
42
- | Claude Desktop | ✅ |
43
- | Cursor | ✅ |
44
- | Windsurf | ✅ |
45
- | Continue.dev | ✅ |
46
- | Cline | ✅ |
47
- | 其他 MCP 兼容客户端 | ✅ |
38
+ | 客户端 | 状态 |
39
+ | ------------------- | ---- |
40
+ | Claude Code | ✅ |
41
+ | Claude Desktop | ✅ |
42
+ | Cursor | ✅ |
43
+ | Windsurf | ✅ |
44
+ | Continue.dev | ✅ |
45
+ | Cline | ✅ |
46
+ | 其他 MCP 兼容客户端 | ✅ |
48
47
 
49
48
  ## 安装
50
49
 
@@ -85,14 +84,12 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
85
84
 
86
85
  ```json
87
86
  {
88
- "mcpServers": {
89
- "ssh": {
90
- "command": "node",
91
- "args": [
92
- "/path/to/mcp-ssh/dist/index.js"
93
- ]
87
+ "mcpServers": {
88
+ "ssh": {
89
+ "command": "node",
90
+ "args": ["/path/to/mcp-ssh/dist/index.js"]
91
+ }
94
92
  }
95
- }
96
93
  }
97
94
  ```
98
95
 
@@ -100,70 +97,78 @@ claude mcp add ssh -- node /path/to/mcp-ssh/dist/index.js
100
97
 
101
98
  ### 连接管理
102
99
 
103
- | 工具 | 描述 |
104
- |---------------------|-----------------------------|
100
+ | 工具 | 描述 |
101
+ | ------------------- | ----------------------------------- |
105
102
  | `ssh_connect` | 建立 SSH 连接(支持 ~/.ssh/config) |
106
- | `ssh_disconnect` | 关闭连接 |
107
- | `ssh_list_sessions` | 列出精简会话,可选详情或字段筛选 |
108
- | `ssh_reconnect` | 重新连接断开的会话 |
109
- | `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
103
+ | `ssh_disconnect` | 关闭连接 |
104
+ | `ssh_list_sessions` | 列出精简会话,可选详情或字段筛选 |
105
+ | `ssh_reconnect` | 重新连接断开的会话 |
106
+ | `ssh_config_list` | 列出 ~/.ssh/config 中的 Host |
107
+
108
+ `ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true`
109
+ 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
110
+
111
+ `ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效。
112
+
113
+ 自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话。
110
114
 
111
- `ssh_list_sessions()` 默认只返回 `alias`、规范化 `identity`、`runAs`、`connected` 和 `lastUsedAt`,使用 `detail=true` 获取连接详情,或通过 `fields=[...]` 选择字段,任何模式都不返回 `keyPath`
115
+ 旧 client 延迟到达的 `close` 不会让过期资源继续挂在同一 alias 下;通过 jump host 建立目标连接时,如果取消发生在
116
+ `forwardOut` pending 阶段,延迟 callback 返回的 channel 会先销毁再结束连接请求
112
117
 
113
118
  ### 命令执行
114
119
 
115
- | 工具 | 描述 |
116
- |---------------------|--------------------|
117
- | `ssh_exec` | 执行命令(支持 PTY 模式) |
120
+ | 工具 | 描述 |
121
+ | ------------------- | ------------------------------- |
122
+ | `ssh_exec` | 执行命令(支持 PTY 模式) |
118
123
  | `ssh_exec_as_user` | 以其他用户身份执行(通过 `su`) |
119
- | `ssh_exec_sudo` | 使用 `sudo` 执行 |
120
- | `ssh_exec_batch` | 批量执行多条命令 |
121
- | `ssh_exec_parallel` | 在多台主机上并行执行命令 |
122
- | `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
123
- | `ssh_exec_script` | 上传并执行远端临时脚本 |
124
+ | `ssh_exec_sudo` | 使用 `sudo` 执行 |
125
+ | `ssh_exec_batch` | 批量执行多条命令 |
126
+ | `ssh_exec_parallel` | 在多台主机上并行执行命令 |
127
+ | `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
128
+ | `ssh_exec_script` | 上传并执行远端临时脚本 |
124
129
 
125
130
  ### 可跟踪任务
126
131
 
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 过滤 |
132
+ | 工具 | 描述 |
133
+ | ---------------------- | --------------------------------------- |
134
+ | `ssh_operation_start` | 启动可跟踪的长时间远端命令 |
135
+ | `ssh_operation_status` | 读取状态、PID、退出码和输出计数 |
136
+ | `ssh_operation_read` | 按字节偏移读取有上限的 stdout 和 stderr |
137
+ | `ssh_operation_cancel` | 校验任务 marker 后发送 TERM |
138
+ | `ssh_operation_list` | 列出未过期任务,可按 alias 过滤 |
134
139
 
135
140
  ### 文件操作
136
141
 
137
- | 工具 | 描述 |
138
- |------------------|------------------------|
139
- | `ssh_upload` | 上传本地文件到远程 |
140
- | `ssh_download` | 从远程下载文件到本地 |
141
- | `ssh_read_file` | 读取远程文件内容 |
142
- | `ssh_write_file` | 写入内容到远程文件 |
143
- | `ssh_list_dir` | 列出远程目录内容 |
144
- | `ssh_file_info` | 获取文件/目录元数据 |
145
- | `ssh_mkdir` | 创建远程目录 |
142
+ | 工具 | 描述 |
143
+ | ---------------- | --------------------------------- |
144
+ | `ssh_upload` | 上传本地文件到远程 |
145
+ | `ssh_download` | 从远程下载文件到本地 |
146
+ | `ssh_read_file` | 读取远程文件内容 |
147
+ | `ssh_write_file` | 写入内容到远程文件 |
148
+ | `ssh_list_dir` | 列出远程目录内容 |
149
+ | `ssh_file_info` | 获取文件/目录元数据 |
150
+ | `ssh_mkdir` | 创建远程目录 |
146
151
  | `ssh_sync` | 智能同步(优先 rsync,回退 SFTP) |
147
152
 
148
153
  ### PTY 会话(持久化交互式终端)
149
154
 
150
- | 工具 | 描述 |
151
- |------------------|-----------------------------------------|
152
- | `ssh_pty_start` | 启动持久化 PTY 会话(用于 top、htop、tmux 等) |
153
- | `ssh_pty_write` | 向 PTY 发送数据(按键、命令) |
155
+ | 工具 | 描述 |
156
+ | ---------------- | --------------------------------------------------------- |
157
+ | `ssh_pty_start` | 启动持久化 PTY 会话(用于 top、htop、tmux 等) |
158
+ | `ssh_pty_write` | 向 PTY 发送数据(按键、命令) |
154
159
  | `ssh_pty_read` | 读取 PTY 输出(screen 模式:当前屏幕,raw 模式:ANSI 流) |
155
- | `ssh_pty_resize` | 调整 PTY 窗口大小 |
156
- | `ssh_pty_close` | 关闭 PTY 会话 |
157
- | `ssh_pty_list` | 列出所有 PTY 会话 |
160
+ | `ssh_pty_resize` | 调整 PTY 窗口大小 |
161
+ | `ssh_pty_close` | 关闭 PTY 会话 |
162
+ | `ssh_pty_list` | 列出所有 PTY 会话 |
158
163
 
159
164
  ### 端口转发
160
165
 
161
- | 工具 | 描述 |
162
- |----------------------|-----------------------|
166
+ | 工具 | 描述 |
167
+ | -------------------- | ------------------------------------ |
163
168
  | `ssh_forward_local` | 本地端口转发(ssh -L):访问远程服务 |
164
169
  | `ssh_forward_remote` | 远程端口转发(ssh -R):暴露本地服务 |
165
- | `ssh_forward_close` | 关闭端口转发 |
166
- | `ssh_forward_list` | 列出所有端口转发 |
170
+ | `ssh_forward_close` | 关闭端口转发 |
171
+ | `ssh_forward_list` | 列出所有端口转发 |
167
172
 
168
173
  ## 使用示例
169
174
 
@@ -214,9 +219,9 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
214
219
  4. ssh_exec_parallel(aliases=["server1", "server2", "server3"], command="uptime")
215
220
  ```
216
221
 
217
- 每台主机的结果保留与 `ssh_exec` 相同的执行元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议。
218
- `ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持 `maxOutputSize`
219
- 限制每台主机的输出
222
+ 每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议。
223
+ `ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持
224
+ `maxOutputSize` 限制每台主机的输出
220
225
 
221
226
  ### 基础:连接和执行
222
227
 
@@ -228,7 +233,8 @@ ssh_disconnect(alias="myserver")
228
233
 
229
234
  ### 连接模板和 runAs
230
235
 
231
- 模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json` 提供,工具显式参数优先于模板值
236
+ 模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json`
237
+ 提供,工具显式参数优先于模板值。选中的模板会在连接前校验,SSH 端口必须是 1 到 65535 的整数。模板无效时,错误只返回模板名和字段路径,不返回认证值
232
238
 
233
239
  ```json
234
240
  {
@@ -250,9 +256,11 @@ ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
250
256
  ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
251
257
  ```
252
258
 
253
- `ssh_connect` 返回 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一 `user@host:port` identity
254
- 下已连接 alias 的 `reusableSessions`,同一个 alias 连接到不同 identity 会被拒绝,并返回现有 identity 和请求
255
- identity,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
259
+ `ssh_connect` 返回实际发布会话的 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一
260
+ `user@host:port` identity 下已连接 alias 的
261
+ `reusableSessions`,并发调用只有在完整会话配置一致时才复用同一 alias,包括 endpoint、认证、`runAs`、环境变量、jump
262
+ host、keepalive 和 timeout;pending 或 active 连接的配置冲突时会被拒绝,即使 `user@host:port`
263
+ identity 相同,template 缺失时返回可用模板名,`configHost` 缺失时返回 SSH config 候选并提示调用 `ssh_config_list`
256
264
 
257
265
  ### 跳板机
258
266
 
@@ -282,27 +290,47 @@ ssh_connect(
282
290
  // 输出: appuser
283
291
  ```
284
292
 
285
- 默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
293
+ 默认加载 shell 配置以确保环境变量可用(`su -c`
294
+ 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
286
295
  )及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
287
296
 
288
- `ssh_exec` 和 `ssh_exec_as_user` 返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
297
+ `ssh_exec`、`ssh_exec_as_user` 和 `ssh_exec_sudo` 使用相同的身份优先级:`useLoginUser=true` 使用登录用户,否则本次
298
+ `runAs` 覆盖连接级 `runAs`,再使用连接级 `runAs`。
299
+
300
+ `ssh_exec` 和 `ssh_exec_as_user`
301
+ 返回执行元数据:`loginUser`、`effectiveUser`、`identity`、`cwd`、`resolvedCwd`、`shell`、
289
302
  `profileLoaded`、`envInjectedKeys`、`failureKind`、`stdoutBytes`、`stderrBytes` 和截断提示,大输出会返回 `stdoutHead`、
290
- `stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`,timeout 错误也包含超时前已经产生的 head/tail 输出,包含
291
- destructive、process-control、service-control、credential-bearing、未限制 `find`、递归 `grep`、长管道、后台任务、直接
292
- `su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
303
+ `stdoutTail`、`stderrHead`、`stderrTail` 和 `recommendedReadCommand`。
304
+
305
+ timeout 错误也包含超时前已经产生的 head/tail 输出。
306
+
307
+ 包含 destructive、process-control、service-control、credential-bearing、未限制 `find`、递归
308
+ `grep`、长管道、后台任务、直接 `su - user -c` 或长运行模式的命令会返回带 `categories` 和 `signals` 的 `commandRisk`
293
309
 
294
310
  ### 可跟踪的长时间命令
295
311
 
296
312
  需要命令跨越一次同步工具调用继续执行时,使用 operation 工具组:
297
313
 
298
314
  ```
299
- ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576)
315
+ ssh_operation_start(alias="server", command="long-running-job", maxOutputBytes=1048576, startTimeoutMs=30000)
300
316
  ssh_operation_status(operationId="op_xxx")
301
317
  ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxBytes=65536)
302
318
  ssh_operation_cancel(operationId="op_xxx")
303
319
  ```
304
320
 
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 行为
321
+ start 返回不可预测的 `operationId`,服务端在请求 SSH
322
+ channel 前创建记录,保存有硬上限的 stdout 和 stderr,并在校验每个任务独立的 marker 后记录远端 PID;`startTimeoutMs`
323
+ 限制 channel 建立等待,默认 30 秒、最大 10 分钟,超时错误的 details 返回 `operationId`,对应记录进入可查询的 `unknown`
324
+ 终态,在旧 channel request 返回或 alias 断开前拒绝同 alias 的另一次 pending start;`maxOutputBytes` 默认 1 MiB、最大 8
325
+ MiB,`retentionMs` 默认 1 小时、最大 24 小时,`ssh_operation_read.maxBytes` 默认 64 KiB、最大 1
326
+ MiB,marker 和 PID 未完成校验时拒绝取消,shell
327
+ profile 在 marker 前写入的 stderr 会保留为任务输出,包括未换行 preamble 后紧接 marker 的情况;使用 operation
328
+ marker 前缀但 token 不匹配、长度超限或进程元数据无效时,记录进入 `failed`
329
+ 终态、关闭 channel 并开始 retention 计时;断开或替换 SSH session 后才返回的 exec、sudo、SFTP、PTY start 和 operation
330
+ start callback 都会被拒绝并销毁 channel,sudo callback 在 timeout 后返回时也会先关闭,不会写入密码;operation
331
+ listener 会在 SSH exec callback 返回前安装,极短命令即使立即输出 marker 并关闭,也会进入终态并设置 `finishedAt` 和
332
+ `expiresAt`;SSH 会话在 tracked command 运行期间断开后状态变为 `unknown`,不会声称远端进程已经停止,`ssh_exec`
333
+ 保持原有同步 timeout 行为
306
334
 
307
335
  ### 交互式命令(PTY 模式)
308
336
 
@@ -320,12 +348,17 @@ ssh_exec_script(alias="server", script="set -e\nwhoami\npwd", cwd="/tmp", runAs=
320
348
 
321
349
  日志发现和过滤使用 `ssh_exec_script`,大结果再用 `ssh_read_file` 分块读取:
322
350
 
351
+ ```bash
352
+ find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' \
353
+ | sort -nr | head -20 > /tmp/mcp-log-files.txt
354
+ grep -n -I -F 'ERROR' /var/log/app/*.log \
355
+ | head -100 > /tmp/mcp-log-errors.txt
356
+ ```
357
+
358
+ 执行上面的脚本,再读取结果:
359
+
323
360
  ```
324
- ssh_exec_script(
325
- alias="server",
326
- script="find /var/log/app -maxdepth 1 -type f -printf '%T@ %p\\n' | sort -nr | head -20 > /tmp/mcp-log-files.txt\ngrep -n -I -F 'ERROR' /var/log/app/*.log | head -100 > /tmp/mcp-log-errors.txt",
327
- timeout=30000
328
- )
361
+ ssh_exec_script(alias="server", script=<script-above>, timeout=30000)
329
362
  ssh_read_file(alias="server", remotePath="/tmp/mcp-log-errors.txt", maxBytes=65536)
330
363
  ```
331
364
 
@@ -344,7 +377,8 @@ ssh_connect(
344
377
 
345
378
  ### 快速一次性执行
346
379
 
347
- 无需管理连接,适用于单次命令:
380
+ 无需管理连接,适用于单次命令。`ssh_quick_exec` 为每次调用创建唯一临时 alias,`readyTimeout` 只限制连接阶段,`timeout`
381
+ 只限制远端命令执行阶段:
348
382
 
349
383
  ```
350
384
  ssh_quick_exec(
@@ -360,7 +394,15 @@ ssh_quick_exec(
360
394
  ```
361
395
  // 上传
362
396
  ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json")
363
- ssh_upload(alias="server", localPath="/tmp/config.json", remotePath="/etc/app/config.json", atomic=true, verifySize=true, verifyMd5=true, verifyMode="0644")
397
+ ssh_upload(
398
+ alias="server",
399
+ localPath="/tmp/config.json",
400
+ remotePath="/etc/app/config.json",
401
+ atomic=true,
402
+ verifySize=true,
403
+ verifyMd5=true,
404
+ verifyMode="0644"
405
+ )
364
406
  // 目录返回 UPLOAD_PATH_IS_DIRECTORY,大文件上传成功后会提示优先使用 ssh_sync,并返回推荐调用
365
407
 
366
408
  // 下载
@@ -373,16 +415,40 @@ ssh_read_file(alias="server", remotePath="/var/log/app.log", offset=1048576, max
373
415
  ssh_read_file(alias="server", remotePath="/var/log/app.log", lineRange="120-180")
374
416
  ```
375
417
 
376
- `ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true` 会先上传到同目录临时文件,返回
377
- `diagnostics.tempRemotePath` 后再 rename 到目标路径,`verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime` 会追加显式传输后校验,命令执行结果在远端命令非零退出且没有
378
- stdout/stderr 时返回
379
- `emptyOutputFailure=true`,同时给出 effective user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过
380
- 16 MiB 时会在远端传输前拒绝,返回 `total_size`、`read_offset`、`read_bytes`、
381
- `remaining_bytes`、`sample_kind` 和 `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围
418
+ `ssh_upload` 返回本地路径策略诊断、远端父目录探测、远端目标元数据和可选校验结果,`atomic=true`
419
+ 使用不可预测的同目录临时路径和 SFTP 独占创建,返回
420
+ `diagnostics.tempRemotePath`,先对临时文件完成全部请求的校验,再 rename 到目标路径;响应使用 `finalRemotePath`
421
+ 表示最终目标,`verifiedRemotePath` 表示实际执行校验的路径,atomic 校验还会返回 `verifiedTempRemotePath`,
422
+ `verification.actual.remotePath` 始终描述真正被校验的文件,即使该临时路径随后已被 rename,最终状态需要结合
423
+ `targetReplaced` 和 `targetReplacementStatus` 判断;已有目标通过 OpenSSH `posix-rename@openssh.com`
424
+ 扩展替换,新目标使用标准 SFTP rename;客户端无法发出 rename 请求时返回
425
+ `operationStatus="failed"`、`targetReplaced=false` 和
426
+ `targetReplacementStatus="not_replaced"`,请求发出后的错误无法证明服务端是否已提交,返回 `operationStatus="unknown"`、
427
+ `targetReplaced=null` 和 `targetReplacementStatus="unknown"`,重试前应先检查目标内容;两种失败都会尝试清理临时文件;
428
+ `verifySize`、`verifyMd5`、`verifyMode`、`verifyOwner`、`verifyMtime`
429
+ 会追加显式传输校验,父目录和目标探测、递归建目录、文件哈希、rename、临时文件清理都使用 SFTP,普通上传不依赖 GNU
430
+ `stat`、`md5sum`、`sha256sum`、`mkdir`、`mv` 或
431
+ `rm`,可用于禁用 exec 的 SFTP-only 服务和 BSD 系统,显式目录 manifest 校验仍会执行远端 shell 命令
432
+
433
+ `ssh_download` 先写入目标同目录的临时文件,SFTP 流关闭且传输字节数与 SFTP `stat`
434
+ 报告的大小一致后再 rename 到本地目标;下载失败、提前截断或取消时会删除临时文件,已有本地目标保持原内容,SFTP 目录列表在构造子路径前会拒绝空名称、`.`、
435
+ `..`、NUL 和路径分隔符
436
+
437
+ 命令执行结果在远端命令非零退出且没有 stdout/stderr 时返回 `emptyOutputFailure=true`,同时给出 effective
438
+ user、cwd 和可用的后续读取建议,`ssh_read_file` 默认读取 1 MiB,`maxBytes` 超过 16 MiB 时会在远端传输前拒绝,返回
439
+ `total_size`、
440
+ `read_offset`、`requested_offset`、`read_bytes`、`read_end`、`next_offset`、`remaining_bytes`、`sample_kind` 和
441
+ `truncated`,调用方可以区分完整读取、头部样本、尾部样本、字节范围和行范围。文本读取不会截断 UTF-8 字符,后续分段应使用
442
+ `next_offset`。
443
+
444
+ `ssh_upload`、`ssh_download`、`ssh_read_file`、`ssh_write_file`、`ssh_list_dir`、`ssh_file_info` 和 `ssh_mkdir`
445
+ 支持单个 SFTP 操作的 `timeout`,默认 10 分钟,最大 1 小时。超时返回 `operationStatus="unknown"` 和
446
+ `retryable=true`,重试前应检查受影响的远端或本地路径
382
447
 
383
448
  ### 使用 rsync 或 SFTP 同步目录
384
449
 
385
- 智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
450
+ 智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
451
+ host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
386
452
 
387
453
  ```
388
454
  // 同步本地目录到远程(上传)
@@ -427,13 +493,27 @@ ssh_sync(
427
493
  ssh_sync(..., delete=true, verify={deletions: true})
428
494
  ```
429
495
 
430
- 目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false` 会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
496
+ 目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false`
497
+ 会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
431
498
 
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`,不会报告部分匹配成功
499
+ 目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root manifest、owner、mode、旧文件和删除结果,
500
+ `verify.deletions=true` 必须同时设置 `delete=true`,工具会在传输前记录目标目录,只检查这些删除候选是否消失,`staleFiles`
501
+ 则独立检查目标端全部额外条目,响应只返回摘要和最多 20 个 mismatch 样本,不返回完整 manifest,默认上限为 10000 个条目、单文件 256
502
+ MiB、总哈希字节 1 GiB,可通过 `verify.maxEntries`、`verify.maxFileBytes` 和 `verify.maxTotalBytes`
503
+ 提高到最多 50000 个条目、单文件 4 GiB、总哈希字节 16 GiB,遇到被跳过的 symlink 或不支持的文件系统条目时,校验会明确返回
504
+ `skipped`,不会报告部分匹配成功
433
505
 
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`
506
+ 请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess` 仍单独表示传输是否完成,
507
+ `verificationStatus`、`verificationSuccess` 和 `failedChecks`
508
+ 描述校验结果,SFTP 单文件同步还会返回本地和远端的 size、mode 或 permissions、mtime、owner/group,以及通过 SFTP 流读取计算的 SHA-256 对比,upload 单文件使用
509
+ `verifyOwner` 和 `verifyMode` ,目录逐项校验使用 `verify.owner` 和 `verify.mode`
435
510
 
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 模式
511
+ 只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump
512
+ host 会使用 SFTP,因为独立 OpenSSH 进程无法安全继承对应路由或认证材料,`preflightTimeout`、`connectTimeout` 和
513
+ `operationTimeout` 分别限制能力预检、rsync
514
+ SSH 建连和完整传输,默认值为 10 秒、30 秒和 10 分钟,不具备 rsync 条件的 session 会返回 `rsyncProbe.status="skipped"`
515
+ 和路由判定原因,不再省略 probe,rsync 模式设置 `StrictHostKeyChecking=accept-new`,SFTP 不支持 `delete=true`
516
+ ,此类请求会明确失败,不会报告已经删除,如需严格的主机密钥验证与管理,请使用 SFTP 模式
437
517
 
438
518
  ### 持久化 PTY 会话(top、tmux 等)
439
519
 
@@ -472,8 +552,11 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
472
552
  ```
473
553
 
474
554
  `ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
475
- `foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回 `active=false`,
476
- 直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS` 调整
555
+ `foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回
556
+ `active=false`,直到显式 close 或 closed session 保留期结束,默认 5 分钟,可通过 `SSH_MCP_PTY_CLOSED_RETENTION_MS`
557
+ 调整。`ssh_pty_write` 返回 `accepted=true` 表示本地 stream 已接收输入,`backpressured=true`
558
+ 只表示缓冲区达到高水位,不代表输入丢失。`ssh_pty_close` 返回 `closed`、`not_found`、`failed` 或
559
+ `unknown`,可重试的失败会保留 PTY 状态
477
560
 
478
561
  常用控制序列:
479
562
 
@@ -495,6 +578,9 @@ ssh_forward_local(alias="server", localPort=13306, remoteHost="<service-host>",
495
578
  // 远程转发:将本地开发服务器 (3000) 暴露到远程端口 8080
496
579
  ssh_forward_remote(alias="server", remotePort=8080, localHost="127.0.0.1", localPort=3000)
497
580
 
581
+ // 由 SSH 服务器动态分配远程端口,使用返回结果中的 remotePort
582
+ ssh_forward_remote(alias="server", remotePort=0, localHost="127.0.0.1", localPort=3000)
583
+
498
584
  // 列出所有转发
499
585
  ssh_forward_list()
500
586
 
@@ -505,44 +591,62 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
505
591
  ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
506
592
  ```
507
593
 
508
- 关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、
509
- `remoteUnforwarded`、`activeConnections`、`closeMode` 和 `retryable`,超时或 callback 失败时 forward 仍保留在
510
- `ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind
594
+ 关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、`remoteUnforwarded`、
595
+ `activeConnections`、`closeMode` 和 `retryable`。`ssh_forward_list` 返回 `lifecycle` 和
596
+ `acceptingConnections`,`closing` 状态仍可重试,但不再接收流量。超时或 callback 失败时 forward 仍保留在
597
+ `ssh_forward_list`,可以使用同一 `forwardId` 重试,本地转发关闭成功后端口可立即重新 bind,`remotePort=0`
598
+ 会返回实际分配端口,后续连接路由和 `unforwardIn` 都使用该端口
599
+
600
+ forward 在 `listen` 或 `forwardIn` 完成前就进入生命周期管理,disconnect 会取消 pending
601
+ creation。延迟返回的本地 listener 会被关闭,延迟分配的远端 listener 会被移除;close 开始后立即拒绝新的本地或远端连接。
602
+ `forwardOut`、close 和 unforward 的延迟 callback 修改状态前会检查同一生命周期记录,已关闭的 forward 不会重新出现在
603
+ `ssh_forward_list`;每条本地转发连接同时跟踪本地 socket 和 SSH `forwardOut`
604
+ channel,任一端关闭或失败都会销毁另一端,force close 只在两端都销毁且 `activeConnections`
605
+ 归零后返回;每个 alias 最多允许 32 个 pending `forwardOut`
606
+ 请求,close 会等待全部 callback;如果 SSH 服务端始终不回应 channel-open,请求会超时并保留可重试的 forward,同时拒绝同 alias 新建 local
607
+ forward,避免 ssh2 pending channel 继续累积,此时断开 alias 才能释放始终不返回的底层请求
511
608
 
512
609
  ## 配置选项
513
610
 
514
611
  ### 连接选项
515
612
 
516
- | 选项 | 类型 | 默认值 | 描述 |
517
- |---------------------|--------|-------|-------------|
518
- | `host` | string | *必需* | 服务器地址 |
519
- | `user` | string | *必需* | 用户名 |
520
- | `password` | string | - | 密码认证 |
521
- | `keyPath` | string | - | SSH 私钥路径 |
522
- | `port` | number | 22 | SSH 端口 |
523
- | `alias` | string | 自动生成 | 连接别名,用于后续引用 |
524
- | `template` | string | - | 连接模板名 |
525
- | `env` | object | - | 环境变量 |
526
- | `defaultEnv` | object | - | 连接级默认环境变量 |
527
- | `runAs` | string | - | 默认执行用户 |
528
- | `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
529
- | `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
613
+ | 选项 | 类型 | 默认值 | 描述 |
614
+ | ----------------------- | ------ | ---------- | --------------------------------------------- |
615
+ | `host` | string | _必需_ | 服务器地址 |
616
+ | `user` | string | _必需_ | 用户名 |
617
+ | `password` | string | - | 密码认证 |
618
+ | `keyPath` | string | - | SSH 私钥路径 |
619
+ | `port` | number | 22 | SSH 端口 |
620
+ | `alias` | string | 自动生成 | 连接别名,用于后续引用 |
621
+ | `template` | string | - | 连接模板名 |
622
+ | `env` | object | - | 环境变量 |
623
+ | `defaultEnv` | object | - | 连接级默认环境变量 |
624
+ | `runAs` | string | - | 默认执行用户 |
625
+ | `keepaliveInterval` | number | 30000 | 心跳间隔(毫秒) |
626
+ | `readyTimeout` | number | 30000 | 等待 SSH ready 的超时,最大 600000 毫秒 |
530
627
  | `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
531
628
 
532
- 连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、`transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、`jump_forward` 或 `target_connect`
629
+ 连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、
630
+ `transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、
631
+ `jump_forward` 或 `target_connect`
533
632
 
534
633
  ### 执行选项
535
634
 
536
- | 选项 | 类型 | 默认值 | 描述 |
537
- |-----------------|---------|-----------|------------------------|
538
- | `timeout` | number | 30000 | 命令超时(毫秒) |
539
- | `cwd` | string | - | 工作目录 |
540
- | `env` | object | - | 额外环境变量 |
541
- | `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
542
- | `maxOutputSize` | number | 10 MB 字符 | 输出截断上限 |
543
- | `runAs` | string | 连接级 runAs | 本次命令执行用户 |
544
- | `useLoginUser` | boolean | false | 跳过连接级 runAs |
545
- | `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
635
+ | 选项 | 类型 | 默认值 | 描述 |
636
+ | --------------- | ------- | ------------ | ------------------------------- |
637
+ | `timeout` | number | 30000 | 命令超时(毫秒) |
638
+ | `cwd` | string | - | 工作目录 |
639
+ | `env` | object | - | 额外环境变量 |
640
+ | `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
641
+ | `maxOutputSize` | number | 10 MB 字符 | 输出截断上限 |
642
+ | `runAs` | string | 连接级 runAs | 本次命令执行用户 |
643
+ | `useLoginUser` | boolean | false | 跳过连接级 runAs |
644
+ | `loadProfile` | boolean | true | runAs 时加载目标用户 shell 配置 |
645
+
646
+ 传入 `cwd` 或 `env` 时,生成的 shell 命令会用 `&&` 连接 `cd` 和每个通过校验的
647
+ `export`,再把完整用户命令作为当前登录 shell 的一个转义后 `eval`
648
+ 参数执行;目录切换或环境变量注入失败后,用户命令的任何部分都不会执行,包括 `;`、换行或 `||`
649
+ 后的内容,Bash/Zsh 专有语法仍由直接 SSH 命令所用的解释器处理
546
650
 
547
651
  ## 安全
548
652
 
@@ -563,14 +667,17 @@ export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
563
667
 
564
668
  ### 可选:文件操作路径白名单
565
669
 
566
- `ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐),
567
- 设置 `SSH_MCP_FILE_OPS_ALLOW_DIRS`(路径分隔符跟随 Node `path.delimiter`:POSIX 用 `:`,Windows 用 `;`):
670
+ `ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐), 设置
671
+ `SSH_MCP_FILE_OPS_ALLOW_DIRS`(路径分隔符跟随 Node `path.delimiter`:POSIX 用 `:`,Windows 用 `;`):
568
672
 
569
673
  ```bash
570
674
  export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
571
675
  ```
572
676
 
573
- 设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析以防逃逸;未设置时不做限制(保留灵活性)
677
+ 设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析;白名单生效时,
678
+ `ssh_sync(direction="upload", followSymlinks=true)`
679
+ 会在选择 transport 前被拒绝,symlink 可在校验和传输之间改变目标,rsync 也无法把预检目标绑定到后续 `-L` 读取;应保持
680
+ `followSymlinks=false`,或先把普通文件复制到允许目录再同步
574
681
 
575
682
  ### 文件大小上限
576
683
 
@@ -583,12 +690,13 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
583
690
 
584
691
  `ssh_sync(direction="upload", ...)` 对本地 symlink 的处理因底层传输方式而异:
585
692
 
586
- | `followSymlinks` | SFTP 路径 | rsync 路径 |
587
- |------------------|----------------------------------------|--------------------------------------------|
588
- | `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 通过 `--no-links` 跳过 |
589
- | `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
693
+ | `followSymlinks` | SFTP 路径 | rsync 路径 |
694
+ | ---------------- | ---------------------------- | ------------------------------- |
695
+ | `false`(默认) | 跳过并写入 `skippedSymlinks` | 使用 `--no-links` 跳过 |
696
+ | `true` | 上传链接目标内容 | 使用 `-L` / `--copy-links` 跟随 |
590
697
 
591
- 两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用 `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
698
+ 两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用
699
+ `--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
592
700
 
593
701
  ## 项目结构
594
702
 
@@ -226,18 +226,43 @@ export function buildRemoteDirectoryManifestCommand(rootPath, request, exclude,
226
226
  'excluded_dirs=()',
227
227
  'while IFS= read -r -d "" item; do',
228
228
  ' if [ "$item" = "__MCP_FIND_ERROR__" ]; then exit 4; fi',
229
- ' if [ "$item" = "$root" ]; then rel=.; elif [ "$root" = / ]; then rel=${item#/}; else rel=${item#"$root"/}; fi',
229
+ ` if [ "$item" = "$root" ]; then
230
+ rel=.
231
+ elif [ "$root" = / ]; then
232
+ rel=\${item#/}
233
+ else
234
+ rel=\${item#"$root"/}
235
+ fi`,
230
236
  ' for excluded_dir in "${excluded_dirs[@]}"; do case "$rel" in "$excluded_dir"/*) continue 2;; esac; done',
231
237
  pathExcludeRegex
232
- ? ` if [ "$rel" != . ] && printf %s "$rel" | grep -Eq -- ${pathExcludeRegex}; then [ -d "$item" ] && excluded_dirs+=("$rel"); continue; fi`
238
+ ? ` if [ "$rel" != . ] && printf %s "$rel" | grep -Eq -- ${pathExcludeRegex}; then
239
+ [ -d "$item" ] && excluded_dirs+=("$rel")
240
+ continue
241
+ fi`
233
242
  : ' :',
234
243
  basenameExcludeRegex
235
- ? ` base=${'${rel##*/}'}; if [ "$rel" != . ] && printf %s "$base" | grep -Eq -- ${basenameExcludeRegex}; then [ -d "$item" ] && excluded_dirs+=("$rel"); continue; fi`
244
+ ? ` base=\${rel##*/}
245
+ if [ "$rel" != . ] && printf %s "$base" | grep -Eq -- ${basenameExcludeRegex}; then
246
+ [ -d "$item" ] && excluded_dirs+=("$rel")
247
+ continue
248
+ fi`
236
249
  : ' :',
237
250
  followSymlinks
238
251
  ? ' :'
239
252
  : ' if [ "$rel" != . ] && [ -L "$item" ]; then skipped_symlinks=$((skipped_symlinks + 1)); continue; fi',
240
- ' if [ -d "$item" ]; then type=directory; size=0; elif [ -f "$item" ]; then type=file; size=$(stat -c %s -- "$item"); else skipped_unsupported=$((skipped_unsupported + 1)); if [ "${#unsupported_samples[@]}" -lt 10 ]; then unsupported_samples+=("$(printf %s "$rel" | base64 | tr -d "\\n")"); fi; continue; fi',
253
+ ` if [ -d "$item" ]; then
254
+ type=directory
255
+ size=0
256
+ elif [ -f "$item" ]; then
257
+ type=file
258
+ size=$(stat -c %s -- "$item")
259
+ else
260
+ skipped_unsupported=$((skipped_unsupported + 1))
261
+ if [ "\${#unsupported_samples[@]}" -lt 10 ]; then
262
+ unsupported_samples+=("$(printf %s "$rel" | base64 | tr -d "\\n")")
263
+ fi
264
+ continue
265
+ fi`,
241
266
  ' count=$((count + 1))',
242
267
  ` if [ "$count" -gt ${maxEntries} ]; then printf '__MCP_LIMIT__\\tentries\\n'; break; fi`,
243
268
  ' raw_mode=$(stat -c %a -- "$item")',