MCP SFTP Orchestrator

🚀 MCP Orchestrator — Servidor de orquestração SSH/SFTP

v11.8.0 Security Refresh — As 82 ferramentas agora publicam as anotações MCP padrão. infra_overview permanece leve sem argumentos, mas infra_overview { alias: "..." } realiza uma descoberta ao vivo e correlaciona Nginx/domínios, portas, Docker/Compose e serviços. Veja CHANGELOG.md.

Versão : 11.8.0
Ferramentas : 82
Licença : MIT
Node : >= 18.0.0
Changelog : CHANGELOG.md

Servidor MCP (Model Context Protocol, transporte stdio) que dá a um agente de IA a capacidade de orquestrar um parque de servidores: SSH, SFTP, edição de arquivos local/remota (hash-safe), diffs entre servidores, shell PTY, snapshots de infraestrutura, notas de protocolo, projetos, sessões de trabalho, inventário, trust SSH (pubkey), grupos de alias e auditoria do parque.

---

✨ Destaques (v11.6)

Domínio	Capacidade
Execução	task_exec multi-servidor / group:oci / dry-run destrutivo / force
Arquivos	file_read / file_edit (cirúrgico) / file_write + hash + dryRun + backup
Parque	notas, infra_audit, fleet_status, server_inventory
Projetos	registro local↔remoto + project_diff
Trabalho	work_start → edições → work_end (nota de intervenção automática)
Trust	ssh_authorize_key (somente pubkey, dry_run por padrão)
Segurança	segredos mascarados, RO global + RO por alias, blocklist, pool SSH robusto

---

📦 Instalação

git clone https://github.com/fkom13/mcp-sftp-orchestrator.git
cd sftp-mcp   # ou tools/sftp-mcp
npm install
cp .env.example .env
# Éditer MCP_DATA_DIR et chemins de clés

Pré-requisitos: Node.js >= 18

---

⚙️ Configuração (.env)

Todas as variáveis são opcionais.

Variável	Padrão	Descrição
MCP_DATA_DIR	~/.config/mcp-orchestrator	Pasta de dados (JSON, snapshots, projetos…)
MCP_SYNC_TIMEOUT_S	120	Atraso (s) antes de passar uma tarefa para segundo plano
MCP_DEFAULT_CMD_TIMEOUT_S	600	Timeout SSH comando (s). 0 = infinito
MCP_INTERACTIVE_CMD_TIMEOUT_S	300	Timeout interativo (s). 0 = infinito
MCP_MAX_WAIT_TIMEOUT_S	600	Timeout máximo task_wait (s)
MAX_CONNECTIONS_PER_SERVER	5	Pool SSH máx / servidor
MIN_CONNECTIONS_PER_SERVER	1	Pool SSH mín / servidor
IDLE_TIMEOUT	300000	Fechamento de conexão inativa (ms)
KEEP_ALIVE_INTERVAL	30000	Keepalive SSH (ms)
MAX_QUEUE_SIZE	1000	Tamanho máximo da fila de jobs
SAVE_INTERVAL	5000	Autosave da fila (ms)
MCP_ALLOWED_ROOTS	(vazio)	Raízes autorizadas para caminhos locais (CSV)
MCP_READONLY	false	1 = recusa escritas / exec mutantes (global)
MCP_COMPACT	false	1 = respostas truncadas (tokens do agente)
MCP_DEBUG	false	Logs detalhados no stderr

Arquivos em MCP_DATA_DIR

Arquivo	Conteúdo
servers.json	Alias SSH (host, user, keyPath/password, port?, readonly?)
apis.json	Catálogo de APIs (segredos mascarados nas ferramentas de leitura)
queue.json / queue.backup.json	Jobs
history.json	Histórico de tarefas
server_notes.json	Protocolos / notas por servidor
server_groups.json	Grupos de alias
projects.json	Registro de projetos
work_sessions.json	Sessões de trabalho
policies.json	Blocklist de comandos
tunnels.json / tunnel_allowlist.json	Túneis SSH
infra_snapshots/	Snapshots content-addressable

---

🔌 Conexão do cliente MCP

Grok / config.toml

