@neoline/hostbridge 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 hostbridge contributors
+
+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.

package/README.md

@@ -0,0 +1,350 @@
+# hostbridge
+
+A local MCP server for AI agents to operate allowlisted interactive shells, usually SSH sessions. It keeps PTYs alive in memory, so an agent can open a session once, run quick commands, start long-running background jobs, and poll logs until completion.
+
+This repo is portable: it ships with no personal server paths or built-in hosts. Each user declares their own connection targets in `~/.hostbridge/hosts.json` or a path set by `HOSTBRIDGE_HOSTS_FILE`.
+
+## Tools
+
+- `hosts_list` — reload and show configured connection targets and local script availability when applicable.
+- `hosts_reload` — explicitly reload configured connection targets without restarting the MCP server.
+- `session_open(host_id, connect_timeout=30)` — open a persistent interactive shell for one configured host.
+- `sessions_list()` — list live sessions in this MCP process.
+- `sessions_close_all()` — close every live session in one call; useful for shutdown and cleanup.
+- `command_run(session_id, command, timeout=60)` — run a foreground command and wait for completion.
+- `task_start(session_id, command)` — start a remote background job under `$HOME/.hostbridge/jobs/<task_id>`.
+- `task_status(session_id, task_id, tail_lines=80)` — poll job state, exit code, and log tail.
+- `task_stop(session_id, task_id)` — terminate a running background job and reap its process.
+- `session_write(session_id, text)` — send a raw line for interactive edge cases.
+- `session_read(session_id, timeout=1.0, max_chars=20000)` — read available raw output after interactive writes.
+- `session_close(session_id)` — close a persistent session.
+
+Every tool returns a structured payload with a stable `error_code` on failure (`HOST_NOT_FOUND`, `SESSION_NOT_FOUND`, `POLICY_DENIED`, `TASK_NOT_FOUND`, `TIMEOUT`, `INTERNAL`).
+
+## Install, connect to agents, and configure hosts
+
+The lifecycle mirrors tools like CodeGraph: install the CLI, register the MCP with local agent clients, then configure per-machine host entries. Installing the CLI alone does not connect it to any agent; `hostbridge install` performs that wiring. It does not configure any servers; per-server setup is the separate `hostbridge setup` step.
+
+The shared distribution path is npm. Users can run the MCP server or setup wizard with `npx`:
+
+```bash
+npx -y @neoline/hostbridge install
+npx -y @neoline/hostbridge setup
+npx -y @neoline/hostbridge list
+```
+
+For a persistent global install:
+
+```bash
+npm install -g @neoline/hostbridge
+hostbridge install
+hostbridge setup
+```
+
+`hostbridge install` detects supported local agents and writes only the hostbridge MCP entry into each detected config, preserving existing MCP servers. Supported targets are:
+
+- Codex CLI: `~/.codex/config.toml`
+- Claude Code: `~/.claude.json`
+- Cursor: `~/.cursor/mcp.json`
+- Gemini CLI: `~/.gemini/settings.json`
+- opencode: `~/.config/opencode/opencode.json`
+- Hermes Agent: `~/.hermes/mcp.json`
+- Antigravity IDE: `~/.antigravity/mcp.json`
+- Kiro: `~/.kiro/settings/mcp.json`
+
+Use `--target <name>` for one client only, for example `hostbridge install --target codex`. From a source checkout, the installer registers `python3 <repo>/run_server.py`. From an installed package, it registers the `hostbridge` executable. Restart open agent clients or start new sessions once after installation so the new MCP server is loaded.
+
+This npm package is a Node launcher around the Python MCP core, so the machine still needs Python 3.11+ and the package's Python dependencies available to that interpreter. To point at a non-default interpreter:
+
+```bash
+HOSTBRIDGE_PYTHON=/path/to/python3 npx -y @neoline/hostbridge setup
+```
+
+For local development from this repository:
+
+```bash
+git clone <repo-url> hostbridge
+cd hostbridge
+python3 -m pip install -e .
+python3 -m server_control_mcp.server install
+npm run test:node
+```
+
+## Guided setup wizard
+
+Run the local setup wizard instead of hand-writing `hosts.json`:
+
+```bash
+hostbridge setup
+```
+
+You can also pass the host id up front to reduce prompts:
+
+```bash
+hostbridge setup gpu_1
+```
+
+The wizard now records the real login path instead of asking a fixed questionnaire:
+
+1. Collect only a stable host id, display label, and the command you already run locally, such as `ssh bastion`, `ssh -J bastion alice@gpu.internal`, `bash ~/.ssh/connect_gpu.sh`, or `docker exec -it training-box bash`.
+2. Start that command in a terminal-style PTY proxy: remote output is printed directly, and user input is forwarded to the setup session.
+3. Record the prompt visible when each line is typed. Secret-looking prompts (`password`, `passphrase`, `token`, `OTP`, `密码`, `验证码`) do not echo locally and are encrypted before saving.
+4. Convert the recorded prompt/input pairs into ordered `login_steps`; type `/ready` once the final remote shell prompt is available.
+5. Send a readiness probe through the same session, then replay the recorded `login_steps` in a fresh connection before saving `~/.hostbridge/hosts.json`.
+
+Useful helper commands:
+
+```bash
+hostbridge install
+hostbridge list
+hostbridge check gpu_1
+hostbridge remove gpu_1
+hostbridge setup --config ./hosts.json
+hostbridge reload
+```
+
+### Agent-friendly setup
+
+Agents should prefer the CLI setup flow over searching shell history or hand-editing JSON. A common JumpServer pattern is to clone a known bastion entry and change only the menu-selected host:
+
+```bash
+hostbridge setup gpu_lab_1 \
+  --label "Lab GPU server" \
+  --from-host bastion \
+  --menu-selection "gpu-lab-01" \
+  --final-prompt '.*[$#] '
+```
+
+This reuses the source host's connection command and encrypted secrets, replaces the menu selection, verifies the resulting runtime path, then saves the new host. After setup, running MCP servers that include runtime reload support will pick up the new entry on the next `hosts_list` or `session_open`; no client restart is required. If an already-running MCP process predates this feature, restart it once.
+
+Recommended agent flow:
+
+1. Call `hosts_list`.
+2. If the target host exists, call `session_open`.
+3. If it does not exist and the user identifies a similar bastion-backed host, run `hostbridge setup <new_id> --from-host <source_id> --menu-selection <ip-or-name> --final-prompt <regex>`.
+4. Call `hosts_list` again, then `session_open(<new_id>)`.
+5. Do not inspect `~/.ssh`, old expect scripts, or shell snapshots unless the user explicitly asks or the setup command lacks required information.
+
+### Encrypted login automation
+
+Some environments require a password prompt, a bastion menu, or a JumpServer host selector before the remote shell is available. The setup wizard can save these as ordered `login_steps`. Secrets are encrypted with a local Fernet key at `~/.hostbridge/key` or `HOSTBRIDGE_KEY_FILE`; the decrypted value is used only in memory while opening a session.
+
+Equivalent non-interactive commands are available:
+
+```bash
+hostbridge secret set bastion password
+hostbridge step add bastion --expect '(?i)password:' --send-secret password
+hostbridge step add bastion --expect 'Opt>' --send 'gpu-lab-01'
+hostbridge step add bastion --expect '.*[$#] ' --send ''
+```
+
+Security model:
+
+- `hosts.json` never stores plaintext passwords.
+- `hostbridge list` and `hosts_list` do not expose secret material.
+- `~/.hostbridge/hosts.json` and `~/.hostbridge/key` should be readable only by the local user running the MCP server.
+- Local encryption protects config-at-rest, not a fully compromised same-user account. Prefer SSH keys or system keychains when available.
+
+## Configure hosts
+
+Create `~/.hostbridge/hosts.json`:
+
+```bash
+mkdir -p ~/.hostbridge
+cat > ~/.hostbridge/hosts.json <<'JSON'
+{
+  "hosts": [
+    {
+      "id": "gpu_direct",
+      "label": "GPU direct SSH",
+      "ssh": {
+        "host": "alice@gpu.example.com"
+      }
+    }
+  ]
+}
+JSON
+```
+
+Running MCP servers reload this file during `hosts_list` and `session_open`, so a client restart is not normally required after editing it.
+
+### Direct SSH, no jump host
+
+```json
+{
+  "hosts": [
+    {
+      "id": "gpu",
+      "label": "GPU server",
+      "ssh": {
+        "host": "alice@gpu.example.com"
+      }
+    }
+  ]
+}
+```
+
+### SSH with port, key, and jump host
+
+```json
+{
+  "hosts": [
+    {
+      "id": "gpu_jump",
+      "label": "GPU via bastion",
+      "ssh": {
+        "host": "alice@gpu.internal",
+        "port": 2222,
+        "identity_file": "~/.ssh/gpu_key",
+        "proxy_jump": "bastion.example.com",
+        "extra_args": ["-o", "ServerAliveInterval=30"]
+      }
+    }
+  ]
+}
+```
+
+### Existing shell script wrapper
+
+Use this if you already have a `.sh` or expect wrapper that opens an interactive remote shell.
+
+```json
+{
+  "hosts": [
+    {
+      "id": "legacy_gpu",
+      "label": "Legacy GPU wrapper",
+      "script": "~/.ssh/connect_gpu.sh"
+    }
+  ]
+}
+```
+
+The wrapper does not need executable permission; the MCP runs it with `/bin/sh`.
+
+### Advanced command mode
+
+Use this for non-SSH interactive shells, containers, or custom connection tools. The MCP calls the executable directly without `shell=True`.
+
+```json
+{
+  "hosts": [
+    {
+      "id": "container",
+      "label": "Local container shell",
+      "command": "docker",
+      "args": ["exec", "-it", "training-box", "bash"]
+    }
+  ]
+}
+```
+
+## Host config rules
+
+- `id` may contain only letters, numbers, `_`, `-`, and `.`.
+- Each host must define exactly one practical connection style: `ssh`, `script`, or `command`.
+- `ssh.host` can be any target accepted by `ssh`, such as `user@example.com` or an alias from `~/.ssh/config`.
+- `ssh.identity_file` and `script` expand `~` for the local user running the MCP server.
+- For a different config path, set `HOSTBRIDGE_HOSTS_FILE=/path/to/hosts.json` in the MCP server environment.
+
+## MCP client config
+
+Prefer the installer:
+
+```bash
+hostbridge install
+```
+
+Single-client install is also available:
+
+```bash
+hostbridge install --target codex
+hostbridge install --target cursor
+hostbridge install --target opencode
+```
+
+Codex config written by the installer, for example in `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.hostbridge]
+command = "npx"
+args = ["-y", "hostbridge"]
+```
+
+Claude Desktop style config:
+
+```json
+{
+  "mcpServers": {
+    "hostbridge": {
+      "command": "npx",
+      "args": ["-y", "hostbridge"]
+    }
+  }
+}
+```
+
+To use a project-specific host file:
+
+```toml
+[mcp_servers.hostbridge.env]
+HOSTBRIDGE_HOSTS_FILE = "/absolute/path/to/hosts.json"
+```
+
+See `examples/` for copyable config templates.
+
+## Policy, audit, and idle reaping
+
+hostbridge ships a lightweight policy layer that runs in the same process as the MCP server. It is on by default and can be tuned or disabled via environment variables or a JSON config file.
+
+Environment variables:
+
+| Variable | Effect |
+| --- | --- |
+| `HOSTBRIDGE_DISABLE_POLICY=1` | Disable policy checks and audit logging entirely. |
+| `HOSTBRIDGE_POLICY_FILE=/path/to/policy.json` | Override policy config path (default `~/.hostbridge/policy.json`). |
+| `HOSTBRIDGE_DENYLIST=pat1:pat2` | Append extra deny regex patterns (colon-separated). |
+| `HOSTBRIDGE_IDLE_TIMEOUT=900` | Idle timeout in seconds before an inactive session is reaped (default 1800). |
+| `HOSTBRIDGE_AUDIT_LOG=/path/to/audit.jsonl` | Override audit log path (default `~/.hostbridge/audit.jsonl`). |
+
+Default denylist blocks obviously destructive commands (`rm -rf /`, `mkfs`, `dd of=/dev/sd*`, fork bombs, `shutdown`, `reboot`). A denied command returns `error_code=POLICY_DENIED` with the matched pattern, and is recorded in the audit log alongside session/task lifecycle events.
+
+Policy config file (optional):
+
+```json
+{
+  "idle_timeout_seconds": 1800,
+  "use_default_denylist": true,
+  "command_denylist": ["\\bmytool\\b"],
+  "audit_log_path": "~/.hostbridge/audit.jsonl"
+}
+```
+
+See `SECURITY.md` and `docs/THREAT_MODEL.md` for the trust model and audited events.
+
+## Typical agent workflow
+
+1. Call `hosts_list` and choose a configured host id.
+2. If the host is missing, ask for only the missing fields and use `hostbridge setup <host_id>` rather than manually editing config.
+3. Call `session_open` once for the chosen host.
+4. Use `command_run` for quick commands such as `nvidia-smi`, `pwd`, `df -h`, or `tmux ls`.
+5. Use `task_start` for long training jobs, downloads, builds, or scripts.
+6. Poll `task_status` until `state` is `finished`; inspect `exit_code` and `log_tail`.
+7. Call `task_stop` early if a job should be aborted.
+8. Call `session_close` when finished, or `sessions_close_all` to tear down every session.
+
+## Security notes
+
+- Host access is allowlisted by config; MCP callers cannot provide arbitrary local connection commands at runtime.
+- The server never reads or logs passwords from underlying SSH/script prompts.
+- Commands still run with your remote shell privileges. Use only with trusted local MCP clients.
+- Background task logs and exit codes are stored on the remote host in `$HOME/.hostbridge/jobs/`.
+- The policy layer blocks a built-in destructive denylist and writes structured audit events. It is defense-in-depth, not a sandbox.
+
+## Contributing
+
+See `CONTRIBUTING.md`. Run tests with `python -m pytest -q`. The full suite should pass before pushing.
+
+## License
+
+MIT. See `LICENSE`.

