mcp-ssh-gateway 6.0.1__tar.gz

mcp_ssh_gateway-6.0.1/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,47 @@
+name: Bug report
+description: Something behaves differently from what the README promises.
+labels: ["bug"]
+body:
+  - type: textarea
+    id: what-happened
+    attributes:
+      label: What happened
+      description: Include the returned JSON, not a terminal screenshot.
+    validations:
+      required: true
+  - type: textarea
+    id: expected
+    attributes:
+      label: What you expected
+    validations:
+      required: true
+  - type: dropdown
+    id: host-type
+    attributes:
+      label: Host type
+      options:
+        - Linux / POSIX shell
+        - Vendor CLI (Keenetic NDM, Cisco-style, other)
+        - NAS / appliance
+        - VPS / cloud
+    validations:
+      required: true
+  - type: input
+    id: client
+    attributes:
+      label: MCP client
+      placeholder: Claude Desktop, Continue.dev, Cursor, ...
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: Server version
+      description: The `version` from the initialize response, or the git tag.
+    validations:
+      required: true
+  - type: textarea
+    id: call
+    attributes:
+      label: Exact tool call
+      description: The tools/call payload you sent.

mcp_ssh_gateway-6.0.1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security vulnerability
+    url: https://github.com/d00mus/MCP-SSH/security/advisories/new
+    about: Report privately — do not open a public issue.

mcp_ssh_gateway-6.0.1/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,35 @@
+name: Feature request
+description: A capability the gateway is missing.
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: What problem does this solve?
+      description: Describe the workflow, not the implementation.
+    validations:
+      required: true
+  - type: textarea
+    id: proposal
+    attributes:
+      label: Proposed behaviour
+    validations:
+      required: true
+  - type: dropdown
+    id: host-type
+    attributes:
+      label: Which host type does this target?
+      options:
+        - Linux / POSIX shell
+        - Vendor CLI (Keenetic NDM, Cisco-style, other)
+        - NAS / appliance
+        - VPS / cloud
+        - Fleet-wide (all of the above)
+    validations:
+      required: true
+  - type: checkboxes
+    id: prompt-tokens
+    attributes:
+      label: Tool catalog
+      options:
+        - label: This needs a new tool (I accept the prompt-token cost for every user)

mcp_ssh_gateway-6.0.1/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,24 @@
+name: Pull request
+description: A change to code, tests or documentation.
+labels: ["change"]
+body:
+  - type: textarea
+    id: summary
+    attributes:
+      label: User-visible effect
+      description: What changes for someone running this server.
+    validations:
+      required: true
+  - type: textarea
+    id: contract
+    attributes:
+      label: Output contract
+      description: Confirm none of these regress: `has_more` counts unread lines; `line_limit` counts lines; `offset` never consumes; no internal markers or prompts reach the agent; non-zero exit stays `completed_nonzero`; every tool keeps its annotations.
+  - type: checkboxes
+    id: checks
+    attributes:
+      label: Checks
+      options:
+        - label: python -m unittest discover -s tests -t . passes
+        - label: Tests added or updated
+        - label: CHANGELOG.md updated under [Unreleased]

mcp_ssh_gateway-6.0.1/.github/workflows/ci.yml