[mcp_servers.orchestrator]
command = "node"
args = ["/chemin/absolu/sftp-mcp/server.js"]
# optionnel:
# env = { MCP_DATA_DIR = "/chemin/absolu/sftp-mcp/data" }

OpenCode / Claude Desktop (JSON)

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

Após modificar o código: recarregar o servidor MCP (/mcps → r ou reiniciar a sessão). Verificar system_diagnostics → version: "11.8.0".

---

🧰 Referência das ferramentas (82)

Diagnóstico e auditoria

Ferramenta	Descrição
help	Guia de ferramentas + .env + dicas
guide	Manual de IA (workflows, cheatsheet, pitfalls, auditoria, segurança)
system_diagnostics	Fila, pool, servidores/APIs mascarados, versão, readOnly
infra_audit	Síntese do parque + projetos + notas + crashed
infra_overview	Servidores + notas (visão leve)
fleet_status	Ping SSH paralelo (latência, load, disco)
server_inventory	Inventário leve (pm2/docker/disco/home, cache 10 min)

Servidores e grupos

Ferramenta	Descrição
server_add	CRUD de alias (keyPath ou password, port, readonly)
server_list	Lista (senhas mascaradas)
server_remove	Remove um alias
server_group_list/set/remove	Grupos (oci, contabo…). Uso: group:oci ou nome do grupo

Projetos (v11.6)

Ferramenta	Descrição
project_list / project_get / project_set / project_remove	Registro
project_resolve	→ { local, remote, ignore, runtime }
project_diff	Diff local↔remoto do projeto

Exemplo project_set:

{
  "name": "p-image",
  "local": { "path": "/home/.../dev-serveur/p-image" },
  "servers": {
    "prod": {
      "alias": "fkomprodmini2_prod",
      "path": "/home/ubuntu/p-image",
      "runtime": { "pm2": "p-image", "port": 5002 },
      "url": "https://pruna.esprit-artificiel.com"
    }
  },
  "ignore": ["node_modules", ".git", "data"]
}

Sessões de trabalho (v11.6)

Ferramenta	Descrição
work_start	Abre um diário (alias, project, tag, snapshot opcional)
work_log	Evento (file_edit, task_exec, …)
work_list	Sessões ativas (+ histórico)
work_end	Encerramento + server_note last_intervention

Trust SSH (v11.6)

Ferramenta	Descrição
ssh_authorize_key	Adiciona uma pubkey em authorized_keys remoto. dry_run padrão. Fontes: string | local_path | alias

{
  "target_alias": "fkomprodmini1_prod",
  "source": { "type": "alias", "alias": "vps_contabo" },
  "comment": "fleet-from-contabo",
  "dry_run": true
}

Políticas

Ferramenta	Descrição
policy_blocklist_list/add/remove	Blocklist de comandos (também aplicada ao shell + sequências)

Catálogo de APIs

Ferramenta	Descrição
api_add / api_list / api_remove / api_check	Monitoramento (chaves mascaradas na listagem)

Execução de tarefas

Ferramenta	Descrição
task_exec	SSH; alias | array | all | group:x; dry_run/force destrutivo
task_exec_interactive	Prompts sim/não, menus
task_exec_sequence	Sequência em um servidor (política por etapa)
task_transfer	SFTP upload/download/server_to_server
task_transfer_multi	Multi + globs

Arquivos / Diff / Shell / Snapshots

Família	Ferramentas
Arquivos	file_read, file_write, file_edit
Diff	diff_files, diff_folders, compare_all_sources
Shell	shell_create, shell_exec (+ skip_policy), shell_list, shell_close
Snapshots	snapshot_create/list/diff/restore/delete

Edição segura: file_read → hash → file_edit + expectedHash (+ dryRun / backup).

Notas do servidor

Ferramenta	Descrição
server_note_set/get/list/remove	Protocolo (descrição, serviços, avisos, intervenção)

Monitoramento e logs

Ferramenta	Descrição
get_system_resources	CPU / RAM / disco
get_services_status	systemd / Docker / PM2
get_fail2ban_status	Fail2Ban
check_api_health	HTTP via SSH+curl
get_pm2_logs / get_docker_logs / tail_file	Logs

Fila

Ferramenta	Descrição
task_queue / task_status / task_history / task_wait / task_logs	Acompanhamento
task_retry / task_retry_all	Relançar
task_purge	Purga (dry_run padrão)
queue_stats / pool_stats	Estatísticas

