Metadata-Version: 2.5
Name: ssh-connector-mcp
Version: 0.1.0
Summary: Minimal SSH connector exposed as an MCP server over stdio, built on paramiko.
Author: newtouch
Keywords: mcp,paramiko,remote,sftp,ssh
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Topic :: System :: Systems Administration
Classifier: Topic :: Terminals
Requires-Python: >=3.10
Requires-Dist: mcp<2.0.0,>=1.10.0
Requires-Dist: paramiko<5.0.0,>=3.4.0
Description-Content-Type: text/markdown

# SSH Connector MCP

一个最小化的 SSH 连接器，以 MCP（Model Context Protocol）server 的形式提供，使用 **stdio** 传输，可被任意 MCP 客户端（Trae、Claude Desktop、Cursor 等）直接配置加载。底层基于 Python + [paramiko](https://www.paramiko.org/)。

只提供常规 SSH 基础操作：连接/断开、远程执行命令、上传文件、下载文件、列出远程目录。支持密码与私钥两种认证方式，**主机指纹始终校验，不提供跳过开关**。

## 目录结构

```
ssh-connector-mcp/
├── pyproject.toml                 # 项目与依赖声明、MCP 入口
├── requirements.txt               # 依赖列表（pip install -r 用）
├── README.md
└── src/
    └── ssh_connector_mcp/
        ├── __init__.py
        ├── __main__.py            # python -m ssh_connector_mcp
        ├── server.py              # MCP 工具定义 + stdio 启动
        └── session.py             # 会话管理、SSH/SFTP 操作、主机指纹校验
```

## 安装

要求 Python 3.10+。

```powershell
cd ssh-connector-mcp
python -m venv .venv
.\.venv\Scripts\python.exe -m pip install -e .
```

（Linux/macOS 下使用 `.venv/bin/python -m pip install -e .`。）

安装后会生成 `ssh-connector-mcp` 命令（位于虚拟环境的 `Scripts/` 或 `bin/` 下），等价于 `python -m ssh_connector_mcp`。

## MCP 客户端配置示例

把项目虚拟环境中的 Python 绝对路径填入 `command`（Windows 路径中的反斜杠需要写成 `\\`）：

```json
{
  "mcpServers": {
    "ssh-connector": {
      "command": "C:\\path\\to\\ssh-connector-mcp\\.venv\\Scripts\\python.exe",
      "args": ["-m", "ssh_connector_mcp"]
    }
  }
}
```

如果虚拟环境的 `Scripts`/`bin` 已在 `PATH` 中，也可以直接使用安装好的入口：

```json
{
  "mcpServers": {
    "ssh-connector": {
      "command": "ssh-connector-mcp"
    }
  }
}
```

两种方式都是 stdio 传输，无需额外参数或环境变量。

## 作为 Trae 插件使用（PyPI + uvx）

`plugin/` 目录是按 Trae 插件结构组织的跨平台插件包，运行时由 `uvx` 从 PyPI 拉取，不包含任何平台相关的二进制：

```
plugin/
├── .trae-plugin/plugin.json   # 插件清单（名称、版本、图标、i18n 描述）
├── .mcp.json                  # MCP 启动声明：uvx --from ssh-connector-mcp==0.1.0 ssh-connector-mcp
└── assets/icon.svg
```

前置条件：安装 [uv](https://docs.astral.sh/uv/)（`pip install uv` 或官方安装脚本），并确保 `uvx` 在 `PATH` 中。

发布到 PyPI：

```bash
cd ssh-connector-mcp
uv build        # 生成 dist/*.whl 和 dist/*.tar.gz
uv publish      # 需要 PyPI API token（UV_PUBLISH_TOKEN 或交互输入）
```

发布后验证一次：

```bash
uvx --from ssh-connector-mcp==0.1.0 ssh-connector-mcp
```

本地加载插件：把 `plugin/` 整体放到插件目录（如 `%USERPROFILE%\.trae-cn\plugins\local\ssh-connector\0.1.0\`）后重启客户端；具体的本地加载入口以当前客户端版本为准。提交市场时，该目录内容即为插件包。

版本升级时需同步修改三处：`pyproject.toml` 的 `version`、`plugin/.trae-plugin/plugin.json` 的 `version`、`plugin/.mcp.json` 中固定的 `ssh-connector-mcp==x.y.z`。

## 主机指纹校验

服务端**不会**自动信任未知主机，也不提供 `AutoAddPolicy` 之类的跳过选项：

- 连接时加载 `~/.ssh/known_hosts`；如果传入了 `known_hosts_path`，额外加载该文件。
- 若主机密钥不存在于 known_hosts，或与已记录密钥不一致，连接会被拒绝，错误信息中会给出服务器实际出示的密钥类型与 `SHA256:...` 指纹，以及添加方法，例如：

```bash
# 先在可信渠道核对该指纹，再执行（非默认端口请带 -p）
ssh-keyscan -p 22 192.168.1.10 >> ~/.ssh/known_hosts
```

非 22 端口的 known_hosts 条目形式为 `[host]:port`，`ssh-keyscan -p` 会自动按此格式写入。

## 工具说明

所有工具共用 `session_id` 来定位连接，默认值均为 `"default"`。同一时间可用不同 `session_id` 维持多个连接。

### `ssh_connect`

建立并保留一个 SSH 会话。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `host` | string | 必填 | 远程主机名或 IP |
| `username` | string | 必填 | 登录用户名 |
| `password` | string | `null` | 密码认证；与 `private_key_path` 至少提供一个 |
| `private_key_path` | string | `null` | 私钥文件路径（RSA/ECDSA/Ed25519），支持 `~` |
| `private_key_passphrase` | string | `null` | 私钥口令（如私钥有加密） |
| `known_hosts_path` | string | `null` | 额外信任的 known_hosts 文件；不存在会报错 |
| `port` | integer | `22` | SSH 端口 |
| `session_id` | string | `"default"` | 会话名，供后续工具使用；重名会报错 |
| `connect_timeout` | number | `15` | TCP/握手/认证超时（秒） |

返回：`session_id`、`host`、`port`、`username`、`server_banner`、`host_key_type`、`host_key_fingerprint`、`known_hosts_files`。

不会使用 ssh-agent，也不会自动搜索 `~/.ssh/id_*`，认证方式完全由参数决定。

### `ssh_disconnect`

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `session_id` | string | `"default"` | 要关闭的会话 |

返回 `disconnected: true`；若会话不存在则返回 `disconnected: false`，不视为错误。

### `ssh_execute`

执行单条非交互命令，返回输出与退出码。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `command` | string | 必填 | 远程 shell 命令 |
| `session_id` | string | `"default"` | 已连接的会话 |
| `timeout` | number | `60` | 命令最长等待秒数；超时会关闭该 channel |

返回：`exit_status`、`stdout`、`stderr`、`truncated`（stdout/stderr 各自最多保留 1 MiB，被截断时为 `true`）。命令以 UTF-8 解码，非法字节替换为 `�`。

### `ssh_upload_file`

通过 SFTP 上传本地文件，远端同名文件会被覆盖。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `local_path` | string | 必填 | 运行本 MCP server 的机器上的文件路径 |
| `remote_path` | string | 必填 | 远端目标路径（目录需已存在） |
| `session_id` | string | `"default"` | 已连接的会话 |

返回：`local_path`、`remote_path`、`size`。

### `ssh_download_file`

通过 SFTP 下载远端文件，本地父目录会自动创建。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `remote_path` | string | 必填 | 远端源文件路径 |
| `local_path` | string | 必填 | 本地目标路径 |
| `session_id` | string | `"default"` | 已连接的会话 |

返回：`remote_path`、`local_path`、`size`。

### `ssh_list_directory`

列出远端目录内容。

| 参数 | 类型 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `remote_path` | string | `"."` | 远端目录路径 |
| `session_id` | string | `"default"` | 已连接的会话 |

返回 `path`、`count` 与 `entries`，每个条目包含 `name`、`path`、`type`（`file` / `dir` / `symlink`）、`size`、`mode`（如 `-rw-r--r--`）、`modified`（UTC ISO 8601）。

## 典型调用顺序

1. `ssh_connect` → 得到一个 `session_id`
2. `ssh_execute` 执行 `uname -a`、部署命令等
3. `ssh_list_directory` / `ssh_upload_file` / `ssh_download_file` 处理文件
4. `ssh_disconnect` 释放连接（不调用也会在进程退出时自动关闭）

## 安全说明

- 主机密钥严格校验；未知或变更的密钥直接导致连接失败，并返回 SHA256 指纹便于人工核对。
- 密码、私钥口令只用于当次认证，不会被记录、回显或写入磁盘。
- 连接禁用 ssh-agent 与默认私钥自动搜索，避免隐式使用预期外的凭据。
- 每个会话内的操作串行执行（会话级锁），输出总量有上限，命令有超时。
- 会话仅保存在进程内存中，MCP server 重启后需重新连接。

## 已知限制

- 只执行单条非交互命令，不提供交互式 shell、PTY 或 `sudo` 密码自动输入。
- 不提供端口转发、跳板机、密钥生成、递归目录传输等扩展能力。
- 所有路径均为运行 MCP server 的本地机器视角；文件内容不经过 MCP 消息传递。