@@ -0,0 +1,18 @@
+name: CI
+
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    strategy:
+      matrix:
+        python-version: ["3.11", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: pip install -r requirements.txt
+      - run: python -m unittest discover -s tests -t . -v

mcp_ssh_gateway-6.0.1/CHANGELOG.md

@@ -0,0 +1,51 @@
+# Changelog
+
+All notable changes to this project are documented here.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [6.0.1] — 2026-09-28
+
+### Changed
+- Rewrite the README around practical SSH fleet workflows, with a verified quickstart and clearer setup and security boundaries.
+- Correct quickstart and security guidance; default the example host configuration to SSH host-key verification.
+
+## [6.0.0] — 2026-09-28
+
+### Changed
+- Unified scrollback: every tab keeps one 2M-character canvas addressed through a
+  single line-based cursor. `run` returns the first `line_limit` lines inline,
+  `has_more` reports the number of unread **lines**, and `read` delivers the next
+  window. No continuation token, no bookkeeping counters.
+- Honest MCP framing: internal exit markers, prompt echoes and gateway machinery
+  never surface in the agent's window.
+- Configuration is hot-reloaded on the health-loop pass (mtime + content hash), so
+  adding a host or tightening a policy no longer drops open sessions.
+- Control requests (Ctrl+C, reads, session control) are served from a separate
+  pool, so an interrupt is never queued behind a long-running command.
+
+### Added
+- Vendor-CLI and pager support: `--More--` style pagers are auto-paginated, and
+  `shell: false` runs an appliance CLI (Keenetic NDM and similar) on a channel with
+  no shell wrapping, kept strictly separate from the POSIX shell tab.
+- `file` tool: in-place remote search-and-replace edit with line-numbered
+  diagnostics, similarity hints, and an optional private `0600` `<path>.mcp.bak`.
+- `--tool-profile lean`: 6 everyday tools, roughly half the catalog tokens.
+- `--import-ssh-config`: register key-auth hosts from `~/.ssh/config`.
+- Degraded mode: without paramiko the server still answers JSON-RPC with real
+  errors (-32700 / -32603) instead of hanging or returning an empty tool catalog.
+- MCP client contract: negotiates protocol 2025-06-18 with fallback to older
+  revisions, sends `instructions` on initialize, and annotates every tool with
+  `readOnlyHint` / `destructiveHint` / `idempotentHint`.
+
+### Security
+- Per-host read-only guardrail and merged command blacklists, with local directory
+  containment for file transfers. Documented explicitly as *not* a security
+  boundary.
+
+## [5.x] and earlier
+
+See the commit history for the pre-6.0 line of development.

mcp_ssh_gateway-6.0.1/CONTRIBUTING.md

@@ -0,0 +1,64 @@
+# Contributing
+
+Thanks for looking at this. The project is small and self-contained, and PRs are welcome.
+
+## Ground rules that are not negotiable
+
+- **Do not break the output contract.** `has_more` is the number of unread *lines*.
+  `line_limit` counts lines, not characters. `offset` never consumes. Output reaching
+  the agent must contain no internal markers, no shell prompt, and no double-echoed
+  commands. The tests in `tests/test_server.py`, `tests/test_ssh.py`,
+  `tests/test_multiserver.py` and `tests/test_fs.py` enforce this.
+- **Non-zero exit is a result, not an error.** `completed_nonzero` + `exit_status`
+  must never become a tool error. Only `failed`/`dead` are errors.
+- **Every tool keeps its annotations.** `TOOL_ANNOTATIONS` in `src/server.py` must
+  cover the whole catalog, and the `lean` profile must keep annotations.
+- **Initialize is a contract.** `protocolVersion` is negotiated against
+  `SUPPORTED_PROTOCOL_VERSIONS`, and `serverInfo` must use the public name
+  (`mcp-ssh`), never an internal codename.
+
+## Setup
+
+```bash
+git clone https://github.com/d00mus/MCP-SSH.git
+cd MCP-SSH
+pip install -r requirements.txt
+```
+
+Python 3.11+ (CI also runs 3.13).
+
+## Run the tests
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+For one module:
+
+```bash
+python -m unittest tests.test_server -v
+```
+
+The suite uses only `unittest` and `unittest.mock`, so no test dependencies are
+needed. Most tests mock paramiko and never open a socket; if you add a test that
+touches the network, mark it clearly and keep it out of the default path.
+
+## Style
+
+- Plain `unittest`, no pytest-only constructs.
+- Comments explain *why*, especially around output framing and concurrency.
+- Keep the tool catalog small. A new tool needs a good reason: it is prompt tokens
+  in every session for every user.
+
+## Opening a change
+
+1. Branch from `master`.
+2. Add or update tests alongside the behaviour change.
+3. Update `CHANGELOG.md` under `[Unreleased]`.
+4. Open a pull request describing the user-visible effect, not just the diff.
+
+## Reporting bugs
+
+Use the issue templates. A useful report includes the MCP client, the host type
+(POSIX shell vs vendor CLI), the exact tool call, and the returned JSON — not a
+screenshot of the terminal.

mcp_ssh_gateway-6.0.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 d00mus
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mcp_ssh_gateway-6.0.1/MANIFEST.in

@@ -0,0 +1,14 @@
+include README.md
+include LICENSE
+include QUICK_START.md
+include CHANGELOG.md
+include CONTRIBUTING.md
+include SECURITY.md
+include requirements.txt
+include servers.json.example
+include mcp.json.example
+include server.json
+include mcp-server.py
+recursive-include src *.py
+recursive-include tests *.py
+recursive-include .github *.yml *.md

mcp_ssh_gateway-6.0.1/PKG-INFO

@@ -0,0 +1,148 @@
+Metadata-Version: 2.4
+Name: mcp-ssh-gateway
+Version: 6.0.1
+Summary: MCP server for a whole fleet of SSH hosts: persistent sessions with scrollback, explicit exit statuses, pager- and router-CLI-aware (Keenetic NDM), hot-reloaded config, honest output paging.
+Author-email: Constantine Shklyarov <d00mus@users.noreply.github.com>
+License: MIT
+Project-URL: Homepage, https://github.com/d00mus/MCP-SSH
+Project-URL: Repository, https://github.com/d00mus/MCP-SSH
+Project-URL: Issues, https://github.com/d00mus/MCP-SSH/issues
+Project-URL: Changelog, https://github.com/d00mus/MCP-SSH/blob/master/CHANGELOG.md
+Keywords: mcp,model-context-protocol,ssh,ssh-gateway,ai-agents,ai-devops,multi-server,keenetic,router,paramiko
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Networking
+Classifier: Topic :: System :: Systems Administration
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: paramiko>=3.0.0
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=5.1; extra == "dev"
+Dynamic: license-file
+
+<!-- mcp-name: io.github.d00mus/mcp-ssh-gateway -->
+
+# MCP SSH Gateway
+
+**Use your MCP client to work with several SSH hosts through one local connection.** Run diagnostics on a VPS, inspect a NAS or query a Keenetic router by name. Sessions preserve terminal state between calls; long output can be read a page at a time.
+
+For people who already use SSH and want an assistant to help with routine diagnostics and administration. It is not an SSH daemon, a hosted proxy or a replacement for access controls on your servers.
+
+[![CI](https://github.com/d00mus/MCP-SSH/actions/workflows/ci.yml/badge.svg)](https://github.com/d00mus/MCP-SSH/actions/workflows/ci.yml) [![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://www.python.org/downloads/) [![License: MIT](https://img.shields.io/badge/License-MIT-green.svg)](LICENSE)
+
+## Try it with one host
+
+You need Python 3.11+, an SSH account on a host you control and an MCP client that can launch a local stdio server. **PyPI publication of version 6.0.1 is pending.** Until it is published, start from this repository.
+
+1. Clone the project and install its dependencies:
+
+   ```bash
+   git clone https://github.com/d00mus/MCP-SSH.git
+   cd MCP-SSH
+   python -m pip install -r requirements.txt
+   ```
+
+2. Create `servers.json` in that directory (replace the address, user and key path with your own):
+
+   ```json
+   {
+     "servers": {
+       "lab": {
+         "host": "192.168.1.10",
+         "user": "your-ssh-user",
+         "key_path": "~/.ssh/id_ed25519"
+       }
+     }
+   }
+   ```
+
+   Host-key verification is enabled by default and uses the machine’s system host-key store. Ensure the host key is already trusted there, and verify its fingerprint independently before adding it. For password authentication, use `"password": "${LAB_SSH_PASSWORD}"` and provide `LAB_SSH_PASSWORD` to the MCP server process. Do not commit real credentials or your `servers.json`. See the [security policy](SECURITY.md).
+
+3. Add this to a client that uses the `mcpServers` config format. **Replace both absolute paths**: clients do not necessarily start in the cloned directory.
+
+   ```json
+   {
+     "mcpServers": {
+       "ssh-gateway": {
+         "command": "python",
+         "args": [
+           "/absolute/path/to/MCP-SSH/mcp-server.py",
+           "--servers-config", "/absolute/path/to/MCP-SSH/servers.json"
+         ]
+       }
+     }
+   }
+   ```
+
+   On Windows, point `command` to your Python executable if needed and use escaped backslashes in JSON paths (for example `C:\\work\\MCP-SSH\\mcp-server.py`). Restart the MCP client after updating its config. Running the script directly is not an interactive SSH terminal: it communicates with the client over stdio.
+
+4. In the client, ask: **“List my SSH hosts, then run `uname -a` on lab.”** If the host is missing, check the config path and the client's MCP server logs. If SSH fails, check credentials and host-key verification.
+
+Add more hosts under `servers` in the same file. [servers.json.example](servers.json.example) shows a multi-host configuration; check its host-key and credential choices before copying it.
+
+## What using it looks like
+
+A Linux host and a router can share one MCP connection. Your client makes calls like these (they are not terminal commands):
+
+```text
+server_list()                                          # find configured hosts
+run(server="lab", command="df -h")                  # inspect disk space
+run(server="keenetic", command="show interface", shell=false)  # router CLI
+```
+
+`run` returns a `session_id`; pass it to later calls if you need the same terminal state. Without it an idle session may be reused with unknown state; `new_session: true` forces a clean session. A command still running after the initial wait (5 seconds by default) reports `still_running: true`. Use `read(session_id="...")` for later output, or whenever `has_more` indicates unread lines. `signal(action="ctrl_c")` interrupts a stuck command. Non-zero exits report `completed_nonzero` and `exit_status`, not silent success.
+
+The `file` tool can inspect and edit remote files through SFTP (with shell fallback). Review edits and give an assistant only the SSH permissions it needs.
+
+## When to use it
+
+- **Multiple hosts:** one MCP server configuration routes calls to named targets. For just one host, this matters less.
+- **Multi-step troubleshooting:** persistent sessions keep shell state, while line-based output windows avoid dumping an entire log into the conversation at once.
+- **A Keenetic alongside Linux hosts:** `shell: false` sends device CLI commands without a POSIX shell; common pagers such as `--More--` are handled. Keenetic NDM is a supported use case, but other vendor CLIs are not guaranteed. Keep NDM CLI and Linux shell operations in separate sessions.
+
+**Security boundary:** `read_only` and command blacklists are best-effort guardrails against mistakes, not a sandbox. Shell expansion and interpreters can bypass checks on command text. Use restricted SSH users and server-side permissions for sensitive hosts. Host-key verification is on by default; avoid turning it off casually.
+
+The SSH connection originates from the machine running the gateway. This project works with MCP clients that can start a stdio server; it does not add SSH access to a chat app without MCP integration.
+
+## Other ways to run it
+
+**Docker (build from this clone):**
+
+```bash
+docker build -t mcp-ssh-server .
+docker run -i --rm \
+  -v /absolute/path/to/servers.json:/app/servers.json:ro \
+  -v /absolute/path/to/your/.ssh:/root/.ssh:ro \
+  mcp-ssh-server --servers-config /app/servers.json
+```
+
+Use absolute mount paths and pass required environment variables with `-e NAME`. This example exposes SSH keys to the container; mount only what it needs. For an MCP client using Docker, set `command` to `docker` and put the same run arguments in `args`.
+
+**PyPI / MCP Registry:** PyPI publication of version 6.0.1 and the MCP Registry listing are pending. Until published, `pip install mcp-ssh-gateway` and `uvx --from mcp-ssh-gateway ...` will not work. See the [release process](docs/PUBLISHING.md). No publication badge is shown until there is a listing.
+
+## Configuration and tools
+
+- Each target has an alias, `host`, `user`, optional `port` (default 22) and a `key_path` or `password`. `verify_host` defaults to `true`. `password` and `key_passphrase` support environment references (`${NAME}`); missing references fail at startup.
+- The default full profile exposes `server_list`, `server_add`, `run`, `read`, `signal`, `file`, `session_list`, `session_update`, `session_close` and `last_command_details`. `server_add` accepts an `alias` and only appends new targets. `--tool-profile lean` exposes six everyday tools for a smaller catalog.
+- Changes to `servers.json` are checked periodically (every 30 seconds); `server_list(reload=true)` checks immediately. Unchanged hosts keep their sessions; removing a host or changing its address, login or host-key settings closes that host’s active sessions.
+- `--log-output meta` (the default) records lifecycle information and command text. `full` also records raw output; `off` disables logging. Consider what secrets might appear in commands and output.
+
+For contributions or vulnerabilities, see [CONTRIBUTING.md](CONTRIBUTING.md) and [SECURITY.md](SECURITY.md).
+
+## Development
+
+```bash
+python -m unittest discover -s tests -t .
+```
+
+See the [changelog](CHANGELOG.md). MIT-licensed; see [LICENSE](LICENSE).

mcp_ssh_gateway-6.0.1/QUICK_START.md

@@ -0,0 +1,159 @@
+# Quick Start: Multi-Server SSH MCP Gateway
+
+Connect an MCP client to your SSH hosts through one locally running gateway. Start with the simpler [README setup](README.md#try-it-with-one-host); the examples below cover more options.
+
+---
+
+## 1. Prepare Configuration (`servers.json`)
+
+Create `servers.json` at the absolute path you will pass with `--servers-config` (or copy [servers.json.example](servers.json.example)):
+
+```json
+{
+  "servers": {
+    "keenetic": {
+      "host": "192.168.1.1",
+      "port": 22,
+      "user": "admin",
+      "password": "${KEENETIC_PASSWORD}",
+      "description": "Keenetic Ultra router",
+      "verify_host": true,
+      "extra_path": "/opt/bin:/opt/sbin"
+    },
+    "nas": {
+      "host": "192.168.1.10",
+      "port": 22,
+      "user": "storage",
+      "key_path": "~/.ssh/id_rsa",
+      "description": "TrueNAS storage",
+      "max_sessions": 10
+    },
+    "vps-prod": {
+      "host": "203.0.113.5",
+      "port": 2222,
+      "user": "ubuntu",
+      "key_path": "~/.ssh/vps_key",
+      "read_only": true,
+      "command_blacklist": ["reboot", "poweroff", "rm -rf"],
+      "description": "Production web server (read-only)"
+    }
+  }
+}
+```
+
+> **Before connecting:** verify and add the SSH host key to the system host-key store on the machine running the gateway. `verify_host: true` rejects unknown host keys. `${KEENETIC_PASSWORD}` must be set in the MCP process environment. `read_only` and command blacklists are mistake guards, not a security boundary; use restricted SSH accounts. See [SECURITY.md](SECURITY.md).
+
+---
+
+## 2. Installation & Running
+
+### Path A: Python (Fastest)
+
+```bash
+pip install -r requirements.txt
+```
+
+### Path B: Docker
+
+```bash
+docker build -t mcp-ssh-server .
+```
+
+---
+
+## 3. Configure your AI Agent
+
+### MCP Client Config (`mcp.json`)
+
+**With Python (Windows example):**
+```json
+{
+  "mcpServers": {
+    "ssh-gateway": {
+      "command": "python",
+      "args": [
+        "C:\\tools\\ssh-gateway\\mcp-server.py",
+        "--servers-config", "C:\\tools\\ssh-gateway\\servers.json",
+        "--project-root", "C:\\work"
+      ],
+      "env": {
+        "KEENETIC_PASSWORD": "your_secure_password"
+      }
+    }
+  }
+}
+```
+
+**With Docker:**
+
+```json
+{
+  "mcpServers": {
+    "ssh-gateway": {
+      "command": "docker",
+      "args": [
+        "run", "-i", "--rm",
+        "-v", "C:/tools/ssh-gateway/servers.json:/app/servers.json:ro",
+        "-v", "C:/Users/username/.ssh:/root/.ssh:ro",
+        "-v", "C:/tools/ssh-gateway/.ssh-cache:/app/.ssh-cache",
+        "mcp-ssh-server",
+        "--servers-config", "/app/servers.json"
+      ],
+      "env": {
+        "KEENETIC_PASSWORD": "your_secure_password"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop (`claude_desktop_config.json`)
+
+```json
+{
+  "mcpServers": {
+    "ssh-gateway": {
+      "command": "python",
+      "args": [
+        "/opt/ssh-gateway/mcp-server.py",
+        "--servers-config", "/opt/ssh-gateway/servers.json"
+      ]
+    }
+  }
+}
+```
+
+---
+
+### 4. Key Agent Workflows & Best Practices
+
+1. **Discover Servers:**
+   The AI calls `server_list` to see all configured hosts, status, and active sessions. `server_list` always provides inline `active_sessions: [{"session_id": "...", "status": "...", "mode": "..."}]` in both profiles, eliminating the need for `session_list`.
+2. **Execute Commands (`run`):**
+   - Explicit target: `run(server="keenetic", command="show interface", shell=false)`
+   - Composite session ID: `run(session_id="nas/1", command="zpool status")`
+   - **Direct Output:** Commands that complete within 5.0s return their first output window directly. Call `read` only if `has_more` reports unread lines, or if a command is still running; a completed command with `has_more: 0` needs no extra read.
+   - **Long-Running Commands:** Commands taking longer than 5.0s return `still_running: true` without failing. Read their remaining output via `read(session_id="...")`. `status` may also be `completed_nonzero`, `interrupted` (e.g. when `hard_timeout` fired; partial output kept) or `stalled` (quiet idle with no end-of-command marker; adds `unconfirmed_completion: true`).
+   - **Sequential vs Concurrent:** Pass `session_id` to run sequential commands in the same session. Omit `session_id` to reuse an idle session (or pass `new_session: true` for a clean one).
+   - **Async Execution:** Pass `wait_timeout: 0` for immediate return while the command continues in its session.
+   - **Standard Shell Pipelines:** Use standard `| grep`, `| awk`, `| head` inside the command string for filtering.
+   - **Single non-interactive commands:** Pass `use_pty: false` for pure single exec commands with closed `stdin` (bypasses terminal echoes and PTY line limits; note: interactive heredocs are not supported when `use_pty: false`).
+3. **Session Management (1 Session = 1 Terminal):**
+   - An SSH session is a single terminal process (PTY). Never send concurrent commands to the same session.
+   - Reuse `session_id` for sequential steps; pass `new_session: true` to execute commands in parallel in a clean session (omitting `session_id` reuses an idle one).
+   - Close temporary diagnostic sessions with `session_close` when done to free the session limit.
+   - For Keenetic: keep NDM CLI (`shell: false`) and Linux shell (`shell: true`) in separate sessions.
+4. **Buffered Output, Scrolling & Canvas Windowing (`read`):**
+   - **One line-based stream** (the tab canvas): `line_limit` (default 200 lines, max 5000, `0` = no line cap), `tail` (last N lines; moves the unread position to the end and reports skipped unread lines as `dropped_data`), `offset` (**line** position: negative=peek back from the cursor, `0`=inspect from the very first line, positive=inspect from line N; any `offset` is a non-consuming peek - the unread cursor does NOT move and progress is preserved). `has_more` is the **number of unread LINES still left** (`0` = caught up) - repeat the same read to continue.
+   - Paging is server-side: there is no continuation token (the old `cursor` argument was removed and is rejected) - a plain `read(session_id)` continues with the unread output.
+   - Per-tab history holds up to 2,000,000 characters; output is mirrored into the canvas and completed run buffers are evicted under a global budget, so `offset: 0` still re-reads whatever the canvas holds (`dropped_data` reports unread text dropped before it could be delivered).
+   - The response also carries `status` (`running`, `completed`, `completed_nonzero`, `interrupted`, `stalled`) and `still_running`; a window cut by `line_limit` is reported through `has_more` plus a `hint` (raise line_limit or read again). `wait_timeout` waits for completion **or** new output and blocks only while the stream is silent.
+5. **Interrupt Stuck Commands (`signal`):**
+   - Call `signal(action="ctrl_c")` to immediately terminate a hanging command and free the session.
+6. **Remote Files (`file`):**
+   - Inspect or download files with `action: "read"`. Supports line-based pagination (`offset_line: 1`, `limit_lines: 200`, returning `next_offset_line`).
+   - Modify remote files with `action: "edit"` and search-and-replace (`edits: [{"old_text": "...", "new_text": "..."}]`); `create_backup: true` requests a `.mcp.bak` backup. Do not assume every remote filesystem or shell fallback guarantees atomic replacement or private permissions.
+7. **Register New Servers On The Fly:**
+   - In full profile, the AI can call `server_add(alias="staging-app", host="10.0.0.5", user="deploy")` without restarting the server.
+8. **Live Hot-Reload:**
+   - Edit credentials or servers in `servers.json` — the gateway detects changes automatically on the next health-loop pass (every 30 seconds), or immediately via `server_list(reload: true)`, with zero downtime for unaffected sessions.