package/bin/hostbridge.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { existsSync } from 'node:fs';
+import { dirname, join, delimiter } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const packageRoot = dirname(__dirname);
+const pythonPath = process.env.HOSTBRIDGE_PYTHON || process.env.SERVER_CONTROL_MCP_PYTHON || 'python3';
+const bundledSrc = join(packageRoot, 'src');
+const moduleDir = join(bundledSrc, 'server_control_mcp');
+const docsUrl = 'https://www.npmjs.com/package/@neoline/hostbridge';
+
+if (!existsSync(moduleDir)) {
+  console.error(`hostbridge: bundled Python sources not found at ${moduleDir}`);
+  console.error(`  This npm package wraps a Python MCP core. See: ${docsUrl}`);
+  process.exit(1);
+}
+
+const env = { ...process.env };
+env.PYTHONPATH = env.PYTHONPATH ? `${bundledSrc}${delimiter}${env.PYTHONPATH}` : bundledSrc;
+
+const child = spawn(pythonPath, ['-m', 'server_control_mcp', ...process.argv.slice(2)], {
+  stdio: 'inherit',
+  env,
+});
+
+child.on('error', (error) => {
+  if (error.code === 'ENOENT') {
+    console.error(`hostbridge: Python interpreter '${pythonPath}' was not found.`);
+    console.error('  Install Python 3.11+ (https://www.python.org/downloads/)');
+    console.error('  or set HOSTBRIDGE_PYTHON to an absolute python3 path.');
+  } else {
+    console.error(`hostbridge: failed to start Python runtime: ${error.message}`);
+    console.error(`  See: ${docsUrl}`);
+  }
+  process.exit(1);
+});
+
+child.on('exit', (code, signal) => {
+  if (signal) {
+    process.kill(process.pid, signal);
+    return;
+  }
+  if (code === 2) {
+    // exit code 2 is reserved by the Python runtime guard for missing dependencies.
+    // The actionable install command was already printed to stderr by Python.
+    console.error(`\nhostbridge: runtime dependency check failed. See: ${docsUrl}`);
+  }
+  process.exit(code ?? 0);
+});

