mcp-hydrocoder-ssh 0.1.2 → 0.1.3

package/CONFIG-GUIDE.md

@@ -0,0 +1,148 @@
+# 配置指南
+
+[README 中文](README_CN.md) | [README English](README.md) | **中文** | [English](CONFIG-GUIDE_EN.md)
+
+## 配置文件位置
+
+配置文件位于用户目录：
+```
+~/.claude/ssh-mcp-config.json
+```
+**适用场景**：个人常用服务器，所有项目共享
+
+---
+
+## 配置示例
+
+### 使用 SSH Agent（推荐）
+```json
+{
+  "servers": [
+    {
+      "id": "prod-server",
+      "name": "Production Server",
+      "host": "example.com",
+      "port": 22,
+      "username": "deploy",
+      "authMethod": "agent"
+    }
+  ]
+}
+```
+
+### 使用私钥文件
+```json
+{
+  "servers": [
+    {
+      "id": "my-server",
+      "name": "My Server",
+      "host": "8.140.225.161",
+      "port": 22,
+      "username": "root",
+      "authMethod": "key",
+      "privateKeyPath": "D:\\Data\\aliyun-ecs\\docslim.pem"
+    }
+  ]
+}
+```
+
+### 使用密码（不推荐）
+```json
+{
+  "servers": [
+    {
+      "id": "test-server",
+      "name": "Test Server",
+      "host": "test.example.com",
+      "port": 22,
+      "username": "ubuntu",
+      "authMethod": "password",
+      "password": "your-password"
+    }
+  ]
+}
+```
+
+---
+
+## 完整配置
+
+```json
+{
+  "servers": [
+    {
+      "id": "prod-server",
+      "name": "Production Server",
+      "host": "prod.example.com",
+      "port": 22,
+      "username": "deploy",
+      "authMethod": "agent",
+      "connectTimeout": 30000
+    },
+    {
+      "id": "test-server",
+      "name": "Test Server",
+      "host": "test.example.com",
+      "port": 2222,
+      "username": "ubuntu",
+      "authMethod": "key",
+      "privateKeyPath": "~/.ssh/id_rsa",
+      "connectTimeout": 15000
+    }
+  ],
+  "settings": {
+    "defaultConnectTimeout": 30000,
+    "defaultKeepaliveInterval": 60000,
+    "commandTimeout": 60000,
+    "maxConnections": 5,
+    "autoReconnect": false,
+    "logCommands": true
+  }
+}
+```
+
+---
+
+## 字段说明
+
+### 服务器配置
+| 字段 | 必填 | 说明 |
+|------|------|------|
+| `id` | ✅ | 服务器唯一标识，用于连接命令 |
+| `name` | ✅ | 服务器名称，方便识别 |
+| `host` | ✅ | 服务器地址（IP 或域名） |
+| `port` | ❌ | SSH 端口，默认 22 |
+| `username` | ✅ | SSH 用户名 |
+| `authMethod` | ❌ | 认证方式：`agent` / `key` / `password`，默认 `agent` |
+| `privateKeyPath` | ❌ | 私钥路径（`authMethod=key` 时需要） |
+| `password` | ❌ | 密码（`authMethod=password` 时需要） |
+| `connectTimeout` | ❌ | 连接超时（毫秒），默认 30000 |
+
+### 全局设置
+| 字段 | 说明 | 默认值 |
+|------|------|--------|
+| `defaultConnectTimeout` | 默认连接超时 | 30000 |
+| `defaultKeepaliveInterval` | 默认心跳间隔（毫秒） | 60000 |
+| `commandTimeout` | 命令执行超时 | 60000 |
+| `maxConnections` | 最大连接数 | 5 |
+| `autoReconnect` | 自动重连 | false |
+| `logCommands` | 记录命令日志 | true |
+
+**心跳配置说明：** `defaultKeepaliveInterval` 用于设置 SSH 连接的心跳间隔，保持长连接活跃，防止因超时而断开。
+
+---
+
+## 常见问题
+
+### SSH Agent 未运行
+```bash
+# Windows：确保 "OpenSSH Authentication Agent" 服务正在运行
+# 或使用密钥文件认证方式
+```
+
+### 私钥权限问题
+确保私钥文件只有当前用户可读取。
+
+### 配置文件格式错误
+使用 JSON 验证工具检查语法。

