@pyrokine/mcp-ssh 1.3.0 → 2.0.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 +53 -3
- package/README_zh.md +54 -8
- package/dist/file-ops.d.ts +8 -3
- package/dist/file-ops.js +363 -115
- package/dist/forward-manager.d.ts +10 -1
- package/dist/forward-manager.js +72 -6
- package/dist/index.d.ts +1 -1
- package/dist/index.js +30 -3
- package/dist/pty-manager.d.ts +5 -0
- package/dist/pty-manager.js +38 -1
- package/dist/security.d.ts +24 -0
- package/dist/security.js +81 -0
- package/dist/session-manager.d.ts +20 -7
- package/dist/session-manager.js +226 -117
- package/dist/ssh-config.js +25 -14
- package/dist/tools/connection.js +26 -29
- package/dist/tools/exec.js +25 -17
- package/dist/tools/file.js +9 -5
- package/dist/tools/forward.js +19 -15
- package/dist/tools/pty.js +6 -10
- package/dist/tools/utils.d.ts +10 -0
- package/dist/tools/utils.js +22 -0
- package/dist/types.d.ts +0 -2
- package/package.json +56 -42
- package/src/file-ops.ts +0 -662
- package/src/forward-manager.ts +0 -258
- package/src/index.ts +0 -62
- package/src/pty-manager.ts +0 -220
- package/src/session-manager.ts +0 -661
- package/src/ssh-config.ts +0 -257
- package/src/tools/connection.ts +0 -240
- package/src/tools/exec.ts +0 -264
- package/src/tools/file.ts +0 -219
- package/src/tools/forward.ts +0 -141
- package/src/tools/index.ts +0 -9
- package/src/tools/pty.ts +0 -203
- package/src/tools/utils.ts +0 -23
- package/src/types.ts +0 -124
- package/tsconfig.json +0 -21
package/README.md
CHANGED
|
@@ -14,7 +14,7 @@ A comprehensive SSH MCP Server for AI assistants (Claude, Cursor, Windsurf, etc.
|
|
|
14
14
|
|
|
15
15
|
## Features
|
|
16
16
|
|
|
17
|
-
- **Multiple Authentication**: Password, SSH key
|
|
17
|
+
- **Multiple Authentication**: Password, SSH key
|
|
18
18
|
- **SSH Config Support**: Read `~/.ssh/config` with Host aliases, `Host *` inheritance, ProxyJump (`user@host:port`)
|
|
19
19
|
- **Connection Management**: Connection pooling, keepalive, auto-reconnect
|
|
20
20
|
- **Session Persistence**: Sessions info saved for reconnection
|
|
@@ -315,8 +315,8 @@ ssh_sync(..., dryRun=true)
|
|
|
315
315
|
|
|
316
316
|
If rsync is not available on remote or local, it automatically falls back to SFTP.
|
|
317
317
|
|
|
318
|
-
**Note**: rsync mode uses SSH key/agent authentication and
|
|
319
|
-
|
|
318
|
+
**Note**: rsync mode uses SSH key/agent authentication and sets `StrictHostKeyChecking=accept-new`.
|
|
319
|
+
If you require strict host key verification and management, use SFTP mode instead.
|
|
320
320
|
|
|
321
321
|
### Persistent PTY Sessions (top, tmux, etc.)
|
|
322
322
|
|
|
@@ -405,6 +405,56 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
405
405
|
| `env` | object | - | Additional environment variables |
|
|
406
406
|
| `pty` | boolean | false | Enable PTY mode for interactive commands |
|
|
407
407
|
|
|
408
|
+
## Security
|
|
409
|
+
|
|
410
|
+
### Path Whitelist for Key/Config Files
|
|
411
|
+
|
|
412
|
+
`keyPath` (private key) and `configPath` (SSH config) must reside under one of the following directories:
|
|
413
|
+
|
|
414
|
+
- `~/.ssh/` — user SSH directory
|
|
415
|
+
- `/etc/ssh/` — system-wide SSH directory
|
|
416
|
+
|
|
417
|
+
To allow additional directories, set the `SSH_MCP_ALLOWED_KEY_DIRS` environment variable, separated by `:` on
|
|
418
|
+
Linux/macOS or `;` on Windows:
|
|
419
|
+
|
|
420
|
+
```bash
|
|
421
|
+
export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
|
|
422
|
+
```
|
|
423
|
+
|
|
424
|
+
Files outside the whitelist are rejected with `Invalid private key path: ...` or `Invalid config path: ...`.
|
|
425
|
+
|
|
426
|
+
### Optional File-Ops Path Whitelist
|
|
427
|
+
|
|
428
|
+
`ssh_upload`, `ssh_download`, `ssh_sync` accept arbitrary local paths by default. To restrict them to specific
|
|
429
|
+
directories (recommended for shared environments), set `SSH_MCP_FILE_OPS_ALLOW_DIRS` (paths separated by Node's
|
|
430
|
+
`path.delimiter` — `:` on POSIX, `;` on Windows):
|
|
431
|
+
|
|
432
|
+
```bash
|
|
433
|
+
export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
434
|
+
```
|
|
435
|
+
|
|
436
|
+
When set, any local path outside the whitelist is rejected. Symlinks are resolved via `realpath` to prevent escape.
|
|
437
|
+
When unset, no restriction is applied (preserves flexibility).
|
|
438
|
+
|
|
439
|
+
### File Size Limits
|
|
440
|
+
|
|
441
|
+
- Private key files: max 64 KB
|
|
442
|
+
- SSH config files: max 1 MB
|
|
443
|
+
|
|
444
|
+
Files exceeding these limits are rejected before being read.
|
|
445
|
+
|
|
446
|
+
### Symlink Handling in `ssh_sync`
|
|
447
|
+
|
|
448
|
+
`ssh_sync(direction="upload", ...)` handles local symlinks differently depending on the underlying transport:
|
|
449
|
+
|
|
450
|
+
| `followSymlinks` | SFTP path | rsync path |
|
|
451
|
+
|-------------------|------------------------------------------------------------|-----------------------------------------------------------------------------|
|
|
452
|
+
| `false` (default) | Skipped, returned in `skippedSymlinks`, printed as warning | Copied as-is (rsync default: preserves the symlink without dereferencing) |
|
|
453
|
+
| `true` | Followed: link target contents are uploaded | Followed via rsync `-L` / `--copy-links`: link target contents are uploaded |
|
|
454
|
+
|
|
455
|
+
Both default modes are safe (neither uploads link target contents). The divergence is whether the destination keeps the
|
|
456
|
+
symlink: SFTP omits it entirely, rsync preserves it as a symlink.
|
|
457
|
+
|
|
408
458
|
## Project Structure
|
|
409
459
|
|
|
410
460
|
```
|
package/README_zh.md
CHANGED
|
@@ -14,7 +14,7 @@
|
|
|
14
14
|
|
|
15
15
|
## 功能特性
|
|
16
16
|
|
|
17
|
-
- **多种认证方式**:密码、SSH
|
|
17
|
+
- **多种认证方式**:密码、SSH 密钥
|
|
18
18
|
- **SSH Config 支持**:读取 `~/.ssh/config`,支持 Host 多别名、`Host *` 继承、ProxyJump(`user@host:port` 格式)
|
|
19
19
|
- **连接管理**:连接池复用、心跳保持、自动重连
|
|
20
20
|
- **会话持久化**:会话信息保存,支持重连
|
|
@@ -229,8 +229,8 @@ ssh_connect(
|
|
|
229
229
|
// 输出: appuser
|
|
230
230
|
```
|
|
231
231
|
|
|
232
|
-
默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc
|
|
233
|
-
)及其他 shell(`.profile
|
|
232
|
+
默认加载 shell 配置以确保环境变量可用(`su -c` 创建非交互式 shell,不会自动执行 rc 文件),支持 bash(`.bashrc`)、zsh(`.zshrc`
|
|
233
|
+
)及其他 shell(`.profile`),如不需要可设置 `loadProfile=false`
|
|
234
234
|
|
|
235
235
|
### 交互式命令(PTY 模式)
|
|
236
236
|
|
|
@@ -312,10 +312,10 @@ ssh_sync(
|
|
|
312
312
|
ssh_sync(..., dryRun=true)
|
|
313
313
|
```
|
|
314
314
|
|
|
315
|
-
如果远程或本地没有 rsync,会自动回退到 SFTP
|
|
315
|
+
如果远程或本地没有 rsync,会自动回退到 SFTP
|
|
316
316
|
|
|
317
|
-
**注意**:rsync 模式使用 SSH
|
|
318
|
-
SFTP
|
|
317
|
+
**注意**:rsync 模式使用 SSH 密钥/代理认证,并设置 `StrictHostKeyChecking=accept-new`(首次连接会自动接受主机密钥),
|
|
318
|
+
如需严格的主机密钥验证与管理,请使用 SFTP 模式
|
|
319
319
|
|
|
320
320
|
### 持久化 PTY 会话(top、tmux 等)
|
|
321
321
|
|
|
@@ -404,6 +404,52 @@ ssh_forward_close(forwardId="fwd_1_xxx")
|
|
|
404
404
|
| `env` | object | - | 额外环境变量 |
|
|
405
405
|
| `pty` | boolean | false | 启用 PTY 模式(用于交互式命令) |
|
|
406
406
|
|
|
407
|
+
## 安全
|
|
408
|
+
|
|
409
|
+
### 私钥/配置文件路径白名单
|
|
410
|
+
|
|
411
|
+
`keyPath`(私钥)和 `configPath`(SSH 配置文件)必须位于以下目录之一:
|
|
412
|
+
|
|
413
|
+
- `~/.ssh/` — 用户 SSH 目录
|
|
414
|
+
- `/etc/ssh/` — 系统 SSH 目录
|
|
415
|
+
|
|
416
|
+
如需扩展白名单,设置环境变量 `SSH_MCP_ALLOWED_KEY_DIRS`,Linux/macOS 用 `:` 分隔,Windows 用 `;` 分隔:
|
|
417
|
+
|
|
418
|
+
```bash
|
|
419
|
+
export SSH_MCP_ALLOWED_KEY_DIRS=/opt/secrets:/var/lib/keys
|
|
420
|
+
```
|
|
421
|
+
|
|
422
|
+
白名单外的文件会被拒绝,错误信息为 `Invalid private key path: ...` 或 `Invalid config path: ...`
|
|
423
|
+
|
|
424
|
+
### 可选:文件操作路径白名单
|
|
425
|
+
|
|
426
|
+
`ssh_upload`、`ssh_download`、`ssh_sync` 默认接受任意本地路径,如需在共享环境下限定到指定目录(推荐),
|
|
427
|
+
设置 `SSH_MCP_FILE_OPS_ALLOW_DIRS`(路径分隔符跟随 Node `path.delimiter`:POSIX 用 `:`,Windows 用 `;`):
|
|
428
|
+
|
|
429
|
+
```bash
|
|
430
|
+
export SSH_MCP_FILE_OPS_ALLOW_DIRS=/tmp:/home/me/work
|
|
431
|
+
```
|
|
432
|
+
|
|
433
|
+
设置后,白名单外的本地路径会被拒绝,symlink 会通过 `realpath` 解析以防逃逸;未设置时不做限制(保留灵活性)
|
|
434
|
+
|
|
435
|
+
### 文件大小上限
|
|
436
|
+
|
|
437
|
+
- 私钥文件:最大 64 KB
|
|
438
|
+
- SSH 配置文件:最大 1 MB
|
|
439
|
+
|
|
440
|
+
超过上限的文件在读取前即被拒绝
|
|
441
|
+
|
|
442
|
+
### `ssh_sync` 的 symlink 处理
|
|
443
|
+
|
|
444
|
+
`ssh_sync(direction="upload", ...)` 对本地 symlink 的处理因底层传输方式而异:
|
|
445
|
+
|
|
446
|
+
| `followSymlinks` | SFTP 路径 | rsync 路径 |
|
|
447
|
+
|------------------|----------------------------------------|--------------------------------------------|
|
|
448
|
+
| `false`(默认) | 跳过,写入 `skippedSymlinks` 字段,warning 中提示 | 按 symlink 本身复制(rsync 默认:保留链接,不上传目标内容) |
|
|
449
|
+
| `true` | 跟随:上传链接目标内容 | 通过 rsync `-L` / `--copy-links` 跟随:上传链接目标内容 |
|
|
450
|
+
|
|
451
|
+
两个默认模式都安全(都不会上传链接目标内容),差异仅在于目标端是否保留 symlink:SFTP 完全跳过不传,rsync 保留为 symlink
|
|
452
|
+
|
|
407
453
|
## 项目结构
|
|
408
454
|
|
|
409
455
|
```
|
|
@@ -421,11 +467,11 @@ mcp-ssh/
|
|
|
421
467
|
|
|
422
468
|
## 贡献
|
|
423
469
|
|
|
424
|
-
欢迎贡献!请随时提交 Pull Request
|
|
470
|
+
欢迎贡献!请随时提交 Pull Request
|
|
425
471
|
|
|
426
472
|
## 许可证
|
|
427
473
|
|
|
428
|
-
MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
474
|
+
MIT 许可证 - 详见 [LICENSE](LICENSE)
|
|
429
475
|
|
|
430
476
|
## 相关项目
|
|
431
477
|
|
package/dist/file-ops.d.ts
CHANGED
|
@@ -1,18 +1,21 @@
|
|
|
1
1
|
/**
|
|
2
2
|
* SSH File Operations - 文件操作
|
|
3
3
|
*/
|
|
4
|
+
import { SFTPWrapper } from 'ssh2';
|
|
4
5
|
import { FileInfo, TransferProgress } from './types.js';
|
|
6
|
+
/** 由 SessionManager.disconnect 调用,防止 alias 重连后读到旧主机的判断 */
|
|
7
|
+
export declare function clearRsyncCache(alias?: string): void;
|
|
5
8
|
/**
|
|
6
9
|
* 上传文件
|
|
7
10
|
*/
|
|
8
|
-
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
|
|
11
|
+
export declare function uploadFile(alias: string, localPath: string, remotePath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
|
|
9
12
|
success: boolean;
|
|
10
13
|
size: number;
|
|
11
14
|
}>;
|
|
12
15
|
/**
|
|
13
16
|
* 下载文件
|
|
14
17
|
*/
|
|
15
|
-
export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void): Promise<{
|
|
18
|
+
export declare function downloadFile(alias: string, remotePath: string, localPath: string, onProgress?: (progress: TransferProgress) => void, sharedSftp?: SFTPWrapper): Promise<{
|
|
16
19
|
success: boolean;
|
|
17
20
|
size: number;
|
|
18
21
|
}>;
|
|
@@ -34,7 +37,7 @@ export declare function writeFile(alias: string, remotePath: string, content: st
|
|
|
34
37
|
/**
|
|
35
38
|
* 列出目录内容
|
|
36
39
|
*/
|
|
37
|
-
export declare function listDir(alias: string, remotePath: string, showHidden?: boolean): Promise<FileInfo[]>;
|
|
40
|
+
export declare function listDir(alias: string, remotePath: string, showHidden?: boolean, sharedSftp?: SFTPWrapper): Promise<FileInfo[]>;
|
|
38
41
|
/**
|
|
39
42
|
* 获取文件信息
|
|
40
43
|
*/
|
|
@@ -61,6 +64,7 @@ export declare function syncFiles(alias: string, localPath: string, remotePath:
|
|
|
61
64
|
dryRun?: boolean;
|
|
62
65
|
exclude?: string[];
|
|
63
66
|
recursive?: boolean;
|
|
67
|
+
followSymlinks?: boolean;
|
|
64
68
|
}): Promise<SyncResult>;
|
|
65
69
|
/**
|
|
66
70
|
* 使用 SFTP 同步文件
|
|
@@ -70,6 +74,7 @@ type SyncResult = {
|
|
|
70
74
|
method: 'rsync' | 'sftp';
|
|
71
75
|
filesTransferred?: number;
|
|
72
76
|
bytesTransferred?: number;
|
|
77
|
+
skippedSymlinks?: number;
|
|
73
78
|
output?: string;
|
|
74
79
|
};
|
|
75
80
|
export {};
|