package/bin/server-control-mcp.js

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import './hostbridge.js';

package/examples/claude_desktop_config.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "hostbridge": {
+      "command": "npx",
+      "args": ["-y", "hostbridge"]
+    }
+  }
+}

package/examples/codex.config.toml

@@ -0,0 +1,7 @@
+[mcp_servers.hostbridge]
+command = "npx"
+args = ["-y", "hostbridge"]
+
+# Optional: use a project-specific host file instead of ~/.hostbridge/hosts.json
+# [mcp_servers.hostbridge.env]
+# HOSTBRIDGE_HOSTS_FILE = "/absolute/path/to/hosts.json"

package/examples/hosts.example.json

@@ -0,0 +1,11 @@
+{
+  "hosts": [
+    {
+      "id": "gpu",
+      "label": "GPU server",
+      "ssh": {
+        "host": "alice@gpu.example.com"
+      }
+    }
+  ]
+}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@neoline/hostbridge",
+  "version": "0.2.0",
+  "description": "HostBridge MCP server for persistent allowlisted SSH and shell sessions.",
+  "type": "module",
+  "license": "MIT",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "ssh",
+    "pty",
+    "remote-control",
+    "ai-agent"
+  ],
+  "homepage": "https://www.npmjs.com/package/@neoline/hostbridge",
+  "engines": {
+    "node": ">=18"
+  },
+  "bin": {
+    "hostbridge": "bin/hostbridge.js",
+    "server-control-mcp": "bin/server-control-mcp.js"
+  },
+  "files": [
+    "bin/",
+    "src/server_control_mcp/**/*.py",
+    "pyproject.toml",
+    "README.md",
+    "LICENSE",
+    "examples/"
+  ],
+  "scripts": {
+    "test:node": "node --test"
+  }
+}

