@akms/mcp-ssh 0.1.9 → 0.2.1

package/CHANGELOG.md

@@ -2,6 +2,19 @@
 
 All notable changes to `@akms/mcp-ssh`. Dates are `YYYY-MM-DD`.
 
+## 0.2.1 — 2026-10-19
+
+### Documentation
+
+- Add a minimum key-based connection example to README and clarify that host/user alone require an available authenticated SSH agent; document password alternatives and Windows launch settings.
+- Make the jump-host/proxy example a complete JSON client configuration.
+
+## 0.2.0 — 2026-10-19
+
+### Changed
+
+- Align the package, CLI and MCP server versions with the 0.2.0 MCP release family. Retain lazy SSH runtime loading and the existing command/path guard API used by WSL.
+
 ## 0.1.9 — 2026-10-19
 
 ### Changed

package/README.md

@@ -16,6 +16,32 @@ npx -y @akms/mcp-ssh --help    # or run it straight from the registry
 akms-mcp-ssh --version        # show the installed version
 ```
 
+## Minimum working configuration
+
+For a direct SSH connection using a private key, use this MCP client entry. Replace the host, user and key path with your own. The SSH server must be reachable on port `22`, and the matching public key must already be authorized for that user.
+
+```json
+{
+    "mcpServers": {
+        "ssh": {
+            "command": "npx",
+            "args": ["-y", "@akms/mcp-ssh"],
+            "env": {
+                "SSH_HOST": "ssh.example.com",
+                "SSH_USER": "deploy",
+                "SSH_KEY": "~/.ssh/id_ed25519"
+            }
+        }
+    }
+}
+```
+
+`SSH_HOST` and `SSH_USER` are required. The example also supplies authentication explicitly: `SSH_KEY` must point to an existing private key file; add `SSH_PASSPHRASE` if it is encrypted. For password authentication, replace `SSH_KEY` with `SSH_PASSWORD`. Omit both only when the MCP process can access an SSH agent with an authorized key (`SSH_AUTH_SOCK`, or the OpenSSH agent on Windows). No default key file or `~/.ssh/config` is loaded automatically.
+
+`SSH_PORT` defaults to `22`; jump-host and proxy settings are optional. Writes are allowed by default; add `"SSH_READONLY": "true"` for a read-only entry.
+
+The JSON example fits an MCP client's `mcpServers` configuration, such as a project `.mcp.json` or Cursor's `mcp.json`. On Windows, use `"command": "cmd"` and `"args": ["/c", "npx", "-y", "@akms/mcp-ssh"]`. For Codex TOML or automatic registration, run `npx -y @akms/mcp-ssh config --target codex` (or choose another client below).
+
 ## ⚙️ MCP client setup
 
 **Let the CLI write it.** `config` opens a small manager for the hosts registered in a client's config. It asks plain questions — host, user, key or password, jump host, read-only — tests the connection, offers to pin the host key, and writes the entry. No `SSH_*` name has to be remembered.
@@ -99,7 +125,7 @@ Only entries that launch this package are listed for management. An edit keeps e
 }
 ```
 
-`SSH_HOST` + `SSH_USER` is the whole minimum, and the **private key stays a file on disk** — only its path goes in the config. Because each server fronts one host, the agent never names it: `ssh_exec({ command: "df -h" })` is a complete call. The server name (`ssh-prod`) is what the agent sees in its tool list, so name it after the host.
+`SSH_HOST` + `SSH_USER` is sufficient only when an SSH agent with an authorized key is available; otherwise also provide a key path or password as shown in [Minimum working configuration](#minimum-working-configuration). The **private key stays a file on disk** — only its path goes in the config. Because each server fronts one host, the agent never names it: `ssh_exec({ command: "df -h" })` is a complete call. The server name (`ssh-prod`) is what the agent sees in its tool list, so name it after the host.
 
 The server speaks MCP over **stdio**: stdout carries the JSON-RPC stream and all logging goes to stderr. Running it by hand in a terminal only prints the startup line and waits. When the client goes away — stdin ends, or the process is simply gone — the server closes its sessions and exits within a few seconds on its own; a stderr nobody reads is never a reason to stay. Its log says `mcp server ready on stdio` with its `pid`, for when one has to be found among a client's processes.
 
@@ -137,12 +163,16 @@ Authentication is tried in this order: **private key by path** (with `SSH_PASSPH
 `~/.ssh/config` is **not** read — the server never shells out to `ssh` — so a `ProxyJump` or `ProxyCommand` that works on the command line has to be stated in the entry. Both OpenSSH shapes are available, and they compose:
 
 ```json
-"ssh-dev": {
-    "command": "npx", "args": ["-y", "@akms/mcp-ssh"],
-    "env": {
-        "SSH_HOST": "10.0.16.12", "SSH_USER": "ubuntu", "SSH_KEY": "~/.ssh/id_ed25519",
-        "SSH_JUMP_HOST": "dev-ak-ssh.example.com",
-        "SSH_PROXY_COMMAND": "cloudflared access ssh --hostname %h"
+{
+    "mcpServers": {
+        "ssh-dev": {
+            "command": "npx", "args": ["-y", "@akms/mcp-ssh"],
+            "env": {
+                "SSH_HOST": "10.0.16.12", "SSH_USER": "ubuntu", "SSH_KEY": "~/.ssh/id_ed25519",
+                "SSH_JUMP_HOST": "dev-ak-ssh.example.com",
+                "SSH_PROXY_COMMAND": "cloudflared access ssh --hostname %h"
+            }
+        }
     }
 }
 ```

package/lib/cli.cjs

@@ -36,7 +36,7 @@ var CWD_MARKER = "__AKMS_SSH_CWD__";
 var MAX_DIRECTORY_ENTRIES = 1e3;
 var SERVER_NAME = "akms-mcp-ssh";
 var PACKAGE_NAME = "@akms/mcp-ssh";
-var SERVER_VERSION = "0.1.9";
+var SERVER_VERSION = "0.2.1";
 
 // src/_defs/command-rules.ts
 var CRITICAL_PATH_PATTERN = new RegExp(