feat: add dynamic per-call SSH connections and secret redaction
- execute-command/upload/download accept host/port/username/password inline to open an ephemeral connection for a single call - add redactSecret/redactSecrets to mask credentials in logs and errors - logger log()/handleError() accept optional secrets[] for redaction - add SSH_CONFIG_MISSING error code and --password-from-env CLI flag - dynamic-mode startup: server runs with no static config
This commit is contained in:
Max Shcheglov
+28
@@ -0,0 +1,28 @@
|
|||||||
|
# 依赖目录
|
||||||
|
node_modules/
|
||||||
|
package-lock.json
|
||||||
|
|
||||||
|
# 构建输出
|
||||||
|
build/
|
||||||
|
|
||||||
|
# 操作系统文件
|
||||||
|
.DS_Store
|
||||||
|
Thumbs.db
|
||||||
|
|
||||||
|
# 编辑器和IDE文件
|
||||||
|
.idea/
|
||||||
|
.vscode/
|
||||||
|
*.swp
|
||||||
|
*.swo
|
||||||
|
.project
|
||||||
|
.classpath
|
||||||
|
.settings/
|
||||||
|
memo.md
|
||||||
|
|
||||||
|
# claude
|
||||||
|
.claude/
|
||||||
|
.mcp.json
|
||||||
|
docs
|
||||||
|
|
||||||
|
# codex
|
||||||
|
.codex/
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
ISC License
|
||||||
|
|
||||||
|
Copyright (c) 2025 junki.cn
|
||||||
|
|
||||||
|
Permission to use, copy, modify, and/or distribute this software for any
|
||||||
|
purpose with or without fee is hereby granted, provided that the above
|
||||||
|
copyright notice and this permission notice appear in all copies.
|
||||||
|
|
||||||
|
THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
|
||||||
|
WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
|
||||||
|
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
|
||||||
|
ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
|
||||||
|
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
|
||||||
|
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
|
||||||
|
OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
|
||||||
@@ -0,0 +1,624 @@
|
|||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<img src="images/ssh-mcp-server-logo-v2.png" alt="ssh-mcp-server logo" width="220">
|
||||||
|
|
||||||
|
# ssh-mcp-server
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
基于 SSH 的 MCP (Model Context Protocol) 服务器，允许通过 MCP 协议远程执行 SSH 命令。
|
||||||
|
|
||||||
|
[English Document](README_EN.md) | 中文文档
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## 📝 项目介绍
|
||||||
|
|
||||||
|
ssh-mcp-server 是一个桥接工具，可以让 AI 助手等支持 MCP 协议的应用通过标准化接口执行远程 SSH 命令。这使得 AI 助手能够安全地操作远程服务器，执行命令并获取结果，而无需直接暴露 SSH 凭据给 AI 模型。
|
||||||
|
|
||||||
|
💬 如有任何问题，欢迎加入微信群交流：
|
||||||
|
|
||||||
|
<img src="images/wechat.jpg" alt="wechat" width="220">
|
||||||
|
|
||||||
|
## ✨ 功能亮点
|
||||||
|
|
||||||
|
- **🔒 安全连接**：支持多种安全的 SSH 连接方式，包括密码认证和私钥认证（支持带密码的私钥）
|
||||||
|
- **🛡️ 命令安全控制**：通过灵活的黑白名单机制，精确控制允许执行的命令范围，防止危险操作
|
||||||
|
- **🔄 标准化接口**：符合 MCP 协议规范，与支持该协议的 AI 助手无缝集成
|
||||||
|
- **🚇 双传输模式**：同时支持 `exec` 和 `shell` 两种 transport，兼容直连主机与堡垒机或跳板机场景
|
||||||
|
- **📂 文件传输**：支持双向文件传输功能，可上传本地文件到服务器或从服务器下载文件
|
||||||
|
- **🔑 凭据隔离**：SSH 凭据完全在本地管理，不会暴露给 AI 模型，增强安全性
|
||||||
|
- **🚀 即用即走**：使用 NPX 可直接运行，无需全局安装，方便快捷
|
||||||
|
|
||||||
|
## 📦 开源仓库
|
||||||
|
|
||||||
|
GitHub：[https://github.com/classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server)
|
||||||
|
|
||||||
|
NPM: [https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server](https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server)
|
||||||
|
|
||||||
|
## 🛠️ 工具列表
|
||||||
|
|
||||||
|
| 工具 | 名称 | 描述 |
|
||||||
|
|---------|-----------|----------|
|
||||||
|
| execute-command | 命令执行工具 | 在远程服务器上执行 SSH 命令并获取执行结果 |
|
||||||
|
| upload | 文件上传工具 | 将本地文件上传到远程服务器指定位置 |
|
||||||
|
| download | 文件下载工具 | 从远程服务器下载文件到本地指定位置 |
|
||||||
|
| list-servers | 服务器列表工具 | 列出所有可用SSH服务器配置 |
|
||||||
|
|
||||||
|
## 📚 使用方法
|
||||||
|
|
||||||
|
### 0. 🤖 通过 AI Skill 快速配置（推荐）
|
||||||
|
|
||||||
|
如果你使用支持 skill 的 AI 编程助手（如 Claude Code），可以直接使用内置的 **ssh-mcp-helper** skill 通过交互式问答完成安装和配置，无需手动编辑 JSON 文件。
|
||||||
|
|
||||||
|
**使用方式：**
|
||||||
|
|
||||||
|
1. 从本仓库 `skills/` 目录安装该 skill
|
||||||
|
2. 告诉你的 AI 助手："帮我配置 ssh-mcp-server" 或 "给 Cursor 加一个 SSH MCP 连接"
|
||||||
|
3. skill 会逐步引导你：检查 Node.js 环境 → 选择 MCP 客户端 → 选择认证方式 → 收集连接参数 → 生成并写入配置
|
||||||
|
|
||||||
|
该 skill 支持下文所有场景（账号密码、私钥、SSH config 复用、SOCKS 代理、堡垒机、多连接、2FA、命令限制等），并自动生成格式正确的配置。
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
下面的章节按从简单到复杂的顺序排列，最简单的入门方式就是用账号密码连接服务器。直接复制对应场景下的 `mcp.json` 配置到你的 MCP 客户端即可使用。
|
||||||
|
|
||||||
|
> **⚠️ 重要提示**：在 MCP 配置文件中，每个命令行参数和其值必须是 `args` 数组中的独立元素。不要用空格将它们连接在一起。例如，使用 `"--host", "192.168.1.1"` 而不是 `"--host 192.168.1.1"`。
|
||||||
|
|
||||||
|
### 1. 🔑 账号密码（最简单）
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 🔐 账号 + 私钥
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--privateKey", "~/.ssh/id_rsa"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 🔏 带密码的私钥
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--privateKey", "~/.ssh/id_rsa",
|
||||||
|
"--passphrase", "pwd123456"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 📋 复用 `~/.ssh/config`
|
||||||
|
|
||||||
|
如果你已经在 `~/.ssh/config` 配置了主机别名，服务器会自动从中读取连接参数，`mcp.json` 里就不用再写一遍。
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "myserver"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
假设你的 `~/.ssh/config` 包含：
|
||||||
|
|
||||||
|
```
|
||||||
|
Host myserver
|
||||||
|
HostName 192.168.1.1
|
||||||
|
Port 22
|
||||||
|
User root
|
||||||
|
IdentityFile ~/.ssh/id_rsa
|
||||||
|
```
|
||||||
|
|
||||||
|
你也可以指定自定义的 SSH 配置文件路径：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "myserver",
|
||||||
|
"--ssh-config-file", "/path/to/custom/ssh_config"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**注意**：命令行参数优先级高于 SSH 配置值。例如，如果你指定了 `--port 2222`，它会覆盖 SSH 配置中的端口。
|
||||||
|
|
||||||
|
### 5. 🌐 通过代理连接
|
||||||
|
|
||||||
|
当目标主机只能通过代理访问时，可使用 `--proxy` 配置 SOCKS5、HTTP 或 HTTPS 代理。
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--proxy", "http://username:password@proxy-host:proxy-port"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
支持的 URL 格式：
|
||||||
|
|
||||||
|
```text
|
||||||
|
socks://username:password@proxy-host:1080
|
||||||
|
socks5://username:password@proxy-host:1080
|
||||||
|
http://username:password@proxy-host:8080
|
||||||
|
https://username:password@proxy-host:8443
|
||||||
|
```
|
||||||
|
|
||||||
|
HTTP 和 HTTPS 代理通过 `CONNECT` 方法建立到 SSH 服务的隧道，用户名和密码使用 Basic 代理认证。HTTP、HTTPS 未填写端口时分别默认使用 `80`、`443`；SOCKS5 必须填写端口。HTTPS 代理证书使用 Node.js 默认信任链进行验证。
|
||||||
|
|
||||||
|
原有 `socksProxy` 配置和 `--socksProxy` 参数继续兼容，但只接受 `socks://` 和 `socks5://`。不要同时配置 `proxy` 和 `socksProxy`。
|
||||||
|
|
||||||
|
### 6. 📝 使用命令白名单 / 黑名单
|
||||||
|
|
||||||
|
通过 `--whitelist` 和 `--blacklist` 限制服务器允许执行的命令范围。多个模式之间用逗号分隔，每个模式都是一个正则表达式。**生产环境强烈建议配置**。
|
||||||
|
|
||||||
|
白名单示例（仅允许只读型查看命令）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--whitelist", "^ls( .*)?,^cat .*,^df.*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
黑名单示例（屏蔽危险命令）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--blacklist", "^rm .*,^shutdown.*,^reboot.*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> 注意：如果同时指定了白名单和黑名单，系统会先检查命令是否在白名单中，再检查是否在黑名单中，命令必须同时通过两项检查才能被执行。
|
||||||
|
|
||||||
|
### 7. 🧩 使用命令模板包裹命令
|
||||||
|
|
||||||
|
`commandTemplate` 会把每条执行的命令套进一个模板里，适合切换用户（`su`）、放进容器、或经过跳板机的场景。当命令会作为 shell 参数传入时使用 `<quotedCommand>`，需要原样插入时使用 `<command>`；模板会**在目录 `cd` 拼接之后**应用，因此整个 `cd ... && <实际命令>` 都会被包裹起来。
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "10.0.0.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "deploy",
|
||||||
|
"--password", "xxx",
|
||||||
|
"--command-template", "su root -c <quotedCommand>"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
当指定目录为 `/data` 执行 `ls /app` 时，实际发送的命令是：
|
||||||
|
|
||||||
|
```
|
||||||
|
su root -c 'cd -- '\''/data'\'' && ls /app'
|
||||||
|
```
|
||||||
|
|
||||||
|
其他常见模板：
|
||||||
|
|
||||||
|
```text
|
||||||
|
sudo bash -c <quotedCommand>
|
||||||
|
docker exec -i mycontainer sh -c <quotedCommand>
|
||||||
|
ssh jumphost <quotedCommand>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. 🚇 堡垒机 / 跳板机（`transportMode: shell`）
|
||||||
|
|
||||||
|
`transportMode` 默认是 `exec`。出现下面这些情况时，应该切换到 `shell`：
|
||||||
|
|
||||||
|
- SSH 登录成功，但 `exec` 执行命令失败
|
||||||
|
- 远端必须等登录 banner、profile、环境初始化完成后才能正常执行命令
|
||||||
|
- 连接目标本质上是堡垒机或只暴露交互式 shell 的设备
|
||||||
|
|
||||||
|
两者差异：
|
||||||
|
|
||||||
|
- `exec`：支持 `execute-command`、`upload`、`download`
|
||||||
|
- `shell`：命令通过持久 shell 会话串行执行，内部带命令队列；但**不支持** `upload` / `download`，因为该模式下禁用了 SFTP
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "bastion.example.com",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "ops",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--transport-mode", "shell",
|
||||||
|
"--shell-ready-timeout", "15000"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
JSON 配置文件中还可以通过 `shellCommandTimeoutMs` 覆盖 shell 模式下单条命令的默认超时。
|
||||||
|
|
||||||
|
### 9. 🔐 多因素认证（2FA / MFA）
|
||||||
|
|
||||||
|
当 SSH 服务器要求多因素认证（密码 + 私钥 + 2FA 验证码）时启用 `tryKeyboard`。密码和私钥会自动提供；对于非密码提示，请在连接前通过服务端环境变量 `SSH_MCP_2FA_CODE` 提供验证码。
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "example.com",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "user",
|
||||||
|
"--password", "your_password",
|
||||||
|
"--privateKey", "/path/to/key",
|
||||||
|
"--try-keyboard"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**认证流程：**
|
||||||
|
1. 私钥认证（如果提供）
|
||||||
|
2. 密码认证（如果提供）
|
||||||
|
3. 键盘交互式认证通过 `SSH_MCP_2FA_CODE` 提供 2FA 验证码
|
||||||
|
|
||||||
|
### 10. 🧩 多 SSH 连接配置
|
||||||
|
|
||||||
|
需要在同一个 MCP server 里同时管理多个 SSH 目标时，给每个连接命名，调用时通过 `connectionName` 选择。共有三种配置方式：
|
||||||
|
|
||||||
|
#### 📄 方式一：使用配置文件（推荐）
|
||||||
|
|
||||||
|
创建 JSON 配置文件（例如 `ssh-config.json`）：
|
||||||
|
|
||||||
|
**数组格式：**
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "dev",
|
||||||
|
"host": "1.2.3.4",
|
||||||
|
"port": 22,
|
||||||
|
"username": "alice",
|
||||||
|
"password": "{abc=P100s0}",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808",
|
||||||
|
"commandTimeoutMs": 120000,
|
||||||
|
"maxOutputBytes": 10485760
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "bastion",
|
||||||
|
"host": "9.9.9.9",
|
||||||
|
"port": 22,
|
||||||
|
"username": "ops",
|
||||||
|
"password": "pwd123456",
|
||||||
|
"transportMode": "shell",
|
||||||
|
"shellReadyTimeoutMs": 15000,
|
||||||
|
"shellCommandTimeoutMs": 45000,
|
||||||
|
"connectionTimeoutMs": 30000,
|
||||||
|
"keepaliveIntervalMs": 10000,
|
||||||
|
"keepaliveCountMax": 3
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "prod",
|
||||||
|
"host": "5.6.7.8",
|
||||||
|
"port": 22,
|
||||||
|
"username": "bob",
|
||||||
|
"password": "yyy",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "secure-server",
|
||||||
|
"host": "secure.example.com",
|
||||||
|
"port": 22,
|
||||||
|
"username": "admin",
|
||||||
|
"password": "your_password",
|
||||||
|
"privateKey": "/path/to/private/key",
|
||||||
|
"tryKeyboard": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**对象格式：**
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"dev": {
|
||||||
|
"host": "1.2.3.4",
|
||||||
|
"port": 22,
|
||||||
|
"username": "alice",
|
||||||
|
"password": "{abc=P100s0}",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808",
|
||||||
|
"commandTimeoutMs": 120000,
|
||||||
|
"maxOutputBytes": 10485760
|
||||||
|
},
|
||||||
|
"bastion": {
|
||||||
|
"host": "9.9.9.9",
|
||||||
|
"port": 22,
|
||||||
|
"username": "ops",
|
||||||
|
"password": "pwd123456",
|
||||||
|
"transportMode": "shell",
|
||||||
|
"shellReadyTimeoutMs": 15000,
|
||||||
|
"shellCommandTimeoutMs": 45000
|
||||||
|
},
|
||||||
|
"prod": {
|
||||||
|
"host": "5.6.7.8",
|
||||||
|
"port": 22,
|
||||||
|
"username": "bob",
|
||||||
|
"password": "yyy",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
然后使用 `--config-file` 参数：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--config-file", "ssh-config.json"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 🔧 方式二：使用 JSON 格式的 --ssh 参数
|
||||||
|
|
||||||
|
可以直接传递 JSON 格式的配置字符串：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
|
||||||
|
"--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}",
|
||||||
|
"--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 📝 方式三：旧格式逗号分隔（向后兼容）
|
||||||
|
|
||||||
|
对于密码中不包含特殊字符的简单情况，仍可使用旧格式：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @fangjunjie/ssh-mcp-server \
|
||||||
|
--ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
|
||||||
|
--ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"
|
||||||
|
```
|
||||||
|
|
||||||
|
> **⚠️ 注意**：旧格式在处理包含特殊字符（如 `=`、`,`、`{`、`}`）的密码时可能会有问题。如果密码包含特殊字符，请使用方式一或方式二。
|
||||||
|
|
||||||
|
在MCP工具调用时，通过 `connectionName` 参数指定目标连接名称，未指定时使用默认连接。
|
||||||
|
|
||||||
|
示例（在prod连接上执行命令）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "execute-command",
|
||||||
|
"params": {
|
||||||
|
"cmdString": "ls -al",
|
||||||
|
"connectionName": "prod"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
示例（带超时选项的命令执行）：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "execute-command",
|
||||||
|
"params": {
|
||||||
|
"cmdString": "ping -c 10 127.0.0.1",
|
||||||
|
"connectionName": "prod",
|
||||||
|
"timeout": 5000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⏱️ 命令执行超时
|
||||||
|
|
||||||
|
`execute-command` 工具支持超时选项，防止命令无限期挂起：
|
||||||
|
|
||||||
|
- **timeout**: 单次调用的命令执行超时时间（毫秒，可选）；传入时会覆盖连接配置，未传入时使用对应连接配置或其 30000ms 默认值
|
||||||
|
- 在 JSON 配置文件里为单个连接设置 `commandTimeoutMs`，可以改掉这个默认值，避免每次调用都手动传 `timeout`（`exec` 模式）
|
||||||
|
- `shell` 模式对应的配置项是 `shellCommandTimeoutMs`
|
||||||
|
- 调用参数里的 `timeout` 始终优先于上面两个配置项
|
||||||
|
- 连接默认启用 SSH keepalive（`keepaliveIntervalMs`: 10000，`keepaliveCountMax`: 3），并使用 `connectionTimeoutMs` 限制连接建立时间
|
||||||
|
- SFTP 打开和传输操作使用 `sftpTimeoutMs` 控制超时（默认 300000ms）
|
||||||
|
- 错误响应现在包含稳定的 `code`、`message`、`retriable` 字段，便于上层 Agent 处理
|
||||||
|
|
||||||
|
这对于像 `ping`、`tail -f` 或其他可能阻塞执行的长时间运行进程特别有用。
|
||||||
|
|
||||||
|
### 📦 命令输出限制
|
||||||
|
|
||||||
|
会限制单条命令捕获的 `stdout` 和 `stderr` 总量，避免大文件或无限输出耗尽 MCP server 内存：
|
||||||
|
|
||||||
|
- 在 JSON 连接配置中使用 `maxOutputBytes` 设置上限，默认值为 `10485760`（10 MiB）
|
||||||
|
- `maxOutputBytes` 必须是非负整数；设置为 `0` 可禁用限制，但不建议对不受信任的命令禁用
|
||||||
|
- 输出超过限制时，远端命令会被中止，工具返回 `OUTPUT_LIMIT_EXCEEDED` 错误和已经捕获的截断输出，不会把中止的命令误报为成功
|
||||||
|
- 当 `pty` 为 `false` 时，成功命令写入 `stderr` 的警告或进度信息会保留在 `[stderr]` 区段中
|
||||||
|
- `exec` 与 `shell` 两种模式都会应用该限制。区别在于 `exec` 模式只关闭该命令的通道，而 `shell` 模式的通道由该连接上的所有命令共用、远端在中止后仍会继续写入，因此会断开连接（与 shell 模式命令超时的处理一致）
|
||||||
|
|
||||||
|
### 🗂️ 列出所有SSH服务器
|
||||||
|
|
||||||
|
可以通过MCP工具 `list-servers` 获取所有可用的SSH服务器配置：
|
||||||
|
|
||||||
|
调用示例：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "list-servers",
|
||||||
|
"params": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
返回示例：
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{ "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
|
||||||
|
{ "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⚙️ 命令行选项参考
|
||||||
|
|
||||||
|
```text
|
||||||
|
选项:
|
||||||
|
--config-file JSON 配置文件路径（推荐用于多服务器配置）
|
||||||
|
--ssh-config-file SSH 配置文件路径（默认: ~/.ssh/config）
|
||||||
|
--ssh SSH 连接配置（可以是 JSON 字符串或旧格式）
|
||||||
|
-h, --host SSH 服务器主机地址或 SSH 配置中的别名
|
||||||
|
-p, --port SSH 服务器端口
|
||||||
|
-u, --username SSH 用户名
|
||||||
|
-w, --password SSH 密码
|
||||||
|
-k, --privateKey SSH 私钥文件路径
|
||||||
|
-P, --passphrase 私钥密码（如果有的话）
|
||||||
|
-a, --agent SSH agent socket 路径
|
||||||
|
--try-keyboard 启用键盘交互式认证以支持 2FA/MFA（默认: false）
|
||||||
|
-W, --whitelist 命令白名单，以逗号分隔的正则表达式
|
||||||
|
-B, --blacklist 命令黑名单，以逗号分隔的正则表达式
|
||||||
|
--proxy 代理地址，支持 SOCKS5、HTTP 和 HTTPS
|
||||||
|
-s, --socksProxy 旧版 SOCKS5 代理地址（兼容参数）
|
||||||
|
--allowed-local-paths upload/download 允许访问的额外本地路径，逗号分隔
|
||||||
|
--allowed-remote-paths SFTP upload/download 允许访问的远端路径（POSIX 绝对路径），逗号分隔
|
||||||
|
--transport-mode SSH transport 模式: exec 或 shell（默认: exec）
|
||||||
|
--shell-ready-timeout shell 就绪探测超时，单位毫秒（默认: 10000）
|
||||||
|
--command-template 命令模板；shell 参数用 <quotedCommand>，原样插入用 <command>
|
||||||
|
--pty 为命令执行分配伪终端（默认: true）
|
||||||
|
--pre-connect 启动时预连接所有配置的 SSH 服务器
|
||||||
|
--version, -v 打印包版本
|
||||||
|
--help 打印帮助信息
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🛡️ 安全注意事项
|
||||||
|
|
||||||
|
该服务器提供了在远程服务器上执行命令和传输文件的强大功能。为确保安全使用，请注意以下几点：
|
||||||
|
|
||||||
|
- **命令白名单**：*强烈建议* 使用 `--whitelist` 选项来限制可执行的命令集合。如果没有白名单，任何命令都可以在远程服务器上执行，这可能带来重大的安全风险。
|
||||||
|
- **私钥安全**：服务器会将 SSH 私钥读入内存。请确保运行 `ssh-mcp-server` 的机器是安全的。不要将服务器暴露给不受信任的网络。
|
||||||
|
- **拒绝服务攻击 (DoS)**：服务器没有内置的速率限制。攻击者可能通过向服务器发送大量连接请求或大文件传输来发起 DoS 攻击。建议在具有速率限制功能的防火墙或反向代理后面运行服务器。
|
||||||
|
- **路径遍历**：服务器内置了对本地文件系统路径遍历攻击的保护。但是，仍然需要注意在 `upload` 和 `download` 命令中使用的路径。
|
||||||
|
- **本地传输范围**：默认仅允许访问当前工作目录。只有在明确可信时，才建议通过 `--allowed-local-paths` 或配置文件中的 `allowedLocalPaths` 放宽范围。
|
||||||
|
- **远端传输范围**：SFTP upload/download 仅接受绝对 POSIX 路径。未配置 `allowedRemotePaths`（或 `--allowed-remote-paths`）时，任意远端路径都允许，但启动时会打印警告。强烈建议显式配置 `allowedRemotePaths` 白名单，避免模型被 prompt 注入后读写 `~/.ssh/authorized_keys`、`/etc/sshd_config` 之类敏感文件。
|
||||||
|
|
||||||
|
## 🌟 Star 历史
|
||||||
|
|
||||||
|
## Star History
|
||||||
|
|
||||||
|
[](https://www.star-history.com/?type=date&legend=top-left&repos=classfang%2Fssh-mcp-server)
|
||||||
+618
@@ -0,0 +1,618 @@
|
|||||||
|
<div align="center">
|
||||||
|
|
||||||
|
<img src="images/ssh-mcp-server-logo-v2.png" alt="ssh-mcp-server logo" width="220">
|
||||||
|
|
||||||
|
# ssh-mcp-server
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
SSH-based MCP (Model Context Protocol) server that allows remote execution of SSH commands via the MCP protocol.
|
||||||
|
|
||||||
|
English Document | [中文文档](README.md)
|
||||||
|
|
||||||
|
</div>
|
||||||
|
|
||||||
|
## 📝 Project Overview
|
||||||
|
|
||||||
|
ssh-mcp-server is a bridging tool that enables AI assistants and other applications supporting the MCP protocol to execute remote SSH commands through a standardized interface. This allows AI assistants to safely operate remote servers, execute commands, and retrieve results without directly exposing SSH credentials to AI models.
|
||||||
|
|
||||||
|
## ✨ Key Features
|
||||||
|
|
||||||
|
- **🔒 Secure Connections**: Supports multiple secure SSH connection methods, including password authentication and private key authentication (with passphrase support)
|
||||||
|
- **🛡️ Command Security Control**: Precisely control the range of allowed commands through flexible blacklist and whitelist mechanisms to prevent dangerous operations
|
||||||
|
- **🔄 Standardized Interface**: Complies with MCP protocol specifications for seamless integration with AI assistants supporting the protocol
|
||||||
|
- **🚇 Dual Transport Modes**: Supports both `exec` and `shell` transport modes for direct SSH hosts and bastion or jump-host scenarios
|
||||||
|
- **📂 File Transfer**: Supports bidirectional file transfers, uploading local files to servers or downloading files from servers
|
||||||
|
- **🔑 Credential Isolation**: SSH credentials are managed entirely locally and never exposed to AI models, enhancing security
|
||||||
|
- **🚀 Ready to Use**: Can be run directly using NPX without global installation, making it convenient and quick to deploy
|
||||||
|
|
||||||
|
## 📦 Open Source Repository
|
||||||
|
|
||||||
|
GitHub: [https://github.com/classfang/ssh-mcp-server](https://github.com/classfang/ssh-mcp-server)
|
||||||
|
|
||||||
|
NPM: [https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server](https://www.npmjs.com/package/@fangjunjie/ssh-mcp-server)
|
||||||
|
|
||||||
|
## 🛠️ Tools List
|
||||||
|
|
||||||
|
| Tool | Name | Description |
|
||||||
|
|---------|-----------|----------|
|
||||||
|
| execute-command | Command Execution Tool | Execute SSH commands on remote servers and get results |
|
||||||
|
| upload | File Upload Tool | Upload local files to specified locations on remote servers |
|
||||||
|
| download | File Download Tool | Download files from remote servers to local specified locations |
|
||||||
|
| list-servers | List Servers Tool | List all available SSH server configurations |
|
||||||
|
|
||||||
|
## 📚 Usage
|
||||||
|
|
||||||
|
### 0. 🤖 Quick Setup via AI Skill (Recommended)
|
||||||
|
|
||||||
|
If you are using an AI coding assistant that supports skills (such as Claude Code), you can use the built-in **ssh-mcp-helper** skill to complete the installation and configuration interactively — no need to manually edit JSON files.
|
||||||
|
|
||||||
|
**How to use:**
|
||||||
|
|
||||||
|
1. Install the skill from this repository's `skills/` directory
|
||||||
|
2. Tell your AI assistant: "Help me set up ssh-mcp-server" or "Configure SSH MCP for my remote server"
|
||||||
|
3. The skill will guide you step by step: check Node.js environment → choose MCP client → select authentication method → collect connection parameters → generate and write configuration
|
||||||
|
|
||||||
|
The skill supports all scenarios covered below (password, private key, SSH config reuse, SOCKS proxy, bastion hosts, multi-connection, 2FA, command restrictions, etc.) and automatically produces correctly formatted configuration.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
The sections below are arranged from the simplest entry point (username + password) to more advanced scenarios. Pick the case that matches yours and copy the `mcp.json` snippet directly into your MCP client configuration.
|
||||||
|
|
||||||
|
> **⚠️ Important**: In MCP configuration files, each command line argument and its value must be separate elements in the `args` array. Do NOT combine them with spaces. For example, use `"--host", "192.168.1.1"` instead of `"--host 192.168.1.1"`.
|
||||||
|
|
||||||
|
### 1. 🔑 Username + Password (simplest)
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 2. 🔐 Username + Private Key
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--privateKey", "~/.ssh/id_rsa"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 3. 🔏 Private Key with Passphrase
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--privateKey", "~/.ssh/id_rsa",
|
||||||
|
"--passphrase", "pwd123456"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### 4. 📋 Reuse `~/.ssh/config`
|
||||||
|
|
||||||
|
If you already have a host alias in `~/.ssh/config`, the server reads connection parameters directly from it — no need to repeat them in `mcp.json`.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "myserver"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Assuming your `~/.ssh/config` contains:
|
||||||
|
|
||||||
|
```
|
||||||
|
Host myserver
|
||||||
|
HostName 192.168.1.1
|
||||||
|
Port 22
|
||||||
|
User root
|
||||||
|
IdentityFile ~/.ssh/id_rsa
|
||||||
|
```
|
||||||
|
|
||||||
|
You can also specify a custom SSH config file path:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "myserver",
|
||||||
|
"--ssh-config-file", "/path/to/custom/ssh_config"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Note**: Command-line parameters take precedence over SSH config values. For example, if you specify `--port 2222`, it will override the port from SSH config.
|
||||||
|
|
||||||
|
### 5. 🌐 Connecting Through a Proxy
|
||||||
|
|
||||||
|
When the target host is only reachable through a proxy, use `--proxy` with a SOCKS5, HTTP, or HTTPS proxy.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--proxy", "http://username:password@proxy-host:proxy-port"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Supported URL formats:
|
||||||
|
|
||||||
|
```text
|
||||||
|
socks://username:password@proxy-host:1080
|
||||||
|
socks5://username:password@proxy-host:1080
|
||||||
|
http://username:password@proxy-host:8080
|
||||||
|
https://username:password@proxy-host:8443
|
||||||
|
```
|
||||||
|
|
||||||
|
HTTP and HTTPS proxies use the `CONNECT` method to tunnel to the SSH server, with optional Basic proxy authentication. HTTP and HTTPS default to ports `80` and `443`; SOCKS5 requires an explicit port. HTTPS proxy certificates are verified using the default Node.js trust store.
|
||||||
|
|
||||||
|
The existing `socksProxy` configuration and `--socksProxy` option remain supported for backward compatibility, but only accept `socks://` and `socks5://`. Do not configure both `proxy` and `socksProxy`.
|
||||||
|
|
||||||
|
### 6. 📝 Restricting Commands With Whitelist / Blacklist
|
||||||
|
|
||||||
|
Use `--whitelist` and `--blacklist` to limit which commands the server is allowed to run. Patterns are comma-separated regular expressions. **Strongly recommended** for any production use.
|
||||||
|
|
||||||
|
Whitelist example (only allow read-only inspection commands):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--whitelist", "^ls( .*)?,^cat .*,^df.*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Blacklist example (block destructive commands):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--blacklist", "^rm .*,^shutdown.*,^reboot.*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
> Note: If both whitelist and blacklist are specified, the command must pass both checks (whitelist first, then blacklist) to be executed.
|
||||||
|
|
||||||
|
### 7. 🧩 Wrapping Commands With a Template
|
||||||
|
|
||||||
|
`commandTemplate` wraps every executed command in a template — useful for switching user via `su`, running inside a container, or jumping through another host. Use `<quotedCommand>` when the command is passed as a shell argument, or `<command>` for raw insertion. The template is applied **after** the working-directory `cd` is prepended, so the entire `cd ... && <actual command>` chain gets wrapped.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "10.0.0.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "deploy",
|
||||||
|
"--password", "xxx",
|
||||||
|
"--command-template", "su root -c <quotedCommand>"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Executing `ls /app` with directory `/data` actually sends:
|
||||||
|
|
||||||
|
```
|
||||||
|
su root -c 'cd -- '\''/data'\'' && ls /app'
|
||||||
|
```
|
||||||
|
|
||||||
|
Other useful templates:
|
||||||
|
|
||||||
|
```text
|
||||||
|
sudo bash -c <quotedCommand>
|
||||||
|
docker exec -i mycontainer sh -c <quotedCommand>
|
||||||
|
ssh jumphost <quotedCommand>
|
||||||
|
```
|
||||||
|
|
||||||
|
### 8. 🚇 Bastion / Jump Host (`transportMode: shell`)
|
||||||
|
|
||||||
|
`transportMode` defaults to `exec`. Switch to `shell` when:
|
||||||
|
|
||||||
|
- SSH login succeeds but `exec` command execution fails
|
||||||
|
- The remote side requires shell startup scripts, banners, or environment initialization first
|
||||||
|
- The target effectively exposes only an interactive shell (bastion hosts, jump hosts, network devices)
|
||||||
|
|
||||||
|
Behavior differences:
|
||||||
|
|
||||||
|
- `exec`: supports `execute-command`, `upload`, and `download`
|
||||||
|
- `shell`: runs commands through a persistent shell session with an internal command queue, but does **not** support `upload` / `download` because SFTP is unavailable in this mode
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "bastion.example.com",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "ops",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--transport-mode", "shell",
|
||||||
|
"--shell-ready-timeout", "15000"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
In JSON config files you can also set `shellCommandTimeoutMs` to override the default per-command timeout for shell-backed connections.
|
||||||
|
|
||||||
|
### 9. 🔐 Multi-Factor Authentication (2FA / MFA)
|
||||||
|
|
||||||
|
When the SSH server requires multi-factor authentication (password + private key + 2FA verification code), enable `tryKeyboard`. The password and private key are auto-supplied. For non-password prompts, set `SSH_MCP_2FA_CODE` in the server environment before connecting.
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "example.com",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "user",
|
||||||
|
"--password", "your_password",
|
||||||
|
"--privateKey", "/path/to/key",
|
||||||
|
"--try-keyboard"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
**Authentication flow:**
|
||||||
|
1. Private key authentication (if provided)
|
||||||
|
2. Password authentication (if provided)
|
||||||
|
3. Keyboard-interactive for 2FA code via `SSH_MCP_2FA_CODE`
|
||||||
|
|
||||||
|
### 10. 🧩 Managing Multiple SSH Connections
|
||||||
|
|
||||||
|
When you need to expose more than one SSH target through the same MCP server, register them under unique connection names and select the target at call time via `connectionName`. There are three ways to configure them:
|
||||||
|
|
||||||
|
#### 📄 Method 1: Using Config File (Recommended)
|
||||||
|
|
||||||
|
Create a JSON configuration file (e.g., `ssh-config.json`):
|
||||||
|
|
||||||
|
**Array Format:**
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{
|
||||||
|
"name": "dev",
|
||||||
|
"host": "1.2.3.4",
|
||||||
|
"port": 22,
|
||||||
|
"username": "alice",
|
||||||
|
"password": "{abc=P100s0}",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808",
|
||||||
|
"commandTimeoutMs": 120000,
|
||||||
|
"maxOutputBytes": 10485760
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "bastion",
|
||||||
|
"host": "9.9.9.9",
|
||||||
|
"port": 22,
|
||||||
|
"username": "ops",
|
||||||
|
"password": "pwd123456",
|
||||||
|
"transportMode": "shell",
|
||||||
|
"shellReadyTimeoutMs": 15000,
|
||||||
|
"shellCommandTimeoutMs": 45000,
|
||||||
|
"connectionTimeoutMs": 30000,
|
||||||
|
"keepaliveIntervalMs": 10000,
|
||||||
|
"keepaliveCountMax": 3
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "prod",
|
||||||
|
"host": "5.6.7.8",
|
||||||
|
"port": 22,
|
||||||
|
"username": "bob",
|
||||||
|
"password": "yyy",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808"
|
||||||
|
},
|
||||||
|
{
|
||||||
|
"name": "secure-server",
|
||||||
|
"host": "secure.example.com",
|
||||||
|
"port": 22,
|
||||||
|
"username": "admin",
|
||||||
|
"password": "your_password",
|
||||||
|
"privateKey": "/path/to/private/key",
|
||||||
|
"tryKeyboard": true
|
||||||
|
}
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
**Object Format:**
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"dev": {
|
||||||
|
"host": "1.2.3.4",
|
||||||
|
"port": 22,
|
||||||
|
"username": "alice",
|
||||||
|
"password": "{abc=P100s0}",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808",
|
||||||
|
"commandTimeoutMs": 120000,
|
||||||
|
"maxOutputBytes": 10485760
|
||||||
|
},
|
||||||
|
"bastion": {
|
||||||
|
"host": "9.9.9.9",
|
||||||
|
"port": 22,
|
||||||
|
"username": "ops",
|
||||||
|
"password": "pwd123456",
|
||||||
|
"transportMode": "shell",
|
||||||
|
"shellReadyTimeoutMs": 15000,
|
||||||
|
"shellCommandTimeoutMs": 45000
|
||||||
|
},
|
||||||
|
"prod": {
|
||||||
|
"host": "5.6.7.8",
|
||||||
|
"port": 22,
|
||||||
|
"username": "bob",
|
||||||
|
"password": "yyy",
|
||||||
|
"socksProxy": "socks://127.0.0.1:10808"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Then use the `--config-file` parameter:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--config-file", "ssh-config.json"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 🔧 Method 2: Using JSON Format with --ssh Parameter
|
||||||
|
|
||||||
|
You can pass JSON-formatted configuration strings directly:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--ssh", "{\"name\":\"dev\",\"host\":\"1.2.3.4\",\"port\":22,\"username\":\"alice\",\"password\":\"{abc=P100s0}\",\"socksProxy\":\"socks://127.0.0.1:10808\"}",
|
||||||
|
"--ssh", "{\"name\":\"bastion\",\"host\":\"9.9.9.9\",\"port\":22,\"username\":\"ops\",\"password\":\"pwd123456\",\"transportMode\":\"shell\",\"shellReadyTimeoutMs\":15000}",
|
||||||
|
"--ssh", "{\"name\":\"prod\",\"host\":\"5.6.7.8\",\"port\":22,\"username\":\"bob\",\"password\":\"yyy\",\"socksProxy\":\"socks://127.0.0.1:10808\"}"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
#### 📝 Method 3: Legacy Comma-Separated Format (Backward Compatible)
|
||||||
|
|
||||||
|
For simple cases without special characters in passwords, you can still use the legacy format:
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npx @fangjunjie/ssh-mcp-server \
|
||||||
|
--ssh "name=dev,host=1.2.3.4,port=22,user=alice,password=xxx" \
|
||||||
|
--ssh "name=prod,host=5.6.7.8,port=22,user=bob,password=yyy"
|
||||||
|
```
|
||||||
|
|
||||||
|
> **⚠️ Note**: The legacy format may have issues with passwords containing special characters like `=`, `,`, `{`, `}`. Use Method 1 or Method 2 for passwords with special characters.
|
||||||
|
|
||||||
|
In MCP tool calls, specify the connection name via the `connectionName` parameter. If omitted, the default connection is used.
|
||||||
|
|
||||||
|
Example (execute command on 'prod' connection):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "execute-command",
|
||||||
|
"params": {
|
||||||
|
"cmdString": "ls -al",
|
||||||
|
"connectionName": "prod"
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Example (execute command with timeout options):
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "execute-command",
|
||||||
|
"params": {
|
||||||
|
"cmdString": "ping -c 10 127.0.0.1",
|
||||||
|
"connectionName": "prod",
|
||||||
|
"timeout": 5000
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⏱️ Command Execution Timeout
|
||||||
|
|
||||||
|
The `execute-command` tool supports timeout options to prevent commands from hanging indefinitely:
|
||||||
|
|
||||||
|
- **timeout**: Per-call command execution timeout in milliseconds (optional); when provided, it overrides the connection setting, otherwise the connection setting or its 30000ms default is used
|
||||||
|
- Set `commandTimeoutMs` per connection in the JSON config file to change that default, so callers do not have to pass `timeout` on every call (`exec` mode)
|
||||||
|
- The `shell` mode equivalent is `shellCommandTimeoutMs`
|
||||||
|
- A `timeout` passed with the call always takes precedence over both settings
|
||||||
|
- Connections use SSH keepalives by default (`keepaliveIntervalMs`: 10000, `keepaliveCountMax`: 3) and respect `connectionTimeoutMs` for connection setup
|
||||||
|
- SFTP open and transfer operations respect `sftpTimeoutMs` (default 300000ms)
|
||||||
|
- Error responses include stable `code`, `message`, and `retriable` fields for easier agent-side handling
|
||||||
|
|
||||||
|
This is particularly useful for commands like `ping`, `tail -f`, or other long-running processes that might block execution.
|
||||||
|
|
||||||
|
### 📦 Command Output Limit
|
||||||
|
|
||||||
|
The combined captured `stdout` and `stderr` for each command is limited to protect the MCP server from large files or unbounded output:
|
||||||
|
|
||||||
|
- Set `maxOutputBytes` in a JSON connection configuration; the default is `10485760` bytes (10 MiB)
|
||||||
|
- `maxOutputBytes` must be a non-negative integer; `0` disables the limit, which is not recommended for untrusted commands
|
||||||
|
- When output exceeds the limit, the remote command is aborted and the tool returns an `OUTPUT_LIMIT_EXCEEDED` error with the captured, truncated output instead of reporting success
|
||||||
|
- With `pty: false`, warnings and progress written to `stderr` by successful commands are preserved in a `[stderr]` section
|
||||||
|
- The limit applies to both `exec` and `shell` mode. `exec` mode closes just that command's channel, whereas the `shell` channel is shared by every command on the connection and the remote keeps writing after an abort, so the connection is dropped instead — the same way a shell mode command timeout behaves
|
||||||
|
|
||||||
|
### 🗂️ List All SSH Servers
|
||||||
|
|
||||||
|
You can use the MCP tool `list-servers` to get all available SSH server configurations:
|
||||||
|
|
||||||
|
Example call:
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"tool": "list-servers",
|
||||||
|
"params": {}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Example response:
|
||||||
|
|
||||||
|
```json
|
||||||
|
[
|
||||||
|
{ "name": "dev", "host": "1.2.3.4", "port": 22, "username": "alice" },
|
||||||
|
{ "name": "prod", "host": "5.6.7.8", "port": 22, "username": "bob" }
|
||||||
|
]
|
||||||
|
```
|
||||||
|
|
||||||
|
### ⚙️ Command Line Options Reference
|
||||||
|
|
||||||
|
```text
|
||||||
|
Options:
|
||||||
|
--config-file JSON configuration file path (recommended for multiple servers)
|
||||||
|
--ssh-config-file SSH config file path (default: ~/.ssh/config)
|
||||||
|
--ssh SSH connection configuration (can be JSON string or legacy format)
|
||||||
|
-h, --host SSH server host address or alias from SSH config
|
||||||
|
-p, --port SSH server port
|
||||||
|
-u, --username SSH username
|
||||||
|
-w, --password SSH password
|
||||||
|
-k, --privateKey SSH private key file path
|
||||||
|
-P, --passphrase Private key passphrase (if any)
|
||||||
|
-a, --agent SSH agent socket path
|
||||||
|
--try-keyboard Enable keyboard-interactive authentication for 2FA/MFA (default: false)
|
||||||
|
-W, --whitelist Command whitelist, comma-separated regular expressions
|
||||||
|
-B, --blacklist Command blacklist, comma-separated regular expressions
|
||||||
|
--proxy Proxy URL supporting SOCKS5, HTTP, and HTTPS
|
||||||
|
-s, --socksProxy Legacy SOCKS5 proxy URL
|
||||||
|
--allowed-local-paths Additional allowed local paths for upload/download, comma-separated
|
||||||
|
--allowed-remote-paths Allowed remote (POSIX, absolute) paths for SFTP upload/download, comma-separated
|
||||||
|
--transport-mode SSH transport mode: exec or shell (default: exec)
|
||||||
|
--shell-ready-timeout Shell readiness probe timeout in milliseconds (default: 10000)
|
||||||
|
--command-template Command template, use <quotedCommand> for shell arguments or <command> for raw insertion
|
||||||
|
--pty Allocate pseudo-tty for command execution (default: true)
|
||||||
|
--pre-connect Pre-connect to all configured SSH servers on startup
|
||||||
|
--version, -v Print package version
|
||||||
|
--help Print this help message
|
||||||
|
```
|
||||||
|
|
||||||
|
## 🛡️ Security Considerations
|
||||||
|
|
||||||
|
This server provides powerful capabilities to execute commands and transfer files on remote servers. To ensure it is used securely, please consider the following:
|
||||||
|
|
||||||
|
- **Command Whitelisting**: It is *strongly recommended* to use the `--whitelist` option to restrict the set of commands that can be executed. Without a whitelist, any command can be executed on the remote server, which can be a significant security risk.
|
||||||
|
- **Private Key Security**: The server reads the SSH private key into memory. Ensure that the machine running the `ssh-mcp-server` is secure. Do not expose the server to untrusted networks.
|
||||||
|
- **Denial of Service (DoS)**: The server does not have built-in rate limiting. An attacker could potentially launch a DoS attack by flooding the server with connection requests or large file transfers. It is recommended to run the server behind a firewall or reverse proxy with rate-limiting capabilities.
|
||||||
|
- **Path Traversal**: The server has built-in protection against path traversal attacks on the local filesystem. However, it is still important to be mindful of the paths used in `upload` and `download` commands.
|
||||||
|
- **Local Transfer Scope**: By default, local file transfers are restricted to the current working directory. Use `--allowed-local-paths` or `allowedLocalPaths` in config only for explicitly trusted directories.
|
||||||
|
- **Remote Transfer Scope**: SFTP upload/download accepts only absolute POSIX paths. If `allowedRemotePaths` (or `--allowed-remote-paths`) is not configured, any remote path is accepted and the server prints a startup warning. Configure `allowedRemotePaths` to whitelist a small set of remote directories; this is strongly recommended to prevent prompt-injection-driven reads or writes of files like `~/.ssh/authorized_keys` or `/etc/sshd_config`.
|
||||||
|
|
||||||
|
## 🌟 Star History
|
||||||
|
|
||||||
|
## Star History
|
||||||
|
|
||||||
|
[](https://www.star-history.com/?type=date&legend=top-left&repos=classfang%2Fssh-mcp-server)
|
||||||
Binary file not shown.
|
After Width: | Height: | Size: 422 KiB |
Binary file not shown.
|
After Width: | Height: | Size: 58 KiB |
@@ -0,0 +1,46 @@
|
|||||||
|
{
|
||||||
|
"name": "@fangjunjie/ssh-mcp-server",
|
||||||
|
"version": "1.9.0",
|
||||||
|
"description": "SSH-based MCP Server (基于 SSH 的 MCP 服务器)",
|
||||||
|
"main": "build/index.js",
|
||||||
|
"type": "module",
|
||||||
|
"repository": {
|
||||||
|
"type": "git",
|
||||||
|
"url": "git+https://github.com/classfang/ssh-mcp-server.git"
|
||||||
|
},
|
||||||
|
"bugs": {
|
||||||
|
"url": "https://github.com/classfang/ssh-mcp-server/issues"
|
||||||
|
},
|
||||||
|
"homepage": "https://github.com/classfang/ssh-mcp-server#readme",
|
||||||
|
"bin": {
|
||||||
|
"ssh-mcp-server": "build/index.js"
|
||||||
|
},
|
||||||
|
"scripts": {
|
||||||
|
"test": "node scripts/run-tests.js",
|
||||||
|
"test:watch": "node --test --watch test/**/*.test.js",
|
||||||
|
"build": "node scripts/build.js",
|
||||||
|
"prepublishOnly": "npm run build"
|
||||||
|
},
|
||||||
|
"keywords": [
|
||||||
|
"ssh",
|
||||||
|
"mcp",
|
||||||
|
"server",
|
||||||
|
"cli"
|
||||||
|
],
|
||||||
|
"author": "Junki",
|
||||||
|
"license": "ISC",
|
||||||
|
"dependencies": {
|
||||||
|
"@modelcontextprotocol/sdk": "^1.27.0",
|
||||||
|
"socks": "^2.8.7",
|
||||||
|
"ssh2": "^1.17.0",
|
||||||
|
"zod": "^4.3.6"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"@types/node": "^22.13.10",
|
||||||
|
"@types/ssh2": "^1.15.5",
|
||||||
|
"typescript": "^5.8.2"
|
||||||
|
},
|
||||||
|
"files": [
|
||||||
|
"build/**/*"
|
||||||
|
]
|
||||||
|
}
|
||||||
@@ -0,0 +1,33 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
import { execSync } from "node:child_process";
|
||||||
|
import { chmodSync } from "node:fs";
|
||||||
|
import { join } from "node:path";
|
||||||
|
import { fileURLToPath } from "node:url";
|
||||||
|
import { dirname } from "node:path";
|
||||||
|
|
||||||
|
const __filename = fileURLToPath(import.meta.url);
|
||||||
|
const __dirname = dirname(__filename);
|
||||||
|
const rootDir = join(__dirname, "..");
|
||||||
|
const buildFile = join(rootDir, "build", "index.js");
|
||||||
|
|
||||||
|
// Run TypeScript compiler
|
||||||
|
console.log("Building TypeScript...");
|
||||||
|
execSync("tsc", { stdio: "inherit", cwd: rootDir });
|
||||||
|
|
||||||
|
// Make executable on Unix-like systems (Linux, macOS, etc.)
|
||||||
|
if (process.platform !== "win32") {
|
||||||
|
try {
|
||||||
|
chmodSync(buildFile, 0o755);
|
||||||
|
console.log("Made build/index.js executable");
|
||||||
|
} catch (error) {
|
||||||
|
console.warn(
|
||||||
|
"Warning: Could not set executable permissions:",
|
||||||
|
error.message
|
||||||
|
);
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
console.log("Skipping chmod on Windows");
|
||||||
|
}
|
||||||
|
|
||||||
|
console.log("Build complete!");
|
||||||
@@ -0,0 +1,23 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 测试运行器
|
||||||
|
* 使用 Node.js 内置的测试框架运行所有测试
|
||||||
|
*/
|
||||||
|
|
||||||
|
import { execSync } from 'child_process';
|
||||||
|
|
||||||
|
console.log('🧪 运行测试...\n');
|
||||||
|
|
||||||
|
try {
|
||||||
|
execSync('node scripts/build.js', {
|
||||||
|
stdio: 'inherit',
|
||||||
|
cwd: new URL('..', import.meta.url).pathname
|
||||||
|
});
|
||||||
|
execSync('node --test test/**/*.test.js', {
|
||||||
|
stdio: 'inherit',
|
||||||
|
cwd: new URL('..', import.meta.url).pathname
|
||||||
|
});
|
||||||
|
} catch (err) {
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
@@ -0,0 +1,166 @@
|
|||||||
|
---
|
||||||
|
name: ssh-mcp-helper
|
||||||
|
description: Use when 用户希望安装、配置或新增 ssh-mcp-server 的 MCP 连接（如「帮我装一下 ssh-mcp-server」「给 Cursor/Claude Code 配置 SSH MCP」「在已有 MCP 里加一台远程主机」「ssh-mcp-server 的 mcp.json 怎么写」）。技能通过逐步问答收集主机、认证、传输模式、命令限制等参数，并把生成的 mcpServers JSON 片段写入对应客户端的配置文件。
|
||||||
|
---
|
||||||
|
|
||||||
|
# ssh-mcp-helper
|
||||||
|
|
||||||
|
## 概述
|
||||||
|
|
||||||
|
帮助用户通过交互式问答完成 `@fangjunjie/ssh-mcp-server` 的安装预检与 MCP 客户端配置。技能本身**不代替用户输入凭据**，而是逐项确认认证方式、连接参数与安全策略，最终产出可直接写入 MCP 客户端配置文件的 `mcpServers` JSON 片段。
|
||||||
|
|
||||||
|
**核心准则：** 所有可枚举的选项（MCP 客户端类型、认证方式、传输模式、是/否开关）必须使用 AskUserQuestion 让用户选择；只有不可枚举的输入（host、用户名、私钥路径、密码、自定义白名单正则等）才允许自由文本提问。
|
||||||
|
|
||||||
|
## 何时使用
|
||||||
|
|
||||||
|
- 用户明确要安装/配置/新增 ssh-mcp-server
|
||||||
|
- 用户提到为 Cursor / Claude Code / Cline / Continue 等客户端添加 SSH MCP
|
||||||
|
- 用户希望在已有 `mcpServers` 中追加一台 SSH 主机
|
||||||
|
- 用户问「ssh-mcp-server 的 mcp.json 怎么写」
|
||||||
|
|
||||||
|
## 何时不使用
|
||||||
|
|
||||||
|
- 用户要修改 ssh-mcp-server 源码 → 直接编辑代码，不进入向导
|
||||||
|
- 用户只是想跑某条 SSH 命令 → 直接调用已存在的 ssh-mcp-server 工具
|
||||||
|
- 用户在问 SSH 协议本身的概念 → 解释即可，无需走流程
|
||||||
|
|
||||||
|
## 工作流程
|
||||||
|
|
||||||
|
```dot
|
||||||
|
digraph ssh_mcp_helper {
|
||||||
|
"0. 前置环境检查" [shape=box];
|
||||||
|
"1. 选择 MCP 客户端" [shape=box];
|
||||||
|
"2. 单台 vs 多台" [shape=diamond];
|
||||||
|
"3. 选择认证方式" [shape=box];
|
||||||
|
"4. 询问连接参数" [shape=box];
|
||||||
|
"5. 询问高级选项" [shape=box];
|
||||||
|
"6. 生成 JSON 片段" [shape=box];
|
||||||
|
"7. 合并写入配置" [shape=box];
|
||||||
|
"8. 提示重启与验证" [shape=doublecircle];
|
||||||
|
|
||||||
|
"0. 前置环境检查" -> "1. 选择 MCP 客户端";
|
||||||
|
"1. 选择 MCP 客户端" -> "2. 单台 vs 多台";
|
||||||
|
"2. 单台 vs 多台" -> "3. 选择认证方式" [label="单台"];
|
||||||
|
"2. 单台 vs 多台" -> "3. 选择认证方式" [label="多台 → 写 ssh-config.json"];
|
||||||
|
"3. 选择认证方式" -> "4. 询问连接参数";
|
||||||
|
"4. 询问连接参数" -> "5. 询问高级选项";
|
||||||
|
"5. 询问高级选项" -> "6. 生成 JSON 片段";
|
||||||
|
"6. 生成 JSON 片段" -> "7. 合并写入配置";
|
||||||
|
"7. 合并写入配置" -> "8. 提示重启与验证";
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
### Step 0：前置环境检查
|
||||||
|
- 运行 `node -v` 与 `npx --version` 确认本机有 Node.js（推荐 v18+）
|
||||||
|
- 缺失则先提示用户安装 Node.js，再继续后续步骤
|
||||||
|
|
||||||
|
### Step 1：选择 MCP 客户端（AskUserQuestion 多选一）
|
||||||
|
|
||||||
|
| 客户端 | 默认配置位置 |
|
||||||
|
|---|---|
|
||||||
|
| Claude Code（全局） | `~/.claude.json` 的 `mcpServers` 字段 |
|
||||||
|
| Claude Code（项目级） | 项目根 `.mcp.json` |
|
||||||
|
| Cursor | `~/.cursor/mcp.json` |
|
||||||
|
| Cline / Continue / 其他 | 让用户提供具体路径 |
|
||||||
|
|
||||||
|
### Step 2：单台 vs 多台（AskUserQuestion 二选一）
|
||||||
|
- **单台**：直接使用命令行参数（`--host` 等）
|
||||||
|
- **多台**：生成 `ssh-config.json` 并使用 `--config-file`
|
||||||
|
|
||||||
|
### Step 3：选择认证方式（AskUserQuestion 多选一）
|
||||||
|
- `password` — 账号 + 密码
|
||||||
|
- `privateKey` — 账号 + 私钥；再用 AskUserQuestion 确认是否带 passphrase
|
||||||
|
- `ssh-config` — 复用 `~/.ssh/config` 中的 Host 别名（只需 `--host <alias>`，可选 `--ssh-config-file`）
|
||||||
|
- `ssh-agent` — 使用 `--agent` 指向 socket
|
||||||
|
- `2fa` — 密码 + 私钥 + 键盘交互，追加 `--try-keyboard`
|
||||||
|
|
||||||
|
### Step 4：连接参数（自由文本）
|
||||||
|
- host / port / username（port=22 可省略）
|
||||||
|
- 按 Step 3 的结果追问密码、私钥路径、passphrase、agent socket 等
|
||||||
|
|
||||||
|
### Step 5：高级选项（每项独立用 AskUserQuestion 询问是/否）
|
||||||
|
1. SOCKS 代理：是 → 追问 `--socksProxy` 字符串
|
||||||
|
2. 命令白名单：是 → 追问逗号分隔正则（**生产环境强烈建议开启**）
|
||||||
|
3. 命令黑名单：是 → 追问逗号分隔正则
|
||||||
|
4. 命令模板：是 → 追问含 `<command>` 占位符的模板
|
||||||
|
5. 传输模式：默认 `exec`；若用户标记目标为堡垒机/跳板机，改 `shell` 并追问 `--shell-ready-timeout`
|
||||||
|
6. 路径白名单：是 → 追问 `--allowed-local-paths` / `--allowed-remote-paths`
|
||||||
|
7. 启动时预连接：是 → 追加 `--pre-connect`
|
||||||
|
|
||||||
|
### Step 6：生成 JSON 片段
|
||||||
|
装配规则：
|
||||||
|
- `command` 固定为 `"npx"`
|
||||||
|
- `args` 第一项 `"-y"`，第二项 `"@fangjunjie/ssh-mcp-server"`
|
||||||
|
- **每个命令行参数与值必须是 args 数组中独立的两个元素**，绝不能写成 `"--host 192.168.1.1"`
|
||||||
|
- 多连接场景：把每个连接写入 `ssh-config.json`（数组或对象格式皆可），客户端配置里只放 `--config-file <绝对路径>`
|
||||||
|
|
||||||
|
### Step 7：合并写入配置
|
||||||
|
- 先用 Read 读取目标 JSON 配置文件
|
||||||
|
- 合并到既存 `mcpServers` 下；若存在同名 key，**先 AskUserQuestion 让用户选择覆盖 / 改名 / 取消**
|
||||||
|
- 写入前把最终片段展示给用户确认
|
||||||
|
- 写入后输出该配置文件的绝对路径
|
||||||
|
|
||||||
|
### Step 8：收尾
|
||||||
|
- 提示用户重启对应 MCP 客户端使配置生效
|
||||||
|
- 给出验证方式：调用 `list-servers`，或对该连接执行 `execute-command "whoami"`
|
||||||
|
|
||||||
|
## 速查表
|
||||||
|
|
||||||
|
| 场景 | 关键参数 |
|
||||||
|
|---|---|
|
||||||
|
| 账号密码 | `--host --port --username --password` |
|
||||||
|
| 私钥（可带 passphrase） | `--host --port --username --privateKey [--passphrase]` |
|
||||||
|
| 复用 ssh config 别名 | `--host <alias>` (+可选 `--ssh-config-file`) |
|
||||||
|
| SOCKS 代理 | `--socksProxy socks://user:pwd@host:port` |
|
||||||
|
| 堡垒机 / 跳板机 | `--transport-mode shell --shell-ready-timeout 15000` |
|
||||||
|
| 多连接 | `--config-file /abs/path/ssh-config.json` |
|
||||||
|
| 2FA / MFA | `--try-keyboard`（搭配密码 + 私钥） |
|
||||||
|
| 命令白名单 | `--whitelist "^ls( .*)?,^cat .*"` |
|
||||||
|
| 命令黑名单 | `--blacklist "^rm .*,^shutdown.*"` |
|
||||||
|
| 命令模板 | `--command-template "su root -c '<command>'"` |
|
||||||
|
| 路径白名单 | `--allowed-local-paths` / `--allowed-remote-paths` |
|
||||||
|
|
||||||
|
## 常见坑
|
||||||
|
|
||||||
|
- ❌ 把 `"--host 192.168.1.1"` 当作一个 args 元素 → ✅ 拆成两个元素 `"--host", "192.168.1.1"`
|
||||||
|
- ❌ 密码含 `{ } = ,` 等字符却用旧式 `--ssh "name=...,password=..."` → ✅ 改用 `--config-file` 或 JSON 形式 `--ssh`
|
||||||
|
- ❌ `shell` 模式下还想用 `upload`/`download` → 该模式禁用 SFTP，需切回 `exec`
|
||||||
|
- ❌ 直接覆盖用户既有 `mcpServers` 中的同名 key → 必须先读后合并，覆盖前显式确认
|
||||||
|
- ❌ 直连生产环境却未配置 `--whitelist` / `--blacklist` → 必须主动提醒安全风险
|
||||||
|
- ❌ 把私钥内容粘进配置 → 配置里应填**私钥文件路径**，凭据留在本地
|
||||||
|
|
||||||
|
## 输出示例
|
||||||
|
|
||||||
|
最简单的账号密码场景产出：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": [
|
||||||
|
"-y",
|
||||||
|
"@fangjunjie/ssh-mcp-server",
|
||||||
|
"--host", "192.168.1.1",
|
||||||
|
"--port", "22",
|
||||||
|
"--username", "root",
|
||||||
|
"--password", "pwd123456",
|
||||||
|
"--whitelist", "^ls( .*)?,^cat .*"
|
||||||
|
]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
多连接场景产出 `ssh-config.json` + 简化的客户端配置：
|
||||||
|
|
||||||
|
```json
|
||||||
|
{
|
||||||
|
"mcpServers": {
|
||||||
|
"ssh-mcp-server": {
|
||||||
|
"command": "npx",
|
||||||
|
"args": ["-y", "@fangjunjie/ssh-mcp-server", "--config-file", "/abs/path/ssh-config.json"]
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
@@ -0,0 +1,483 @@
|
|||||||
|
import { parseArgs } from "node:util";
|
||||||
|
import { SSHConfig, SshConnectionConfigMap, ParsedArgs } from "../models/types.js";
|
||||||
|
import fs from "fs";
|
||||||
|
import path from "path";
|
||||||
|
import os from "os";
|
||||||
|
import { lookupSshConfig } from "../utils/ssh-config-parser.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Command line argument parser class
|
||||||
|
*/
|
||||||
|
export class CommandLineParser {
|
||||||
|
private static readonly DEFAULT_TRANSPORT_MODE: SSHConfig["transportMode"] = "exec";
|
||||||
|
private static readonly DEFAULT_SHELL_READY_TIMEOUT_MS = 10000;
|
||||||
|
|
||||||
|
private static parseBoolean(value: unknown): boolean | undefined {
|
||||||
|
if (value === undefined) {
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
if (typeof value === "boolean") {
|
||||||
|
return value;
|
||||||
|
}
|
||||||
|
if (typeof value === "string") {
|
||||||
|
const normalized = value.trim().toLowerCase();
|
||||||
|
if (normalized === "true") {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
if (normalized === "false") {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
return Boolean(value);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static parseTransportMode(
|
||||||
|
value: unknown,
|
||||||
|
): SSHConfig["transportMode"] | undefined {
|
||||||
|
if (value === undefined || value === null || value === "") {
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (value === "exec" || value === "shell") {
|
||||||
|
return value;
|
||||||
|
}
|
||||||
|
|
||||||
|
throw new Error(
|
||||||
|
`transportMode must be either 'exec' or 'shell', got: ${String(value)}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
private static parseTimeout(
|
||||||
|
value: unknown,
|
||||||
|
fieldName: string,
|
||||||
|
): number | undefined {
|
||||||
|
if (value === undefined || value === null || value === "") {
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
|
||||||
|
const parsed =
|
||||||
|
typeof value === "number" ? value : parseInt(String(value), 10);
|
||||||
|
|
||||||
|
if (!Number.isFinite(parsed) || parsed <= 0) {
|
||||||
|
throw new Error(`${fieldName} must be a positive number, got: ${String(value)}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
return parsed;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static parseMaxOutputBytes(value: unknown): number | undefined {
|
||||||
|
if (value === undefined || value === null || value === "") {
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
|
||||||
|
const parsed = typeof value === "number" ? value : Number(String(value));
|
||||||
|
|
||||||
|
if (!Number.isSafeInteger(parsed) || parsed < 0) {
|
||||||
|
throw new Error(
|
||||||
|
`maxOutputBytes must be a non-negative integer, got: ${String(value)}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return parsed;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Parse command line arguments
|
||||||
|
*/
|
||||||
|
public static parseArgs(): ParsedArgs {
|
||||||
|
const { values, positionals } = parseArgs({
|
||||||
|
args: process.argv.slice(2),
|
||||||
|
options: {
|
||||||
|
"config-file": { type: "string" },
|
||||||
|
"ssh-config-file": { type: "string" },
|
||||||
|
ssh: { type: "string", multiple: true },
|
||||||
|
// Compatible with single connection legacy parameters
|
||||||
|
host: { type: "string", short: "h" },
|
||||||
|
port: { type: "string", short: "p" },
|
||||||
|
username: { type: "string", short: "u" },
|
||||||
|
password: { type: "string", short: "w" },
|
||||||
|
privateKey: { type: "string", short: "k" },
|
||||||
|
passphrase: { type: "string", short: "P" },
|
||||||
|
agent: { type: "string", short: "a" },
|
||||||
|
"password-from-env": { type: "string" },
|
||||||
|
whitelist: { type: "string", short: "W" },
|
||||||
|
blacklist: { type: "string", short: "B" },
|
||||||
|
proxy: { type: "string" },
|
||||||
|
socksProxy: { type: "string", short: "s" },
|
||||||
|
"allowed-local-paths": { type: "string" },
|
||||||
|
"allowed-remote-paths": { type: "string" },
|
||||||
|
"transport-mode": { type: "string" },
|
||||||
|
"shell-ready-timeout": { type: "string" },
|
||||||
|
"command-template": { type: "string" },
|
||||||
|
pty: { type: "boolean" },
|
||||||
|
"try-keyboard": { type: "boolean" },
|
||||||
|
"pre-connect": { type: "boolean" },
|
||||||
|
},
|
||||||
|
allowPositionals: true,
|
||||||
|
});
|
||||||
|
|
||||||
|
const configMap: SshConnectionConfigMap = {};
|
||||||
|
|
||||||
|
// Priority 1: Load from config file if specified
|
||||||
|
if (values["config-file"]) {
|
||||||
|
const configFilePath = path.resolve(values["config-file"]);
|
||||||
|
if (!fs.existsSync(configFilePath)) {
|
||||||
|
throw new Error(`Config file not found: ${configFilePath}`);
|
||||||
|
}
|
||||||
|
try {
|
||||||
|
const configContent = fs.readFileSync(configFilePath, "utf-8");
|
||||||
|
const fileConfig = JSON.parse(configContent);
|
||||||
|
|
||||||
|
// Support both array format and object format
|
||||||
|
if (Array.isArray(fileConfig)) {
|
||||||
|
// Array format: [{name: "dev", host: "...", ...}, ...]
|
||||||
|
for (const config of fileConfig) {
|
||||||
|
if (!config.name || !config.host || !config.port || !config.username) {
|
||||||
|
throw new Error("Each config in array must include name, host, port, username");
|
||||||
|
}
|
||||||
|
configMap[config.name] = this.normalizeConfig(config);
|
||||||
|
}
|
||||||
|
} else if (typeof fileConfig === "object" && fileConfig !== null) {
|
||||||
|
// Object format: {"dev": {host: "...", ...}, "prod": {...}}
|
||||||
|
for (const [name, config] of Object.entries(fileConfig)) {
|
||||||
|
const normalizedConfig = this.normalizeConfig(config as any);
|
||||||
|
normalizedConfig.name = name;
|
||||||
|
configMap[name] = normalizedConfig;
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
throw new Error("Config file must contain an array or object of SSH configurations");
|
||||||
|
}
|
||||||
|
} catch (err) {
|
||||||
|
if (err instanceof SyntaxError) {
|
||||||
|
throw new Error(`Invalid JSON in config file: ${(err as Error).message}`);
|
||||||
|
}
|
||||||
|
throw err;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Priority 2: Parse --ssh parameters (only if no config file was loaded)
|
||||||
|
if (Object.keys(configMap).length === 0) {
|
||||||
|
const sshParams: string[] = Array.isArray(values.ssh)
|
||||||
|
? values.ssh
|
||||||
|
: values.ssh
|
||||||
|
? [values.ssh]
|
||||||
|
: [];
|
||||||
|
|
||||||
|
for (const sshStr of sshParams) {
|
||||||
|
let conf: SSHConfig;
|
||||||
|
|
||||||
|
// Try to parse as JSON first
|
||||||
|
if (sshStr.trim().startsWith("{")) {
|
||||||
|
try {
|
||||||
|
const jsonConfig = JSON.parse(sshStr);
|
||||||
|
conf = this.normalizeConfig(jsonConfig);
|
||||||
|
if (!conf.name) {
|
||||||
|
throw new Error("JSON config must include 'name' field");
|
||||||
|
}
|
||||||
|
} catch (err) {
|
||||||
|
throw new Error(`Invalid JSON format in --ssh parameter: ${(err as Error).message}`);
|
||||||
|
}
|
||||||
|
} else {
|
||||||
|
// Fallback to legacy comma-separated format for backward compatibility
|
||||||
|
conf = this.parseLegacySshFormat(sshStr);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!conf.name || !conf.host || !conf.port || !conf.username) {
|
||||||
|
throw new Error("Each --ssh must include name, host, port, username");
|
||||||
|
}
|
||||||
|
configMap[conf.name] = conf;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Priority 3: Compatible with single connection legacy parameters
|
||||||
|
if (Object.keys(configMap).length === 0) {
|
||||||
|
const host = values.host || positionals[0];
|
||||||
|
|
||||||
|
// 尝试从 SSH config 读取配置
|
||||||
|
let sshConfigEntry = null;
|
||||||
|
if (host) {
|
||||||
|
try {
|
||||||
|
sshConfigEntry = lookupSshConfig(host, values["ssh-config-file"]);
|
||||||
|
} catch (err) {
|
||||||
|
// 显式指定配置文件但读取失败时抛错
|
||||||
|
throw err;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const portStr = values.port || positionals[1] || sshConfigEntry?.port?.toString() || "22";
|
||||||
|
const username = values.username || positionals[2] || sshConfigEntry?.user;
|
||||||
|
const password =
|
||||||
|
values.password ||
|
||||||
|
(values["password-from-env"]
|
||||||
|
? (process.env[values["password-from-env"]] ?? undefined)
|
||||||
|
: undefined) ||
|
||||||
|
positionals[3];
|
||||||
|
const privateKey = values.privateKey || sshConfigEntry?.identityFile;
|
||||||
|
const passphrase = values.passphrase || process.env.SSH_MCP_PASSPHRASE;
|
||||||
|
const resolvedAgent = values.agent !== undefined
|
||||||
|
? values.agent
|
||||||
|
: !password && !privateKey
|
||||||
|
? process.env.SSH_AUTH_SOCK
|
||||||
|
: undefined;
|
||||||
|
const whitelist = values.whitelist;
|
||||||
|
const blacklist = values.blacklist;
|
||||||
|
const allowedLocalPaths = values["allowed-local-paths"];
|
||||||
|
const allowedRemotePaths = values["allowed-remote-paths"];
|
||||||
|
const commandTemplate = values["command-template"];
|
||||||
|
const pty = values.pty;
|
||||||
|
const tryKeyboard = values["try-keyboard"];
|
||||||
|
|
||||||
|
// 实际连接地址：优先使用 SSH config 的 HostName
|
||||||
|
const actualHost = sshConfigEntry?.hostName || host;
|
||||||
|
|
||||||
|
// No connection args provided at all: run in dynamic mode where each
|
||||||
|
// tool call may supply host/username/password inline. An empty config
|
||||||
|
// is valid and lets the MCP server start without any pre-saved server.
|
||||||
|
if (!actualHost) {
|
||||||
|
return {
|
||||||
|
configs: configMap,
|
||||||
|
preConnect: values["pre-connect"] === true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
if (!portStr || !username || (!password && !privateKey && !resolvedAgent)) {
|
||||||
|
throw new Error(
|
||||||
|
"Missing required parameters, need to provide host, port, username and password, private key or agent"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
const port = parseInt(portStr, 10);
|
||||||
|
if (isNaN(port)) {
|
||||||
|
throw new Error("Port must be a valid number");
|
||||||
|
}
|
||||||
|
|
||||||
|
configMap["default"] = this.normalizeConfig({
|
||||||
|
name: "default",
|
||||||
|
host: actualHost,
|
||||||
|
port,
|
||||||
|
username,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
agent: resolvedAgent,
|
||||||
|
proxy: values.proxy,
|
||||||
|
socksProxy: values.socksProxy,
|
||||||
|
pty: pty !== undefined ? pty : undefined,
|
||||||
|
tryKeyboard: tryKeyboard !== undefined ? tryKeyboard : undefined,
|
||||||
|
transportMode: values["transport-mode"],
|
||||||
|
shellReadyTimeoutMs: values["shell-ready-timeout"],
|
||||||
|
commandTemplate,
|
||||||
|
commandWhitelist: whitelist
|
||||||
|
? whitelist
|
||||||
|
.split(",")
|
||||||
|
.map((pattern) => pattern.trim())
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
commandBlacklist: blacklist
|
||||||
|
? blacklist
|
||||||
|
.split(",")
|
||||||
|
.map((pattern) => pattern.trim())
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
allowedLocalPaths: allowedLocalPaths
|
||||||
|
? allowedLocalPaths
|
||||||
|
.split(",")
|
||||||
|
.map((allowedPath) => allowedPath.trim())
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
allowedRemotePaths: allowedRemotePaths
|
||||||
|
? allowedRemotePaths
|
||||||
|
.split(",")
|
||||||
|
.map((allowedPath) => allowedPath.trim())
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
configs: configMap,
|
||||||
|
preConnect: values["pre-connect"] === true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Parse legacy comma-separated format: name=dev,host=1.2.3.4,port=22,user=alice,password=xxx
|
||||||
|
* @private
|
||||||
|
*/
|
||||||
|
private static parseLegacySshFormat(sshStr: string): SSHConfig {
|
||||||
|
const conf: any = {};
|
||||||
|
const parts = sshStr.split(",");
|
||||||
|
|
||||||
|
for (const part of parts) {
|
||||||
|
// Only split on the first '=' to handle values containing '='
|
||||||
|
const equalIndex = part.indexOf("=");
|
||||||
|
if (equalIndex > 0) {
|
||||||
|
const k = part.substring(0, equalIndex).trim();
|
||||||
|
const v = part.substring(equalIndex + 1).trim();
|
||||||
|
if (k && v) {
|
||||||
|
conf[k] = v;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
const port = parseInt(conf.port, 10);
|
||||||
|
if (isNaN(port)) {
|
||||||
|
throw new Error(
|
||||||
|
`Port for connection ${conf.name || "unknown"} must be a valid number`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return this.normalizeConfig(conf);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Normalize SSH config object to ensure proper types and structure
|
||||||
|
* @private
|
||||||
|
*/
|
||||||
|
private static normalizeConfig(config: any): SSHConfig {
|
||||||
|
const port = typeof config.port === "number"
|
||||||
|
? config.port
|
||||||
|
: parseInt(config.port, 10);
|
||||||
|
|
||||||
|
if (isNaN(port)) {
|
||||||
|
throw new Error(`Port must be a valid number, got: ${config.port}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
return {
|
||||||
|
name: config.name,
|
||||||
|
host: config.host,
|
||||||
|
port,
|
||||||
|
username: config.username || config.user,
|
||||||
|
password: config.password,
|
||||||
|
privateKey: config.privateKey
|
||||||
|
? this.normalizeLocalPath(String(config.privateKey))
|
||||||
|
: undefined,
|
||||||
|
passphrase: config.passphrase || process.env.SSH_MCP_PASSPHRASE,
|
||||||
|
agent: config.agent,
|
||||||
|
algorithms: config.algorithms,
|
||||||
|
proxy: config.proxy,
|
||||||
|
socksProxy: config.socksProxy,
|
||||||
|
pty: this.parseBoolean(config.pty),
|
||||||
|
tryKeyboard: this.parseBoolean(config.tryKeyboard),
|
||||||
|
transportMode:
|
||||||
|
this.parseTransportMode(config.transportMode) ||
|
||||||
|
this.DEFAULT_TRANSPORT_MODE,
|
||||||
|
shellReadyTimeoutMs:
|
||||||
|
this.parseTimeout(
|
||||||
|
config.shellReadyTimeoutMs,
|
||||||
|
"shellReadyTimeoutMs",
|
||||||
|
) || this.DEFAULT_SHELL_READY_TIMEOUT_MS,
|
||||||
|
shellCommandTimeoutMs: this.parseTimeout(
|
||||||
|
config.shellCommandTimeoutMs,
|
||||||
|
"shellCommandTimeoutMs",
|
||||||
|
),
|
||||||
|
commandTimeoutMs: this.parseTimeout(
|
||||||
|
config.commandTimeoutMs,
|
||||||
|
"commandTimeoutMs",
|
||||||
|
),
|
||||||
|
connectionTimeoutMs: this.parseTimeout(
|
||||||
|
config.connectionTimeoutMs,
|
||||||
|
"connectionTimeoutMs",
|
||||||
|
),
|
||||||
|
sftpTimeoutMs: this.parseTimeout(config.sftpTimeoutMs, "sftpTimeoutMs"),
|
||||||
|
maxOutputBytes: this.parseMaxOutputBytes(config.maxOutputBytes),
|
||||||
|
keepaliveIntervalMs: this.parseTimeout(
|
||||||
|
config.keepaliveIntervalMs,
|
||||||
|
"keepaliveIntervalMs",
|
||||||
|
),
|
||||||
|
keepaliveCountMax: this.parseTimeout(
|
||||||
|
config.keepaliveCountMax,
|
||||||
|
"keepaliveCountMax",
|
||||||
|
),
|
||||||
|
commandWhitelist: Array.isArray(config.commandWhitelist)
|
||||||
|
? config.commandWhitelist
|
||||||
|
: config.whitelist
|
||||||
|
? typeof config.whitelist === "string"
|
||||||
|
? config.whitelist.split("|").map((s: string) => s.trim()).filter(Boolean)
|
||||||
|
: config.whitelist
|
||||||
|
: undefined,
|
||||||
|
commandBlacklist: Array.isArray(config.commandBlacklist)
|
||||||
|
? config.commandBlacklist
|
||||||
|
: config.blacklist
|
||||||
|
? typeof config.blacklist === "string"
|
||||||
|
? config.blacklist.split("|").map((s: string) => s.trim()).filter(Boolean)
|
||||||
|
: config.blacklist
|
||||||
|
: undefined,
|
||||||
|
allowedLocalPaths: Array.isArray(config.allowedLocalPaths)
|
||||||
|
? config.allowedLocalPaths
|
||||||
|
.map((allowedPath: unknown) =>
|
||||||
|
this.normalizeLocalPath(String(allowedPath)),
|
||||||
|
)
|
||||||
|
.filter(Boolean)
|
||||||
|
: typeof config.allowedLocalPaths === "string"
|
||||||
|
? config.allowedLocalPaths
|
||||||
|
.split("|")
|
||||||
|
.map((allowedPath: string) =>
|
||||||
|
this.normalizeLocalPath(allowedPath.trim()),
|
||||||
|
)
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
allowedRemotePaths: Array.isArray(config.allowedRemotePaths)
|
||||||
|
? config.allowedRemotePaths
|
||||||
|
.map((allowedPath: unknown) =>
|
||||||
|
this.normalizeRemotePath(String(allowedPath)),
|
||||||
|
)
|
||||||
|
: typeof config.allowedRemotePaths === "string"
|
||||||
|
? config.allowedRemotePaths
|
||||||
|
.split("|")
|
||||||
|
.map((allowedPath: string) =>
|
||||||
|
this.normalizeRemotePath(allowedPath.trim()),
|
||||||
|
)
|
||||||
|
.filter(Boolean)
|
||||||
|
: undefined,
|
||||||
|
commandTemplate: this.parseCommandTemplate(config.commandTemplate),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
private static parseCommandTemplate(
|
||||||
|
value: unknown,
|
||||||
|
): string | undefined {
|
||||||
|
if (value === undefined || value === null || value === "") {
|
||||||
|
return undefined;
|
||||||
|
}
|
||||||
|
|
||||||
|
const template = String(value);
|
||||||
|
if (!template.includes("<command>") && !template.includes("<quotedCommand>")) {
|
||||||
|
throw new Error(
|
||||||
|
`commandTemplate must contain '<command>' or '<quotedCommand>' placeholder, got: ${template}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return template;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static normalizeLocalPath(localPath: string): string {
|
||||||
|
return path.resolve(this.expandHomePath(localPath));
|
||||||
|
}
|
||||||
|
|
||||||
|
private static expandHomePath(localPath: string): string {
|
||||||
|
if (localPath === "~") {
|
||||||
|
return os.homedir();
|
||||||
|
}
|
||||||
|
if (localPath.startsWith("~/")) {
|
||||||
|
return path.join(os.homedir(), localPath.slice(2));
|
||||||
|
}
|
||||||
|
return localPath;
|
||||||
|
}
|
||||||
|
|
||||||
|
private static normalizeRemotePath(remotePath: string): string {
|
||||||
|
if (!remotePath) {
|
||||||
|
return "";
|
||||||
|
}
|
||||||
|
if (!path.posix.isAbsolute(remotePath)) {
|
||||||
|
throw new Error(
|
||||||
|
`allowedRemotePaths entries must be absolute POSIX paths, got: ${remotePath}`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
const normalized = path.posix.normalize(remotePath);
|
||||||
|
if (normalized.length > 1 && normalized.endsWith("/")) {
|
||||||
|
return normalized.slice(0, -1);
|
||||||
|
}
|
||||||
|
return normalized;
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,4 @@
|
|||||||
|
/**
|
||||||
|
* Export all configurations
|
||||||
|
*/
|
||||||
|
export * from './server.js';
|
||||||
@@ -0,0 +1,21 @@
|
|||||||
|
import { readFileSync } from "node:fs";
|
||||||
|
|
||||||
|
function readPackageVersion(): string {
|
||||||
|
const packageJson = JSON.parse(
|
||||||
|
readFileSync(new URL("../../package.json", import.meta.url), "utf8"),
|
||||||
|
) as { version?: unknown };
|
||||||
|
|
||||||
|
if (typeof packageJson.version !== "string") {
|
||||||
|
throw new Error("package.json must include a string version");
|
||||||
|
}
|
||||||
|
|
||||||
|
return packageJson.version;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* MCP Server configuration
|
||||||
|
*/
|
||||||
|
export const SERVER_CONFIG = {
|
||||||
|
name: "ssh-mcp-server",
|
||||||
|
version: readPackageVersion(),
|
||||||
|
};
|
||||||
@@ -0,0 +1,133 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
|
||||||
|
import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
|
||||||
|
import { CommandLineParser } from "../cli/command-line-parser.js";
|
||||||
|
import { Logger } from "../utils/logger.js";
|
||||||
|
import { registerAllTools } from "../tools/index.js";
|
||||||
|
import { SERVER_CONFIG } from "../config/server.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* MCP Server class
|
||||||
|
*/
|
||||||
|
export class SshMcpServer {
|
||||||
|
private server: McpServer;
|
||||||
|
private sshManager: SSHConnectionManager;
|
||||||
|
private shutdownHandlersRegistered = false;
|
||||||
|
private shutdownPromise?: Promise<void>;
|
||||||
|
|
||||||
|
constructor() {
|
||||||
|
this.server = new McpServer(SERVER_CONFIG);
|
||||||
|
|
||||||
|
this.sshManager = SSHConnectionManager.getInstance();
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register tools
|
||||||
|
*/
|
||||||
|
private registerTools(): void {
|
||||||
|
registerAllTools(this.server);
|
||||||
|
}
|
||||||
|
|
||||||
|
private async shutdown(reason: string, exitCode?: number): Promise<void> {
|
||||||
|
if (!this.shutdownPromise) {
|
||||||
|
this.shutdownPromise = (async () => {
|
||||||
|
Logger.log(`Received ${reason}, shutting down SSH MCP server...`, "info");
|
||||||
|
|
||||||
|
this.sshManager.disconnect();
|
||||||
|
|
||||||
|
try {
|
||||||
|
await this.server.close();
|
||||||
|
} catch (error) {
|
||||||
|
Logger.log(
|
||||||
|
`Failed to close MCP server cleanly: ${(error as Error).message}`,
|
||||||
|
"error",
|
||||||
|
);
|
||||||
|
}
|
||||||
|
})();
|
||||||
|
}
|
||||||
|
|
||||||
|
await this.shutdownPromise;
|
||||||
|
|
||||||
|
if (exitCode !== undefined) {
|
||||||
|
process.exit(exitCode);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
private registerShutdownHandlers(): void {
|
||||||
|
if (this.shutdownHandlersRegistered) {
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const handleSignal = (signal: NodeJS.Signals) => {
|
||||||
|
void this.shutdown(signal, 0);
|
||||||
|
};
|
||||||
|
|
||||||
|
process.once("SIGINT", handleSignal);
|
||||||
|
process.once("SIGTERM", handleSignal);
|
||||||
|
process.stdin.resume();
|
||||||
|
process.stdin.once("end", () => void this.shutdown("stdin end", 0));
|
||||||
|
process.stdin.once("close", () => void this.shutdown("stdin close", 0));
|
||||||
|
|
||||||
|
this.shutdownHandlersRegistered = true;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Run the server
|
||||||
|
*/
|
||||||
|
public async run(): Promise<void> {
|
||||||
|
// Initialize SSH configuration
|
||||||
|
const parsedArgs = CommandLineParser.parseArgs();
|
||||||
|
this.sshManager.setConfig(parsedArgs.configs);
|
||||||
|
this.registerShutdownHandlers();
|
||||||
|
|
||||||
|
// Register tools before accepting MCP requests.
|
||||||
|
this.registerTools();
|
||||||
|
|
||||||
|
// Create transport instance and connect.
|
||||||
|
const transport = new StdioServerTransport();
|
||||||
|
await this.server.connect(transport);
|
||||||
|
|
||||||
|
Logger.log("MCP server connection established");
|
||||||
|
|
||||||
|
// Security warning
|
||||||
|
const allConfigs = Object.values(parsedArgs.configs);
|
||||||
|
if (
|
||||||
|
allConfigs.some(
|
||||||
|
(c) => !c.commandWhitelist || c.commandWhitelist.length === 0
|
||||||
|
)
|
||||||
|
) {
|
||||||
|
Logger.log(
|
||||||
|
"WARNING: Running without a command whitelist is strongly discouraged. Please configure a whitelist to restrict the commands that can be executed.",
|
||||||
|
"info"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
if (
|
||||||
|
allConfigs.some(
|
||||||
|
(c) =>
|
||||||
|
(c.transportMode || "exec") === "exec" &&
|
||||||
|
(!c.allowedRemotePaths || c.allowedRemotePaths.length === 0)
|
||||||
|
)
|
||||||
|
) {
|
||||||
|
Logger.log(
|
||||||
|
"WARNING: Running without allowedRemotePaths is strongly discouraged. SFTP upload/download can read or write any path on the remote server. Configure allowedRemotePaths to restrict the SFTP surface.",
|
||||||
|
"info"
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
// Pre-connect to all servers if flag is set
|
||||||
|
if (parsedArgs.preConnect) {
|
||||||
|
Logger.log("Pre-connecting to all configured SSH servers...", "info");
|
||||||
|
void this.sshManager
|
||||||
|
.connectAll()
|
||||||
|
.then(() => {
|
||||||
|
Logger.log("Successfully pre-connected to all SSH servers", "info");
|
||||||
|
})
|
||||||
|
.catch((error) => {
|
||||||
|
Logger.log(
|
||||||
|
`Warning: Some SSH connections failed during pre-connect: ${(error as Error).message}`,
|
||||||
|
"error"
|
||||||
|
);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,58 @@
|
|||||||
|
#!/usr/bin/env node
|
||||||
|
|
||||||
|
import { SshMcpServer } from "./core/mcp-server.js";
|
||||||
|
import { SERVER_CONFIG } from "./config/server.js";
|
||||||
|
import { Logger } from "./utils/logger.js";
|
||||||
|
|
||||||
|
const HELP_TEXT = `Usage: ssh-mcp-server [options] [host port username password]
|
||||||
|
|
||||||
|
Options:
|
||||||
|
--config-file <path> Load SSH server configs from a JSON file
|
||||||
|
--ssh-config-file <path> Read host aliases from SSH config (default: ~/.ssh/config)
|
||||||
|
--ssh <config> Add an SSH config as JSON or legacy key=value pairs (repeatable)
|
||||||
|
-h, --host <host> SSH host or SSH config alias for single-host mode
|
||||||
|
-p, --port <port> SSH port for single-host mode
|
||||||
|
-u, --username <name> SSH username for single-host mode
|
||||||
|
-w, --password <password> SSH password for single-host mode
|
||||||
|
--password-from-env <name> Read the SSH password for single-host mode from the named environment variable (avoids exposing it in process args)
|
||||||
|
-k, --privateKey <path> SSH private key path for single-host mode
|
||||||
|
-P, --passphrase <passphrase> SSH private key passphrase
|
||||||
|
-a, --agent <path> SSH agent socket path or pageant on Windows
|
||||||
|
-W, --whitelist <patterns> Command whitelist regexes, comma-separated
|
||||||
|
-B, --blacklist <patterns> Command blacklist regexes, comma-separated
|
||||||
|
--proxy <url> Proxy URL (SOCKS5, HTTP, or HTTPS)
|
||||||
|
-s, --socksProxy <url> Legacy SOCKS5 proxy URL
|
||||||
|
--allowed-local-paths <paths> Extra allowed local paths, comma-separated
|
||||||
|
--allowed-remote-paths <paths> Allowed remote POSIX absolute paths, comma-separated
|
||||||
|
--transport-mode <mode> SSH transport mode: exec or shell (default: exec)
|
||||||
|
--shell-ready-timeout <ms> Shell readiness probe timeout (default: 10000)
|
||||||
|
--command-template <template> Wrap commands with <command> or <quotedCommand>
|
||||||
|
--pty Allocate pseudo-tty for exec mode commands (default: true)
|
||||||
|
--try-keyboard Enable keyboard-interactive authentication
|
||||||
|
--pre-connect Pre-connect to all SSH servers on startup
|
||||||
|
--version, -v Print package version
|
||||||
|
--help Print this help message`;
|
||||||
|
|
||||||
|
function hasArg(...names: string[]): boolean {
|
||||||
|
return process.argv.slice(2).some((arg) => names.includes(arg));
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Main program entry
|
||||||
|
*/
|
||||||
|
async function main(): Promise<void> {
|
||||||
|
if (hasArg("--help")) {
|
||||||
|
console.log(HELP_TEXT);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (hasArg("--version", "-v")) {
|
||||||
|
console.log(SERVER_CONFIG.version);
|
||||||
|
return;
|
||||||
|
}
|
||||||
|
|
||||||
|
const sshMcpServer = new SshMcpServer();
|
||||||
|
await sshMcpServer.run();
|
||||||
|
}
|
||||||
|
|
||||||
|
main().catch((error) => Logger.handleError(error, "【SSH MCP Server Error】", true));
|
||||||
@@ -0,0 +1,114 @@
|
|||||||
|
import type { Algorithms } from "ssh2";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* SSH connection configuration interface
|
||||||
|
*/
|
||||||
|
export interface SSHConfig {
|
||||||
|
name?: string; // Connection name, optional, compatible with single connection
|
||||||
|
host: string;
|
||||||
|
port: number;
|
||||||
|
username: string;
|
||||||
|
password?: string;
|
||||||
|
privateKey?: string;
|
||||||
|
passphrase?: string;
|
||||||
|
agent?: string; // SSH agent for authentication (use 'pageant' for Windows Pageant)
|
||||||
|
tryKeyboard?: boolean; // Enable keyboard-interactive authentication. Password prompts use `password`; non-password prompts (e.g. OTP) use the SSH_MCP_2FA_CODE env var. Default: false
|
||||||
|
commandWhitelist?: string[]; // Command whitelist (array of regex strings)
|
||||||
|
commandBlacklist?: string[]; // Command blacklist (array of regex strings)
|
||||||
|
proxy?: string; // Proxy URL supporting SOCKS5, HTTP, and HTTPS
|
||||||
|
socksProxy?: string; // Legacy SOCKS5-only proxy URL
|
||||||
|
algorithms?: Algorithms; // Custom SSH algorithms (kex, cipher, serverHostKey, hmac, compress)
|
||||||
|
pty?: boolean; // Allocate pseudo-tty for command execution, default: true
|
||||||
|
allowedLocalPaths?: string[]; // Allowed local paths for upload/download
|
||||||
|
allowedRemotePaths?: string[]; // Allowed remote paths for SFTP upload/download (POSIX, absolute)
|
||||||
|
transportMode?: "exec" | "shell"; // SSH transport mode, default: exec
|
||||||
|
shellReadyTimeoutMs?: number; // Shell readiness probe timeout, default: 10000ms
|
||||||
|
shellCommandTimeoutMs?: number; // Shell command timeout override, default: 30000ms
|
||||||
|
commandTimeoutMs?: number; // Exec command timeout override, default: 30000ms
|
||||||
|
connectionTimeoutMs?: number; // SSH connection and handshake timeout, default: 30000ms
|
||||||
|
sftpTimeoutMs?: number; // SFTP open and transfer timeout, default: 300000ms
|
||||||
|
maxOutputBytes?: number; // Max captured bytes per command (stdout+stderr) before aborting, default: 10485760; set 0 to disable
|
||||||
|
keepaliveIntervalMs?: number; // SSH keepalive interval, default: 10000ms
|
||||||
|
keepaliveCountMax?: number; // Unanswered keepalive packets before disconnect, default: 3
|
||||||
|
commandTemplate?: string; // Command template, use <quotedCommand> for shell arguments or <command> for raw insertion
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Multiple SSH connection configuration Map
|
||||||
|
*/
|
||||||
|
export type SshConnectionConfigMap = Record<string, SSHConfig>;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Connection parameters that may be supplied per tool call instead of being
|
||||||
|
* read from static configuration. When these are present, a fresh SSH client
|
||||||
|
* is established on the fly for that single operation.
|
||||||
|
*/
|
||||||
|
export interface DynamicSSHParams {
|
||||||
|
host: string;
|
||||||
|
port?: number;
|
||||||
|
username: string;
|
||||||
|
password?: string;
|
||||||
|
privateKey?: string;
|
||||||
|
passphrase?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Log levels
|
||||||
|
*/
|
||||||
|
export type LogLevel = "info" | "error" | "debug";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* System status information
|
||||||
|
*/
|
||||||
|
export interface ServerStatus {
|
||||||
|
reachable: boolean;
|
||||||
|
hostname?: string;
|
||||||
|
ipAddresses?: string[];
|
||||||
|
osName?: string;
|
||||||
|
osVersion?: string;
|
||||||
|
kernelVersion?: string;
|
||||||
|
uptime?: string;
|
||||||
|
diskSpace?: {
|
||||||
|
free: string;
|
||||||
|
total: string;
|
||||||
|
};
|
||||||
|
drives?: Array<{
|
||||||
|
device: string;
|
||||||
|
mountPoint: string;
|
||||||
|
total: string;
|
||||||
|
used: string;
|
||||||
|
free: string;
|
||||||
|
usagePercent: string;
|
||||||
|
filesystem?: string;
|
||||||
|
}>;
|
||||||
|
memory?: {
|
||||||
|
free: string;
|
||||||
|
total: string;
|
||||||
|
};
|
||||||
|
cpu?: {
|
||||||
|
name?: string;
|
||||||
|
usage?: string;
|
||||||
|
};
|
||||||
|
gpus?: Array<{
|
||||||
|
name: string;
|
||||||
|
usage?: string;
|
||||||
|
path?: string;
|
||||||
|
}>;
|
||||||
|
processes?: {
|
||||||
|
running: number;
|
||||||
|
threads: number;
|
||||||
|
};
|
||||||
|
services?: {
|
||||||
|
running: number;
|
||||||
|
installed: number;
|
||||||
|
};
|
||||||
|
lastUpdated?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Parsed command line arguments result
|
||||||
|
*/
|
||||||
|
export interface ParsedArgs {
|
||||||
|
configs: SshConnectionConfigMap;
|
||||||
|
preConnect: boolean;
|
||||||
|
}
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,87 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { z } from "zod";
|
||||||
|
import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
|
||||||
|
import { Logger } from "../utils/logger.js";
|
||||||
|
import { toToolError } from "../utils/tool-error.js";
|
||||||
|
import { redactSecrets } from "../utils/redact.js";
|
||||||
|
import { DynamicSSHParams } from "../models/types.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register file download tool
|
||||||
|
*/
|
||||||
|
export function registerDownloadTool(server: McpServer): void {
|
||||||
|
const sshManager = SSHConnectionManager.getInstance();
|
||||||
|
|
||||||
|
server.registerTool(
|
||||||
|
"download",
|
||||||
|
{
|
||||||
|
description:
|
||||||
|
"Download file from connected server. Either specify connectionName for a " +
|
||||||
|
"pre-configured host, or provide host+username to connect on the fly.",
|
||||||
|
inputSchema: {
|
||||||
|
remotePath: z.string().describe("Remote path"),
|
||||||
|
localPath: z.string().describe("Local path"),
|
||||||
|
connectionName: z.string().optional().describe("Pre-configured SSH connection name (optional, default is 'default')"),
|
||||||
|
host: z.string().optional().describe("Dynamic target host (IP or hostname)"),
|
||||||
|
port: z.number().optional().describe("Dynamic target SSH port (default: 22)"),
|
||||||
|
username: z.string().optional().describe("Dynamic target SSH username"),
|
||||||
|
password: z.string().optional().describe("Dynamic target SSH password"),
|
||||||
|
privateKey: z.string().optional().describe("Dynamic target SSH private key file path or PEM contents"),
|
||||||
|
passphrase: z.string().optional().describe("Passphrase for the dynamic target private key"),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
async ({
|
||||||
|
remotePath,
|
||||||
|
localPath,
|
||||||
|
connectionName,
|
||||||
|
host,
|
||||||
|
port,
|
||||||
|
username,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
}) => {
|
||||||
|
const isDynamic = Boolean(host && username);
|
||||||
|
const secrets = [password, passphrase];
|
||||||
|
|
||||||
|
try {
|
||||||
|
let result: string;
|
||||||
|
if (isDynamic) {
|
||||||
|
const params: DynamicSSHParams = {
|
||||||
|
host: host as string,
|
||||||
|
port,
|
||||||
|
username: username as string,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
};
|
||||||
|
result = await sshManager.downloadDynamic(params, remotePath, localPath);
|
||||||
|
} else {
|
||||||
|
result = await sshManager.download(remotePath, localPath, connectionName);
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
content: [{ type: "text", text: result }],
|
||||||
|
};
|
||||||
|
} catch (error: unknown) {
|
||||||
|
const toolError = toToolError(error, "UNKNOWN_ERROR");
|
||||||
|
const safeMessage = redactSecrets(toolError.message, secrets);
|
||||||
|
Logger.handleError(toolError, "Failed to download file", false, secrets);
|
||||||
|
return {
|
||||||
|
content: [{
|
||||||
|
type: "text",
|
||||||
|
text: JSON.stringify(
|
||||||
|
{
|
||||||
|
code: toolError.code,
|
||||||
|
message: safeMessage,
|
||||||
|
retriable: toolError.retriable,
|
||||||
|
},
|
||||||
|
null,
|
||||||
|
2,
|
||||||
|
),
|
||||||
|
}],
|
||||||
|
isError: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -0,0 +1,130 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { z } from "zod";
|
||||||
|
import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
|
||||||
|
import { Logger } from "../utils/logger.js";
|
||||||
|
import { toToolError } from "../utils/tool-error.js";
|
||||||
|
import { redactSecrets } from "../utils/redact.js";
|
||||||
|
import { DynamicSSHParams } from "../models/types.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register execute command tool
|
||||||
|
*/
|
||||||
|
export function registerExecuteCommandTool(server: McpServer): void {
|
||||||
|
const sshManager = SSHConnectionManager.getInstance();
|
||||||
|
|
||||||
|
server.registerTool(
|
||||||
|
"execute-command",
|
||||||
|
{
|
||||||
|
description:
|
||||||
|
"Execute command on connected server and get output result. " +
|
||||||
|
"Either specify connectionName for a pre-configured host, or provide host+username " +
|
||||||
|
"(plus password/privateKey) to connect on the fly.",
|
||||||
|
inputSchema: {
|
||||||
|
cmdString: z.string().describe("Command to execute"),
|
||||||
|
directory: z.string().optional().describe("Working directory for command execution"),
|
||||||
|
connectionName: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe(
|
||||||
|
"Pre-configured SSH connection name (optional, default is 'default'). When provided, the static host is used.",
|
||||||
|
),
|
||||||
|
timeout: z
|
||||||
|
.number()
|
||||||
|
.optional()
|
||||||
|
.describe(
|
||||||
|
"Command execution timeout in milliseconds (optional; defaults to 30000ms)",
|
||||||
|
),
|
||||||
|
host: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe(
|
||||||
|
"Dynamic target host (IP or hostname). When provided, an ephemeral connection is opened for this call only.",
|
||||||
|
),
|
||||||
|
port: z
|
||||||
|
.number()
|
||||||
|
.optional()
|
||||||
|
.describe("Dynamic target SSH port (default: 22)"),
|
||||||
|
username: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe("Dynamic target SSH username"),
|
||||||
|
password: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe("Dynamic target SSH password"),
|
||||||
|
privateKey: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe("Dynamic target SSH private key file path or PEM contents"),
|
||||||
|
passphrase: z
|
||||||
|
.string()
|
||||||
|
.optional()
|
||||||
|
.describe("Passphrase for the dynamic target private key"),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
async ({
|
||||||
|
cmdString,
|
||||||
|
directory,
|
||||||
|
connectionName,
|
||||||
|
timeout,
|
||||||
|
host,
|
||||||
|
port,
|
||||||
|
username,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
}) => {
|
||||||
|
const isDynamic = Boolean(host && username);
|
||||||
|
const secrets = [password, passphrase];
|
||||||
|
|
||||||
|
try {
|
||||||
|
let result: string;
|
||||||
|
if (isDynamic) {
|
||||||
|
const params: DynamicSSHParams = {
|
||||||
|
host: host as string,
|
||||||
|
port,
|
||||||
|
username: username as string,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
};
|
||||||
|
result = await sshManager.executeCommandDynamic(
|
||||||
|
params,
|
||||||
|
cmdString,
|
||||||
|
directory,
|
||||||
|
{ timeout },
|
||||||
|
);
|
||||||
|
} else {
|
||||||
|
result = await sshManager.executeCommand(
|
||||||
|
cmdString,
|
||||||
|
directory,
|
||||||
|
connectionName,
|
||||||
|
{ timeout },
|
||||||
|
);
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
content: [{ type: "text", text: result }],
|
||||||
|
};
|
||||||
|
} catch (error: unknown) {
|
||||||
|
const toolError = toToolError(error, "UNKNOWN_ERROR");
|
||||||
|
const safeMessage = redactSecrets(toolError.message, secrets);
|
||||||
|
Logger.handleError(toolError, "Failed to execute command", false, secrets);
|
||||||
|
return {
|
||||||
|
content: [{
|
||||||
|
type: "text",
|
||||||
|
text: JSON.stringify(
|
||||||
|
{
|
||||||
|
code: toolError.code,
|
||||||
|
message: safeMessage,
|
||||||
|
retriable: toolError.retriable,
|
||||||
|
},
|
||||||
|
null,
|
||||||
|
2,
|
||||||
|
),
|
||||||
|
}],
|
||||||
|
isError: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
},
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -0,0 +1,16 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { registerExecuteCommandTool } from "./execute-command.js";
|
||||||
|
import { registerUploadTool } from "./upload.js";
|
||||||
|
import { registerDownloadTool } from "./download.js";
|
||||||
|
import { registerListServersTool } from "./list-servers.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register all tools
|
||||||
|
* @param server MCP server instance
|
||||||
|
*/
|
||||||
|
export function registerAllTools(server: McpServer): void {
|
||||||
|
registerExecuteCommandTool(server);
|
||||||
|
registerUploadTool(server);
|
||||||
|
registerDownloadTool(server);
|
||||||
|
registerListServersTool(server);
|
||||||
|
}
|
||||||
@@ -0,0 +1,65 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
|
||||||
|
|
||||||
|
type ServerInfo = ReturnType<SSHConnectionManager["getAllServerInfos"]>[number];
|
||||||
|
|
||||||
|
export function formatServerList(servers: ServerInfo[]): string {
|
||||||
|
if (servers.length === 0) {
|
||||||
|
return "No SSH servers configured.";
|
||||||
|
}
|
||||||
|
|
||||||
|
const summary = servers.map((server) => {
|
||||||
|
const parts = [
|
||||||
|
`[${server.connected ? "connected" : "disconnected"}] ${server.name}`,
|
||||||
|
`${server.username}@${server.host}:${server.port}`,
|
||||||
|
];
|
||||||
|
|
||||||
|
if (server.status?.hostname) {
|
||||||
|
parts.push(`hostname=${server.status.hostname}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (server.status?.osName) {
|
||||||
|
parts.push(`os=${server.status.osName}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
if (server.status?.lastUpdated) {
|
||||||
|
parts.push(`updated=${server.status.lastUpdated}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
return parts.join(" | ");
|
||||||
|
});
|
||||||
|
|
||||||
|
return [
|
||||||
|
"Configured SSH servers:",
|
||||||
|
...summary,
|
||||||
|
"",
|
||||||
|
"Raw JSON:",
|
||||||
|
// Not indented: the pretty printed form is roughly 40% larger for the same
|
||||||
|
// data, and this output is fed to a model rather than read as a document.
|
||||||
|
JSON.stringify(servers),
|
||||||
|
].join("\n");
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register list-servers tool
|
||||||
|
*/
|
||||||
|
export function registerListServersTool(server: McpServer): void {
|
||||||
|
server.registerTool(
|
||||||
|
"list-servers",
|
||||||
|
{
|
||||||
|
description: "List all available SSH server configurations",
|
||||||
|
},
|
||||||
|
async () => {
|
||||||
|
const sshManager = SSHConnectionManager.getInstance();
|
||||||
|
const servers = sshManager.getAllServerInfos();
|
||||||
|
return {
|
||||||
|
content: [
|
||||||
|
{
|
||||||
|
type: "text",
|
||||||
|
text: formatServerList(servers),
|
||||||
|
},
|
||||||
|
],
|
||||||
|
};
|
||||||
|
},
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -0,0 +1,87 @@
|
|||||||
|
import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
|
||||||
|
import { z } from "zod";
|
||||||
|
import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
|
||||||
|
import { Logger } from "../utils/logger.js";
|
||||||
|
import { toToolError } from "../utils/tool-error.js";
|
||||||
|
import { redactSecrets } from "../utils/redact.js";
|
||||||
|
import { DynamicSSHParams } from "../models/types.js";
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Register file upload tool
|
||||||
|
*/
|
||||||
|
export function registerUploadTool(server: McpServer): void {
|
||||||
|
const sshManager = SSHConnectionManager.getInstance();
|
||||||
|
|
||||||
|
server.registerTool(
|
||||||
|
"upload",
|
||||||
|
{
|
||||||
|
description:
|
||||||
|
"Upload file to connected server. Either specify connectionName for a " +
|
||||||
|
"pre-configured host, or provide host+username to connect on the fly.",
|
||||||
|
inputSchema: {
|
||||||
|
localPath: z.string().describe("Local path"),
|
||||||
|
remotePath: z.string().describe("Remote path"),
|
||||||
|
connectionName: z.string().optional().describe("Pre-configured SSH connection name (optional, default is 'default')"),
|
||||||
|
host: z.string().optional().describe("Dynamic target host (IP or hostname)"),
|
||||||
|
port: z.number().optional().describe("Dynamic target SSH port (default: 22)"),
|
||||||
|
username: z.string().optional().describe("Dynamic target SSH username"),
|
||||||
|
password: z.string().optional().describe("Dynamic target SSH password"),
|
||||||
|
privateKey: z.string().optional().describe("Dynamic target SSH private key file path or PEM contents"),
|
||||||
|
passphrase: z.string().optional().describe("Passphrase for the dynamic target private key"),
|
||||||
|
},
|
||||||
|
},
|
||||||
|
async ({
|
||||||
|
localPath,
|
||||||
|
remotePath,
|
||||||
|
connectionName,
|
||||||
|
host,
|
||||||
|
port,
|
||||||
|
username,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
}) => {
|
||||||
|
const isDynamic = Boolean(host && username);
|
||||||
|
const secrets = [password, passphrase];
|
||||||
|
|
||||||
|
try {
|
||||||
|
let result: string;
|
||||||
|
if (isDynamic) {
|
||||||
|
const params: DynamicSSHParams = {
|
||||||
|
host: host as string,
|
||||||
|
port,
|
||||||
|
username: username as string,
|
||||||
|
password,
|
||||||
|
privateKey,
|
||||||
|
passphrase,
|
||||||
|
};
|
||||||
|
result = await sshManager.uploadDynamic(params, localPath, remotePath);
|
||||||
|
} else {
|
||||||
|
result = await sshManager.upload(localPath, remotePath, connectionName);
|
||||||
|
}
|
||||||
|
return {
|
||||||
|
content: [{ type: "text", text: result }],
|
||||||
|
};
|
||||||
|
} catch (error: unknown) {
|
||||||
|
const toolError = toToolError(error, "UNKNOWN_ERROR");
|
||||||
|
const safeMessage = redactSecrets(toolError.message, secrets);
|
||||||
|
Logger.handleError(toolError, "Failed to upload file", false, secrets);
|
||||||
|
return {
|
||||||
|
content: [{
|
||||||
|
type: "text",
|
||||||
|
text: JSON.stringify(
|
||||||
|
{
|
||||||
|
code: toolError.code,
|
||||||
|
message: safeMessage,
|
||||||
|
retriable: toolError.retriable,
|
||||||
|
},
|
||||||
|
null,
|
||||||
|
2,
|
||||||
|
),
|
||||||
|
}],
|
||||||
|
isError: true,
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
);
|
||||||
|
}
|
||||||
@@ -0,0 +1,47 @@
|
|||||||
|
import { LogLevel } from '../models/types.js';
|
||||||
|
import { redactSecrets } from './redact.js';
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Logger class
|
||||||
|
*/
|
||||||
|
export class Logger {
|
||||||
|
/**
|
||||||
|
* Log a message
|
||||||
|
* Note: All logging goes to stderr to avoid interfering with MCP stdio protocol (which uses stdout)
|
||||||
|
* @param secrets Optional list of secrets to redact from the message before writing.
|
||||||
|
*/
|
||||||
|
public static log(
|
||||||
|
message: string,
|
||||||
|
level: LogLevel = "info",
|
||||||
|
secrets: Array<string | undefined | null> = [],
|
||||||
|
): void {
|
||||||
|
const safeMessage = secrets.length > 0 ? redactSecrets(message, secrets) : message;
|
||||||
|
const timestamp = new Date().toISOString();
|
||||||
|
const formattedMessage = `[${timestamp}] [${level.toUpperCase()}] ${safeMessage}`;
|
||||||
|
|
||||||
|
// Always write to stderr to avoid corrupting MCP protocol messages on stdout
|
||||||
|
process.stderr.write(formattedMessage + '\n');
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Handle error
|
||||||
|
* @param secrets Optional list of secrets to redact before logging and returning.
|
||||||
|
*/
|
||||||
|
public static handleError(
|
||||||
|
error: unknown,
|
||||||
|
prefix: string = "",
|
||||||
|
exit: boolean = false,
|
||||||
|
secrets: Array<string | undefined | null> = [],
|
||||||
|
): string {
|
||||||
|
const errorMessage = error instanceof Error ? error.message : String(error);
|
||||||
|
const fullMessage = prefix ? `${prefix}: ${errorMessage}` : errorMessage;
|
||||||
|
|
||||||
|
Logger.log(fullMessage, "error", secrets);
|
||||||
|
|
||||||
|
if (exit) {
|
||||||
|
process.exit(1);
|
||||||
|
}
|
||||||
|
|
||||||
|
return redactSecrets(fullMessage, secrets);
|
||||||
|
}
|
||||||
|
}
|
||||||
@@ -0,0 +1,60 @@
|
|||||||
|
/**
|
||||||
|
* Secret redaction utilities.
|
||||||
|
*
|
||||||
|
* The dynamic-connection mode accepts credentials (password / private key /
|
||||||
|
* passphrase) directly in each tool call. Those values must never leak into
|
||||||
|
* logs or error messages returned to the model. Use `redactSecret()` anywhere
|
||||||
|
* a potentially sensitive string is logged or turned into an error message.
|
||||||
|
*
|
||||||
|
* Redaction is deliberately strict about short values: a 1-3 character secret
|
||||||
|
* is a substring of too much normal text to mask reliably, so it is only
|
||||||
|
* replaced when it appears as a whole word on its own token. Longer secrets
|
||||||
|
* are replaced anywhere.
|
||||||
|
*/
|
||||||
|
|
||||||
|
const MIN_WHOLE_TOKEN_SECRET_LENGTH = 4;
|
||||||
|
const REDACTED = "[REDACTED]";
|
||||||
|
|
||||||
|
function escapeRegExp(value: string): string {
|
||||||
|
return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Replace every occurrence of `secret` in `text` with `[REDACTED]`.
|
||||||
|
*
|
||||||
|
* - Empty strings and strings shorter than 2 characters are ignored.
|
||||||
|
* - Secrets of 2-3 characters are only masked when they stand alone as a whole
|
||||||
|
* token, to avoid destroying common short words that coincidentally match.
|
||||||
|
* - Longer secrets are masked everywhere (including inside larger words).
|
||||||
|
*/
|
||||||
|
export function redactSecret(text: string, secret: string | undefined | null): string {
|
||||||
|
if (!text || !secret) {
|
||||||
|
return text;
|
||||||
|
}
|
||||||
|
|
||||||
|
const trimmed = secret.trim();
|
||||||
|
if (trimmed.length < 2) {
|
||||||
|
return text;
|
||||||
|
}
|
||||||
|
|
||||||
|
const escaped = escapeRegExp(trimmed);
|
||||||
|
if (trimmed.length < MIN_WHOLE_TOKEN_SECRET_LENGTH) {
|
||||||
|
return text.replace(
|
||||||
|
new RegExp(`(^|[^A-Za-z0-9])${escaped}([^A-Za-z0-9]|$)`, "g"),
|
||||||
|
`$1${REDACTED}$2`,
|
||||||
|
);
|
||||||
|
}
|
||||||
|
|
||||||
|
return text.split(escaped).join(REDACTED);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Redact many secrets at once.
|
||||||
|
*/
|
||||||
|
export function redactSecrets(text: string, secrets: Array<string | undefined | null>): string {
|
||||||
|
let result = text;
|
||||||
|
for (const secret of secrets) {
|
||||||
|
result = redactSecret(result, secret);
|
||||||
|
}
|
||||||
|
return result;
|
||||||
|
}
|
||||||
@@ -0,0 +1,236 @@
|
|||||||
|
import * as fs from 'fs';
|
||||||
|
import * as path from 'path';
|
||||||
|
import * as os from 'os';
|
||||||
|
|
||||||
|
interface SshConfigEntry {
|
||||||
|
hostName?: string;
|
||||||
|
user?: string;
|
||||||
|
port?: number;
|
||||||
|
identityFile?: string;
|
||||||
|
}
|
||||||
|
|
||||||
|
interface HostBlock {
|
||||||
|
patterns: string[];
|
||||||
|
config: Map<string, string>;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 查找 SSH 配置文件中指定主机别名的配置
|
||||||
|
* @param hostAlias 主机别名
|
||||||
|
* @param configFilePath 配置文件路径，默认为 ~/.ssh/config
|
||||||
|
* @returns 解析后的配置项，未找到返回 null
|
||||||
|
*/
|
||||||
|
export function lookupSshConfig(
|
||||||
|
hostAlias: string,
|
||||||
|
configFilePath?: string
|
||||||
|
): SshConfigEntry | null {
|
||||||
|
const configPath = configFilePath || path.join(os.homedir(), '.ssh', 'config');
|
||||||
|
|
||||||
|
// 默认路径不存在时静默返回 null
|
||||||
|
if (!configFilePath && !fs.existsSync(configPath)) {
|
||||||
|
return null;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 显式指定路径不存在时抛错
|
||||||
|
if (configFilePath && !fs.existsSync(configPath)) {
|
||||||
|
throw new Error(`SSH config file not found: ${configPath}`);
|
||||||
|
}
|
||||||
|
|
||||||
|
const blocks = parseConfigFile(configPath, new Set());
|
||||||
|
return matchHost(hostAlias, blocks);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 解析 SSH 配置文件
|
||||||
|
*/
|
||||||
|
function parseConfigFile(filePath: string, visited: Set<string>): HostBlock[] {
|
||||||
|
// 防止循环引用
|
||||||
|
const realPath = fs.realpathSync(filePath);
|
||||||
|
if (visited.has(realPath)) {
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
visited.add(realPath);
|
||||||
|
|
||||||
|
const content = fs.readFileSync(filePath, 'utf-8');
|
||||||
|
const lines = content.split('\n');
|
||||||
|
const blocks: HostBlock[] = [];
|
||||||
|
let currentBlock: HostBlock | null = null;
|
||||||
|
|
||||||
|
for (let line of lines) {
|
||||||
|
// 移除注释和前后空白
|
||||||
|
const commentIndex = line.indexOf('#');
|
||||||
|
if (commentIndex !== -1) {
|
||||||
|
line = line.substring(0, commentIndex);
|
||||||
|
}
|
||||||
|
line = line.trim();
|
||||||
|
|
||||||
|
if (!line) continue;
|
||||||
|
|
||||||
|
// 解析 Include 指令
|
||||||
|
if (line.toLowerCase().startsWith('include ')) {
|
||||||
|
if (currentBlock) {
|
||||||
|
blocks.push(currentBlock);
|
||||||
|
currentBlock = null;
|
||||||
|
}
|
||||||
|
const pattern = line.substring(8).trim();
|
||||||
|
const includePaths = expandIncludePath(pattern, path.dirname(filePath));
|
||||||
|
for (const includePath of includePaths) {
|
||||||
|
if (fs.existsSync(includePath)) {
|
||||||
|
blocks.push(...parseConfigFile(includePath, visited));
|
||||||
|
}
|
||||||
|
}
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 解析 Host 行
|
||||||
|
if (line.toLowerCase().startsWith('host ')) {
|
||||||
|
if (currentBlock) {
|
||||||
|
blocks.push(currentBlock);
|
||||||
|
}
|
||||||
|
const hostPatterns = line.substring(5).trim().split(/\s+/);
|
||||||
|
currentBlock = {
|
||||||
|
patterns: hostPatterns,
|
||||||
|
config: new Map()
|
||||||
|
};
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
// 解析配置项
|
||||||
|
if (!currentBlock) {
|
||||||
|
currentBlock = {
|
||||||
|
patterns: ['*'],
|
||||||
|
config: new Map()
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
const spaceIndex = line.search(/\s/);
|
||||||
|
if (spaceIndex !== -1) {
|
||||||
|
const key = line.substring(0, spaceIndex).toLowerCase();
|
||||||
|
const value = line.substring(spaceIndex + 1).trim();
|
||||||
|
|
||||||
|
// 只保存第一次出现的值（SSH first-match-wins）
|
||||||
|
if (!currentBlock.config.has(key)) {
|
||||||
|
currentBlock.config.set(key, value);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (currentBlock) {
|
||||||
|
blocks.push(currentBlock);
|
||||||
|
}
|
||||||
|
|
||||||
|
return blocks;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 展开 Include 路径（支持 ~ 和通配符）
|
||||||
|
*/
|
||||||
|
function expandIncludePath(pattern: string, baseDir: string): string[] {
|
||||||
|
// 展开 ~
|
||||||
|
if (pattern.startsWith('~/')) {
|
||||||
|
pattern = path.join(os.homedir(), pattern.substring(2));
|
||||||
|
} else if (pattern.startsWith('~')) {
|
||||||
|
// ~user 形式不支持，直接返回空
|
||||||
|
return [];
|
||||||
|
} else if (!path.isAbsolute(pattern)) {
|
||||||
|
// 相对路径相对于配置文件所在目录
|
||||||
|
pattern = path.join(baseDir, pattern);
|
||||||
|
}
|
||||||
|
|
||||||
|
// 使用 glob 展开通配符
|
||||||
|
try {
|
||||||
|
// Node.js 22+ 支持 fs.globSync
|
||||||
|
if (typeof fs.globSync === 'function') {
|
||||||
|
return fs.globSync(pattern);
|
||||||
|
}
|
||||||
|
} catch (e) {
|
||||||
|
// glob 失败时静默跳过
|
||||||
|
}
|
||||||
|
|
||||||
|
// 降级：无通配符时直接返回
|
||||||
|
if (!pattern.includes('*') && !pattern.includes('?')) {
|
||||||
|
return [pattern];
|
||||||
|
}
|
||||||
|
|
||||||
|
return [];
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 匹配主机别名
|
||||||
|
*/
|
||||||
|
function matchHost(hostAlias: string, blocks: HostBlock[]): SshConfigEntry | null {
|
||||||
|
const result: SshConfigEntry = {};
|
||||||
|
|
||||||
|
for (const block of blocks) {
|
||||||
|
const matched = hostBlockMatches(hostAlias, block.patterns);
|
||||||
|
|
||||||
|
if (!matched) continue;
|
||||||
|
|
||||||
|
// first-match-wins：只取第一个匹配到的值
|
||||||
|
if (!result.hostName && block.config.has('hostname')) {
|
||||||
|
result.hostName = block.config.get('hostname');
|
||||||
|
}
|
||||||
|
if (!result.user && block.config.has('user')) {
|
||||||
|
result.user = block.config.get('user');
|
||||||
|
}
|
||||||
|
if (!result.port && block.config.has('port')) {
|
||||||
|
const portStr = block.config.get('port');
|
||||||
|
const portNum = parseInt(portStr!, 10);
|
||||||
|
if (!isNaN(portNum)) {
|
||||||
|
result.port = portNum;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
if (!result.identityFile && block.config.has('identityfile')) {
|
||||||
|
result.identityFile = expandTilde(block.config.get('identityfile')!);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return Object.keys(result).length > 0 ? result : null;
|
||||||
|
}
|
||||||
|
|
||||||
|
function hostBlockMatches(hostAlias: string, patterns: string[]): boolean {
|
||||||
|
let positiveMatch = false;
|
||||||
|
|
||||||
|
for (const pattern of patterns) {
|
||||||
|
const isNegated = pattern.startsWith('!');
|
||||||
|
const patternBody = isNegated ? pattern.slice(1) : pattern;
|
||||||
|
if (!patternBody) {
|
||||||
|
continue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (hostPatternMatches(hostAlias, patternBody)) {
|
||||||
|
if (isNegated) {
|
||||||
|
return false;
|
||||||
|
}
|
||||||
|
positiveMatch = true;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
return positiveMatch;
|
||||||
|
}
|
||||||
|
|
||||||
|
function hostPatternMatches(hostAlias: string, pattern: string): boolean {
|
||||||
|
if (pattern === '*') {
|
||||||
|
return true;
|
||||||
|
}
|
||||||
|
|
||||||
|
const regexSource = pattern
|
||||||
|
.replace(/[.+^${}()|[\]\\]/g, '\\$&')
|
||||||
|
.replace(/\*/g, '.*')
|
||||||
|
.replace(/\?/g, '.');
|
||||||
|
|
||||||
|
return new RegExp(`^${regexSource}$`).test(hostAlias);
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* 展开路径中的 ~
|
||||||
|
*/
|
||||||
|
function expandTilde(filePath: string): string {
|
||||||
|
if (filePath.startsWith('~/')) {
|
||||||
|
return path.join(os.homedir(), filePath.substring(2));
|
||||||
|
}
|
||||||
|
if (filePath === '~') {
|
||||||
|
return os.homedir();
|
||||||
|
}
|
||||||
|
return filePath;
|
||||||
|
}
|
||||||
@@ -0,0 +1,304 @@
|
|||||||
|
import { ServerStatus } from "../models/types.js";
|
||||||
|
import { Logger } from "./logger.js";
|
||||||
|
|
||||||
|
type StatusCommandRunner = (
|
||||||
|
command: string,
|
||||||
|
connectionName: string,
|
||||||
|
) => Promise<string>;
|
||||||
|
|
||||||
|
type StatusCommandAuthorizer = (
|
||||||
|
command: string,
|
||||||
|
connectionName: string,
|
||||||
|
) => boolean;
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Join the probes into a single remote command, each result introduced by a
|
||||||
|
* marker line.
|
||||||
|
*
|
||||||
|
* Running them separately costs one SSH channel per probe — open, pty request,
|
||||||
|
* exec and close, several round trips each — plus a remote shell per probe. In
|
||||||
|
* shell transport it is worse still: the per-connection queue serialises them,
|
||||||
|
* so the first command the user issues after connecting waits behind all of
|
||||||
|
* them.
|
||||||
|
*
|
||||||
|
* Every probe is wrapped so that a missing tool or a non-zero exit cannot
|
||||||
|
* abort the rest, and the whole script ends successfully.
|
||||||
|
*/
|
||||||
|
function buildStatusScript(
|
||||||
|
commands: Record<string, string>,
|
||||||
|
marker: string,
|
||||||
|
): string {
|
||||||
|
const probes = Object.entries(commands).map(
|
||||||
|
([field, command]) =>
|
||||||
|
`printf '\\n${marker}${field}\\n'; { ${command}; } 2>/dev/null`,
|
||||||
|
);
|
||||||
|
return `${probes.join("; ")}; true`;
|
||||||
|
}
|
||||||
|
|
||||||
|
function parseStatusScriptOutput(
|
||||||
|
output: string,
|
||||||
|
marker: string,
|
||||||
|
): Map<string, string> {
|
||||||
|
const values = new Map<string, string>();
|
||||||
|
const normalized = output.replace(/\r\n/g, "\n").replace(/\r/g, "\n");
|
||||||
|
// Splitting on a capturing group yields [before, field, value, field, ...].
|
||||||
|
const segments = normalized.split(new RegExp(`\\n?${marker}(\\w+)\\n`));
|
||||||
|
|
||||||
|
for (let index = 1; index < segments.length; index += 2) {
|
||||||
|
values.set(segments[index], (segments[index + 1] ?? "").trim());
|
||||||
|
}
|
||||||
|
|
||||||
|
return values;
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Collect system status information from remote server
|
||||||
|
*/
|
||||||
|
export async function collectSystemStatus(
|
||||||
|
runCommand: StatusCommandRunner,
|
||||||
|
connectionName: string,
|
||||||
|
isCommandAllowed: StatusCommandAuthorizer = () => true,
|
||||||
|
): Promise<ServerStatus> {
|
||||||
|
const status: ServerStatus = {
|
||||||
|
reachable: true,
|
||||||
|
lastUpdated: new Date().toISOString(),
|
||||||
|
};
|
||||||
|
|
||||||
|
try {
|
||||||
|
// Collected in a single remote command; see buildStatusScript.
|
||||||
|
const commands = {
|
||||||
|
hostname: "hostname",
|
||||||
|
ipAddresses: "ip -o addr show | awk '{print $4}' | grep -v '^127\\.' | cut -d'/' -f1",
|
||||||
|
osName: "uname -s",
|
||||||
|
osVersion: "cat /etc/os-release 2>/dev/null | grep '^PRETTY_NAME=' | cut -d'=' -f2 | tr -d '\"' || uname -o",
|
||||||
|
kernelVersion: "uname -r",
|
||||||
|
uptime: "uptime -p 2>/dev/null || uptime | awk -F'up ' '{print $2}' | awk -F',' '{print $1}'",
|
||||||
|
diskSpace: "df -h / | tail -1 | awk '{print \"free:\" $4 \" total:\" $2}'",
|
||||||
|
memory: "free -h | grep '^Mem:' | awk '{print \"free:\" $7 \" total:\" $2}'",
|
||||||
|
cpuName: "sh -c '(lscpu 2>/dev/null | grep \"^Model name:\" | cut -d\":\" -f2 | xargs || cat /proc/cpuinfo 2>/dev/null | grep \"model name\" | head -1 | cut -d\":\" -f2 | xargs || echo \"$(nproc 2>/dev/null || echo '\''?'\'')-core $(uname -m 2>/dev/null || echo '\''unknown'\'') processor\") || true'",
|
||||||
|
cpuUsage: "top -bn1 | grep 'Cpu(s)' | sed 's/.*, *\\([0-9.]*\\)%* id.*/\\1/' | awk '{print 100 - $1}'",
|
||||||
|
gpus: "sh -c '(nvidia-smi --query-gpu=name,utilization.gpu --format=csv,noheader,nounits 2>/dev/null | while IFS=\",\" read -r name usage; do echo \"NVIDIA|${name}|${usage}\"; done || lspci | grep -iE \"vga|3d|display\" | while read -r line; do gpu_name=$(echo \"$line\" | cut -d\":\" -f3 | xargs); echo \"OTHER|${gpu_name}|\"; done) || true'",
|
||||||
|
gpuPaths: "ls -1 /dev/dri/card* 2>/dev/null | sort -V || echo ''",
|
||||||
|
drives: "df -h | awk 'NR>1 && $1 !~ /^(tmpfs|devtmpfs|overlay|shfs|rootfs)$/ && $6 !~ /^(\\/dev|\\/run|\\/sys|\\/proc|\\/boot|\\/usr|\\/lib)$/ && $6 != \"\" {print $1\"|\"$2\"|\"$3\"|\"$4\"|\"$5\"|\"$6}'",
|
||||||
|
// Old gpuPaths: "sh -c '(nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader,nounits 2>/dev/null | head -1 || rocm-smi --showuse 2>/dev/null | grep -i \"GPU use\" | head -1 | awk \"{print \\$NF}\" | tr -d \"%\" || radeontop -l 1 -d - 2>/dev/null | tail -1 | sed -n \"s/.*gpu \\([0-9.]*\\)%.*/\\1/p\" || intel_gpu_top -l 1 -o - 2>/dev/null | tail -1 | awk \"{print \\$NF}\" | tr -d \"%\" || echo \"N/A\") || echo \"N/A\"'",
|
||||||
|
processes: "ps aux | wc -l",
|
||||||
|
threads: "ps -eLf | wc -l",
|
||||||
|
servicesRunning: "systemctl list-units --type=service --state=running 2>/dev/null | wc -l || service --status-all 2>/dev/null | grep running | wc -l || echo '0'",
|
||||||
|
servicesInstalled: "systemctl list-unit-files --type=service 2>/dev/null | wc -l || ls /etc/init.d/ 2>/dev/null | wc -l || echo '0'",
|
||||||
|
};
|
||||||
|
|
||||||
|
// Validate each probe before batching. Validating only the combined script
|
||||||
|
// would allow one whitelist match to authorize every command in it.
|
||||||
|
const allowedCommands = Object.fromEntries(
|
||||||
|
Object.entries(commands).filter(([, command]) =>
|
||||||
|
isCommandAllowed(command, connectionName),
|
||||||
|
),
|
||||||
|
);
|
||||||
|
|
||||||
|
// Execute the allowed probes and collect results.
|
||||||
|
const marker = `__MCP_FIELD_${Math.random().toString(16).slice(2, 10)}_`;
|
||||||
|
let values = new Map<string, string>();
|
||||||
|
try {
|
||||||
|
if (Object.keys(allowedCommands).length === 0) {
|
||||||
|
return status;
|
||||||
|
}
|
||||||
|
values = parseStatusScriptOutput(
|
||||||
|
await runCommand(
|
||||||
|
buildStatusScript(allowedCommands, marker),
|
||||||
|
connectionName,
|
||||||
|
),
|
||||||
|
marker,
|
||||||
|
);
|
||||||
|
} catch {
|
||||||
|
// A rejected command (an unreachable host, a command whitelist that does
|
||||||
|
// not admit the probe) leaves every field unset, the same as when the
|
||||||
|
// probes ran separately and each failed on its own.
|
||||||
|
}
|
||||||
|
|
||||||
|
// Parse results
|
||||||
|
const readField = (field: keyof typeof commands): string =>
|
||||||
|
values.get(field) ?? "";
|
||||||
|
|
||||||
|
const hostnameValue = readField("hostname");
|
||||||
|
const ipAddressesValue = readField("ipAddresses");
|
||||||
|
const osNameValue = readField("osName");
|
||||||
|
const osVersionValue = readField("osVersion");
|
||||||
|
const kernelVersionValue = readField("kernelVersion");
|
||||||
|
const uptimeValue = readField("uptime");
|
||||||
|
const diskSpaceValue = readField("diskSpace");
|
||||||
|
const memoryValue = readField("memory");
|
||||||
|
const cpuNameValue = readField("cpuName");
|
||||||
|
const cpuUsageValue = readField("cpuUsage");
|
||||||
|
const gpusValue = readField("gpus");
|
||||||
|
const gpuPathsValue = readField("gpuPaths");
|
||||||
|
const drivesValue = readField("drives");
|
||||||
|
const processesValue = readField("processes");
|
||||||
|
const threadsValue = readField("threads");
|
||||||
|
const servicesRunningValue = readField("servicesRunning");
|
||||||
|
const servicesInstalledValue = readField("servicesInstalled");
|
||||||
|
|
||||||
|
if (hostnameValue) {
|
||||||
|
status.hostname = hostnameValue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (ipAddressesValue) {
|
||||||
|
status.ipAddresses = ipAddressesValue
|
||||||
|
.split("\n")
|
||||||
|
.filter((ip) => ip.trim() && !ip.includes("127.0.0.1"));
|
||||||
|
}
|
||||||
|
|
||||||
|
if (osNameValue) {
|
||||||
|
status.osName = osNameValue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (osVersionValue) {
|
||||||
|
status.osVersion = osVersionValue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (kernelVersionValue) {
|
||||||
|
status.kernelVersion = kernelVersionValue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (uptimeValue) {
|
||||||
|
status.uptime = uptimeValue;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (diskSpaceValue) {
|
||||||
|
const diskMatch = diskSpaceValue.match(/free:(\S+)\s+total:(\S+)/);
|
||||||
|
if (diskMatch) {
|
||||||
|
status.diskSpace = {
|
||||||
|
free: diskMatch[1],
|
||||||
|
total: diskMatch[2],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (memoryValue) {
|
||||||
|
const memMatch = memoryValue.match(/free:(\S+)\s+total:(\S+)/);
|
||||||
|
if (memMatch) {
|
||||||
|
status.memory = {
|
||||||
|
free: memMatch[1],
|
||||||
|
total: memMatch[2],
|
||||||
|
};
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Handle CPU name
|
||||||
|
if (cpuNameValue && cpuNameValue.trim()) {
|
||||||
|
status.cpu = {
|
||||||
|
name: cpuNameValue.trim(),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
if (status.cpu && cpuUsageValue && cpuUsageValue !== "N/A") {
|
||||||
|
status.cpu.usage = `${parseFloat(cpuUsageValue).toFixed(1)}%`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Handle GPUs
|
||||||
|
if (gpusValue && gpusValue.trim()) {
|
||||||
|
const gpuPaths: string[] = [];
|
||||||
|
if (gpuPathsValue) {
|
||||||
|
gpuPaths.push(...gpuPathsValue.split("\n").filter((p) => p.trim()));
|
||||||
|
}
|
||||||
|
|
||||||
|
const gpuLines = gpusValue.split("\n").filter((line) => line.trim());
|
||||||
|
const gpus: Array<{ name: string; usage?: string; path?: string }> = [];
|
||||||
|
|
||||||
|
gpuLines.forEach((line, index) => {
|
||||||
|
const parts = line.split("|");
|
||||||
|
if (parts.length >= 2) {
|
||||||
|
const name = parts[1].trim();
|
||||||
|
const usage = parts[2]?.trim();
|
||||||
|
|
||||||
|
if (name && name !== "N/A") {
|
||||||
|
const gpu: { name: string; usage?: string; path?: string } = {
|
||||||
|
name: name,
|
||||||
|
};
|
||||||
|
|
||||||
|
if (usage && usage.trim() !== "" && usage.trim() !== "N/A" && !isNaN(parseFloat(usage.trim()))) {
|
||||||
|
gpu.usage = `${parseFloat(usage.trim()).toFixed(1)}%`;
|
||||||
|
}
|
||||||
|
|
||||||
|
// Assign path if available
|
||||||
|
if (gpuPaths[index]) {
|
||||||
|
gpu.path = gpuPaths[index];
|
||||||
|
}
|
||||||
|
|
||||||
|
gpus.push(gpu);
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
if (gpus.length > 0) {
|
||||||
|
status.gpus = gpus;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
// Handle drives
|
||||||
|
if (drivesValue && drivesValue.trim()) {
|
||||||
|
const driveLines = drivesValue.split("\n").filter((line) => line.trim());
|
||||||
|
const drives: Array<{
|
||||||
|
device: string;
|
||||||
|
mountPoint: string;
|
||||||
|
total: string;
|
||||||
|
used: string;
|
||||||
|
free: string;
|
||||||
|
usagePercent: string;
|
||||||
|
filesystem?: string;
|
||||||
|
}> = [];
|
||||||
|
|
||||||
|
driveLines.forEach((line) => {
|
||||||
|
const parts = line.split("|");
|
||||||
|
if (parts.length >= 6) {
|
||||||
|
const device = parts[0].trim();
|
||||||
|
const total = parts[1].trim();
|
||||||
|
const used = parts[2].trim();
|
||||||
|
const free = parts[3].trim();
|
||||||
|
const usagePercent = parts[4].trim();
|
||||||
|
const mountPoint = parts[5].trim();
|
||||||
|
|
||||||
|
if (device && mountPoint) {
|
||||||
|
drives.push({
|
||||||
|
device,
|
||||||
|
mountPoint,
|
||||||
|
total,
|
||||||
|
used,
|
||||||
|
free,
|
||||||
|
usagePercent,
|
||||||
|
});
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
if (drives.length > 0) {
|
||||||
|
status.drives = drives;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
if (processesValue || threadsValue) {
|
||||||
|
const processCount = parseInt(processesValue || "0", 10) - 1; // Subtract header line
|
||||||
|
const threadCount = parseInt(threadsValue || "0", 10) - 1; // Subtract header line
|
||||||
|
status.processes = {
|
||||||
|
running: Math.max(0, processCount),
|
||||||
|
threads: Math.max(0, threadCount),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
if (servicesRunningValue || servicesInstalledValue) {
|
||||||
|
const runningCount = parseInt(servicesRunningValue || "0", 10) - 1; // Subtract header line
|
||||||
|
const installedCount = parseInt(servicesInstalledValue || "0", 10) - 1; // Subtract header line
|
||||||
|
status.services = {
|
||||||
|
running: Math.max(0, runningCount),
|
||||||
|
installed: Math.max(0, installedCount),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
} catch (error) {
|
||||||
|
Logger.log(
|
||||||
|
`Failed to collect system status for [${connectionName}]: ${(error as Error).message}`,
|
||||||
|
"error"
|
||||||
|
);
|
||||||
|
status.reachable = false;
|
||||||
|
}
|
||||||
|
|
||||||
|
return status;
|
||||||
|
}
|
||||||
@@ -0,0 +1,43 @@
|
|||||||
|
export type ToolErrorCode =
|
||||||
|
| "COMMAND_VALIDATION_FAILED"
|
||||||
|
| "COMMAND_EXECUTION_ERROR"
|
||||||
|
| "OUTPUT_LIMIT_EXCEEDED"
|
||||||
|
| "COMMAND_TIMEOUT"
|
||||||
|
| "SSH_CONNECTION_FAILED"
|
||||||
|
| "SSH_CONNECTION_TIMEOUT"
|
||||||
|
| "SSH_AUTHENTICATION_MISSING"
|
||||||
|
| "SSH_CONFIG_MISSING"
|
||||||
|
| "LOCAL_PATH_NOT_ALLOWED"
|
||||||
|
| "REMOTE_PATH_NOT_ALLOWED"
|
||||||
|
| "LOCAL_FILE_READ_FAILED"
|
||||||
|
| "LOCAL_FILE_WRITE_FAILED"
|
||||||
|
| "OPERATION_TIMEOUT"
|
||||||
|
| "SFTP_ERROR"
|
||||||
|
| "UNSUPPORTED_IN_SHELL_MODE"
|
||||||
|
| "UNKNOWN_ERROR";
|
||||||
|
|
||||||
|
export class ToolError extends Error {
|
||||||
|
constructor(
|
||||||
|
public readonly code: ToolErrorCode,
|
||||||
|
message: string,
|
||||||
|
public readonly retriable: boolean = false,
|
||||||
|
) {
|
||||||
|
super(message);
|
||||||
|
this.name = "ToolError";
|
||||||
|
}
|
||||||
|
}
|
||||||
|
|
||||||
|
export function toToolError(
|
||||||
|
error: unknown,
|
||||||
|
fallbackCode: ToolErrorCode,
|
||||||
|
): ToolError {
|
||||||
|
if (error instanceof ToolError) {
|
||||||
|
return error;
|
||||||
|
}
|
||||||
|
|
||||||
|
if (error instanceof Error) {
|
||||||
|
return new ToolError(fallbackCode, error.message, false);
|
||||||
|
}
|
||||||
|
|
||||||
|
return new ToolError(fallbackCode, String(error), false);
|
||||||
|
}
|
||||||
+191
@@ -0,0 +1,191 @@
|
|||||||
|
# 测试文档
|
||||||
|
|
||||||
|
本项目使用 Node.js 内置的测试框架进行单元测试和集成测试。
|
||||||
|
|
||||||
|
## 测试结构
|
||||||
|
|
||||||
|
```
|
||||||
|
test/
|
||||||
|
├── ssh-config-parser.test.js # SSH 配置解析器测试
|
||||||
|
├── command-line-parser.test.js # 命令行参数解析器测试
|
||||||
|
├── ssh-connection-manager.test.js # SSH 连接管理器测试
|
||||||
|
├── integration.test.js # 集成测试
|
||||||
|
└── fixtures/ # 测试数据（自动生成）
|
||||||
|
```
|
||||||
|
|
||||||
|
## 运行测试
|
||||||
|
|
||||||
|
### 运行所有测试
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
### 监听模式（开发时使用）
|
||||||
|
|
||||||
|
```bash
|
||||||
|
npm run test:watch
|
||||||
|
```
|
||||||
|
|
||||||
|
监听模式会在文件变化时自动重新运行测试。
|
||||||
|
|
||||||
|
### 运行单个测试文件
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --test test/ssh-config-parser.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## 测试覆盖范围
|
||||||
|
|
||||||
|
### 1. SSH Config Parser 测试
|
||||||
|
|
||||||
|
测试 `src/utils/ssh-config-parser.ts` 的功能：
|
||||||
|
|
||||||
|
- ✅ 基本 Host 别名解析
|
||||||
|
- ✅ 多别名 Host 行（`Host a b c`）
|
||||||
|
- ✅ 通配符匹配（`Host *.example.com`）
|
||||||
|
- ✅ `Host *` 默认值 fallback
|
||||||
|
- ✅ `Include` 指令支持
|
||||||
|
- ✅ 路径展开（`~` 和相对路径）
|
||||||
|
- ✅ First-match-wins 语义
|
||||||
|
- ✅ 错误处理（文件不存在等）
|
||||||
|
|
||||||
|
### 2. Command Line Parser 测试
|
||||||
|
|
||||||
|
测试 `src/cli/command-line-parser.ts` 的功能：
|
||||||
|
|
||||||
|
- ✅ JSON 配置文件解析（对象和数组格式）
|
||||||
|
- ✅ `--ssh` 参数解析（JSON 和旧格式）
|
||||||
|
- ✅ 单连接模式（命令行参数和位置参数）
|
||||||
|
- ✅ SSH config 集成
|
||||||
|
- ✅ 参数优先级（命令行 > SSH config）
|
||||||
|
- ✅ 命令白名单和黑名单
|
||||||
|
- ✅ 其他选项（`--pty`, `--pre-connect`, `--proxy`, `--socksProxy`）
|
||||||
|
- ✅ 错误处理
|
||||||
|
|
||||||
|
### 3. SSH Connection Manager 测试
|
||||||
|
|
||||||
|
测试 `src/services/ssh-connection-manager.ts` 的功能：
|
||||||
|
|
||||||
|
- ✅ 配置管理（初始化、获取配置）
|
||||||
|
- ✅ 命令验证（白名单、黑名单、正则表达式）
|
||||||
|
- ✅ 连接状态管理
|
||||||
|
- ✅ 多服务器支持
|
||||||
|
|
||||||
|
### 4. 集成测试
|
||||||
|
|
||||||
|
端到端测试完整流程：
|
||||||
|
|
||||||
|
- ✅ 从命令行参数到连接管理器的完整流程
|
||||||
|
- ✅ 从 SSH config 到连接管理器的完整流程
|
||||||
|
- ✅ 多服务器配置场景
|
||||||
|
- ✅ 错误处理（无效配置、缺少字段等）
|
||||||
|
|
||||||
|
## 编写新测试
|
||||||
|
|
||||||
|
### 测试文件命名
|
||||||
|
|
||||||
|
测试文件应该以 `.test.js` 结尾，并放在 `test/` 目录下。
|
||||||
|
|
||||||
|
### 测试示例
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
import { describe, it, before, after } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
|
||||||
|
describe('功能模块名称', () => {
|
||||||
|
before(() => {
|
||||||
|
// 测试前的准备工作
|
||||||
|
});
|
||||||
|
|
||||||
|
after(() => {
|
||||||
|
// 测试后的清理工作
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('子功能', () => {
|
||||||
|
it('应该做某事', () => {
|
||||||
|
// 测试代码
|
||||||
|
assert.strictEqual(1 + 1, 2);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该处理错误情况', () => {
|
||||||
|
assert.throws(() => {
|
||||||
|
throw new Error('测试错误');
|
||||||
|
}, /测试错误/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## 测试最佳实践
|
||||||
|
|
||||||
|
1. **独立性**：每个测试应该独立运行，不依赖其他测试的状态
|
||||||
|
2. **清理**：使用 `after` 钩子清理测试创建的临时文件和资源
|
||||||
|
3. **描述性**：测试名称应该清楚地描述测试的内容
|
||||||
|
4. **覆盖边界情况**：测试正常情况、边界情况和错误情况
|
||||||
|
5. **使用 fixtures**：将测试数据放在 `test/fixtures/` 目录下
|
||||||
|
|
||||||
|
## CI/CD 集成
|
||||||
|
|
||||||
|
测试可以轻松集成到 CI/CD 流程中：
|
||||||
|
|
||||||
|
```yaml
|
||||||
|
# GitHub Actions 示例
|
||||||
|
- name: Run tests
|
||||||
|
run: npm test
|
||||||
|
```
|
||||||
|
|
||||||
|
## 调试测试
|
||||||
|
|
||||||
|
### 使用 Node.js 调试器
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --inspect-brk --test test/ssh-config-parser.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
然后在 Chrome 中打开 `chrome://inspect` 进行调试。
|
||||||
|
|
||||||
|
### 查看详细输出
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --test --test-reporter=tap test/**/*.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
## 常见问题
|
||||||
|
|
||||||
|
### Q: 测试失败但没有详细错误信息？
|
||||||
|
|
||||||
|
A: 使用 `--test-reporter=spec` 查看详细输出：
|
||||||
|
|
||||||
|
```bash
|
||||||
|
node --test --test-reporter=spec test/**/*.test.js
|
||||||
|
```
|
||||||
|
|
||||||
|
### Q: 如何跳过某个测试？
|
||||||
|
|
||||||
|
A: 使用 `it.skip()`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
it.skip('暂时跳过的测试', () => {
|
||||||
|
// 测试代码
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
### Q: 如何只运行某个测试？
|
||||||
|
|
||||||
|
A: 使用 `it.only()`:
|
||||||
|
|
||||||
|
```javascript
|
||||||
|
it.only('只运行这个测试', () => {
|
||||||
|
// 测试代码
|
||||||
|
});
|
||||||
|
```
|
||||||
|
|
||||||
|
## 贡献指南
|
||||||
|
|
||||||
|
提交 PR 时，请确保：
|
||||||
|
|
||||||
|
1. 所有测试通过：`npm test`
|
||||||
|
2. 新功能有对应的测试
|
||||||
|
3. 测试覆盖了正常情况和边界情况
|
||||||
|
4. 代码编译通过：`npm run build`
|
||||||
@@ -0,0 +1,95 @@
|
|||||||
|
import { describe, it } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { spawnSync } from 'node:child_process';
|
||||||
|
import * as fs from 'node:fs';
|
||||||
|
import * as path from 'node:path';
|
||||||
|
import { fileURLToPath } from 'node:url';
|
||||||
|
import { SERVER_CONFIG } from '../build/config/server.js';
|
||||||
|
|
||||||
|
const __filename = fileURLToPath(import.meta.url);
|
||||||
|
const __dirname = path.dirname(__filename);
|
||||||
|
const rootDir = path.resolve(__dirname, '..');
|
||||||
|
const entrypoint = path.join(rootDir, 'build', 'index.js');
|
||||||
|
const packageJson = JSON.parse(
|
||||||
|
fs.readFileSync(path.join(rootDir, 'package.json'), 'utf8')
|
||||||
|
);
|
||||||
|
|
||||||
|
const expectedHelpOptions = [
|
||||||
|
'--config-file <path>',
|
||||||
|
'--ssh-config-file <path>',
|
||||||
|
'--ssh <config>',
|
||||||
|
'-h, --host <host>',
|
||||||
|
'-p, --port <port>',
|
||||||
|
'-u, --username <name>',
|
||||||
|
'-w, --password <password>',
|
||||||
|
'-k, --privateKey <path>',
|
||||||
|
'-P, --passphrase <passphrase>',
|
||||||
|
'-a, --agent <path>',
|
||||||
|
'-W, --whitelist <patterns>',
|
||||||
|
'-B, --blacklist <patterns>',
|
||||||
|
'--proxy <url>',
|
||||||
|
'-s, --socksProxy <url>',
|
||||||
|
'--allowed-local-paths <paths>',
|
||||||
|
'--allowed-remote-paths <paths>',
|
||||||
|
'--transport-mode <mode>',
|
||||||
|
'--shell-ready-timeout <ms>',
|
||||||
|
'--command-template <template>',
|
||||||
|
'--pty',
|
||||||
|
'--try-keyboard',
|
||||||
|
'--pre-connect',
|
||||||
|
'--version, -v',
|
||||||
|
'--help',
|
||||||
|
];
|
||||||
|
|
||||||
|
function runCli(args) {
|
||||||
|
return spawnSync(process.execPath, [entrypoint, ...args], {
|
||||||
|
cwd: rootDir,
|
||||||
|
encoding: 'utf8',
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('CLI info flags', () => {
|
||||||
|
it('keeps the MCP server version in sync with package metadata', () => {
|
||||||
|
assert.strictEqual(SERVER_CONFIG.version, packageJson.version);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('prints package version and exits successfully for --version', () => {
|
||||||
|
const result = runCli(['--version']);
|
||||||
|
|
||||||
|
assert.strictEqual(result.status, 0);
|
||||||
|
assert.strictEqual(result.stdout.trim(), packageJson.version);
|
||||||
|
assert.doesNotMatch(result.stderr, /Unknown option/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('prints package version and exits successfully for -v', () => {
|
||||||
|
const result = runCli(['-v']);
|
||||||
|
|
||||||
|
assert.strictEqual(result.status, 0);
|
||||||
|
assert.strictEqual(result.stdout.trim(), packageJson.version);
|
||||||
|
assert.doesNotMatch(result.stderr, /Unknown option/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('prints help and exits successfully for --help', () => {
|
||||||
|
const result = runCli(['--help']);
|
||||||
|
|
||||||
|
assert.strictEqual(result.status, 0);
|
||||||
|
assert.match(result.stdout, /Usage: ssh-mcp-server/);
|
||||||
|
for (const option of expectedHelpOptions) {
|
||||||
|
assert.ok(
|
||||||
|
result.stdout.includes(option),
|
||||||
|
`Expected help output to include ${option}`
|
||||||
|
);
|
||||||
|
}
|
||||||
|
assert.doesNotMatch(result.stderr, /Unknown option/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('handles info flags before normal config parsing', () => {
|
||||||
|
const missingConfigPath = path.join(rootDir, 'missing-cli-info-config.json');
|
||||||
|
const result = runCli(['--config-file', missingConfigPath, '--help']);
|
||||||
|
|
||||||
|
assert.strictEqual(result.status, 0);
|
||||||
|
assert.match(result.stdout, /Usage: ssh-mcp-server/);
|
||||||
|
assert.doesNotMatch(result.stderr, /Config file not found/);
|
||||||
|
assert.doesNotMatch(result.stderr, /Unknown option/);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,645 @@
|
|||||||
|
import { describe, it, before, after } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { CommandLineParser } from '../build/cli/command-line-parser.js';
|
||||||
|
import * as fs from 'fs';
|
||||||
|
import * as path from 'path';
|
||||||
|
import * as os from 'os';
|
||||||
|
|
||||||
|
describe('Command Line Parser', () => {
|
||||||
|
let originalArgv;
|
||||||
|
let fixturesDir;
|
||||||
|
let testConfigPath;
|
||||||
|
let testSshConfigPath;
|
||||||
|
|
||||||
|
before(() => {
|
||||||
|
originalArgv = process.argv;
|
||||||
|
|
||||||
|
// 创建测试配置文件
|
||||||
|
fixturesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ssh-mcp-cli-test-'));
|
||||||
|
|
||||||
|
testConfigPath = path.join(fixturesDir, 'test-config.json');
|
||||||
|
testSshConfigPath = path.join(fixturesDir, 'test-ssh-config');
|
||||||
|
|
||||||
|
// 创建 JSON 配置文件
|
||||||
|
fs.writeFileSync(testConfigPath, JSON.stringify({
|
||||||
|
dev: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'devuser',
|
||||||
|
password: 'devpass'
|
||||||
|
},
|
||||||
|
prod: {
|
||||||
|
host: '10.0.0.50',
|
||||||
|
port: 22,
|
||||||
|
username: 'produser',
|
||||||
|
privateKey: '~/.ssh/prod_key'
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
// 创建 SSH 配置文件
|
||||||
|
fs.writeFileSync(testSshConfigPath, `
|
||||||
|
Host testhost
|
||||||
|
HostName 172.16.0.1
|
||||||
|
Port 2222
|
||||||
|
User testuser
|
||||||
|
IdentityFile ~/.ssh/test_key
|
||||||
|
`);
|
||||||
|
});
|
||||||
|
|
||||||
|
after(() => {
|
||||||
|
process.argv = originalArgv;
|
||||||
|
fs.rmSync(fixturesDir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('配置文件解析', () => {
|
||||||
|
it('应该正确解析 JSON 配置文件（对象格式）', () => {
|
||||||
|
process.argv = ['node', 'test', '--config-file', testConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 2);
|
||||||
|
assert.strictEqual(result.configs.dev.host, '192.168.1.100');
|
||||||
|
assert.strictEqual(result.configs.dev.username, 'devuser');
|
||||||
|
assert.strictEqual(result.configs.prod.privateKey, path.join(os.homedir(), '.ssh', 'prod_key'));
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 JSON 配置文件（数组格式）', () => {
|
||||||
|
const arrayConfigPath = path.join(fixturesDir, 'array-config.json');
|
||||||
|
fs.writeFileSync(arrayConfigPath, JSON.stringify([
|
||||||
|
{
|
||||||
|
name: 'server1',
|
||||||
|
host: '1.2.3.4',
|
||||||
|
port: 22,
|
||||||
|
username: 'user1',
|
||||||
|
password: 'pass1'
|
||||||
|
},
|
||||||
|
{
|
||||||
|
name: 'server2',
|
||||||
|
host: '5.6.7.8',
|
||||||
|
port: 2222,
|
||||||
|
username: 'user2',
|
||||||
|
privateKey: '~/.ssh/key2'
|
||||||
|
}
|
||||||
|
]));
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--config-file', arrayConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 2);
|
||||||
|
assert.strictEqual(result.configs.server1.host, '1.2.3.4');
|
||||||
|
assert.strictEqual(result.configs.server2.port, 2222);
|
||||||
|
|
||||||
|
fs.unlinkSync(arrayConfigPath);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该保留 JSON 配置中的 SSH algorithms', () => {
|
||||||
|
const algorithmsConfigPath = path.join(fixturesDir, 'algorithms-config.json');
|
||||||
|
const algorithms = {
|
||||||
|
serverHostKey: { append: ['ssh-rsa'] },
|
||||||
|
hmac: ['hmac-sha1', 'hmac-md5']
|
||||||
|
};
|
||||||
|
fs.writeFileSync(algorithmsConfigPath, JSON.stringify({
|
||||||
|
legacy: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'legacy-user',
|
||||||
|
password: 'legacy-pass',
|
||||||
|
algorithms
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', algorithmsConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.deepStrictEqual(result.configs.legacy.algorithms, algorithms);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(algorithmsConfigPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该保留并校验 JSON 配置中的 maxOutputBytes', () => {
|
||||||
|
const outputLimitConfigPath = path.join(fixturesDir, 'output-limit-config.json');
|
||||||
|
fs.writeFileSync(outputLimitConfigPath, JSON.stringify({
|
||||||
|
limited: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'limited-user',
|
||||||
|
password: 'limited-pass',
|
||||||
|
maxOutputBytes: 2048
|
||||||
|
},
|
||||||
|
unlimited: {
|
||||||
|
host: '192.168.1.101',
|
||||||
|
port: 22,
|
||||||
|
username: 'unlimited-user',
|
||||||
|
password: 'unlimited-pass',
|
||||||
|
maxOutputBytes: 0
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', outputLimitConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.limited.maxOutputBytes, 2048);
|
||||||
|
assert.strictEqual(result.configs.unlimited.maxOutputBytes, 0);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(outputLimitConfigPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应从配置文件解析 commandTimeoutMs', () => {
|
||||||
|
const timeoutConfigPath = path.join(fixturesDir, 'command-timeout-config.json');
|
||||||
|
fs.writeFileSync(timeoutConfigPath, JSON.stringify({
|
||||||
|
slow: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'slow-user',
|
||||||
|
password: 'slow-pass',
|
||||||
|
commandTimeoutMs: 180000
|
||||||
|
},
|
||||||
|
plain: {
|
||||||
|
host: '192.168.1.101',
|
||||||
|
port: 22,
|
||||||
|
username: 'plain-user',
|
||||||
|
password: 'plain-pass'
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', timeoutConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.slow.commandTimeoutMs, 180000);
|
||||||
|
assert.strictEqual(result.configs.plain.commandTimeoutMs, undefined);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(timeoutConfigPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('无效的 commandTimeoutMs 应抛出错误', () => {
|
||||||
|
const invalidTimeoutPath = path.join(fixturesDir, 'invalid-command-timeout-config.json');
|
||||||
|
fs.writeFileSync(invalidTimeoutPath, JSON.stringify({
|
||||||
|
invalid: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'invalid-user',
|
||||||
|
password: 'invalid-pass',
|
||||||
|
commandTimeoutMs: 0
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', invalidTimeoutPath];
|
||||||
|
assert.throws(
|
||||||
|
() => CommandLineParser.parseArgs(),
|
||||||
|
/commandTimeoutMs must be a positive number/,
|
||||||
|
);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(invalidTimeoutPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('无效的 maxOutputBytes 应抛出错误', () => {
|
||||||
|
const invalidConfigPath = path.join(fixturesDir, 'invalid-output-limit-config.json');
|
||||||
|
fs.writeFileSync(invalidConfigPath, JSON.stringify({
|
||||||
|
invalid: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'invalid-user',
|
||||||
|
password: 'invalid-pass',
|
||||||
|
maxOutputBytes: -1
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', invalidConfigPath];
|
||||||
|
assert.throws(
|
||||||
|
() => CommandLineParser.parseArgs(),
|
||||||
|
/maxOutputBytes must be a non-negative integer/,
|
||||||
|
);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(invalidConfigPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('配置文件不存在时应抛出错误', () => {
|
||||||
|
process.argv = ['node', 'test', '--config-file', '/nonexistent/config.json'];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /not found/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('动态模式（无连接参数）', () => {
|
||||||
|
it('没有任何连接参数时应返回空配置以允许按调用动态连接', () => {
|
||||||
|
process.argv = ['node', 'test'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
assert.deepStrictEqual(result.configs, {});
|
||||||
|
assert.strictEqual(result.preConnect, false);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('只传 --pre-connect 而无连接参数时同样返回空配置', () => {
|
||||||
|
process.argv = ['node', 'test', '--pre-connect'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
assert.deepStrictEqual(result.configs, {});
|
||||||
|
assert.strictEqual(result.preConnect, true);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('--ssh 参数解析', () => {
|
||||||
|
it('应该正确解析 JSON 格式的 --ssh 参数', () => {
|
||||||
|
const sshJson = JSON.stringify({
|
||||||
|
name: 'test',
|
||||||
|
host: '1.2.3.4',
|
||||||
|
port: 22,
|
||||||
|
username: 'testuser',
|
||||||
|
password: 'testpass',
|
||||||
|
transportMode: 'shell',
|
||||||
|
shellReadyTimeoutMs: 15000,
|
||||||
|
maxOutputBytes: 0
|
||||||
|
});
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--ssh', sshJson];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.test.host, '1.2.3.4');
|
||||||
|
assert.strictEqual(result.configs.test.username, 'testuser');
|
||||||
|
assert.strictEqual(result.configs.test.transportMode, 'shell');
|
||||||
|
assert.strictEqual(result.configs.test.shellReadyTimeoutMs, 15000);
|
||||||
|
assert.strictEqual(result.configs.test.maxOutputBytes, 0);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析旧格式的 --ssh 参数', () => {
|
||||||
|
process.argv = ['node', 'test', '--ssh', 'name=legacy,host=1.2.3.4,port=22,user=legacyuser,password=legacypass'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.legacy.host, '1.2.3.4');
|
||||||
|
assert.strictEqual(result.configs.legacy.username, 'legacyuser');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持多个 --ssh 参数', () => {
|
||||||
|
const ssh1 = JSON.stringify({ name: 'server1', host: '1.1.1.1', port: 22, username: 'user1', password: 'pass1' });
|
||||||
|
const ssh2 = JSON.stringify({ name: 'server2', host: '2.2.2.2', port: 22, username: 'user2', password: 'pass2' });
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--ssh', ssh1, '--ssh', ssh2];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 2);
|
||||||
|
assert.strictEqual(result.configs.server1.host, '1.1.1.1');
|
||||||
|
assert.strictEqual(result.configs.server2.host, '2.2.2.2');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('单连接模式（旧格式）', () => {
|
||||||
|
it('应该正确解析命令行参数', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'testuser', '--password', 'testpass'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '1.2.3.4');
|
||||||
|
assert.strictEqual(result.configs.default.port, 22);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'testuser');
|
||||||
|
assert.strictEqual(result.configs.default.password, 'testpass');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析位置参数', () => {
|
||||||
|
process.argv = ['node', 'test', '1.2.3.4', '22', 'testuser', 'testpass'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '1.2.3.4');
|
||||||
|
assert.strictEqual(result.configs.default.port, 22);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'testuser');
|
||||||
|
assert.strictEqual(result.configs.default.password, 'testpass');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持私钥认证', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'testuser', '--privateKey', '~/.ssh/id_rsa'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.privateKey, path.join(os.homedir(), '.ssh', 'id_rsa'));
|
||||||
|
assert.strictEqual(result.configs.default.password, undefined);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('显式 password 存在时不应注入环境 SSH agent', () => {
|
||||||
|
const originalSshAuthSock = process.env.SSH_AUTH_SOCK;
|
||||||
|
process.env.SSH_AUTH_SOCK = '/tmp/environment-agent.sock';
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--username', 'testuser', '--password', 'testpass'];
|
||||||
|
|
||||||
|
try {
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.password, 'testpass');
|
||||||
|
assert.strictEqual(result.configs.default.agent, undefined);
|
||||||
|
} finally {
|
||||||
|
if (originalSshAuthSock === undefined) {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
} else {
|
||||||
|
process.env.SSH_AUTH_SOCK = originalSshAuthSock;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('显式 privateKey 存在时不应注入环境 SSH agent', () => {
|
||||||
|
const originalSshAuthSock = process.env.SSH_AUTH_SOCK;
|
||||||
|
process.env.SSH_AUTH_SOCK = '/tmp/environment-agent.sock';
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--username', 'testuser', '--privateKey', '~/.ssh/id_rsa'];
|
||||||
|
|
||||||
|
try {
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.privateKey, path.join(os.homedir(), '.ssh', 'id_rsa'));
|
||||||
|
assert.strictEqual(result.configs.default.agent, undefined);
|
||||||
|
} finally {
|
||||||
|
if (originalSshAuthSock === undefined) {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
} else {
|
||||||
|
process.env.SSH_AUTH_SOCK = originalSshAuthSock;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('缺少必需参数时应抛出错误', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4'];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /Missing required parameters/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('SSH Config 集成', () => {
|
||||||
|
it('SSH config 缺少 Port 和 IdentityFile 时应使用默认端口和 SSH agent', () => {
|
||||||
|
const minimalSshConfigPath = path.join(fixturesDir, 'minimal-ssh-config');
|
||||||
|
const originalSshAuthSock = process.env.SSH_AUTH_SOCK;
|
||||||
|
fs.writeFileSync(minimalSshConfigPath, `
|
||||||
|
Host minimalhost
|
||||||
|
HostName 172.16.0.2
|
||||||
|
User minimaluser
|
||||||
|
`);
|
||||||
|
process.env.SSH_AUTH_SOCK = '/tmp/test-ssh-agent.sock';
|
||||||
|
process.argv = ['node', 'test', '--host', 'minimalhost', '--ssh-config-file', minimalSshConfigPath];
|
||||||
|
|
||||||
|
try {
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '172.16.0.2');
|
||||||
|
assert.strictEqual(result.configs.default.port, 22);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'minimaluser');
|
||||||
|
assert.strictEqual(result.configs.default.agent, '/tmp/test-ssh-agent.sock');
|
||||||
|
} finally {
|
||||||
|
if (originalSshAuthSock === undefined) {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
} else {
|
||||||
|
process.env.SSH_AUTH_SOCK = originalSshAuthSock;
|
||||||
|
}
|
||||||
|
fs.unlinkSync(minimalSshConfigPath);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('命令行 port 和 agent 应覆盖 SSH config 默认值', () => {
|
||||||
|
const originalSshAuthSock = process.env.SSH_AUTH_SOCK;
|
||||||
|
process.env.SSH_AUTH_SOCK = '/tmp/environment-agent.sock';
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = [
|
||||||
|
'node', 'test', '--host', 'testhost', '--port', '3333', '--agent', '/tmp/explicit-agent.sock',
|
||||||
|
'--ssh-config-file', testSshConfigPath,
|
||||||
|
];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.port, 3333);
|
||||||
|
assert.strictEqual(result.configs.default.agent, '/tmp/explicit-agent.sock');
|
||||||
|
} finally {
|
||||||
|
if (originalSshAuthSock === undefined) {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
} else {
|
||||||
|
process.env.SSH_AUTH_SOCK = originalSshAuthSock;
|
||||||
|
}
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该从 SSH config 读取连接参数', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', 'testhost', '--ssh-config-file', testSshConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '172.16.0.1');
|
||||||
|
assert.strictEqual(result.configs.default.port, 2222);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'testuser');
|
||||||
|
assert.ok(
|
||||||
|
result.configs.default.privateKey.endsWith(path.join('.ssh', 'test_key')),
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('命令行参数应覆盖 SSH config 值', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', 'testhost', '--port', '3333', '--ssh-config-file', testSshConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.port, 3333); // 覆盖
|
||||||
|
assert.strictEqual(result.configs.default.host, '172.16.0.1'); // 从 SSH config
|
||||||
|
assert.strictEqual(result.configs.default.username, 'testuser'); // 从 SSH config
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持 SSH config 别名 + 密码认证', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', 'testhost', '--password', 'mypass', '--ssh-config-file', testSshConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.password, 'mypass');
|
||||||
|
assert.strictEqual(result.configs.default.host, '172.16.0.1');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('命令白名单和黑名单', () => {
|
||||||
|
it('应该正确解析命令白名单', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--whitelist', 'ls,cat,grep'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.deepStrictEqual(result.configs.default.commandWhitelist, ['ls', 'cat', 'grep']);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析命令黑名单', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--blacklist', 'rm,shutdown,reboot'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.deepStrictEqual(result.configs.default.commandBlacklist, ['rm', 'shutdown', 'reboot']);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('其他选项', () => {
|
||||||
|
it('默认 transportMode 应为 exec', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.transportMode, 'exec');
|
||||||
|
assert.strictEqual(result.configs.default.shellReadyTimeoutMs, 10000);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 shell transport 相关选项', () => {
|
||||||
|
process.argv = [
|
||||||
|
'node',
|
||||||
|
'test',
|
||||||
|
'--host', '1.2.3.4',
|
||||||
|
'--port', '22',
|
||||||
|
'--username', 'user',
|
||||||
|
'--password', 'pass',
|
||||||
|
'--transport-mode', 'shell',
|
||||||
|
'--shell-ready-timeout', '15000'
|
||||||
|
];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.transportMode, 'shell');
|
||||||
|
assert.strictEqual(result.configs.default.shellReadyTimeoutMs, 15000);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 --pty 选项', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--pty'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.pty, true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析配置文件中的字符串 false pty', () => {
|
||||||
|
const ptyConfigPath = path.join(fixturesDir, 'pty-config.json');
|
||||||
|
fs.writeFileSync(ptyConfigPath, JSON.stringify({
|
||||||
|
dev: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'devuser',
|
||||||
|
password: 'devpass',
|
||||||
|
pty: 'false'
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--config-file', ptyConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.dev.pty, false);
|
||||||
|
|
||||||
|
fs.unlinkSync(ptyConfigPath);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 --pre-connect 选项', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--pre-connect'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.preConnect, true);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 SOCKS 代理', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--socksProxy', 'socks://proxy:1080'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.socksProxy, 'socks://proxy:1080');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析通用代理', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--proxy', 'http://proxy:8080'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.proxy, 'http://proxy:8080');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 allowed local paths', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--allowed-local-paths', './tmp,~/.ssh'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.ok(Array.isArray(result.configs.default.allowedLocalPaths));
|
||||||
|
assert.strictEqual(result.configs.default.allowedLocalPaths.length, 2);
|
||||||
|
assert.ok(result.configs.default.allowedLocalPaths.every((entry) => path.isAbsolute(entry)));
|
||||||
|
assert.strictEqual(result.configs.default.allowedLocalPaths[1], path.join(os.homedir(), '.ssh'));
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析 allowed remote paths', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--allowed-remote-paths', '/var/log,/home/ops/inbox/'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.deepStrictEqual(
|
||||||
|
result.configs.default.allowedRemotePaths,
|
||||||
|
['/var/log', '/home/ops/inbox']
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('相对的 allowedRemotePaths 条目应抛出错误', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', '22', '--username', 'user', '--password', 'pass', '--allowed-remote-paths', 'var/log'];
|
||||||
|
assert.throws(() => CommandLineParser.parseArgs(), /absolute POSIX/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析配置文件中的 commandTemplate', () => {
|
||||||
|
const templateConfigPath = path.join(fixturesDir, 'template-config.json');
|
||||||
|
fs.writeFileSync(templateConfigPath, JSON.stringify({
|
||||||
|
dev: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'devuser',
|
||||||
|
password: 'devpass',
|
||||||
|
commandTemplate: "su root -c '<command>'"
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--config-file', templateConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.dev.commandTemplate, "su root -c '<command>'");
|
||||||
|
|
||||||
|
fs.unlinkSync(templateConfigPath);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持 commandTemplate 的 <quotedCommand> 占位符', () => {
|
||||||
|
const templateConfigPath = path.join(fixturesDir, 'quoted-template-config.json');
|
||||||
|
fs.writeFileSync(templateConfigPath, JSON.stringify({
|
||||||
|
dev: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'devuser',
|
||||||
|
password: 'devpass',
|
||||||
|
commandTemplate: "su root -c <quotedCommand>"
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--config-file', templateConfigPath];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.dev.commandTemplate, "su root -c <quotedCommand>");
|
||||||
|
|
||||||
|
fs.unlinkSync(templateConfigPath);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('commandTemplate 缺少 <command> 占位符时应抛出错误', () => {
|
||||||
|
const badConfigPath = path.join(fixturesDir, 'bad-template-config.json');
|
||||||
|
fs.writeFileSync(badConfigPath, JSON.stringify({
|
||||||
|
dev: {
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'devuser',
|
||||||
|
password: 'devpass',
|
||||||
|
commandTemplate: "su root -c 'missing placeholder'"
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
process.argv = ['node', 'test', '--config-file', badConfigPath];
|
||||||
|
assert.throws(() => CommandLineParser.parseArgs(), /<command>/);
|
||||||
|
|
||||||
|
fs.unlinkSync(badConfigPath);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('优先级测试', () => {
|
||||||
|
it('配置文件应优先于 --ssh 参数', () => {
|
||||||
|
const sshJson = JSON.stringify({ name: 'test', host: '1.1.1.1', port: 22, username: 'user1', password: 'pass1' });
|
||||||
|
process.argv = ['node', 'test', '--config-file', testConfigPath, '--ssh', sshJson];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
// 应该只有配置文件中的服务器
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 2);
|
||||||
|
assert.ok(result.configs.dev);
|
||||||
|
assert.ok(result.configs.prod);
|
||||||
|
assert.ok(!result.configs.test);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('--ssh 参数应优先于单连接模式', () => {
|
||||||
|
const sshJson = JSON.stringify({ name: 'test', host: '1.1.1.1', port: 22, username: 'user1', password: 'pass1' });
|
||||||
|
process.argv = ['node', 'test', '--ssh', sshJson, '--host', '2.2.2.2', '--port', '22', '--username', 'user2', '--password', 'pass2'];
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 1);
|
||||||
|
assert.strictEqual(result.configs.test.host, '1.1.1.1');
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,267 @@
|
|||||||
|
import { describe, it, before, after } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { CommandLineParser } from '../build/cli/command-line-parser.js';
|
||||||
|
import { SSHConnectionManager } from '../build/services/ssh-connection-manager.js';
|
||||||
|
import * as fs from 'fs';
|
||||||
|
import * as path from 'path';
|
||||||
|
import * as os from 'os';
|
||||||
|
let fixturesDir;
|
||||||
|
|
||||||
|
describe('集成测试', () => {
|
||||||
|
let originalArgv;
|
||||||
|
|
||||||
|
before(() => {
|
||||||
|
originalArgv = process.argv;
|
||||||
|
|
||||||
|
fixturesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ssh-mcp-integration-test-'));
|
||||||
|
});
|
||||||
|
|
||||||
|
after(() => {
|
||||||
|
process.argv = originalArgv;
|
||||||
|
fs.rmSync(fixturesDir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('端到端场景', () => {
|
||||||
|
it('应该能够从命令行参数创建完整配置并传递给连接管理器', () => {
|
||||||
|
process.argv = [
|
||||||
|
'node',
|
||||||
|
'test',
|
||||||
|
'--host', '192.168.1.100',
|
||||||
|
'--port', '22',
|
||||||
|
'--username', 'testuser',
|
||||||
|
'--password', 'testpass',
|
||||||
|
'--whitelist', 'ls,cat,grep',
|
||||||
|
'--blacklist', 'rm,shutdown'
|
||||||
|
];
|
||||||
|
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '192.168.1.100');
|
||||||
|
assert.strictEqual(result.configs.default.port, 22);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'testuser');
|
||||||
|
assert.deepStrictEqual(result.configs.default.commandWhitelist, ['ls', 'cat', 'grep']);
|
||||||
|
assert.deepStrictEqual(result.configs.default.commandBlacklist, ['rm', 'shutdown']);
|
||||||
|
|
||||||
|
// 验证可以用这个配置初始化连接管理器
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
manager.setConfig(result.configs);
|
||||||
|
|
||||||
|
const config = manager.getConfig('default');
|
||||||
|
assert.strictEqual(config.host, '192.168.1.100');
|
||||||
|
assert.strictEqual(config.username, 'testuser');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该能够从命令行参数生成 shell transport 配置', () => {
|
||||||
|
process.argv = [
|
||||||
|
'node',
|
||||||
|
'test',
|
||||||
|
'--host', '192.168.1.110',
|
||||||
|
'--port', '22',
|
||||||
|
'--username', 'shelluser',
|
||||||
|
'--password', 'shellpass',
|
||||||
|
'--transport-mode', 'shell',
|
||||||
|
'--shell-ready-timeout', '18000'
|
||||||
|
];
|
||||||
|
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
assert.strictEqual(result.configs.default.transportMode, 'shell');
|
||||||
|
assert.strictEqual(result.configs.default.shellReadyTimeoutMs, 18000);
|
||||||
|
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
manager.setConfig(result.configs);
|
||||||
|
|
||||||
|
const config = manager.getConfig('default');
|
||||||
|
assert.strictEqual(config.transportMode, 'shell');
|
||||||
|
assert.strictEqual(config.shellReadyTimeoutMs, 18000);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该能够从 SSH config 创建完整配置', () => {
|
||||||
|
const tempSshConfig = path.join(fixturesDir, 'integration-ssh-config');
|
||||||
|
fs.writeFileSync(tempSshConfig, [
|
||||||
|
'Host integration-test',
|
||||||
|
' HostName 192.168.1.200',
|
||||||
|
' Port 2222',
|
||||||
|
' User integrationuser',
|
||||||
|
' IdentityFile ~/.ssh/integration_key',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = [
|
||||||
|
'node',
|
||||||
|
'test',
|
||||||
|
'--host', 'integration-test',
|
||||||
|
'--ssh-config-file', tempSshConfig
|
||||||
|
];
|
||||||
|
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
|
||||||
|
assert.strictEqual(result.configs.default.host, '192.168.1.200');
|
||||||
|
assert.strictEqual(result.configs.default.port, 2222);
|
||||||
|
assert.strictEqual(result.configs.default.username, 'integrationuser');
|
||||||
|
assert.ok(result.configs.default.privateKey.includes('integration_key'));
|
||||||
|
|
||||||
|
// 验证可以用这个配置初始化连接管理器
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
manager.setConfig(result.configs);
|
||||||
|
|
||||||
|
const config = manager.getConfig('default');
|
||||||
|
assert.strictEqual(config.host, '192.168.1.200');
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(tempSshConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该能够处理多服务器配置', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'multi-server-config.json');
|
||||||
|
fs.writeFileSync(tempConfig, JSON.stringify({
|
||||||
|
server1: {
|
||||||
|
host: '192.168.1.1',
|
||||||
|
port: 22,
|
||||||
|
username: 'user1',
|
||||||
|
password: 'pass1',
|
||||||
|
commandWhitelist: ['^ls', '^cat']
|
||||||
|
},
|
||||||
|
server2: {
|
||||||
|
host: '192.168.1.2',
|
||||||
|
port: 2222,
|
||||||
|
username: 'user2',
|
||||||
|
privateKey: '~/.ssh/key2',
|
||||||
|
commandBlacklist: ['^rm', '^shutdown']
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', tempConfig];
|
||||||
|
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
assert.strictEqual(Object.keys(result.configs).length, 2);
|
||||||
|
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
manager.setConfig(result.configs);
|
||||||
|
|
||||||
|
// 验证配置列表
|
||||||
|
const allInfos = manager.getAllServerInfos();
|
||||||
|
assert.strictEqual(allInfos.length, 2);
|
||||||
|
|
||||||
|
const server1 = allInfos.find(i => i.name === 'server1');
|
||||||
|
assert.ok(server1);
|
||||||
|
assert.strictEqual(server1.host, '192.168.1.1');
|
||||||
|
assert.strictEqual(server1.connected, false);
|
||||||
|
|
||||||
|
const server2 = allInfos.find(i => i.name === 'server2');
|
||||||
|
assert.ok(server2);
|
||||||
|
assert.strictEqual(server2.port, 2222);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该能够从配置文件生成 shell transport 配置', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'shell-server-config.json');
|
||||||
|
fs.writeFileSync(tempConfig, JSON.stringify({
|
||||||
|
shellbox: {
|
||||||
|
host: '192.168.1.20',
|
||||||
|
port: 22,
|
||||||
|
username: 'shelluser',
|
||||||
|
password: 'shellpass',
|
||||||
|
transportMode: 'shell',
|
||||||
|
shellReadyTimeoutMs: 12000
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', tempConfig];
|
||||||
|
|
||||||
|
const result = CommandLineParser.parseArgs();
|
||||||
|
assert.strictEqual(result.configs.shellbox.transportMode, 'shell');
|
||||||
|
assert.strictEqual(result.configs.shellbox.shellReadyTimeoutMs, 12000);
|
||||||
|
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
manager.setConfig(result.configs);
|
||||||
|
|
||||||
|
const config = manager.getConfig('shellbox');
|
||||||
|
assert.strictEqual(config.transportMode, 'shell');
|
||||||
|
assert.strictEqual(config.shellReadyTimeoutMs, 12000);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('错误处理', () => {
|
||||||
|
it('应该正确处理无效的 JSON 配置文件', () => {
|
||||||
|
const invalidConfig = path.join(fixturesDir, 'invalid-config.json');
|
||||||
|
fs.writeFileSync(invalidConfig, '{ invalid json }');
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', invalidConfig];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /Invalid JSON/);
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(invalidConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理缺少必需字段的配置', () => {
|
||||||
|
const incompleteConfig = path.join(fixturesDir, 'incomplete-config.json');
|
||||||
|
fs.writeFileSync(incompleteConfig, JSON.stringify({
|
||||||
|
server1: {
|
||||||
|
host: '192.168.1.1'
|
||||||
|
// 缺少 port, username 等必需字段
|
||||||
|
}
|
||||||
|
}));
|
||||||
|
|
||||||
|
try {
|
||||||
|
process.argv = ['node', 'test', '--config-file', incompleteConfig];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
});
|
||||||
|
} finally {
|
||||||
|
fs.unlinkSync(incompleteConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理不存在的配置文件', () => {
|
||||||
|
process.argv = ['node', 'test', '--config-file', '/nonexistent/config.json'];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /not found/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理缺少认证参数的情况', () => {
|
||||||
|
const emptySshConfig = path.join(fixturesDir, 'empty-ssh-config');
|
||||||
|
const originalSshAuthSock = process.env.SSH_AUTH_SOCK;
|
||||||
|
fs.writeFileSync(emptySshConfig, '');
|
||||||
|
|
||||||
|
try {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
process.argv = [
|
||||||
|
'node',
|
||||||
|
'test',
|
||||||
|
'--host', '1.2.3.4',
|
||||||
|
'--port', '22',
|
||||||
|
'--username', 'user',
|
||||||
|
'--ssh-config-file', emptySshConfig
|
||||||
|
];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /Missing required parameters/);
|
||||||
|
} finally {
|
||||||
|
if (originalSshAuthSock === undefined) {
|
||||||
|
delete process.env.SSH_AUTH_SOCK;
|
||||||
|
} else {
|
||||||
|
process.env.SSH_AUTH_SOCK = originalSshAuthSock;
|
||||||
|
}
|
||||||
|
fs.unlinkSync(emptySshConfig);
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理无效的端口号', () => {
|
||||||
|
process.argv = ['node', 'test', '--host', '1.2.3.4', '--port', 'abc', '--username', 'user', '--password', 'pass'];
|
||||||
|
assert.throws(() => {
|
||||||
|
CommandLineParser.parseArgs();
|
||||||
|
}, /Port must be a valid number/);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,36 @@
|
|||||||
|
import test from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { spawnSync } from 'node:child_process';
|
||||||
|
import { pathToFileURL } from 'node:url';
|
||||||
|
import * as path from 'node:path';
|
||||||
|
|
||||||
|
test('does not load SSH dependencies when importing the connection manager', () => {
|
||||||
|
const managerUrl = pathToFileURL(
|
||||||
|
path.resolve('build/services/ssh-connection-manager.js'),
|
||||||
|
).href;
|
||||||
|
const loader = `data:text/javascript,${encodeURIComponent(`
|
||||||
|
export async function resolve(specifier, context, nextResolve) {
|
||||||
|
if (specifier === 'ssh2' || specifier === 'socks') {
|
||||||
|
throw new Error('eager SSH dependency: ' + specifier);
|
||||||
|
}
|
||||||
|
return nextResolve(specifier, context);
|
||||||
|
}
|
||||||
|
`)}`;
|
||||||
|
const result = spawnSync(
|
||||||
|
process.execPath,
|
||||||
|
[
|
||||||
|
'--experimental-loader',
|
||||||
|
loader,
|
||||||
|
'--input-type=module',
|
||||||
|
'--eval',
|
||||||
|
`await import(${JSON.stringify(managerUrl)});`,
|
||||||
|
],
|
||||||
|
{ cwd: path.resolve('.'), encoding: 'utf8', timeout: 10_000 },
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(
|
||||||
|
result.status,
|
||||||
|
0,
|
||||||
|
[result.error?.stack, result.stderr, result.stdout].filter(Boolean).join('\n'),
|
||||||
|
);
|
||||||
|
});
|
||||||
@@ -0,0 +1,206 @@
|
|||||||
|
import { describe, it } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { spawn } from 'node:child_process';
|
||||||
|
import * as fs from 'node:fs';
|
||||||
|
import * as net from 'node:net';
|
||||||
|
import * as os from 'node:os';
|
||||||
|
import * as path from 'node:path';
|
||||||
|
import { fileURLToPath } from 'node:url';
|
||||||
|
|
||||||
|
const __filename = fileURLToPath(import.meta.url);
|
||||||
|
const __dirname = path.dirname(__filename);
|
||||||
|
const rootDir = path.join(__dirname, '..');
|
||||||
|
const entrypoint = path.join(rootDir, 'build', 'index.js');
|
||||||
|
|
||||||
|
function waitForOutput(stream, pattern, timeoutMs = 5000) {
|
||||||
|
return new Promise((resolve, reject) => {
|
||||||
|
let output = '';
|
||||||
|
const timeout = setTimeout(() => {
|
||||||
|
cleanup();
|
||||||
|
reject(new Error(`Timed out waiting for ${pattern}. Output:\n${output}`));
|
||||||
|
}, timeoutMs);
|
||||||
|
|
||||||
|
const onData = (chunk) => {
|
||||||
|
output += chunk.toString();
|
||||||
|
if (pattern.test(output)) {
|
||||||
|
cleanup();
|
||||||
|
resolve(output);
|
||||||
|
}
|
||||||
|
};
|
||||||
|
|
||||||
|
const cleanup = () => {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
stream.off('data', onData);
|
||||||
|
};
|
||||||
|
|
||||||
|
stream.on('data', onData);
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
async function waitForRunning(child, delayMs = 200) {
|
||||||
|
await new Promise((resolve) => setTimeout(resolve, delayMs));
|
||||||
|
assert.strictEqual(child.exitCode, null);
|
||||||
|
}
|
||||||
|
|
||||||
|
function waitForExit(child, timeoutMs = 5000) {
|
||||||
|
return new Promise((resolve, reject) => {
|
||||||
|
const timeout = setTimeout(() => {
|
||||||
|
child.kill('SIGKILL');
|
||||||
|
reject(new Error('Process did not exit before timeout'));
|
||||||
|
}, timeoutMs);
|
||||||
|
|
||||||
|
child.once('exit', (code, signal) => {
|
||||||
|
clearTimeout(timeout);
|
||||||
|
resolve({ code, signal });
|
||||||
|
});
|
||||||
|
});
|
||||||
|
}
|
||||||
|
|
||||||
|
function createTempConfig() {
|
||||||
|
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ssh-mcp-lifecycle-'));
|
||||||
|
const configPath = path.join(tmpDir, 'config.json');
|
||||||
|
|
||||||
|
fs.writeFileSync(configPath, JSON.stringify({
|
||||||
|
test: {
|
||||||
|
host: '127.0.0.1',
|
||||||
|
port: 22,
|
||||||
|
username: 'test',
|
||||||
|
password: 'test',
|
||||||
|
commandWhitelist: ['^echo'],
|
||||||
|
},
|
||||||
|
}));
|
||||||
|
|
||||||
|
return { tmpDir, configPath };
|
||||||
|
}
|
||||||
|
|
||||||
|
function createPreConnectConfig(port) {
|
||||||
|
const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ssh-mcp-lifecycle-'));
|
||||||
|
const configPath = path.join(tmpDir, 'config.json');
|
||||||
|
|
||||||
|
fs.writeFileSync(configPath, JSON.stringify({
|
||||||
|
test: {
|
||||||
|
host: '127.0.0.1',
|
||||||
|
port,
|
||||||
|
username: 'test',
|
||||||
|
password: 'test',
|
||||||
|
connectionTimeoutMs: 10000,
|
||||||
|
commandWhitelist: ['^echo'],
|
||||||
|
},
|
||||||
|
}));
|
||||||
|
|
||||||
|
return { tmpDir, configPath };
|
||||||
|
}
|
||||||
|
|
||||||
|
function spawnServer(configPath) {
|
||||||
|
const child = spawn(process.execPath, [entrypoint, '--config-file', configPath], {
|
||||||
|
stdio: ['pipe', 'pipe', 'pipe'],
|
||||||
|
});
|
||||||
|
|
||||||
|
let closed = false;
|
||||||
|
return {
|
||||||
|
child,
|
||||||
|
closeInput: () => {
|
||||||
|
if (closed) return;
|
||||||
|
closed = true;
|
||||||
|
child.stdin.end();
|
||||||
|
},
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('MCP server lifecycle', () => {
|
||||||
|
// Windows has no POSIX signals: child.kill('SIGTERM') maps to
|
||||||
|
// TerminateProcess, so the handler under test never runs and the exit is
|
||||||
|
// always reported as signalled. The stdin path below covers shutdown there,
|
||||||
|
// and is what MCP clients actually use.
|
||||||
|
it('exits after SIGTERM even when stdin remains open', { skip: process.platform === 'win32' && 'no POSIX signals on Windows' }, async () => {
|
||||||
|
const { tmpDir, configPath } = createTempConfig();
|
||||||
|
const { child, closeInput } = spawnServer(configPath);
|
||||||
|
|
||||||
|
try {
|
||||||
|
await waitForRunning(child, 1500);
|
||||||
|
|
||||||
|
child.kill('SIGTERM');
|
||||||
|
const result = await waitForExit(child);
|
||||||
|
|
||||||
|
assert.strictEqual(result.signal, null);
|
||||||
|
assert.strictEqual(result.code, 0);
|
||||||
|
} finally {
|
||||||
|
try {
|
||||||
|
closeInput();
|
||||||
|
} catch {}
|
||||||
|
child.kill('SIGKILL');
|
||||||
|
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('exits after stdin is closed', async () => {
|
||||||
|
const { tmpDir, configPath } = createTempConfig();
|
||||||
|
const { child, closeInput } = spawnServer(configPath);
|
||||||
|
|
||||||
|
try {
|
||||||
|
await waitForRunning(child);
|
||||||
|
|
||||||
|
closeInput();
|
||||||
|
const result = await waitForExit(child);
|
||||||
|
|
||||||
|
assert.strictEqual(result.signal, null);
|
||||||
|
assert.strictEqual(result.code, 0);
|
||||||
|
} finally {
|
||||||
|
try {
|
||||||
|
closeInput();
|
||||||
|
} catch {}
|
||||||
|
child.kill('SIGKILL');
|
||||||
|
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('accepts initialize requests while pre-connect is still pending', async () => {
|
||||||
|
const handshakeServer = net.createServer();
|
||||||
|
const sockets = new Set();
|
||||||
|
handshakeServer.on('connection', (socket) => {
|
||||||
|
sockets.add(socket);
|
||||||
|
// Killing the child resets this connection instead of closing it
|
||||||
|
// cleanly on some platforms; an unhandled 'error' would fail the test.
|
||||||
|
socket.on('error', () => {});
|
||||||
|
socket.on('close', () => sockets.delete(socket));
|
||||||
|
});
|
||||||
|
|
||||||
|
await new Promise((resolve, reject) => {
|
||||||
|
handshakeServer.once('error', reject);
|
||||||
|
handshakeServer.listen(0, '127.0.0.1', resolve);
|
||||||
|
});
|
||||||
|
|
||||||
|
const address = handshakeServer.address();
|
||||||
|
assert.ok(address && typeof address !== 'string');
|
||||||
|
const { tmpDir, configPath } = createPreConnectConfig(address.port);
|
||||||
|
const child = spawn(process.execPath, [entrypoint, '--config-file', configPath, '--pre-connect'], {
|
||||||
|
stdio: ['pipe', 'pipe', 'pipe'],
|
||||||
|
});
|
||||||
|
|
||||||
|
try {
|
||||||
|
child.stdin.write(`${JSON.stringify({
|
||||||
|
jsonrpc: '2.0',
|
||||||
|
id: 61,
|
||||||
|
method: 'initialize',
|
||||||
|
params: {
|
||||||
|
protocolVersion: '2025-11-25',
|
||||||
|
capabilities: {},
|
||||||
|
clientInfo: { name: 'lifecycle-test', version: '1.0.0' },
|
||||||
|
},
|
||||||
|
})}\n`);
|
||||||
|
|
||||||
|
const output = await waitForOutput(child.stdout, /"id":61/, 1250);
|
||||||
|
assert.match(output, /"result"/);
|
||||||
|
} finally {
|
||||||
|
child.stdin.end();
|
||||||
|
if (child.exitCode === null) {
|
||||||
|
const exitPromise = waitForExit(child);
|
||||||
|
child.kill('SIGKILL');
|
||||||
|
await exitPromise;
|
||||||
|
}
|
||||||
|
for (const socket of sockets) socket.destroy();
|
||||||
|
await new Promise((resolve) => handshakeServer.close(resolve));
|
||||||
|
fs.rmSync(tmpDir, { recursive: true, force: true });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,68 @@
|
|||||||
|
import { describe, it } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { formatServerList } from '../build/tools/list-servers.js';
|
||||||
|
|
||||||
|
describe('List Servers Tool', () => {
|
||||||
|
it('没有配置时应返回友好提示', () => {
|
||||||
|
assert.strictEqual(formatServerList([]), 'No SSH servers configured.');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应返回可读摘要和原始 JSON', () => {
|
||||||
|
const output = formatServerList([
|
||||||
|
{
|
||||||
|
name: 'dev',
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'root',
|
||||||
|
connected: true,
|
||||||
|
status: {
|
||||||
|
reachable: true,
|
||||||
|
hostname: 'dev-box',
|
||||||
|
osName: 'Linux',
|
||||||
|
lastUpdated: '2026-04-02T12:00:00.000Z'
|
||||||
|
}
|
||||||
|
}
|
||||||
|
]);
|
||||||
|
|
||||||
|
assert.match(output, /Configured SSH servers:/);
|
||||||
|
assert.match(output, /\[connected\] dev \| root@192.168.1.100:22/);
|
||||||
|
assert.match(output, /hostname=dev-box/);
|
||||||
|
assert.match(output, /Raw JSON:/);
|
||||||
|
assert.match(output, /"name":"dev"/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('原始 JSON 不缩进，且仍可解析回等价对象', () => {
|
||||||
|
const servers = [
|
||||||
|
{
|
||||||
|
name: 'dev',
|
||||||
|
host: '192.168.1.100',
|
||||||
|
port: 22,
|
||||||
|
username: 'root',
|
||||||
|
connected: true,
|
||||||
|
status: {
|
||||||
|
reachable: true,
|
||||||
|
hostname: 'dev-box',
|
||||||
|
osName: 'Linux',
|
||||||
|
drives: [
|
||||||
|
{
|
||||||
|
device: '/dev/sda1',
|
||||||
|
mountPoint: '/',
|
||||||
|
total: '512G',
|
||||||
|
used: '380G',
|
||||||
|
free: '106G',
|
||||||
|
usagePercent: '78%',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
lastUpdated: '2026-04-02T12:00:00.000Z',
|
||||||
|
},
|
||||||
|
},
|
||||||
|
];
|
||||||
|
|
||||||
|
const rawJson = formatServerList(servers).split('\nRaw JSON:\n')[1];
|
||||||
|
|
||||||
|
assert.deepStrictEqual(JSON.parse(rawJson), servers);
|
||||||
|
// 缩进换行是这里的主要体积来源，压缩后应只剩一行
|
||||||
|
assert.ok(!rawJson.includes('\n'));
|
||||||
|
assert.ok(rawJson.length < JSON.stringify(servers, null, 2).length * 0.7);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,62 @@
|
|||||||
|
import test from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { redactSecret, redactSecrets } from '../build/utils/redact.js';
|
||||||
|
import { SSHConnectionManager } from '../build/services/ssh-connection-manager.js';
|
||||||
|
|
||||||
|
test('redactSecret masks long secrets everywhere', () => {
|
||||||
|
const text = 'login with hunter2hunter2 then done';
|
||||||
|
assert.strictEqual(redactSecret(text, 'hunter2'), 'login with [REDACTED][REDACTED] then done');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret masks long secret even mid-word', () => {
|
||||||
|
assert.strictEqual(
|
||||||
|
redactSecret('password: secretvalue and secretvalueagain', 'secretvalue'),
|
||||||
|
'password: [REDACTED] and [REDACTED]again',
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret masks short secrets only as whole tokens', () => {
|
||||||
|
// 2-3 char secrets are only replaced when they stand alone
|
||||||
|
const text = 'the cat sat on a mat';
|
||||||
|
assert.strictEqual(redactSecret(text, 'cat'), 'the [REDACTED] sat on a mat');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret ignores short secret inside a word', () => {
|
||||||
|
// "cat" inside "catastrophe" must not be destroyed
|
||||||
|
assert.strictEqual(redactSecret('a catastrophe', 'cat'), 'a catastrophe');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret ignores empty and 1-char secrets', () => {
|
||||||
|
assert.strictEqual(redactSecret('abc', ''), 'abc');
|
||||||
|
assert.strictEqual(redactSecret('abc', 'a'), 'abc');
|
||||||
|
assert.strictEqual(redactSecret('abc', undefined), 'abc');
|
||||||
|
assert.strictEqual(redactSecret('abc', null), 'abc');
|
||||||
|
assert.strictEqual(redactSecret('', 'secret'), '');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret escapes regex special characters', () => {
|
||||||
|
const text = 'tokens like a.b and aXb';
|
||||||
|
assert.strictEqual(redactSecret(text, 'a.b'), 'tokens like [REDACTED] and aXb');
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecrets redacts many secrets at once', () => {
|
||||||
|
const text = 'user=alice pass=topsecret key=pLskey-end';
|
||||||
|
assert.strictEqual(
|
||||||
|
redactSecrets(text, ['topsecret', 'pLskey']),
|
||||||
|
'user=alice pass=[REDACTED] key=[REDACTED]-end',
|
||||||
|
);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('redactSecret returns original when no match', () => {
|
||||||
|
const text = 'nothing sensitive here';
|
||||||
|
assert.strictEqual(redactSecret(text, 'nope'), text);
|
||||||
|
});
|
||||||
|
|
||||||
|
test('dynamic mode config requires host and username', async () => {
|
||||||
|
const manager = SSHConnectionManager.getInstance();
|
||||||
|
|
||||||
|
await assert.rejects(
|
||||||
|
() => manager.executeCommandDynamic({ username: 'root' }, 'id'),
|
||||||
|
(err) => err?.code === 'SSH_CONFIG_MISSING',
|
||||||
|
);
|
||||||
|
});
|
||||||
@@ -0,0 +1,310 @@
|
|||||||
|
import { describe, it, before, after } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { lookupSshConfig } from '../build/utils/ssh-config-parser.js';
|
||||||
|
import * as fs from 'fs';
|
||||||
|
import * as path from 'path';
|
||||||
|
import * as os from 'os';
|
||||||
|
let fixturesDir;
|
||||||
|
|
||||||
|
describe('SSH Config Parser', () => {
|
||||||
|
let testConfigPath;
|
||||||
|
let testConfigWithIncludePath;
|
||||||
|
let includedConfigPath;
|
||||||
|
let originalHome;
|
||||||
|
|
||||||
|
before(() => {
|
||||||
|
originalHome = process.env.HOME;
|
||||||
|
fixturesDir = fs.mkdtempSync(path.join(os.tmpdir(), 'ssh-mcp-config-test-'));
|
||||||
|
|
||||||
|
testConfigPath = path.join(fixturesDir, 'ssh-config-basic');
|
||||||
|
testConfigWithIncludePath = path.join(fixturesDir, 'ssh-config-include');
|
||||||
|
includedConfigPath = path.join(fixturesDir, 'ssh-config-included');
|
||||||
|
|
||||||
|
// 基本测试配置
|
||||||
|
fs.writeFileSync(testConfigPath, [
|
||||||
|
'# 多别名测试',
|
||||||
|
'Host dev staging',
|
||||||
|
' HostName 192.168.1.100',
|
||||||
|
' Port 2222',
|
||||||
|
' User devuser',
|
||||||
|
' IdentityFile ~/.ssh/dev_key',
|
||||||
|
'',
|
||||||
|
'# 单别名测试',
|
||||||
|
'Host prod',
|
||||||
|
' HostName 10.0.0.50',
|
||||||
|
' User produser',
|
||||||
|
' IdentityFile ~/.ssh/prod_key',
|
||||||
|
'',
|
||||||
|
'# 通配符测试',
|
||||||
|
'Host *.example.com',
|
||||||
|
' User wildcarduser',
|
||||||
|
' Port 2200',
|
||||||
|
'',
|
||||||
|
'# 全局默认值',
|
||||||
|
'Host *',
|
||||||
|
' Port 22',
|
||||||
|
' User defaultuser',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
// 被包含的配置文件
|
||||||
|
fs.writeFileSync(includedConfigPath, [
|
||||||
|
'Host included-host',
|
||||||
|
' HostName 172.16.0.1',
|
||||||
|
' Port 3333',
|
||||||
|
' User includeduser',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
// 带 Include 的配置文件
|
||||||
|
fs.writeFileSync(testConfigWithIncludePath, [
|
||||||
|
`Include ${includedConfigPath}`,
|
||||||
|
'',
|
||||||
|
'Host main-host',
|
||||||
|
' HostName 192.168.1.1',
|
||||||
|
' User mainuser',
|
||||||
|
'',
|
||||||
|
'Host *',
|
||||||
|
' Port 22',
|
||||||
|
].join('\n'));
|
||||||
|
});
|
||||||
|
|
||||||
|
after(() => {
|
||||||
|
process.env.HOME = originalHome;
|
||||||
|
fs.rmSync(fixturesDir, { recursive: true, force: true });
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('基本功能', () => {
|
||||||
|
it('应该正确解析单个 Host 别名', () => {
|
||||||
|
const config = lookupSshConfig('prod', testConfigPath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '10.0.0.50');
|
||||||
|
assert.strictEqual(config.user, 'produser');
|
||||||
|
assert.strictEqual(config.identityFile, path.join(os.homedir(), '.ssh', 'prod_key'));
|
||||||
|
assert.strictEqual(config.port, 22); // 从 Host * fallback
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析多别名 Host 行 - dev', () => {
|
||||||
|
const config = lookupSshConfig('dev', testConfigPath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '192.168.1.100');
|
||||||
|
assert.strictEqual(config.port, 2222);
|
||||||
|
assert.strictEqual(config.user, 'devuser');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确解析多别名 Host 行 - staging', () => {
|
||||||
|
const config = lookupSshConfig('staging', testConfigPath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '192.168.1.100');
|
||||||
|
assert.strictEqual(config.port, 2222);
|
||||||
|
assert.strictEqual(config.user, 'devuser');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持通配符匹配', () => {
|
||||||
|
const config = lookupSshConfig('server.example.com', testConfigPath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.user, 'wildcarduser');
|
||||||
|
assert.strictEqual(config.port, 2200);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该使用 Host * 作为默认值', () => {
|
||||||
|
const config = lookupSshConfig('unknown-host', testConfigPath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.user, 'defaultuser');
|
||||||
|
assert.strictEqual(config.port, 22);
|
||||||
|
assert.strictEqual(config.hostName, undefined);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('通配符匹配应转义正则特殊字符', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'special-pattern-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'Host host[1]',
|
||||||
|
' User literaluser',
|
||||||
|
'',
|
||||||
|
'Host *',
|
||||||
|
' User defaultuser',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const literalConfig = lookupSshConfig('host[1]', tempConfig);
|
||||||
|
const regexLikeConfig = lookupSshConfig('host1', tempConfig);
|
||||||
|
|
||||||
|
assert.ok(literalConfig);
|
||||||
|
assert.strictEqual(literalConfig.user, 'literaluser');
|
||||||
|
assert.ok(regexLikeConfig);
|
||||||
|
assert.strictEqual(regexLikeConfig.user, 'defaultuser');
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该支持 Host 中的否定模式', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'negated-pattern-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'Host *.example.com !blocked.example.com',
|
||||||
|
' User wildcarduser',
|
||||||
|
'',
|
||||||
|
'Host *',
|
||||||
|
' User defaultuser',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const allowedConfig = lookupSshConfig('app.example.com', tempConfig);
|
||||||
|
const blockedConfig = lookupSshConfig('blocked.example.com', tempConfig);
|
||||||
|
|
||||||
|
assert.ok(allowedConfig);
|
||||||
|
assert.strictEqual(allowedConfig.user, 'wildcarduser');
|
||||||
|
assert.ok(blockedConfig);
|
||||||
|
assert.strictEqual(blockedConfig.user, 'defaultuser');
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('Include 指令', () => {
|
||||||
|
it('应该正确处理 Include 指令', () => {
|
||||||
|
const config = lookupSshConfig('included-host', testConfigWithIncludePath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '172.16.0.1');
|
||||||
|
assert.strictEqual(config.port, 3333);
|
||||||
|
assert.strictEqual(config.user, 'includeduser');
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该在 Include 后继续解析主配置文件', () => {
|
||||||
|
const config = lookupSshConfig('main-host', testConfigWithIncludePath);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '192.168.1.1');
|
||||||
|
assert.strictEqual(config.user, 'mainuser');
|
||||||
|
assert.strictEqual(config.port, 22);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该静默跳过不存在的 Include 文件', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'temp-include-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'Include /nonexistent/path/config',
|
||||||
|
'',
|
||||||
|
'Host test',
|
||||||
|
' HostName 1.2.3.4',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const config = lookupSshConfig('test', tempConfig);
|
||||||
|
assert.ok(config, '应该返回非 null 的配置');
|
||||||
|
assert.strictEqual(config.hostName, '1.2.3.4');
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('边界情况', () => {
|
||||||
|
it('默认配置文件不存在时应返回 null', () => {
|
||||||
|
const fakeHome = fs.mkdtempSync(path.join(fixturesDir, 'fake-home-'));
|
||||||
|
process.env.HOME = fakeHome;
|
||||||
|
|
||||||
|
try {
|
||||||
|
const config = lookupSshConfig('any-host');
|
||||||
|
assert.strictEqual(config, null);
|
||||||
|
} finally {
|
||||||
|
process.env.HOME = originalHome;
|
||||||
|
fs.rmSync(fakeHome, { recursive: true, force: true });
|
||||||
|
}
|
||||||
|
});
|
||||||
|
|
||||||
|
it('显式指定的配置文件不存在时应抛出错误', () => {
|
||||||
|
assert.throws(() => {
|
||||||
|
lookupSshConfig('any-host', '/nonexistent/config');
|
||||||
|
}, /not found/);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('未找到匹配的 Host 时应返回 null', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'empty-config');
|
||||||
|
fs.writeFileSync(tempConfig, '# Empty config\n');
|
||||||
|
|
||||||
|
const config = lookupSshConfig('any-host', tempConfig);
|
||||||
|
assert.strictEqual(config, null);
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确展开 ~ 路径', () => {
|
||||||
|
const config = lookupSshConfig('dev', testConfigPath);
|
||||||
|
assert.ok(config);
|
||||||
|
assert.ok(config.identityFile.startsWith(os.homedir()));
|
||||||
|
assert.ok(!config.identityFile.includes('~'));
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理注释行', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'comment-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'# 这是注释',
|
||||||
|
'Host test',
|
||||||
|
' HostName 1.2.3.4 # 行内注释',
|
||||||
|
' Port 2222',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const config = lookupSshConfig('test', tempConfig);
|
||||||
|
assert.ok(config);
|
||||||
|
assert.strictEqual(config.hostName, '1.2.3.4');
|
||||||
|
assert.strictEqual(config.port, 2222);
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('应该正确处理空白行和缩进', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'whitespace-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'',
|
||||||
|
' Host test ',
|
||||||
|
' HostName 1.2.3.4 ',
|
||||||
|
'',
|
||||||
|
' Port 2222 ',
|
||||||
|
'',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const config = lookupSshConfig('test', tempConfig);
|
||||||
|
assert.ok(config);
|
||||||
|
assert.strictEqual(config.hostName, '1.2.3.4');
|
||||||
|
assert.strictEqual(config.port, 2222);
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
|
||||||
|
describe('First-match-wins 语义', () => {
|
||||||
|
it('应该使用第一个匹配的值', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'priority-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'Host test',
|
||||||
|
' Port 2222',
|
||||||
|
' User firstuser',
|
||||||
|
'',
|
||||||
|
'Host test',
|
||||||
|
' Port 3333',
|
||||||
|
' User seconduser',
|
||||||
|
'',
|
||||||
|
'Host *',
|
||||||
|
' Port 22',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const config = lookupSshConfig('test', tempConfig);
|
||||||
|
assert.ok(config);
|
||||||
|
assert.strictEqual(config.port, 2222);
|
||||||
|
assert.strictEqual(config.user, 'firstuser');
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('特定 Host 的值应优先于 Host *', () => {
|
||||||
|
const tempConfig = path.join(fixturesDir, 'specific-priority-config');
|
||||||
|
fs.writeFileSync(tempConfig, [
|
||||||
|
'Host specific',
|
||||||
|
' Port 2222',
|
||||||
|
'',
|
||||||
|
'Host *',
|
||||||
|
' Port 22',
|
||||||
|
' User globaluser',
|
||||||
|
].join('\n'));
|
||||||
|
|
||||||
|
const config = lookupSshConfig('specific', tempConfig);
|
||||||
|
assert.ok(config);
|
||||||
|
assert.strictEqual(config.port, 2222); // 来自 Host specific
|
||||||
|
assert.strictEqual(config.user, 'globaluser'); // 来自 Host *
|
||||||
|
|
||||||
|
fs.unlinkSync(tempConfig);
|
||||||
|
});
|
||||||
|
});
|
||||||
|
});
|
||||||
File diff suppressed because it is too large
Load Diff
@@ -0,0 +1,159 @@
|
|||||||
|
import { describe, it } from 'node:test';
|
||||||
|
import assert from 'node:assert';
|
||||||
|
import { collectSystemStatus } from '../build/utils/status-collector.js';
|
||||||
|
|
||||||
|
const PROBE_PATTERN = /printf '\\n(__MCP_FIELD_\w+_)(\w+)\\n'/g;
|
||||||
|
|
||||||
|
/** Field names in the order the script probes them, plus the shared marker. */
|
||||||
|
function readProbes(script) {
|
||||||
|
const probes = [...script.matchAll(PROBE_PATTERN)];
|
||||||
|
return {
|
||||||
|
marker: probes[0]?.[1],
|
||||||
|
fields: probes.map((probe) => probe[2]),
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
/**
|
||||||
|
* Stand-in for the remote shell: emits the marker line for every probe the
|
||||||
|
* script declares, followed by whatever `values` supplies for it.
|
||||||
|
*/
|
||||||
|
function fakeRemote(values, { lineEnding = '\n' } = {}) {
|
||||||
|
return (script) => {
|
||||||
|
const { marker, fields } = readProbes(script);
|
||||||
|
const output = fields
|
||||||
|
.map((field) => `${marker}${field}${lineEnding}${values[field] ?? ''}`)
|
||||||
|
.join(lineEnding);
|
||||||
|
return Promise.resolve(lineEnding + output);
|
||||||
|
};
|
||||||
|
}
|
||||||
|
|
||||||
|
describe('status collector', () => {
|
||||||
|
it('所有探针合并为一条单行命令', async () => {
|
||||||
|
const scripts = [];
|
||||||
|
await collectSystemStatus((script) => {
|
||||||
|
scripts.push(script);
|
||||||
|
return Promise.resolve('');
|
||||||
|
}, 'dev');
|
||||||
|
|
||||||
|
assert.strictEqual(scripts.length, 1);
|
||||||
|
// 多行脚本会被 commandTemplate 的引号包裹破坏
|
||||||
|
assert.ok(!scripts[0].includes('\n'));
|
||||||
|
// 每个探针都被隔离，单个失败不影响其余，且整体以成功退出
|
||||||
|
assert.ok(scripts[0].endsWith('; true'));
|
||||||
|
|
||||||
|
const { fields } = readProbes(scripts[0]);
|
||||||
|
assert.ok(fields.includes('hostname'));
|
||||||
|
assert.ok(fields.includes('servicesInstalled'));
|
||||||
|
assert.strictEqual(new Set(fields).size, fields.length);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('按 marker 还原各字段', async () => {
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
fakeRemote({
|
||||||
|
hostname: 'web-01',
|
||||||
|
osName: 'Linux',
|
||||||
|
kernelVersion: '6.1.0',
|
||||||
|
memory: 'free:2.1G total:7.7G',
|
||||||
|
processes: '181',
|
||||||
|
threads: '901',
|
||||||
|
}),
|
||||||
|
'dev',
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(status.reachable, true);
|
||||||
|
assert.strictEqual(status.hostname, 'web-01');
|
||||||
|
assert.strictEqual(status.osName, 'Linux');
|
||||||
|
assert.strictEqual(status.kernelVersion, '6.1.0');
|
||||||
|
assert.deepStrictEqual(status.memory, { free: '2.1G', total: '7.7G' });
|
||||||
|
// 解析时会各减去一行表头
|
||||||
|
assert.deepStrictEqual(status.processes, { running: 180, threads: 900 });
|
||||||
|
});
|
||||||
|
|
||||||
|
// 多行字段是 CRLF 归一化真正起作用的地方：逐行拆分的值不会再单独 trim，
|
||||||
|
// 残留的 \r 会直接进入结果。
|
||||||
|
it('pty 的 CRLF 输出同样能解析', async () => {
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
fakeRemote(
|
||||||
|
{
|
||||||
|
hostname: 'web-02',
|
||||||
|
ipAddresses: '10.0.0.7\r\n192.168.1.5',
|
||||||
|
drives: '/dev/sda1|50G|20G|30G|40%|/',
|
||||||
|
},
|
||||||
|
{ lineEnding: '\r\n' },
|
||||||
|
),
|
||||||
|
'dev',
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(status.hostname, 'web-02');
|
||||||
|
assert.deepStrictEqual(status.ipAddresses, ['10.0.0.7', '192.168.1.5']);
|
||||||
|
assert.deepStrictEqual(status.drives, [
|
||||||
|
{
|
||||||
|
device: '/dev/sda1',
|
||||||
|
total: '50G',
|
||||||
|
used: '20G',
|
||||||
|
free: '30G',
|
||||||
|
usagePercent: '40%',
|
||||||
|
mountPoint: '/',
|
||||||
|
},
|
||||||
|
]);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('空探针不影响其它字段', async () => {
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
fakeRemote({ hostname: 'web-03', ipAddresses: '', osName: 'Linux' }),
|
||||||
|
'dev',
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(status.hostname, 'web-03');
|
||||||
|
assert.strictEqual(status.osName, 'Linux');
|
||||||
|
assert.strictEqual(status.ipAddresses, undefined);
|
||||||
|
});
|
||||||
|
|
||||||
|
// 命令白名单会拒绝这条探针脚本；那种情况下字段留空即可，
|
||||||
|
// 不能把主机报成不可达。
|
||||||
|
it('命令被拒绝时字段留空但仍视为可达', async () => {
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
() => Promise.reject(new Error('Command validation failed')),
|
||||||
|
'dev',
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(status.reachable, true);
|
||||||
|
assert.strictEqual(status.hostname, undefined);
|
||||||
|
assert.ok(status.lastUpdated);
|
||||||
|
});
|
||||||
|
|
||||||
|
it('先逐条授权探针，再只批量执行允许的命令', async () => {
|
||||||
|
const scripts = [];
|
||||||
|
const recordingRemote = fakeRemote({ hostname: 'allowed-host' });
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
(script) => {
|
||||||
|
scripts.push(script);
|
||||||
|
return recordingRemote(script);
|
||||||
|
},
|
||||||
|
'dev',
|
||||||
|
(command) => command === 'hostname',
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(status.hostname, 'allowed-host');
|
||||||
|
assert.strictEqual(scripts.length, 1);
|
||||||
|
assert.match(scripts[0], /hostname/);
|
||||||
|
assert.ok(!scripts[0].includes('uname -s'));
|
||||||
|
assert.ok(!scripts[0].includes('cat /etc/os-release'));
|
||||||
|
});
|
||||||
|
|
||||||
|
it('没有获准探针时不执行远端脚本', async () => {
|
||||||
|
let calls = 0;
|
||||||
|
const status = await collectSystemStatus(
|
||||||
|
async () => {
|
||||||
|
calls += 1;
|
||||||
|
return '';
|
||||||
|
},
|
||||||
|
'dev',
|
||||||
|
() => false,
|
||||||
|
);
|
||||||
|
|
||||||
|
assert.strictEqual(calls, 0);
|
||||||
|
assert.strictEqual(status.reachable, true);
|
||||||
|
assert.strictEqual(status.hostname, undefined);
|
||||||
|
});
|
||||||
|
});
|
||||||
@@ -0,0 +1,15 @@
|
|||||||
|
{
|
||||||
|
"compilerOptions": {
|
||||||
|
"target": "ES2022",
|
||||||
|
"module": "Node16",
|
||||||
|
"moduleResolution": "Node16",
|
||||||
|
"outDir": "./build",
|
||||||
|
"rootDir": "./src",
|
||||||
|
"strict": true,
|
||||||
|
"esModuleInterop": true,
|
||||||
|
"skipLibCheck": true,
|
||||||
|
"forceConsistentCasingInFileNames": true
|
||||||
|
},
|
||||||
|
"include": ["src/**/*"],
|
||||||
|
"exclude": ["node_modules"]
|
||||||
|
}
|
||||||
Reference in New Issue
Block a user