package/pyproject.toml

@@ -0,0 +1,89 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hostbridge"
+version = "0.2.0"
+description = "HostBridge MCP server for persistent allowlisted SSH and shell sessions."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [
+  { name = "HostBridge contributors" },
+]
+keywords = [
+  "mcp",
+  "model-context-protocol",
+  "ssh",
+  "pty",
+  "remote-control",
+  "ai-agent",
+]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Environment :: Console",
+  "Intended Audience :: Developers",
+  "Intended Audience :: System Administrators",
+  "Operating System :: POSIX",
+  "Operating System :: MacOS",
+  "Programming Language :: Python :: 3",
+  "Programming Language :: Python :: 3.11",
+  "Programming Language :: Python :: 3.12",
+  "Programming Language :: Python :: 3.13",
+  "Topic :: System :: Systems Administration",
+  "Topic :: Software Development :: Libraries",
+]
+dependencies = [
+  "mcp>=1.0.0",
+  "pexpect>=4.9.0",
+  "cryptography>=42.0.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0.0",
+  "pytest-cov>=4.1.0",
+  "ruff>=0.6.0",
+  "mypy>=1.10.0",
+]
+
+[project.scripts]
+hostbridge = "server_control_mcp.server:main"
+
+[tool.setuptools]
+package-dir = { "" = "src" }
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 120
+target-version = "py311"
+extend-exclude = ["docs", "build", "dist"]
+
+[tool.ruff.lint]
+select = [
+  "E", "F", "W",   # pycodestyle / pyflakes
+  "I",             # isort
+  "UP",            # pyupgrade
+  "B",             # bugbear
+  "C4",            # comprehensions
+  "SIM",           # simplify
+]
+ignore = ["E501"]  # line length handled by formatter
+
+[tool.ruff.lint.per-file-ignores]
+"tests/*" = ["E402", "B011"]
+
+[tool.mypy]
+python_version = "3.11"
+ignore_missing_imports = true
+warn_unused_ignores = true
+warn_redundant_casts = true
+files = ["src/server_control_mcp"]

