mcp-hydrocoder-ssh 0.1.0 → 0.1.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +267 -44
  2. package/package.json +6 -2
package/README.md CHANGED
@@ -1,91 +1,314 @@
1
1
  # mcp-hydrocoder-ssh
2
2
 
3
- SSH MCP Server for Claude Code - connect to remote servers directly from Claude Code.
3
+ [中文](README_CN.md) | **English** | [Configuration Guide](CONFIG-GUIDE_EN.md) | [配置指南](CONFIG-GUIDE.md)
4
4
 
5
- ## Quick Start
5
+ MCP server that provides SSH remote connection capabilities for Claude Code. Connect to remote servers, execute commands, and automate deployments without needing a separate SSH terminal.
6
6
 
7
- ### 1. Install from npm
7
+ [![npm version](https://img.shields.io/npm/v/mcp-hydrocoder-ssh.svg)](https://www.npmjs.com/package/mcp-hydrocoder-ssh)
8
+ [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
9
+
10
+ ---
11
+
12
+ ## Part 1: Features
13
+
14
+ ### What is this?
15
+
16
+ `mcp-hydrocoder-ssh` is an MCP (Model Context Protocol) server that enables Claude Code to:
17
+ - 🔌 Connect to remote SSH servers directly (persistent background connections)
18
+ - ⚡ Execute commands and get complete output
19
+ - 🔄 Maintain connection state for multi-step operations
20
+ - 🚀 Run deployment scripts (git pull, npm install, systemctl restart, etc.)
21
+
22
+ ### Key Benefits
23
+
24
+ | Benefit | Description |
25
+ |---------|-------------|
26
+ | **No window switching** | Complete all remote operations within Claude Code conversation |
27
+ | **Smart deployment** | Claude can auto-determine next steps based on command output |
28
+ | **Multi-server management** | Manage multiple server configs, switch quickly |
29
+ | **Secure authentication** | Support SSH agent, key files |
30
+ | **Connection pooling** | Maintain persistent connections, avoid re-authentication overhead |
31
+
32
+ ### Available Tools
33
+
34
+ **SSH Connection Tools (5):**
35
+ - `ssh_list_servers` - List all configured servers
36
+ - `ssh_connect` - Connect to a server
37
+ - `ssh_exec` - Execute commands (with working directory support)
38
+ - `ssh_get_status` - Get connection status
39
+ - `ssh_disconnect` - Disconnect from server
40
+
41
+ **Configuration Management Tools (5):**
42
+ - `ssh_add_server` - Add new server configuration
43
+ - `ssh_remove_server` - Remove server configuration
44
+ - `ssh_update_server` - Update server configuration
45
+ - `ssh_view_config` - View config (filters sensitive info)
46
+ - `ssh_help` - Show help information
47
+
48
+ ---
49
+
50
+ ## Part 2: Quick Installation
51
+
52
+ ### Step 1: Choose Installation Method
53
+
54
+ **Option A: Global Installation (Recommended)**
8
55
 
9
56
  ```bash
10
57
  npm install -g mcp-hydrocoder-ssh
11
58
  ```
12
59
 
13
- ### 2. Configure Servers
60
+ **Option B: Using npx (No installation required)**
61
+
62
+ ```bash
63
+ # No action needed - use npx directly in config
64
+ ```
65
+
66
+ ---
67
+
68
+ ### Step 2: Configure Claude Code
69
+
70
+ Edit `~/.claude.json` in your user directory:
71
+
72
+ **Option A (Global Install):**
73
+ ```json
74
+ {
75
+ "mcpServers": {
76
+ "hydrossh": {
77
+ "command": "mcp-hydrocoder-ssh"
78
+ }
79
+ }
80
+ }
81
+ ```
82
+
83
+ **Option B (npx):**
84
+ ```json
85
+ {
86
+ "mcpServers": {
87
+ "hydrossh": {
88
+ "command": "npx",
89
+ "args": ["-y", "mcp-hydrocoder-ssh"]
90
+ }
91
+ }
92
+ }
93
+ ```
94
+
95
+ > **Note:**
96
+ > - `hydrossh` is the server identifier, can be changed to any name you prefer.
97
+ > - `-y` flag lets npx auto-confirm installation, avoiding interactive prompts.
98
+
99
+ ### Step 3: Restart Claude Code
100
+
101
+ Close and reopen Claude Code to load the configuration.
102
+
103
+ ### Step 4: Verify Installation
104
+
105
+ In Claude Code, enter:
106
+ ```
107
+ List available SSH servers
108
+ ```
109
+
110
+ If you see a server list (empty list means no servers configured yet), the installation was successful. You can use natural language to add configs, modify configs, or connect to servers.
111
+
112
+ ---
113
+
114
+ ## Part 3: Using from Source Code
115
+
116
+ ### 1. Clone Repository
14
117
 
15
- On first run, the server will auto-create `~/.hydrossh/config.json` from the example template.
118
+ ```bash
119
+ git clone https://github.com/hydroCoderClaud/mcpHydroSSH.git
120
+ cd mcpHydroSSH
121
+ ```
122
+
123
+ ### 2. Install Dependencies
16
124
 
17
- Edit the config file with your SSH servers:
18
125
  ```bash
19
- # Windows
20
- notepad C:\Users\ynzys\.hydrossh\config.json
126
+ npm install
127
+ ```
21
128
 
22
- # macOS/Linux
23
- nano ~/.hydrossh/config.json
129
+ ### 3. Build
130
+
131
+ ```bash
132
+ npm run build
24
133
  ```
25
134
 
26
- See [CONFIG-GUIDE.md](CONFIG-GUIDE.md) for detailed configuration options.
135
+ Build output goes to `dist/` directory:
136
+ - `dist/index.js` - MCP server entry point
137
+ - `dist/ssh-manager.js` - SSH connection management
138
+ - `dist/config.js` - Configuration management
27
139
 
28
- ### 3. Add to Claude Code
140
+ ### 4. Configure Claude Code
29
141
 
30
- Add to your Claude Code settings (`~/.claude.json`):
142
+ Edit `~/.claude.json` in your user directory:
31
143
 
32
- **Windows:**
33
144
  ```json
34
145
  {
35
146
  "mcpServers": {
36
147
  "hydrossh": {
37
- "command": "npx",
38
- "args": ["mcp-hydrocoder-ssh"]
148
+ "command": "node",
149
+ "args": ["<absolute-path>/dist/index.js"]
39
150
  }
40
151
  }
41
152
  }
42
153
  ```
43
154
 
44
- **macOS/Linux:**
155
+ > **Note:** Replace `<absolute-path>` with your actual source directory absolute path.
156
+
157
+ ### 5. Restart Claude Code
158
+
159
+ Close and reopen Claude Code to load the configuration.
160
+
161
+ ### 6. Development Mode (Optional)
162
+
163
+ For hot-reload development:
164
+ ```bash
165
+ npm run dev
166
+ ```
167
+
168
+ Then configure Claude Code with:
169
+
45
170
  ```json
46
171
  {
47
172
  "mcpServers": {
48
173
  "hydrossh": {
49
174
  "command": "npx",
50
- "args": ["mcp-hydrocoder-ssh"]
175
+ "args": ["tsx", "<absolute-path>/src/index.ts"]
51
176
  }
52
177
  }
53
178
  }
54
179
  ```
55
180
 
56
- > **Note:** The server name `hydrossh` is used to avoid conflicts with other SSH-related MCP servers.
57
- > For global install: use `"command": "mcp-hydrocoder-ssh"` (no npx needed).
181
+ ---
182
+
183
+ ## Appendix A: SSH Configuration
184
+
185
+ Configuration file location: `~/.claude/ssh-mcp-config.json`
186
+
187
+ ### Configuration Example
188
+
189
+ ```json
190
+ {
191
+ "servers": [
192
+ {
193
+ "id": "prod-server",
194
+ "name": "Production Server",
195
+ "host": "example.com",
196
+ "port": 22,
197
+ "username": "deploy",
198
+ "authMethod": "agent"
199
+ },
200
+ {
201
+ "id": "test-server",
202
+ "name": "Test Server",
203
+ "host": "test.example.com",
204
+ "username": "ubuntu",
205
+ "authMethod": "key",
206
+ "privateKeyPath": "~/.ssh/id_rsa"
207
+ }
208
+ ],
209
+ "settings": {
210
+ "defaultConnectTimeout": 30000,
211
+ "defaultKeepaliveInterval": 60000,
212
+ "commandTimeout": 60000,
213
+ "maxConnections": 5,
214
+ "logCommands": true
215
+ }
216
+ }
217
+ ```
58
218
 
59
- ### 4. Usage
219
+ ### Authentication Methods
60
220
 
61
- In Claude Code, simply say:
62
- - "List available servers"
63
- - "Connect to my-server"
64
- - "Run command: uptime"
65
- - "Show connection status"
66
- - "Disconnect"
221
+ | Method | Configuration | Description |
222
+ |--------|---------------|-------------|
223
+ | **SSH Agent** | `"authMethod": "agent"` | Recommended, uses system SSH agent |
224
+ | **Key File** | `"authMethod": "key", "privateKeyPath": "~/.ssh/id_rsa"` | Default, reads private key file |
225
+ | **Password** | `"authMethod": "password", "password": "xxx"` | Not recommended, password stored in plaintext |
67
226
 
68
- ## MCP Tools
227
+ See [CONFIG-GUIDE_EN.md](CONFIG-GUIDE_EN.md) for details.
69
228
 
70
- ### SSH Connection Tools
229
+ ---
230
+
231
+ ## Appendix B: Usage Examples
232
+
233
+ ### Basic Usage
234
+
235
+ ```
236
+ User: List available servers
237
+ Claude: Found 2 configured servers: prod-server, test-server
238
+
239
+ User: Connect to prod-server
240
+ Claude: [ssh_connect] Connected! connectionId: xxx
241
+
242
+ User: Execute command: uptime
243
+ Claude: [ssh_exec] Returns: up 30 days, 2 users, load average: 0.1, 0.2, 0.5
244
+
245
+ User: Disconnect
246
+ Claude: [ssh_disconnect] Disconnected
247
+ ```
248
+
249
+ ### Automated Deployment
250
+
251
+ ```
252
+ User: Deploy latest code to production server
253
+ Claude: Okay, I'll execute the deployment flow...
254
+ 1. Connect to prod-server
255
+ 2. cd /opt/myapp && git pull
256
+ 3. npm ci --production
257
+ 4. sudo systemctl restart myapp
258
+ 5. Check service status
259
+ 6. Disconnect
260
+ Deployment complete!
261
+ ```
262
+
263
+ ---
264
+
265
+ ## Appendix C: Security Notes
266
+
267
+ - 🔒 **SSH Agent Recommended** - Prefer `authMethod: "agent"`
268
+ - 🔒 **Config File Permissions** - Ensure `~/.claude/ssh-mcp-config.json` is readable only by you
269
+ - 🔒 **Config Viewing** - `ssh_view_config` tool automatically filters passwords and key paths
270
+
271
+ ---
272
+
273
+ ## Appendix D: Troubleshooting
274
+
275
+ | Issue | Solution |
276
+ |-------|----------|
277
+ | SSH Agent not running | Windows: Start "OpenSSH Authentication Agent" service |
278
+ | Connection timeout | Check server address, port, network connectivity |
279
+ | Command not found | Verify npm global install or check PATH environment variable |
280
+ | Config not loaded | Check if `~/.claude.json` format is correct |
281
+
282
+ ---
283
+
284
+ ## Appendix E: Command Reference
285
+
286
+ ### Development Commands
287
+
288
+ ```bash
289
+ npm run build # Build TypeScript
290
+ npm run dev # Development mode (hot reload)
291
+ npm test # Run tests
292
+ npm run lint # Code linting
293
+ npm run format # Code formatting
294
+ ```
71
295
 
72
- | Tool | Description |
73
- |------|-------------|
74
- | `ssh_list_servers` | List all configured servers |
75
- | `ssh_connect` | Connect to a server |
76
- | `ssh_exec` | Execute a command |
77
- | `ssh_get_status` | Get connection status (or all statuses) |
78
- | `ssh_disconnect` | Disconnect from server |
296
+ ### MCP Tool Parameters
79
297
 
80
- ### Config Management Tools
298
+ | Tool | Parameters | Description |
299
+ |------|------------|-------------|
300
+ | `ssh_list_servers` | none | List all configured servers |
301
+ | `ssh_connect` | `serverId`, `timeout?` | Connect to server |
302
+ | `ssh_exec` | `command`, `connectionId?`, `timeout?`, `cwd?` | Execute command |
303
+ | `ssh_get_status` | `connectionId?` | Get connection status (all if not specified) |
304
+ | `ssh_disconnect` | `connectionId?` | Disconnect (most recent if not specified) |
305
+ | `ssh_add_server` | `id`, `name`, `host`, `username`, `port?`, `authMethod?`, `privateKeyPath?`, `password?` | Add server config |
306
+ | `ssh_remove_server` | `serverId` | Remove server config |
307
+ | `ssh_update_server` | `serverId`, `name?`, `host?`, `port?`, `username?`, `authMethod?`, `privateKeyPath?`, `password?` | Update server config |
308
+ | `ssh_view_config` | none | View config (filters sensitive info) |
309
+ | `ssh_help` | `topic?` | Show help information |
81
310
 
82
- | Tool | Description |
83
- |------|-------------|
84
- | `ssh_add_server` | Add a new server to config |
85
- | `ssh_remove_server` | Remove a server from config |
86
- | `ssh_update_server` | Update an existing server config |
87
- | `ssh_view_config` | View full configuration (sanitized) |
88
- | `ssh_help` | Show help and usage examples |
311
+ ---
89
312
 
90
313
  ## License
91
314
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "mcp-hydrocoder-ssh",
3
- "version": "0.1.0",
3
+ "version": "0.1.2",
4
4
  "description": "SSH MCP Server for Claude Code",
5
5
  "type": "module",
6
6
  "main": "dist/index.js",
@@ -27,7 +27,11 @@
27
27
  "test": "vitest run",
28
28
  "test:watch": "vitest"
29
29
  },
30
- "keywords": ["mcp", "ssh", "claude"],
30
+ "keywords": [
31
+ "mcp",
32
+ "ssh",
33
+ "claude"
34
+ ],
31
35
  "author": "",
32
36
  "license": "MIT",
33
37
  "dependencies": {