Merge branch 'master' of https://git.startmywifi.com/AS1024Private/mcp-ssh

.gitignore

@@ -6,3 +6,6 @@ artifacts/
 *.suo
 .vs/
 .vscode/
+
+# MCP Vector Search index directory
+.mcp-vector-search/

skills/mcp-ssh-server/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: mcp-ssh-server
+description: "Use an MCP SSH Server exposed to Codex for remote SSH operations. Use when Codex needs to run bounded remote commands, manage an interactive SSH terminal session, list remote directories, download files, or upload files through the mcp-ssh tools: ssh_exec, ssh_terminal_start, ssh_terminal_write, ssh_terminal_read, ssh_terminal_stop, sftp_list, sftp_get, and sftp_put."
+---
+
+# MCP SSH Server
+
+## Overview
+
+Use this skill when an MCP SSH server is available and the task requires remote shell or file-transfer work. The server accepts direct SSH connection inputs and uses key-file authentication; it does not resolve OpenSSH aliases or use an SSH agent in the current tool surface.
+
+For detailed inputs and examples, read [references/tool-usage.md](references/tool-usage.md).
+
+## Workflow
+
+1. Identify the narrowest operation. Use `ssh_exec` for one command, terminal tools for interactive/stateful work, `sftp_list` for remote directory listing, and `sftp_get`/`sftp_put` for file transfer.
+2. Collect connection inputs before calling a tool: `host`, `username`, optional `port`, optional `keyPath`, and optional `keyPassphrase`.
+3. Treat `host` as a direct hostname or IP address. Do not pass OpenSSH aliases unless the user confirms they resolve directly for this server.
+4. Prefer explicit bounds for risky operations: `timeoutSeconds` for commands, `idleTimeoutSeconds` for terminals, and `maxBytes` for transfers.
+5. Keep secrets out of visible text. Use `keyPassphrase` only when required and never echo or store it.
+6. Stop terminal sessions when finished with `ssh_terminal_stop`.
+
+## Tool Selection
+
+- Use `ssh_exec` for checks, deployments, service commands, one-shot scripts, and commands where stdout/stderr and exit code matter.
+- Use `ssh_terminal_start` plus `ssh_terminal_write` and `ssh_terminal_read` for REPLs, long-running interactive tools, TTY-sensitive commands, or workflows that need shell state.
+- Use `sftp_list` to inspect remote directories.
+- Use `sftp_get` to download a remote file into the MCP server working directory.
+- Use `sftp_put` to upload a local file from the MCP server working directory to the remote host.
+
+## Safety Rules
+
+- Set `timeoutSeconds` for commands that might hang. The default is bounded, but explicit values make intent clear.
+- Use `cwd` with `ssh_exec` instead of shelling through `cd ... && ...` when the tool supports it.
+- For terminal sessions, read output after writes and stop the session when done.
+- For downloads and uploads, remember local paths must stay inside the MCP server process working directory.
+- Leave `overwrite` false unless the user asked to replace an existing local or remote file.
+- For large files, set `maxBytes` deliberately.
+
+## Current Limits
+
+- SSH agent auth is not part of the current tool inputs.
+- OpenSSH config aliases, `ssh -G`, ProxyJump, ProxyCommand, and known-host policy controls are not part of the current tool inputs.
+- Directory upload/download is not exposed; transfer individual files.
+- `sftp_list` has no SCP fallback. `sftp_get` and `sftp_put` silently fall back to SCP when SFTP is unavailable.

skills/mcp-ssh-server/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "MCP SSH Server"
+  short_description: "Use SSH MCP tools safely"
+  default_prompt: "Use $mcp-ssh-server to run a bounded remote command or transfer a file over SSH."

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.