@pyrokine/mcp-ssh 2.4.1 → 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.md +174 -130
- package/README_zh.md +232 -128
- package/dist/directory-verification.js +29 -4
- package/dist/file-ops.d.ts +13 -8
- package/dist/file-ops.js +191 -115
- package/dist/forward-manager.js +9 -3
- package/dist/operation-manager.d.ts +0 -5
- package/dist/operation-manager.js +13 -55
- package/dist/pty-manager.d.ts +3 -3
- package/dist/pty-manager.js +61 -15
- package/dist/session-manager.d.ts +3 -3
- package/dist/session-manager.js +44 -20
- package/dist/sftp-timeout.d.ts +9 -0
- package/dist/sftp-timeout.js +49 -0
- package/dist/tools/connection.js +75 -29
- package/dist/tools/exec.js +16 -6
- package/dist/tools/file.js +101 -55
- package/dist/tools/forward.js +6 -5
- package/dist/tools/operation.js +2 -1
- package/dist/tools/pty.js +17 -13
- package/dist/tools/schema.d.ts +4 -0
- package/dist/tools/schema.js +9 -0
- package/dist/types.d.ts +15 -0
- package/dist/utf8.d.ts +3 -0
- package/dist/utf8.js +44 -0
- package/package.json +6 -6
package/README_zh.md
CHANGED
|
@@ -8,8 +8,7 @@
|
|
|
8
8
|
[](https://nodejs.org/)
|
|
9
9
|
[](https://modelcontextprotocol.io/)
|
|
10
10
|
|
|
11
|
-

|
|
12
|
-

|
|
11
|
+
 
|
|
13
12
|

|
|
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
|
-
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
|
|
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,72 +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
110
|
|
|
111
|
-
`
|
|
111
|
+
`ssh_reconnect` 会在发布替代连接前,使绑定旧 client 的 operation、PTY、forward 和传输能力缓存失效。
|
|
112
112
|
|
|
113
|
-
|
|
113
|
+
自动重连 timer 绑定发起调度的 session 和 client,不会断开同一 alias 下后来发布的新会话。
|
|
114
|
+
|
|
115
|
+
旧 client 延迟到达的 `close` 不会让过期资源继续挂在同一 alias 下;通过 jump host 建立目标连接时,如果取消发生在
|
|
116
|
+
`forwardOut` pending 阶段,延迟 callback 返回的 channel 会先销毁再结束连接请求
|
|
114
117
|
|
|
115
118
|
### 命令执行
|
|
116
119
|
|
|
117
|
-
| 工具
|
|
118
|
-
|
|
119
|
-
| `ssh_exec` | 执行命令(支持 PTY 模式)
|
|
120
|
+
| 工具 | 描述 |
|
|
121
|
+
| ------------------- | ------------------------------- |
|
|
122
|
+
| `ssh_exec` | 执行命令(支持 PTY 模式) |
|
|
120
123
|
| `ssh_exec_as_user` | 以其他用户身份执行(通过 `su`) |
|
|
121
|
-
| `ssh_exec_sudo` | 使用 `sudo` 执行
|
|
122
|
-
| `ssh_exec_batch` | 批量执行多条命令
|
|
123
|
-
| `ssh_exec_parallel` | 在多台主机上并行执行命令
|
|
124
|
-
| `ssh_quick_exec` | 一次性执行:连接、执行、断开
|
|
125
|
-
| `ssh_exec_script` | 上传并执行远端临时脚本
|
|
124
|
+
| `ssh_exec_sudo` | 使用 `sudo` 执行 |
|
|
125
|
+
| `ssh_exec_batch` | 批量执行多条命令 |
|
|
126
|
+
| `ssh_exec_parallel` | 在多台主机上并行执行命令 |
|
|
127
|
+
| `ssh_quick_exec` | 一次性执行:连接、执行、断开 |
|
|
128
|
+
| `ssh_exec_script` | 上传并执行远端临时脚本 |
|
|
126
129
|
|
|
127
130
|
### 可跟踪任务
|
|
128
131
|
|
|
129
|
-
| 工具
|
|
130
|
-
|
|
131
|
-
| `ssh_operation_start` | 启动可跟踪的长时间远端命令
|
|
132
|
-
| `ssh_operation_status` | 读取状态、PID、退出码和输出计数
|
|
133
|
-
| `ssh_operation_read` | 按字节偏移读取有上限的 stdout 和 stderr
|
|
134
|
-
| `ssh_operation_cancel` | 校验任务 marker 后发送 TERM
|
|
135
|
-
| `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 过滤 |
|
|
136
139
|
|
|
137
140
|
### 文件操作
|
|
138
141
|
|
|
139
|
-
| 工具
|
|
140
|
-
|
|
141
|
-
| `ssh_upload` | 上传本地文件到远程
|
|
142
|
-
| `ssh_download` | 从远程下载文件到本地
|
|
143
|
-
| `ssh_read_file` | 读取远程文件内容
|
|
144
|
-
| `ssh_write_file` | 写入内容到远程文件
|
|
145
|
-
| `ssh_list_dir` | 列出远程目录内容
|
|
146
|
-
| `ssh_file_info` | 获取文件/目录元数据
|
|
147
|
-
| `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` | 创建远程目录 |
|
|
148
151
|
| `ssh_sync` | 智能同步(优先 rsync,回退 SFTP) |
|
|
149
152
|
|
|
150
153
|
### PTY 会话(持久化交互式终端)
|
|
151
154
|
|
|
152
|
-
| 工具
|
|
153
|
-
|
|
154
|
-
| `ssh_pty_start` | 启动持久化 PTY 会话(用于 top、htop、tmux 等)
|
|
155
|
-
| `ssh_pty_write` | 向 PTY 发送数据(按键、命令)
|
|
155
|
+
| 工具 | 描述 |
|
|
156
|
+
| ---------------- | --------------------------------------------------------- |
|
|
157
|
+
| `ssh_pty_start` | 启动持久化 PTY 会话(用于 top、htop、tmux 等) |
|
|
158
|
+
| `ssh_pty_write` | 向 PTY 发送数据(按键、命令) |
|
|
156
159
|
| `ssh_pty_read` | 读取 PTY 输出(screen 模式:当前屏幕,raw 模式:ANSI 流) |
|
|
157
|
-
| `ssh_pty_resize` | 调整 PTY 窗口大小
|
|
158
|
-
| `ssh_pty_close` | 关闭 PTY 会话
|
|
159
|
-
| `ssh_pty_list` | 列出所有 PTY 会话
|
|
160
|
+
| `ssh_pty_resize` | 调整 PTY 窗口大小 |
|
|
161
|
+
| `ssh_pty_close` | 关闭 PTY 会话 |
|
|
162
|
+
| `ssh_pty_list` | 列出所有 PTY 会话 |
|
|
160
163
|
|
|
161
164
|
### 端口转发
|
|
162
165
|
|
|
163
|
-
| 工具
|
|
164
|
-
|
|
166
|
+
| 工具 | 描述 |
|
|
167
|
+
| -------------------- | ------------------------------------ |
|
|
165
168
|
| `ssh_forward_local` | 本地端口转发(ssh -L):访问远程服务 |
|
|
166
169
|
| `ssh_forward_remote` | 远程端口转发(ssh -R):暴露本地服务 |
|
|
167
|
-
| `ssh_forward_close` | 关闭端口转发
|
|
168
|
-
| `ssh_forward_list` | 列出所有端口转发
|
|
170
|
+
| `ssh_forward_close` | 关闭端口转发 |
|
|
171
|
+
| `ssh_forward_list` | 列出所有端口转发 |
|
|
169
172
|
|
|
170
173
|
## 使用示例
|
|
171
174
|
|
|
@@ -216,9 +219,9 @@ ssh_connect(configHost="myserver", configPath="/custom/path/config")
|
|
|
216
219
|
4. ssh_exec_parallel(aliases=["server1", "server2", "server3"], command="uptime")
|
|
217
220
|
```
|
|
218
221
|
|
|
219
|
-
|
|
220
|
-
`ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持
|
|
221
|
-
限制每台主机的输出
|
|
222
|
+
每台主机的结果包含与 `ssh_exec` 相同的元数据,包括 `failureKind`、`effectiveUser`、`cwd`、截断字段和诊断建议。
|
|
223
|
+
`ssh_exec_parallel` 单次最多 32 个 alias,默认最多并发 4 台主机,可用 `maxConcurrency` 调整(最大 8),并支持
|
|
224
|
+
`maxOutputSize` 限制每台主机的输出
|
|
222
225
|
|
|
223
226
|
### 基础:连接和执行
|
|
224
227
|
|
|
@@ -230,7 +233,8 @@ ssh_disconnect(alias="myserver")
|
|
|
230
233
|
|
|
231
234
|
### 连接模板和 runAs
|
|
232
235
|
|
|
233
|
-
模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json`
|
|
236
|
+
模板可以通过 `SSH_MCP_TEMPLATES` 或 `~/.mcp-ssh/templates.json`
|
|
237
|
+
提供,工具显式参数优先于模板值。选中的模板会在连接前校验,SSH 端口必须是 1 到 65535 的整数。模板无效时,错误只返回模板名和字段路径,不返回认证值
|
|
234
238
|
|
|
235
239
|
```json
|
|
236
240
|
{
|
|
@@ -252,7 +256,11 @@ ssh_exec(alias="app-dev", command="whoami && echo $APP_ENV")
|
|
|
252
256
|
ssh_exec(alias="app-dev", command="whoami", useLoginUser=true)
|
|
253
257
|
```
|
|
254
258
|
|
|
255
|
-
`ssh_connect` 返回实际发布会话的 `identity`、`loginUser`、`runAs`、`reused`、`defaultEnvKeys`、`envKeys`,以及同一
|
|
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,14 +290,22 @@ ssh_connect(
|
|
|
282
290
|
// 输出: appuser
|
|
283
291
|
```
|
|
284
292
|
|
|
285
|
-
默认加载 shell 配置以确保环境变量可用(`su -c`
|
|
293
|
+
默认加载 shell 配置以确保环境变量可用(`su -c`
|
|
294
|
+
创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
|
|
286
295
|
)及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
|
|
287
296
|
|
|
288
|
-
`ssh_exec` 和 `
|
|
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
|
|
291
|
-
|
|
292
|
-
|
|
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
|
|
|
@@ -302,7 +318,19 @@ ssh_operation_read(operationId="op_xxx", stdoutOffset=0, stderrOffset=0, maxByte
|
|
|
302
318
|
ssh_operation_cancel(operationId="op_xxx")
|
|
303
319
|
```
|
|
304
320
|
|
|
305
|
-
start 返回不可预测的 `operationId`,服务端在请求 SSH
|
|
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
|
|
323
356
|
```
|
|
324
|
-
|
|
325
|
-
|
|
326
|
-
|
|
327
|
-
|
|
328
|
-
)
|
|
357
|
+
|
|
358
|
+
执行上面的脚本,再读取结果:
|
|
359
|
+
|
|
360
|
+
```
|
|
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(
|
|
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,15 +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
|
-
|
|
378
|
-
`
|
|
379
|
-
|
|
380
|
-
|
|
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`,重试前应检查受影响的远端或本地路径
|
|
381
447
|
|
|
382
448
|
### 使用 rsync 或 SFTP 同步目录
|
|
383
449
|
|
|
384
|
-
智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
|
|
450
|
+
智能同步只在直连且存在已校验 key path 或可用 SSH agent 时选择 rsync,password、inline key、jump
|
|
451
|
+
host 和其他无法安全交给 OpenSSH 的路由直接使用 SFTP:
|
|
385
452
|
|
|
386
453
|
```
|
|
387
454
|
// 同步本地目录到远程(上传)
|
|
@@ -426,13 +493,27 @@ ssh_sync(
|
|
|
426
493
|
ssh_sync(..., delete=true, verify={deletions: true})
|
|
427
494
|
```
|
|
428
495
|
|
|
429
|
-
目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false`
|
|
496
|
+
目录源路径在 rsync 和 SFTP 模式下都表示“把源目录内容同步到目标根目录”,目录源使用 `recursive=false`
|
|
497
|
+
会被明确拒绝,相对排除模式按源目录下的相对路径匹配,不含 `/` 的模式匹配每一级 basename
|
|
430
498
|
|
|
431
|
-
目录校验会生成有界的本地和远端 manifest,可比较条目数、SHA-256 root manifest、owner、mode
|
|
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`,不会报告部分匹配成功
|
|
432
505
|
|
|
433
|
-
请求校验后,mismatch、skipped 或校验错误都会令顶层 `success=false`,`transferSuccess`
|
|
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`
|
|
434
510
|
|
|
435
|
-
只有直连且存在已校验 key path 或可用 SSH agent 时才选择 rsync,password、inline key 和 jump
|
|
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 模式
|
|
436
517
|
|
|
437
518
|
### 持久化 PTY 会话(top、tmux 等)
|
|
438
519
|
|
|
@@ -471,8 +552,11 @@ ssh_pty_write(ptyId="pty_1_xxx", data="\x02d")
|
|
|
471
552
|
```
|
|
472
553
|
|
|
473
554
|
`ssh_pty_read` 和 `ssh_pty_list` 返回 `lastInputAt`、`lastOutputAt`、`lastReadAt`、`unreadRawBytes`、`rawBufferLimit`、
|
|
474
|
-
`foregroundProcess`,便于观察长时间运行的会话,无需读取完整 raw 流,有限命令自然结束后仍可读取最终 screen,返回
|
|
475
|
-
|
|
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 状态
|
|
476
560
|
|
|
477
561
|
常用控制序列:
|
|
478
562
|
|
|
@@ -507,46 +591,62 @@ ssh_forward_close(forwardId="fwd_1_xxx", mode="graceful", timeoutMs=5000)
|
|
|
507
591
|
ssh_forward_close(forwardId="fwd_1_xxx", mode="force", timeoutMs=5000)
|
|
508
592
|
```
|
|
509
593
|
|
|
510
|
-
关闭成功表示本地 `server.close` 或远端 `unforwardIn` callback 已完成,结果包含 `listenerReleased`、`remoteUnforwarded
|
|
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` 都使用该端口
|
|
511
599
|
|
|
512
|
-
forward 在 `listen` 或 `forwardIn` 完成前就进入生命周期管理,disconnect 会取消 pending
|
|
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 才能释放始终不返回的底层请求
|
|
513
608
|
|
|
514
609
|
## 配置选项
|
|
515
610
|
|
|
516
611
|
### 连接选项
|
|
517
612
|
|
|
518
|
-
| 选项
|
|
519
|
-
|
|
520
|
-
| `host`
|
|
521
|
-
| `user`
|
|
522
|
-
| `password`
|
|
523
|
-
| `keyPath`
|
|
524
|
-
| `port`
|
|
525
|
-
| `alias`
|
|
526
|
-
| `template`
|
|
527
|
-
| `env`
|
|
528
|
-
| `defaultEnv`
|
|
529
|
-
| `runAs`
|
|
530
|
-
| `keepaliveInterval`
|
|
531
|
-
| `readyTimeout`
|
|
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 毫秒 |
|
|
532
627
|
| `jumpHost.readyTimeout` | number | 继承顶层值 | 跳板机等待 SSH ready 的超时,最大 600000 毫秒 |
|
|
533
628
|
|
|
534
|
-
连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout
|
|
629
|
+
连接失败返回 `failureStage`、`retryable` 和限量建议,`failureStage` 为 `preflight`、`authentication`、`ready_timeout`、
|
|
630
|
+
`transport_or_handshake` 或 `unknown`,多跳连接还可能返回 `connectionStep`,取值为 `key_read`、`jump_connect`、
|
|
631
|
+
`jump_forward` 或 `target_connect`
|
|
535
632
|
|
|
536
633
|
### 执行选项
|
|
537
634
|
|
|
538
|
-
| 选项
|
|
539
|
-
|
|
540
|
-
| `timeout` | number | 30000
|
|
541
|
-
| `cwd` | string | -
|
|
542
|
-
| `env` | object | -
|
|
543
|
-
| `pty` | boolean | false
|
|
544
|
-
| `maxOutputSize` | number | 10 MB 字符
|
|
545
|
-
| `runAs` | string | 连接级 runAs | 本次命令执行用户
|
|
546
|
-
| `useLoginUser` | boolean | false
|
|
547
|
-
| `loadProfile` | boolean | true
|
|
548
|
-
|
|
549
|
-
传入 `cwd` 或 `env` 时,生成的 shell 命令会用 `&&` 连接 `cd` 和每个通过校验的
|
|
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 命令所用的解释器处理
|
|
550
650
|
|
|
551
651
|
## 安全
|
|
552
652
|
|
|
@@ -567,14 +667,17 @@ export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
|
|
|
567
667
|
|
|
568
668
|
### 可选:文件操作路径白名单
|
|
569
669
|
|
|
570
|
-
`ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐),
|
|
571
|
-
|
|
670
|
+
`ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐), 设置
|
|
671
|
+
`SSH_MCP_FILE_OPS_ALLOW_DIRS`(路径分隔符跟随 Node `path.delimiter`:POSIX 用 `:`,Windows 用 `;`):
|
|
572
672
|
|
|
573
673
|
```bash
|
|
574
674
|
export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
575
675
|
```
|
|
576
676
|
|
|
577
|
-
设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath`
|
|
677
|
+
设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析;白名单生效时,
|
|
678
|
+
`ssh_sync(direction="upload", followSymlinks=true)`
|
|
679
|
+
会在选择 transport 前被拒绝,symlink 可在校验和传输之间改变目标,rsync 也无法把预检目标绑定到后续 `-L` 读取;应保持
|
|
680
|
+
`followSymlinks=false`,或先把普通文件复制到允许目录再同步
|
|
578
681
|
|
|
579
682
|
### 文件大小上限
|
|
580
683
|
|
|
@@ -587,12 +690,13 @@ export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
|
587
690
|
|
|
588
691
|
`ssh_sync(direction="upload", ...)` 对本地 symlink 的处理因底层传输方式而异:
|
|
589
692
|
|
|
590
|
-
| `followSymlinks` | SFTP 路径
|
|
591
|
-
|
|
592
|
-
| `false`(默认)
|
|
593
|
-
| `true` |
|
|
693
|
+
| `followSymlinks` | SFTP 路径 | rsync 路径 |
|
|
694
|
+
| ---------------- | ---------------------------- | ------------------------------- |
|
|
695
|
+
| `false`(默认) | 跳过并写入 `skippedSymlinks` | 使用 `--no-links` 跳过 |
|
|
696
|
+
| `true` | 上传链接目标内容 | 使用 `-L` / `--copy-links` 跟随 |
|
|
594
697
|
|
|
595
|
-
两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用
|
|
698
|
+
两种传输都会跳过 device 和特殊文件系统条目,SFTP 返回 `skippedUnsupported` 和最多 10 个样本路径,rsync 使用
|
|
699
|
+
`--no-devices --no-specials`,目录校验也会报告被跳过的 symlink 和不支持条目,不会把不完整 manifest 当成匹配成功
|
|
596
700
|
|
|
597
701
|
## 项目结构
|
|
598
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
|
-
|
|
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
|
|
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
|
|
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
|
-
|
|
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")',
|