package/CONFIG-GUIDE_EN.md

@@ -0,0 +1,148 @@
+# Configuration Guide
+
+[README 中文](README_CN.md) | [README English](README.md) | [中文](CONFIG-GUIDE.md) | **English**
+
+## Configuration File Location
+
+The configuration file is located in the user directory:
+```
+~/.claude/ssh-mcp-config.json
+```
+**Use case**: Personal frequently-used servers, shared across all projects
+
+---
+
+## Configuration Examples
+
+### Using SSH Agent (Recommended)
+```json
+{
+  "servers": [
+    {
+      "id": "prod-server",
+      "name": "Production Server",
+      "host": "example.com",
+      "port": 22,
+      "username": "deploy",
+      "authMethod": "agent"
+    }
+  ]
+}
+```
+
+### Using Private Key File
+```json
+{
+  "servers": [
+    {
+      "id": "my-server",
+      "name": "My Server",
+      "host": "8.140.225.161",
+      "port": 22,
+      "username": "root",
+      "authMethod": "key",
+      "privateKeyPath": "D:\\Data\\aliyun-ecs\\docslim.pem"
+    }
+  ]
+}
+```
+
+### Using Password (Not Recommended)
+```json
+{
+  "servers": [
+    {
+      "id": "test-server",
+      "name": "Test Server",
+      "host": "test.example.com",
+      "port": 22,
+      "username": "ubuntu",
+      "authMethod": "password",
+      "password": "your-password"
+    }
+  ]
+}
+```
+
+---
+
+## Complete Configuration
+
+```json
+{
+  "servers": [
+    {
+      "id": "prod-server",
+      "name": "Production Server",
+      "host": "prod.example.com",
+      "port": 22,
+      "username": "deploy",
+      "authMethod": "agent",
+      "connectTimeout": 30000
+    },
+    {
+      "id": "test-server",
+      "name": "Test Server",
+      "host": "test.example.com",
+      "port": 2222,
+      "username": "ubuntu",
+      "authMethod": "key",
+      "privateKeyPath": "~/.ssh/id_rsa",
+      "connectTimeout": 15000
+    }
+  ],
+  "settings": {
+    "defaultConnectTimeout": 30000,
+    "defaultKeepaliveInterval": 60000,
+    "commandTimeout": 60000,
+    "maxConnections": 5,
+    "autoReconnect": false,
+    "logCommands": true
+  }
+}
+```
+
+---
+
+## Field Descriptions
+
+### Server Configuration
+| Field | Required | Description |
+|-------|----------|-------------|
+| `id` | ✅ | Unique server identifier, used for connect command |
+| `name` | ✅ | Server name for easy identification |
+| `host` | ✅ | Server address (IP or domain) |
+| `port` | ❌ | SSH port, default 22 |
+| `username` | ✅ | SSH username |
+| `authMethod` | ❌ | Authentication method: `agent` / `key` / `password`, default `agent` |
+| `privateKeyPath` | ❌ | Private key path (required when `authMethod=key`) |
+| `password` | ❌ | Password (required when `authMethod=password`) |
+| `connectTimeout` | ❌ | Connection timeout (milliseconds), default 30000 |
+
+### Global Settings
+| Field | Description | Default |
+|-------|-------------|---------|
+| `defaultConnectTimeout` | Default connection timeout | 30000 |
+| `defaultKeepaliveInterval` | Default keepalive interval (milliseconds) | 60000 |
+| `commandTimeout` | Command execution timeout | 60000 |
+| `maxConnections` | Maximum connections | 5 |
+| `autoReconnect` | Auto reconnect | false |
+| `logCommands` | Log commands | true |
+
+**Keepalive Configuration:** `defaultKeepaliveInterval` sets the SSH connection keepalive interval to keep persistent connections active and prevent timeout disconnections.
+
+---
+
+## Troubleshooting
+
+### SSH Agent Not Running
+```bash
+# Windows: Ensure "OpenSSH Authentication Agent" service is running
+# Or use key file authentication method
+```
+
+### Private Key Permissions
+Ensure the private key file is readable only by the current user.
+
+### Configuration File Format Error
+Use a JSON validation tool to check syntax.