package/src/server_control_mcp/__init__.py

@@ -0,0 +1,54 @@
+"""Persistent SSH control MCP server."""
+
+from __future__ import annotations
+
+import sys
+from typing import NoReturn
+
+__all__ = ["__version__", "ensure_runtime"]
+__version__ = "0.2.0"
+
+# (import_name, pip_name) pairs for runtime dependency probing.
+_REQUIRED_DEPENDENCIES = (
+    ("mcp", "mcp"),
+    ("pexpect", "pexpect"),
+    ("cryptography", "cryptography"),
+)
+
+
+def _missing_dependencies() -> list[str]:
+    """Return pip names of runtime dependencies that cannot be imported."""
+
+    missing: list[str] = []
+    for import_name, pip_name in _REQUIRED_DEPENDENCIES:
+        try:
+            __import__(import_name)
+        except ImportError:
+            missing.append(pip_name)
+    return missing
+
+
+def ensure_runtime() -> None:
+    """Abort with an actionable error if required runtime deps are missing.
+
+    Called early from the server entrypoint and from the CLI so the user gets a
+    single, copy-pasteable fix instead of a deep ImportError traceback.
+    """
+
+    missing = _missing_dependencies()
+    if not missing:
+        return
+
+    install_command = "pip install " + " ".join(missing)
+    message = (
+        f"hostbridge: missing Python dependencies: {', '.join(missing)}\n"
+        f"  Install them with:  {install_command}\n"
+        "  Or reinstall the package:  pip install --force-reinstall hostbridge"
+    )
+    print(message, file=sys.stderr)
+    sys.exit(2)
+
+
+def _abort_with_error(message: str) -> NoReturn:
+    print(message, file=sys.stderr)
+    sys.exit(2)

package/src/server_control_mcp/__main__.py

@@ -0,0 +1,16 @@
+from __future__ import annotations
+
+from . import ensure_runtime
+
+
+def main() -> None:
+    ensure_runtime()
+    # Imported lazily so a missing mcp/pexpect/cryptography dependency surfaces
+    # the friendly ensure_runtime() message instead of a raw ImportError.
+    from .server import main as server_main
+
+    server_main()
+
+
+if __name__ == "__main__":
+    main()