# 安装手册

## 先由 AI 询问安装方式

将安装任务交给 AI 时，AI 必须先询问并等待安装者选择：**独立本机使用、接入已有中心、部署自己的中心**；随后确认要接入的客户端，或是否只安装程序并生成配置。完整问法见 [START_HERE.md](../START_HERE.md)。不能预设安装方式，也不能自动选择检测到的客户端。

本页后续步骤适用于安装者选择的**独立本机方式**。已有中心或自建中心按 [CENTER.md](CENTER.md) 继续；中心地址、Key、部署目标只在该方式被选中后获取。已有明确选择时沿用，不重复索要；其他安装依赖和写入必须与所选范围一致。

## 1. 校验和安装程序

Linux 在解压根目录运行：

```bash
sha256sum -c SHA256SUMS
bash ./linux-x86_64/install.sh
```

默认安装到 `~/.local/share/sshmcp/releases/5.1.1/`，也可传 `--prefix /绝对路径`。程序和 helper 作为同一版本保存；同一目标文件已有不同内容时停止，不覆盖活动程序。

Windows 在解压根目录打开 PowerShell：

```powershell
Get-Content .\SHA256SUMS | ForEach-Object {
  $expected, $name = $_ -split '  ', 2
  if ((Get-FileHash -LiteralPath $name -Algorithm SHA256).Hash.ToLowerInvariant() -ne $expected) {
    throw "Checksum mismatch: $name"
  }
}
powershell -NoProfile -ExecutionPolicy Bypass -File .\windows-x86_64\Install.ps1
```

默认安装到 `%LOCALAPPDATA%\SSHMCP\releases\5.1.1\`，也可给脚本传 `-Destination 'C:\用户私有目录\SSHMCP'`。`ExecutionPolicy Bypass` 只针对这一次脚本进程，不修改全局执行策略。脚本输出 JSON 中的 executable 是实际程序位置。

也可把对应平台目录整体放到稳定目录，直接引用其中程序。不要只复制主程序：必须保留 `sshmcp-file-agent`，它是在远端 Linux 上执行的静态助手。双击主程序没有设置界面；stdio 模式等待 MCP 客户端输入是正常行为。

## 2. 准备自己的目录

建议把本机配置放在用户私有目录，例如 Linux `~/.config/sshmcp/`，Windows `%USERPROFILE%\.sshmcp-standalone\`。首次使用可复制 `config/ssh-config.empty.toml` 为 `ssh-config.toml`，同时新建空 `standalone.env`。已有文件只合并需要的配置，不覆盖。

Linux 目录权限建议 0700、文件 0600；Windows 保留当前用户的私密 ACL。两份文件后续可能保存认证材料，不随软件分发。参考 `config/ssh-config.example.toml` 添加自己的服务器，或接入 AI 后使用 ssh_server_manage。

## 3. 接入 MCP 客户端

下面的 `/ABS/...` 和 `C:/Users/YOU/...` 都必须换成真实绝对路径，不能原样复制。安装脚本仅安装文件；接入配置由你或 AI 合并到实际使用的客户端。

Codex：常见用户配置为 `~/.codex/config.toml`（Windows 也在用户目录下）。保留原文件其他内容：

```toml
[mcp_servers.ssh-manager]
command = "/ABS/sshmcp/releases/5.1.1/mcp-ssh-manager"
args = ["--stdio"]
startup_timeout_ms = 20000

[mcp_servers.ssh-manager.env]
SSH_CONFIG_PATH = "/ABS/private/ssh-config.toml"
SSH_ENV_PATH = "/ABS/private/standalone.env"
```

Windows 的 command 改为安装输出的 `mcp-ssh-manager.exe` 绝对路径。TOML/JSON 路径可用正斜杠，避免反斜杠转义错误。

JSON 客户端合并示例：

```json
{
  "mcpServers": {
    "sshmcp": {
      "command": "C:/Users/YOU/AppData/Local/SSHMCP/releases/5.1.1/mcp-ssh-manager.exe",
      "args": ["--stdio"],
      "env": {
        "SSH_CONFIG_PATH": "C:/Users/YOU/.sshmcp-standalone/ssh-config.toml",
        "SSH_ENV_PATH": "C:/Users/YOU/.sshmcp-standalone/standalone.env"
      }
    }
  }
}
```

本程序适配器采用的常见位置如下；客户端或环境变量有自定义时以实际路径为准。

| 客户端 | 常见用户配置位置 |
| --- | --- |
| Snow | `~/.snow/settings.json` |
| Pi（已启用 MCP adapter） | `~/.pi/agent/mcp.json` |
| Claude Code | `~/.claude.json` |
| Claude Desktop / Windows | `%APPDATA%\Claude\claude_desktop_config.json` |

Linux 只有相应客户端已安装并支持 stdio 时才适用，不因为目录存在就认为官方桌面程序已安装。网页聊天界面不会自动获得本机文件和网络。

## 4. 完成验收

重载客户端的 MCP 连接，让 AI 调用 `ssh_list_servers`。首次空目录应返回 count=0；加入自己的服务器后名称应可见。使用一个只读命令验证 SSH 登录。程序 `--version` 返回版本只能证明可执行，不能替代 MCP discovery 或实际 SSH 验证。