package/README_CN.md

@@ -0,0 +1,325 @@
+# mcp-hydrocoder-ssh
+
+**中文** | [English](README.md) | [Configuration Guide](CONFIG-GUIDE_EN.md) | [配置指南](CONFIG-GUIDE.md)
+
+为 Claude Code 提供 SSH 远程连接能力的 MCP 服务器。连接远程服务器、执行命令、自动化部署，无需单独打开 SSH 工具窗口。
+
+[![npm version](https://img.shields.io/npm/v/mcp-hydrocoder-ssh.svg)](https://www.npmjs.com/package/mcp-hydrocoder-ssh)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 第一部分：功能介绍
+
+### 这是什么？
+
+`mcp-hydrocoder-ssh` 是一个 MCP (Model Context Protocol) 服务器，让 Claude Code 能够：
+- 🔌 直接连接远程 SSH 服务器（后台长连接）
+- ⚡ 执行命令并获取完整输出
+- 🔄 保持连接状态，支持多步连续操作
+- 🚀 运行部署脚本（git pull、npm install、systemctl restart 等）
+
+### 主要好处
+
+| 好处 | 说明 |
+|------|------|
+| **无需切换窗口** | 在 Claude Code 对话中完成所有远程操作 |
+| **智能部署** | Claude 可根据命令输出自动判断下一步操作 |
+| **多服务器管理** | 同时管理多个服务器配置，快速切换 |
+| **安全认证** | 支持 SSH agent、密钥文件 |
+| **连接池管理** | 保持长连接，避免重复认证和连接开销 |
+
+### 可用工具
+
+**SSH 连接工具 (5 个)：**
+- `ssh_list_servers` - 列出所有配置的服务器
+- `ssh_connect` - 连接到指定服务器
+- `ssh_exec` - 执行命令（支持指定工作目录）
+- `ssh_get_status` - 获取连接状态
+- `ssh_disconnect` - 断开连接
+
+**配置管理工具 (5 个)：**
+- `ssh_add_server` - 添加新服务器配置
+- `ssh_remove_server` - 删除服务器配置
+- `ssh_update_server` - 更新服务器配置
+- `ssh_view_config` - 查看配置（过滤敏感信息）
+- `ssh_help` - 显示帮助信息
+
+---
+
+## 第二部分：快速安装（推荐）
+
+### 步骤 1：选择安装方式
+
+**方式 A：全局安装（推荐）**
+
+```bash
+npm install -g mcp-hydrocoder-ssh
+```
+
+**方式 B：使用 npx（无需安装）**
+
+```bash
+# 无需执行任何命令，直接在配置中使用 npx
+```
+
+---
+
+### 步骤 2：配置 Claude Code
+
+编辑用户目录的 `~/.claude.json` 文件：
+
+**Windows 路径：** `C:\Users\<你的用户名>\.claude.json`
+**macOS/Linux 路径：** `~/.claude.json`
+
+**方式 A（全局安装）的配置：**
+```json
+{
+  "mcpServers": {
+    "hydrossh": {
+      "command": "mcp-hydrocoder-ssh"
+    }
+  }
+}
+```
+
+**方式 B（npx）的配置：**
+```json
+{
+  "mcpServers": {
+    "hydrossh": {
+      "command": "npx",
+      "args": ["-y", "mcp-hydrocoder-ssh"]
+    }
+  }
+}
+```
+
+> **注意：**
+> - `hydrossh` 是服务器名称标识，可以改为任意你喜欢的名字。
+> - `-y` 标志让 npx 自动确认安装，避免交互提示卡住。
+
+### 步骤 3：重启 Claude Code
+
+关闭并重新打开 Claude Code，配置将自动加载。
+
+### 步骤 4：验证安装
+
+在 Claude Code 中输入：
+```
+列出可用的 SSH 服务器
+```
+
+如果看到服务器列表（空列表表示尚未配置），说明安装成功。你可以通过自然语言让 Claude 帮你添加配置、修改配置或连接服务器，连接后可以执行各种操作。
+
+---
+
+## 第三部分：源码使用（开发方式）
+
+### 1. 下载源码
+
+```bash
+git clone https://github.com/hydroCoderClaud/mcpHydroSSH.git
+cd mcpHydroSSH
+```
+
+### 2. 安装依赖
+
+```bash
+npm install
+```
+
+### 3. 编译构建
+
+```bash
+npm run build
+```
+
+编译输出到 `dist/` 目录，主要文件：
+- `dist/index.js` - MCP 服务器入口
+- `dist/ssh-manager.js` - SSH 连接管理
+- `dist/config.js` - 配置管理
+
+### 4. 配置 Claude Code
+
+编辑用户目录的 `~/.claude.json` 文件：
+
+**Windows 路径：** `C:\Users\<你的用户名>\.claude.json`
+**macOS/Linux 路径：** `~/.claude.json`
+
+```json
+{
+  "mcpServers": {
+    "hydrossh": {
+      "command": "node",
+      "args": ["<项目绝对路径>/dist/index.js"]
+    }
+  }
+}
+```
+
+> **注意：** 将 `<项目绝对路径>` 替换为你实际的源码目录绝对路径。
+> - Windows 示例：`C:\\workspace\\develop\\ccExtensions\\mcpHydroSSH`
+> - macOS/Linux 示例：`/home/user/projects/mcpHydroSSH`
+
+### 5. 重启 Claude Code
+
+关闭并重新打开 Claude Code，配置将自动加载。
+
+### 6. 开发模式（可选）
+
+如需热重载开发：
+```bash
+npm run dev
+```
+
+此时 Claude Code 配置改为：
+
+```json
+{
+  "mcpServers": {
+    "hydrossh": {
+      "command": "npx",
+      "args": ["tsx", "<项目绝对路径>/src/index.ts"]
+    }
+  }
+}
+```
+
+> **注意：** 将 `<项目绝对路径>` 替换为你实际的源码目录绝对路径。
+
+---
+
+## 附录 A：配置 SSH 服务器
+
+首次运行时，服务器会自动创建配置文件 `~/.hydrossh/config.json`。
+
+### 配置示例
+
+```json
+{
+  "servers": [
+    {
+      "id": "prod-server",
+      "name": "生产服务器",
+      "host": "example.com",
+      "port": 22,
+      "username": "deploy",
+      "authMethod": "agent"
+    },
+    {
+      "id": "test-server",
+      "name": "测试服务器",
+      "host": "test.example.com",
+      "username": "ubuntu",
+      "authMethod": "key",
+      "privateKeyPath": "~/.ssh/id_rsa"
+    }
+  ],
+  "settings": {
+    "defaultConnectTimeout": 30000,
+    "defaultKeepaliveInterval": 60000,
+    "commandTimeout": 60000,
+    "maxConnections": 5,
+    "logCommands": true
+  }
+}
+```
+
+### 认证方式
+
+| 方式 | 配置 | 说明 |
+|------|------|------|
+| **SSH Agent** | `"authMethod": "agent"` | 推荐，使用系统 SSH agent |
+| **密钥文件** | `"authMethod": "key", "privateKeyPath": "~/.ssh/id_rsa"` | 默认，直接读取密钥文件 |
+| **密码** | `"authMethod": "password", "password": "xxx"` | 不推荐，密码会明文存储 |
+
+详见 [CONFIG-GUIDE.md](CONFIG-GUIDE.md)
+
+---
+
+## 附录 B：使用示例
+
+### 基本用法
+
+```
+用户：列出可用的服务器
+Claude: 发现 2 个配置的服务器：prod-server、test-server
+
+用户：连接到 prod-server
+Claude: [调用 ssh_connect] 连接成功！connectionId: xxx
+
+用户：执行命令：uptime
+Claude: [调用 ssh_exec] 返回：up 30 days, 2 users, load average: 0.1, 0.2, 0.5
+
+用户：断开连接
+Claude: [调用 ssh_disconnect] 已断开
+```
+
+### 自动化部署
+
+```
+用户：部署最新代码到生产服务器
+Claude: 好的，我来执行部署流程...
+1. 连接 prod-server
+2. cd /opt/myapp && git pull
+3. npm ci --production
+4. sudo systemctl restart myapp
+5. 检查服务状态
+6. 断开连接
+部署完成！
+```
+
+---
+
+## 附录 C：安全说明
+
+- 🔒 **推荐 SSH Agent** - 优先使用 `authMethod: "agent"`
+- 🔒 **配置文件权限** - 确保 `~/.hydrossh/config.json` 权限设置为仅自己可读
+- 🔒 **配置查看过滤** - `ssh_view_config` 工具会自动过滤密码和密钥路径
+
+---
+
+## 附录 D：故障排查
+
+| 问题 | 解决方案 |
+|------|---------|
+| SSH Agent 未运行 | Windows: 启动 "OpenSSH Authentication Agent" 服务 |
+| 连接超时 | 检查服务器地址、端口、网络连通性 |
+| 命令未找到 | 确认 npm 全局安装成功，或检查 PATH 环境变量 |
+| 配置未加载 | 检查 `~/.claude.json` 格式是否正确 |
+
+---
+
+## 附录 E：命令参考
+
+### 开发命令
+
+```bash
+npm run build        # 编译构建
+npm run dev          # 开发模式（热重载）
+npm test             # 运行测试
+npm run lint         # 代码检查
+npm run format       # 代码格式化
+```
+
+### MCP 工具参数
+
+| 工具 | 参数 | 说明 |
+|------|------|------|
+| `ssh_list_servers` | 无 | 列出所有配置的服务器 |
+| `ssh_connect` | `serverId`, `timeout?` | 连接到服务器 |
+| `ssh_exec` | `command`, `connectionId?`, `timeout?`, `cwd?` | 执行命令 |
+| `ssh_get_status` | `connectionId?` | 获取连接状态（不传返回全部） |
+| `ssh_disconnect` | `connectionId?` | 断开连接（不传断开最近的一个） |
+| `ssh_add_server` | `id`, `name`, `host`, `username`, `port?`, `authMethod?`, `privateKeyPath?`, `password?` | 添加服务器配置 |
+| `ssh_remove_server` | `serverId` | 删除服务器配置 |
+| `ssh_update_server` | `serverId`, `name?`, `host?`, `port?`, `username?`, `authMethod?`, `privateKeyPath?`, `password?` | 更新服务器配置 |
+| `ssh_view_config` | 无 | 查看配置（过滤敏感信息） |
+| `ssh_help` | `topic?` | 显示帮助信息 |
+
+---
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-hydrocoder-ssh",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "SSH MCP Server for Claude Code",
   "type": "module",
   "main": "dist/index.js",
@@ -14,6 +14,9 @@
     "dist/types.js",
     "example-config.json",
     "README.md",
+    "README_CN.md",
+    "CONFIG-GUIDE.md",
+    "CONFIG-GUIDE_EN.md",
     "LICENSE"
   ],
   "scripts": {