MCP SFTP Orchestrator

Điều phối các tác vụ máy chủ từ xa qua SSH và SFTP với hàng đợi liên tục. Lý tưởng cho DevOps và các tác nhân AI.

Tài liệu

🚀 MCP Orchestrator — SSH/SFTP Infrastructure Orchestration Server

Version : 11.3.0
License : MIT
Node : >= 18.0.0

A Model Context Protocol (MCP) server that turns any AI agent (Claude, OpenCode, Cursor...) into a full-fledged system administrator. Persistent queue, SSH connection pool, hybrid sync/async execution.

✨ Key Features

63 MCP tools — SSH, SFTP, file ops, monitoring, snapshots, tunnels
Built-in security — Command blocklist, port allowlist, hash protection
Multi-server — task_exec {alias:["vps1","vps2"]} or alias:"all"}
Persistence — tmux + persistent queue = sessions that survive crashes
Snapshots — Deduplicated versioning of your critical files
SSH Tunnels — Local, Remote, SOCKS5 with secured port allowlist
AI Guide — Built-in manual for the agent (section:index/workflows/audit/security)

🇫🇷 Version française : README.fr.md

📦 Installation

Via npx (recommended)

npx @fkom13/mcp-sftp-orchestrator

Via git

git clone https://github.com/fkom13/mcp-sftp-orchestrator.git
cd mcp-sftp-orchestrator
npm install
cp .env.example .env
# Edit .env with your paths

Requirements: Node.js >= 18.0.0

⚙️ Configuration (.env)

All variables are optional. Defaults are designed for standard usage.

Variable	Default	Description
`MCP_DATA_DIR`	`~/.config/mcp-orchestrator`	Data directory (servers.json, apis.json, queue.json)
`MCP_SYNC_TIMEOUT_S`	`120`	Seconds before background execution
`MCP_DEFAULT_CMD_TIMEOUT_S`	`600`	Default SSH timeout (0 = unlimited)
`MCP_INTERACTIVE_CMD_TIMEOUT_S`	`300`	Interactive command timeout (0 = unlimited)
`MCP_MAX_WAIT_TIMEOUT_S`	`600`	Max timeout for `task_wait`
`MAX_CONNECTIONS_PER_SERVER`	`5`	Max parallel SSH connections per server
`MIN_CONNECTIONS_PER_SERVER`	`1`	Min pooled connections per server
`IDLE_TIMEOUT`	`300000`	Idle connection close delay (ms)
`KEEP_ALIVE_INTERVAL`	`30000`	SSH keepalive interval (ms)
`MAX_QUEUE_SIZE`	`1000`	Max jobs in queue
`SAVE_INTERVAL`	`5000`	Queue disk save interval (ms)
`MCP_ALLOWED_ROOTS`	(empty)	Restrict file access to these roots (comma-separated). Empty = full access
`MCP_DEBUG`	`false`	Enable detailed debug logs

🔌 MCP Client Configuration (OpenCode, Claude Desktop, etc.)

{
  "mcpServers": {
    "orchestrator": {
      "command": "node",
      "args": ["/path/to/sftp-mcp/server.js"],
      "env": {
        "MCP_DATA_DIR": "/path/to/sftp-mcp/data"
      }
    }
  }
}

🧰 Tool Reference (63 tools)

Help & Diagnostics

Tool	Description
`help`	Complete guide: tools, env vars, parameter schemas
`guide`	AI manual: workflows, cheatsheet, audit, security
`system_diagnostics`	Full system diagnostic (queue, pool, servers, APIs)

Server Management

Tool	Description
`server_add`	Add/update a server alias
`server_list`	List all configured servers
`server_remove`	Remove a server alias
`infra_overview`	Fleet-wide overview (roles, services, warnings)
`server_note_set/get/list/remove`	Documented server context

Security (Blocklist)

Tool	Description
`policy_blocklist_list`	List blocked commands
`policy_blocklist_add`	Add a pattern to blocklist
`policy_blocklist_remove`	Remove a pattern from blocklist

Task Execution

