🛡️ SSH Remote MCP — Matlock Edition

"Never trust raw command piping. Verify state forensically. Contain the blast radius."
An enterprise-grade Model Context Protocol (MCP) server engineered with Grab's Matlock Agent Mindset for safe, deterministic, and audited remote infrastructure management.

⚡ The Problem with Commodity SSH MCPs

Traditional SSH MCPs treat the remote server like a dumb stdin/stdout pipe:

1. Blind Execution / Command Injection: Raw multiline scripts and unescaped quotes corrupt remote configuration files or cause hanging heredocs.

2. Zero Blast-Radius Control: A hallucinated rm -rf / or recursive permission change runs unconditionally, permanently bricking nodes.

3. No Forensic Verification: Commands returning exit code 0 are assumed successful, even when background services fail to bind ports or immediately enter crash loops.

4. Dangerous Remote File Mutations: Overwriting remote files without backup snapshots or unified diff inspection leads to silent data loss.

5. Session Hanging on Long Tasks: Builds, container pulls, or migrations cause client stdio timeouts.

Related MCP server: ssh-pro-mcp

🏛️ The Matlock Architecture

                       ┌────────────────────────────────────────┐
                       │           AI Agent / Client            │
                       └───────────────────┬────────────────────┘
                                           │ JSON-RPC (MCP)
                                           ▼
┌────────────────────────────────────────────────────────────────────────────────────────┐
│                                 SSH REMOTE MCP                                         │
│                                                                                        │
│  ┌───────────────────────┐  ┌─────────────────────────┐  ┌─────────────────────────┐  │
│  │ 3-Tier Blast Radius   │  │   Forensic Assertion    │  │   Safe SFTP Engine      │  │
│  │     Containment       │  │         Engine          │  │  (Atomic + Diff + Roll) │  │
│  │                       │  │                         │  │                         │  │
│  │ • Tier 1: Safe Read   │  │ • Port Listening Verify │  │ • Auto .matlock.bak     │  │
│  │ • Tier 2: Mutating    │  │ • Process Liveness Check│  │ • Base64 Safe Transfer  │  │
│  │ • Tier 3: Block/Gate  │  │ • File State Check      │  │ • Unified Git Diffs     │  │
│  │   (Safety Bypass Tkn) │  │ • HTTP Health Probe     │  │ • 1-Click Rollback      │  │
│  └───────────────────────┘  └─────────────────────────┘  └─────────────────────────┘  │
│                                                                                        │
│  ┌──────────────────────────────────┐  ┌─────────────────────────────────────────┐     │
│  │   Background Task Envelope       │  │     Multiplexed Session & Profile Store │     │
│  │   (Detached + Poll + Kill)       │  │     (~/.matlock/profiles.json)          │     │
│  └──────────────────────────────────┘  └─────────────────────────────────────────┘     │
└──────────────────────────────────────────┬─────────────────────────────────────────────┘
                                           │ SSH2 / SFTP Keepalive Pool
                                           ▼
                                 ┌───────────────────┐
                                 │    Remote Host    │
                                 │ (Homelab / Cloud) │
                                 └───────────────────┘

🧰 Available Tools (10 Primitives)

1. Command Execution & Telemetry

2. Long-Running Task Envelope

3. Safe Atomic SFTP Primitives

4. Profile, Key Bootstrap & Credential Isolation

🔒 3-Tier Blast Radius Containment

• Tier 1 (Safe / Telemetry): Read-only inspection (ls, cat, df, free, ps, docker ps, ss). Automatically executed.

• Tier 2 (Mutating): System mutations (mkdir, systemctl restart, docker compose up -d, apt install). Executed with pre/post flight forensic assertions.

• Tier 3 (Destructive): High-risk operations (rm -rf /, mkfs, dd to /dev/sd*, shutdown, reboot, iptables -F, kill -9 1). Interpreted and BLOCKED before transmission unless explicit confirmDangerToken: true is supplied.

🚀 1-Click Universal Auto-Installer (Cài tự động cho mọi Agent IDE)

ssh-remote-mcp tích hợp sẵn bộ Auto-Installer thông minh, tự động quét và cài đặt vào mọi Agent IDE có trên máy tính của bạn (Claude Desktop, VS Code Native MCP, Antigravity, Cursor, Windsurf, Cline, Roo Code, Continue, Zed):

# 1-Click Cài đặt tự động qua NPX (tự động nhận diện IDE và cấu hình an toàn):
npx github:nguyenquocanhz/ssh-remote-mcp install

# Hoặc cài từ local repo:
node dist/index.js install

# Xem danh sách các IDE được phát hiện trên máy:
npx github:nguyenquocanhz/ssh-remote-mcp list

# Cài đặt ép buộc cho tất cả IDE (kể cả chưa khởi tạo config):
npx github:nguyenquocanhz/ssh-remote-mcp install --all

✨ Tính năng an toàn của Auto-Installer:

• Không ghi đè dữ liệu cũ: Giữ nguyên 100% các MCP server đang có (zmp-mcp, unityMCP,...).

• Tự động sao lưu: Tạo file snapshot .matlock.bak.<timestamp> trước khi chỉnh sửa.

• Hỗ trợ đa nền tảng: Windows, macOS, Linux.

⚙️ Cấu hình thủ công (Manual Configuration)

Nếu bạn muốn cấu hình thủ công vào file config của IDE:

Cách 1: Chạy trực tiếp qua NPX từ GitHub:

{
  "mcpServers": {
    "ssh-remote-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "github:nguyenquocanhz/ssh-remote-mcp"
      ]
    }
  }
}

Cách 2: Chạy từ source code cục bộ:

cd D:\ssh-remote-mcp
npm install
npm run build

Cấu hình trong mcp_config.json:

{
  "mcpServers": {
    "ssh-remote-mcp": {
      "command": "node",
      "args": [
        "D:\\ssh-remote-mcp\\dist\\index.js"
      ]
    }
  }
}

🧪 Verification & Evidence

Run the integrated automated forensic test suite:

node test-matlock.js

Verified against Homelab Node (192.168.100.169):

• ✅ ssh_host_diagnose: OS Ubuntu 24.04.5 LTS, 15 Docker containers detected (zaloapp-backend healthy on port 8088).

• ✅ ssh_exec: Post-flight assertions verified Port 8088 listening and cloudflared active.

• ✅ Blast-Radius: Destructive rm -rf / blocked by Matlock guardrails.

• ✅ Safe SFTP: Atomic backup created, unified diff generated, rolled back cleanly.

• ✅ Background Envelope: Detached runner script executed for loop, polled output, and returned exit code 0.