Tmux e túneis

Ferramenta	Descrição
tmux_create/exec/read/list/kill	Sessões tmux remotas
tunnel_create/list/close	Túneis SSH local/remoto/socks
tunnel_allowlist_add/remove	Portas permitidas para túneis

---

📖 Workflows recomendados para o agente

Início de sessão

infra_audit  (ou infra_overview)
fleet_status
project_list / project_resolve

Trabalho em um projeto

work_start { project: "p-image", alias: "fkomprodmini2_prod", tag: "fix-x", message: "…" }
file_read → file_edit (expectedHash, dryRun puis apply)
work_log { type: "file_edit", path: "…" }
work_end { summary: "…" }   → note serveur mise à jour
project_diff { name: "p-image" }

Comandos longos

task_exec { timeout: 0, … }  → si > syncTimeout → task_wait { id }

Alvos multi-servidores

task_exec { alias: "group:oci", cmd: "hostname" }
task_exec { alias: "all", cmd: "uptime" }

---

🏗️ Arquitetura

Client MCP (stdio)
    │
server.js ─── 82 tools
    │
    ├── queue.js          File d’attente persistante + purge/retry
    ├── ssh.js / sshPool  Exécution + pool (retry safe, port configurable)
    ├── sftp.js           Transferts (server_to_server via sourceAdapter/pool)
    ├── sourceAdapter.js  Local fs | remote SFTP pool
    ├── fileOps.js        Read/write/edit + hash + dryRun + backup
    ├── diffEngine.js / compareEngine.js / diffFormatter.js
    ├── shellSessions.js  PTY persistants + policy
    ├── snapshotManager.js
    ├── projects.js / workSession.js / inventory.js / groups.js / fleet.js
    ├── sshTrust.js       authorized_keys (pubkey only)
    ├── servers.js / apis.js / notes.js / policies.js / tunnels.js
    ├── history.js / guide.js / config.js / utils.js

Ciclo de vida de um job

pending → running → completed | failed | partial
                      ↓ (redémarrage MCP pendant running)
                    crashed → task_retry → pending

---

🔒 Segurança

Mecanismo	Detalhe
Segredos	Mascarados em api_list / diagnósticos (*** + 4 últimos caracteres)
Shell escape	escapeShellArg em curl, logs, caminhos
Blocklist	policies.json; shell + sequência incluídos; skip_policy para forçar
RO global	MCP_READONLY=1
RO alias	"readonly": true em servers.json
Destrutivo	task_exec dry-run se padrão perigoso sem force:true
Trust	Somente pubkey; dry_run por padrão
Chaves	Preferir keyPath SSH; Vaultwarden para segredos de API

---

🧪 Testes

npm test:unit    # p0 + p1 + p16 (43 tests)
npm test         # unit + smoke MCP + features
node diagnose.js # diagnostic local optionnel

Arquivo	Cobertura
test_p0_unit.js	utils, políticas, redact, timeouts, versão
test_p1_unit.js	groups, purge, destructive, RO env
test_p16_unit.js	projects, work session, compact, sshTrust
test_mcp.js	smoke SDK
test_features.js	queue / pool / globs / prompts

---

🛣️ Versões recentes

Versão	Conteúdo	Snapshot gencodedoc
11.6.1	Hardening multi-agente: RO transversal, server-to-server dossiês/force, raízes permitidas anti-symlink, quoting shell/tmux, fila + armazenamentos JSON atômicos	—
11.6.0	Projetos, sessões de trabalho, inventário, ssh_authorize_key, RO alias, compact	#23 (docs finais)
11.4.0	fleet, infra_audit, groups, retry_all, purge, reescrita do pool	#21
11.3.0	Máscara de segredos, política shell/seq, porta SSH, wait parcial	#20
10.4–10.0	operações de arquivo, diff, shell, snapshots, notas, guia	#17–19
9.x / 8.x	SFTP force, timeouts, interativo, segurança básica	—

Detalhe: CHANGELOG.md · planos históricos: ROADMAP.md, ROADMAP_EXTENDED.md.

---

📄 Licença

MIT — Copyright (c) 2025-2026 Franck (fkom13)