Tool	Description
`task_exec`	SSH one-shot. Supports `alias:["vps1","vps2"]` or `alias:"all"`
`task_exec_interactive`	SSH with interactive prompt handling
`task_exec_sequence`	Sequential SSH commands
`task_transfer`	SFTP transfer. Supports `server_to_server`
`task_transfer_multi`	Bulk transfers with glob patterns

Monitoring

Tool	Description
`get_system_resources`	CPU, RAM, Disk metrics
`get_services_status`	systemd, Docker, PM2 status (graceful fallback)
`get_fail2ban_status`	Fail2Ban status
`check_api_health`	HTTP health check

Logs

Tool	Description
`get_pm2_logs`	PM2 logs
`get_docker_logs`	Docker logs
`tail_file`	Tail a remote file

File Operations (Local + Remote)

Tool	Description
`file_read`	Read file + SHA-256 hash (edit protection)
`file_write`	Create/overwrite with `dryRun` and `backup`
`file_edit`	Surgical or full edit + hash protection

Comparison & Drift Detection

Tool	Description
`diff_files`	Compare 2 files (local/remote, cross-server)
`diff_folders`	Compare 2 directories
`compare_all_sources`	Detect drifts across N servers

Persistent Shell Sessions

Tool	Description
`shell_create`	Open a persistent shell (cd/env preserved)
`shell_exec`	Execute in an existing session
`shell_list` / `shell_close`	List/close sessions

tmux (Surviving Terminal Sessions)

Tool	Description
`tmux_create`	Create a persistent tmux session
`tmux_exec`	Send a command to a session
`tmux_read`	Read session buffer
`tmux_list` / `tmux_kill`	List/kill sessions

SSH Tunnels

Tool	Description
`tunnel_create`	Local/remote/SOCKS5 tunnel, persistent via tmux
`tunnel_list`	List active tunnels
`tunnel_close`	Close a tunnel
`tunnel_allowlist_add/remove`	Manage allowed ports

Snapshots (File Versioning)

Tool	Description
`snapshot_create`	Capture file state with deduplication
`snapshot_list`	List snapshots
`snapshot_diff`	Compare 2 snapshots
`snapshot_restore`	Restore (dryRun by default)
`snapshot_delete`	Delete + orphan cleanup

Queue & Monitoring

Tool	Description
`task_queue`	View all active/pending tasks
`task_status`	Task detail by ID
`task_history`	Filterable history
`task_retry`	Retry a failed task
`task_wait`	Wait for a background task
`task_logs`	MCP internal logs
`queue_stats` / `pool_stats`	Queue and SSH pool stats

API Catalog

Tool	Description
`api_add` / `api_list` / `api_remove`	API monitoring catalog
`api_check`	Health check via SSH + curl

📖 Usage Examples

Multi-server

# One command, multiple servers
task_exec {alias:["vps1","vps2","vps3"], cmd:"uptime"}

# Entire fleet
task_exec {alias:"all", cmd:"df -h /"}

SOCKS5 Proxy Tunnel

tunnel_create {name:"proxy", type:"socks", listen_port:1080, via:"vps_paris"}
# → Browser → SOCKS5 127.0.0.1:1080 → Paris VPS

Local Tunnel (access remote service)

tunnel_create {name:"crm", type:"local", listen_port:8080, target:"127.0.0.1:3100", via:"vps_prod"}
# → http://localhost:8080 → production CRM

Remote Tunnel (expose local service)

tunnel_create {name:"dev", type:"remote", listen_port:9090, target:"127.0.0.1:3000", via:"vps", source:"vps_prod", key_path:"/home/user/.ssh/vps.key"}
# → vps_prod:9090 → your local machine:3000

Persistent tmux Session

tmux_create {alias:"vps", name:"build", start_cmd:"npm run build"}
tmux_read {alias:"vps", session:"build"}
tmux_kill {alias:"vps", session:"build"}

Security Blocklist

# List blocked commands
policy_blocklist_list
# → ["rm -rf /", "mkfs*", ...]

# Conscious bypass
task_exec {alias:"vps", cmd:"rm -rf /tmp/cache", skip_policy:true}

Secure File Editing

