Add skills

skills/mcp-ssh-server/references/tool-usage.md

@@ -0,0 +1,154 @@
+# MCP SSH Tool Usage
+
+## Connection Inputs
+
+Most tools use these inputs:
+
+- `host`: direct remote hostname or IP address.
+- `username`: remote SSH username.
+- `port`: optional remote SSH port, default 22.
+- `keyPath`: optional local private key path. If omitted, the server tries `~/.ssh/id_ed25519`, then `~/.ssh/id_ecdsa`, then `~/.ssh/id_rsa`.
+- `keyPassphrase`: optional passphrase for encrypted private keys. Treat as sensitive.
+
+Current limit: do not rely on OpenSSH aliases, SSH agent identities, ProxyJump, ProxyCommand, or `ssh -G` resolution.
+
+## `ssh_exec`
+
+Use for one bounded remote command.
+
+Inputs:
+
+- Required: `host`, `username`, `command`.
+- Optional: `cwd`, `port`, `keyPath`, `keyPassphrase`, `timeoutSeconds`.
+
+Example:
+
+```json
+{
+  "host": "prod-api.example.com",
+  "username": "deploy",
+  "command": "systemctl status nginx --no-pager",
+  "cwd": "/var/www",
+  "timeoutSeconds": 30
+}
+```
+
+Expected result includes `exitCode`, `stdout`, `stderr`, and `durationMs`. Non-zero exit codes are preserved. Timeout results use `timedOut: true`.
+
+## Terminal Session Tools
+
+Use for interactive or stateful remote shell work.
+
+Start:
+
+```json
+{
+  "host": "prod-api.example.com",
+  "username": "deploy",
+  "cols": 120,
+  "rows": 40,
+  "idleTimeoutSeconds": 900
+}
+```
+
+Write:
+
+```json
+{
+  "sessionId": "term_abc123",
+  "input": "pwd\n"
+}
+```
+
+Read:
+
+```json
+{
+  "sessionId": "term_abc123",
+  "maxBytes": 12000
+}
+```
+
+Stop:
+
+```json
+{
+  "sessionId": "term_abc123"
+}
+```
+
+Operational notes:
+
+- Include newline characters when submitting shell commands.
+- Read after each write when command output matters.
+- Stop sessions explicitly after finishing.
+- The remote account's default shell starts without injected setup commands.
+
+## `sftp_list`
+
+Use to list a remote directory over SFTP.
+
+```json
+{
+  "host": "prod-api.example.com",
+  "username": "deploy",
+  "remotePath": "/var/www"
+}
+```
+
+Result entries include `name`, `path`, `type`, `size`, and `modifiedUtc`.
+
+No SCP fallback is available for directory listing.
+
+## `sftp_get`
+
+Use to download one remote file into the MCP server working directory.
+
+```json
+{
+  "host": "prod-api.example.com",
+  "username": "deploy",
+  "remotePath": "/var/log/app.log",
+  "localPath": "downloads/app.log",
+  "overwrite": false,
+  "maxBytes": 104857600
+}
+```
+
+Notes:
+
+- Local paths must stay inside the MCP server working directory.
+- Existing local files are not overwritten unless `overwrite` is true.
+- The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.
+
+## `sftp_put`
+
+Use to upload one local file from the MCP server working directory.
+
+```json
+{
+  "host": "prod-api.example.com",
+  "username": "deploy",
+  "localPath": "dist/app.tar.gz",
+  "remotePath": "/tmp/app.tar.gz",
+  "overwrite": false,
+  "maxBytes": 104857600
+}
+```
+
+Notes:
+
+- Local paths must stay inside the MCP server working directory.
+- Existing remote files are not overwritten unless `overwrite` is true.
+- The server tries SFTP first and silently falls back to SCP when SFTP is unavailable.
+
+## Common Error Handling
+
+Treat these as actionable errors:
+
+- `ssh_key_not_found`: supply `keyPath` or ensure a default key exists.
+- `ssh_authentication_failed`: check `username`, key, and `keyPassphrase`.
+- `invalid_host`, `invalid_username`, `invalid_port`: fix connection inputs.
+- `local_file_exists` or `remote_file_exists`: decide whether `overwrite: true` is appropriate.
+- `unsafe_local_path`: choose a local path inside the MCP server working directory.
+- `download_too_large` or `upload_too_large`: raise `maxBytes` only if the transfer is intended.