# Read + hash
file_read {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"}}
# → content + hash

# Edit with protection
file_edit {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"},
           oldString:"worker_connections 768;",
           newString:"worker_connections 1024;",
           expectedHash:"abc123...",
           backup:true}

# Preview without writing
file_edit {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"},
           oldString:"worker_connections 768;",
           newString:"worker_connections 1024;",
           dryRun:true}

Snapshot Before Risky Changes

# Before
snapshot_create {source:{type:"remote", alias:"vps"}, paths:["/etc/nginx/"], tag:"before-fix"}

# After if something broke
snapshot_restore {snapshotId:"...", target:{type:"remote", alias:"vps"}, dryRun:false, force:true}

Multi-server Drift Detection

compare_all_sources {sources:[
  {type:"remote", alias:"vps1", path:"/etc/nginx/nginx.conf", label:"prod"},
  {type:"remote", alias:"vps2", path:"/etc/nginx/nginx.conf", label:"staging"}
]}

📚 AI Built-in Manual (guide)

The orchestrator includes an interactive manual for your AI agent:

guide section:index       # Table of contents
guide section:workflows   # Copy-paste recipes
guide section:cheatsheet  # Tool → usage table
guide section:audit       # Full fleet audit in 8 steps
guide section:security    # Blocklist + tunnels
guide section:pitfalls    # Common mistakes

🏗️ Architecture

MCP Client (stdio)
    │
server.js ─── 63 MCP tools registered
    │
    ├── queue.js ─────── Persistent job queue (JSON + backup)
    ├── ssh.js ───────── SSH execution (pool + dedicated connections)
    ├── sftp.js ──────── SFTP transfers (upload/download/multi)
    ├── sshPool.js ───── Persistent SSH connection pool
    ├── servers.js ───── CRUD server aliases
    ├── apis.js ──────── CRUD API catalog
    ├── history.js ───── Task history
    ├── config.js ────── Centralized configuration
    ├── utils.js ─────── Utilities (escapeShellArg)
    ├── fileOps.js ───── File operations (read/write/edit)
    ├── diffEngine.js ── Diff engine (files/dirs/sources)
    ├── compareEngine.js ─ Multi-source comparison
    ├── diffFormatter.js ─ Diff formatting
    ├── sourceAdapter.js ─ Local/remote abstraction
    ├── shellSessions.js ─ Persistent shell sessions
    ├── snapshotManager.js ─ Versioned snapshots
    ├── notes.js ──────── Documented server context
    ├── policies.js ──── Command blocklist
    ├── tunnels.js ────── SSH tunnels (local/remote/SOCKS)
    ├── guide.js ──────── AI built-in manual
    └── diagnose.js ───── Diagnostics

Job Lifecycle

pending → running → completed / failed
                      ↓ (on restart)
                    crashed → retry → pending

🔒 Security

Command Blocklist : rm -rf /, mkfs*, fork bombs, and other destructive commands are blocked by default
Conscious bypass : skip_policy: true to force execution
Tunnel port allowlist : only explicitly allowed ports can be used
File access restriction : MCP_ALLOWED_ROOTS env var to limit file operations to specific directories
escapeShellArg() : all URLs and paths are escaped before being passed to curl/shell
Plaintext secret detection : warning on startup if passwords/API keys are in plaintext
Pre-modification snapshots : backup:true on file_edit/file_write for instant rollback
Recommendation : use SSH keys (not passwords), store secrets in Vaultwarden

🧪 Tests

node diagnose.js        # Full diagnostic
node test_mcp.js        # MCP smoke test
node test_features.js   # Unit tests (queue, pool, glob, prompts, crash)

🛣️ Roadmap

Version	Changes
10.0.0	New tools: file_read/write/edit, diff, snapshots, shell, notes
10.4.0	server_to_server, help with schemas, audit guide
11.0.0	Command Blocklist, Multi-host (`alias:"all"`), tmux
11.2.0	SSH Tunnels (local/remote/SOCKS5), allowlist, ssh2 stderr fix
11.3.0	AllowedRoots (`MCP_ALLOWED_ROOTS`) for file restriction
12.0.0 (planned)	Auto key setup for tunnels, webhooks, static dashboard