@fkom13/mcp-sftp-orchestrator 6.0.0 → 11.3.0

package/README.md

@@ -1,102 +1,374 @@
-# 🚀 MCP SFTP/SSH Orchestrator
+# 🚀 MCP Orchestrator — SSH/SFTP Infrastructure Orchestration Server
 
-Un serveur MCP (Model-Context-Protocol) puissant pour l'orchestration de tâches distantes. Il gère des connexions SSH et SFTP, une file d'attente de tâches persistante, et expose un ensemble riche d'outils pour la gestion de serveurs, le monitoring, et l'exécution de commandes via une interface `stdio` compatible avec les LLM.
+**Version** : 11.3.0  
+**License** : MIT  
+**Node** : >= 18.0.0
 
-✨ **Fonctionnalités Principales**
+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.
 
-- **Gestion de Serveurs** : Ajoutez, listez et supprimez des configurations de serveurs SSH/SFTP.
-- **Exécution de Tâches SSH** : Simple, interactive, ou en séquence.
-- **Transferts de Fichiers SFTP** : Upload/Download de fichiers et dossiers, avec support des patterns `glob`.
-- **File d'Attente Intelligente** : Mode hybride (synchrone/asynchrone) et persistance des tâches.
-- **Pooling de Connexions** : Gère un pool de connexions SSH pour une exécution ultra-rapide.
-- **Outils de Monitoring** : Surveillez les ressources système, le statut des services (systemd, Docker, PM2) et Fail2Ban.
-- **Outils de Logs** : Récupérez les logs de PM2, Docker, ou suivez la fin d'un fichier (`tail`).
+### ✨ 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](README.fr.md)
+
+---
 
 ## 📦 Installation
 
-Ce projet est conçu pour être utilisé comme un outil MCP dans un environnement compatible (comme la `gemini-cli`).
+### Via npx (recommended)
+```bash
+npx @fkom13/mcp-sftp-orchestrator
+```
+
+### Via git
+```bash
+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
+
+---
 
-Enregistrez ce MCP auprès de votre client en utilisant la configuration suivante :
+## ⚙️ 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.)
 
 ```json
 {
   "mcpServers": {
-    "mcp-sftp-orchestrator": {
-      "command": "npx",
-      "args": [
-        "@fkom13/mcp-sftp-orchestrator"
-      ],
+    "orchestrator": {
+      "command": "node",
+      "args": ["/path/to/sftp-mcp/server.js"],
       "env": {
-        "MCP_DATA_DIR": "~/.config/mcp-orchestrator"
+        "MCP_DATA_DIR": "/path/to/sftp-mcp/data"
       }
     }
   }
 }
 ```
 
-Le client MCP lancera automatiquement le serveur via `npx` lors de son premier appel.
+---
+
+## 🧰 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 |
 
-## 🛠️ Configuration
+### 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 |
 
-Le serveur est configurable via des variables d'environnement. Vous pouvez créer un fichier `.env` à la racine du projet si vous l'exécutez localement pour le développement.
+### 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 |
 
-- `MCP_DATA_DIR`: Le dossier où seront stockées les données (configurations des serveurs, historique, etc.). Par défaut : `~/.config/mcp-orchestrator`.
-- `MCP_SYNC_TIMEOUT_S`: Le délai en secondes avant qu'une tâche longue ne passe en arrière-plan. Par défaut : `30`.
+### 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 |
 
-## 🧰 Référence des Outils (API)
+### Logs
+| Tool | Description |
+|------|-------------|
+| `get_pm2_logs` | PM2 logs |
+| `get_docker_logs` | Docker logs |
+| `tail_file` | Tail a remote file |
 
-Voici la liste complète des outils exposés par ce serveur MCP.
+### 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 |
 
-### Gestion des Serveurs
+### 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 |
 
-- `server_add`: Enregistre ou met à jour les informations de connexion d'un serveur.
-- `server_list`: Affiche la liste de tous les alias de serveurs configurés.
-- `server_remove`: Supprime un alias de serveur de la configuration.
+### 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 |
 
-### Exécution de Tâches
+### 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 |
 
-- `task_exec`: Exécute une commande SSH (hybride synchrone/asynchrone).
-- `task_transfer`: Transfère un fichier ou dossier via SFTP (hybride synchrone/asynchrone).
-- `task_exec_interactive`: Exécute une commande SSH interactive (gère les prompts `yes/no`, etc.).
-- `task_exec_sequence`: Exécute plusieurs commandes SSH en séquence sur le même serveur.
-- `task_transfer_multi`: Transfère plusieurs fichiers/dossiers avec support de patterns `glob`.
+### 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 |
 
-### Monitoring & Diagnostics
+### 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 |
 
-- `get_system_resources`: Récupère les métriques système vitales (CPU, RAM, Disque).
-- `get_services_status`: Récupère le statut des services (systemd, Docker, PM2).
-- `get_fail2ban_status`: Récupère les informations du service Fail2Ban.
+### 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 |
 
-### Récupération de Logs
+### API Catalog
+| Tool | Description |
+|------|-------------|
+| `api_add` / `api_list` / `api_remove` | API monitoring catalog |
+| `api_check` | Health check via SSH + curl |
 
-- `get_pm2_logs`: Raccourci pour récupérer les logs PM2.
-- `get_docker_logs`: Raccourci pour récupérer les logs d'un container Docker.
-- `tail_file`: Affiche les dernières lignes d'un fichier distant.
+---
 
-### Gestion de la File d'Attente (Queue)
+## 📖 Usage Examples
+
+### Multi-server
+```bash
+# One command, multiple servers
+task_exec {alias:["vps1","vps2","vps3"], cmd:"uptime"}
+
+# Entire fleet
+task_exec {alias:"all", cmd:"df -h /"}
+```
+
+### SOCKS5 Proxy Tunnel
+```bash
+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)
+```bash
+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)
+```bash
+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
+```bash
+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
+```bash
+# List blocked commands
+policy_blocklist_list
+# → ["rm -rf /", "mkfs*", ...]
+
+# Conscious bypass
+task_exec {alias:"vps", cmd:"rm -rf /tmp/cache", skip_policy:true}
+```
 
-- `task_queue`: Affiche le statut de toutes les tâches dans la file d'attente.
-- `task_status`: Récupère les détails d'une tâche par son ID.
-- `task_history`: Affiche l'historique des dernières tâches lancées.
-- `task_retry`: Relance une tâche qui a échoué ou crashé.
-- `queue_stats`: Affiche les statistiques de la queue de tâches.
+### Secure File Editing
+```bash
+# Read + hash
+file_read {source:{type:"remote", alias:"vps", path:"/etc/nginx/nginx.conf"}}
+# → content + hash
 
-### Gestion des APIs (Monitoring Externe)
+# 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}
 
-- `api_add`: Ajoute une API au catalogue de monitoring.
-- `api_list`: Affiche toutes les APIs configurées.
-- `api_remove`: Supprime une API du catalogue.
-- `api_check`: Lance un test de santé sur une API.
+# 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
+```bash
+# 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
+```bash
+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:
+
+```bash
+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
+
+```bash
+node diagnose.js        # Full diagnostic
+node test_mcp.js        # MCP smoke test
+node test_features.js   # Unit tests (queue, pool, glob, prompts, crash)
+```
 
-### Administration du Serveur MCP
+---
 
-- `task_logs`: Affiche les logs du système MCP lui-même.
-- `pool_stats`: Affiche les statistiques du pool de connexions SSH.
+## 🛣️ Roadmap
 
-## 🤝 Contribution
+| 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 |
 
-Les contributions sont les bienvenues ! N'hésitez pas à ouvrir une *Issue* pour signaler un bug ou proposer une fonctionnalité, ou une *Pull Request* pour soumettre des modifications.
+---
 
-## 📄 Licence
+## 📄 License
 
-Ce projet est sous licence MIT.
+MIT — Copyright (c) 2025-2026 Franck (fkom13)

package/ROADMAP.md

@@ -0,0 +1,21 @@
+# Roadmap MCP Orchestrator
+
+## v11.2.0 (actuelle)
+- ✅ Command Blocklist (policies.js) — sécurité des commandes
+- ✅ Multi-host execution (alias array / "all")
+- ✅ tmux sessions persistantes (create/exec/read/list/kill)
+- ✅ Tunnels SSH (local/remote/SOCKS5) avec allowlist
+- ✅ Guide IA intégré (audit, security, cheatsheet)
+- ✅ Help avec schémas JSON des paramètres
+- ✅ Snapshots versionnés avec déduplication
+- ✅ File edit chirurgical avec protection hash
+- ✅ Diff multi-serveur (compare_all_sources)
+- ✅ get_services_status graceful fallback
+
+## v12.x (planifiée)
+- [ ] Tunnels auto-setup de clés entre serveurs
+- [ ] Webhook on tunnel up/down (n8n compatible)
+- [ ] Dashboard web statique pour l'état du parc
+- [ ] Mode "agent" : exécution planifiée (cron-like)
+- [ ] Intégration Vaultwarden pour les secrets
+- [ ] Tests automatisés CI/CD

package/apis.js

@@ -45,6 +45,23 @@ async function saveApis() {
 // Ajouter ou mettre à jour une API
 async function addApi(alias, apiConfig) {
     await ensureInitialized();
+    
+    // Validation
+    if (!alias || typeof alias !== 'string') {
+        throw new Error("L'alias doit être une chaîne non vide.");
+    }
+    
+    if (!apiConfig.url) {
+        throw new Error("L'URL de l'API est obligatoire.");
+    }
+    
+    // Valider l'URL
+    try {
+        new URL(apiConfig.url);
+    } catch (e) {
+        throw new Error(`URL invalide: ${apiConfig.url}`);
+    }
+    
     apis[alias] = apiConfig;
     await saveApis();
     return { success: true, message: `API '${alias}' ajoutée/mise à jour avec succès.` };

package/compareEngine.js

@@ -0,0 +1,132 @@
+import { createTwoFilesPatch } from 'diff';
+import sourceAdapter from './sourceAdapter.js';
+import fileOps from './fileOps.js';
+
+/**
+ * compareEngine — Comparaison d'un même fichier (ou de fichiers équivalents à
+ * des emplacements différents) sur plusieurs sources.
+ * Détecte les "drifts" de configuration entre serveurs (et localhost).
+ *
+ * Regroupe les sources par hash : chaque groupe = ensemble de sources ayant
+ * un contenu identique. Plus d'un groupe → drift détecté.
+ *
+ * Chaque source peut porter :
+ *   - un path différent d'une source à l'autre (ex: .bashrc ici, .zshrc là)
+ *   - un label personnalisé (source.label) pour un affichage clair
+ * Quand un drift est détecté, on peut générer le DIFF réel entre la version
+ * de référence (groupe majoritaire) et chaque version divergente.
+ */
+
+export default {
+    /**
+     * Compare le contenu d'un fichier sur plusieurs sources.
+     * sources = [{ type, path, alias?, label? }, ...] (min 2, local et/ou remote)
+     * options = { includeContent: bool (défaut false), includeDiff: bool (défaut true) }
+     *
+     * Retourne :
+     *   {
+     *     drift: bool,                 // true si plus d'une version distincte
+     *     reference: { label, sources } | null,  // groupe majoritaire (référence)
+     *     groups: [{ hash, size, sources:[{server,path,label}], content?, isReference }],
+     *     drifts: [{ from, to, added, removed, diff }],  // diff référence → chaque divergence
+     *     errors: [{ source:{server,path,label}, error }],
+     *     stats: { totalSources, successfulReads, uniqueVersions, unreadable }
+     *   }
+     */
+    async compareSources(sources, options = {}) {
+        const includeContent = options.includeContent === true;
+        const includeDiff = options.includeDiff !== false; // défaut true
+        const results = [];
+        const errors = [];
+
+        // Lecture de chaque source (séquentiel : simple et robuste ; le pool gère le reste)
+        for (const source of sources) {
+            const origin = sourceAdapter.describe(source);
+            try {
+                const file = await fileOps.readFile(source);
+                results.push({ origin, hash: file.hash, size: file.size, content: file.content });
+            } catch (e) {
+                errors.push({ source: origin, error: e.message });
+            }
+        }
+
+        // Regroupement par hash (on garde le contenu en interne pour le diff)
+        const groupsMap = new Map();
+        for (const r of results) {
+            if (!groupsMap.has(r.hash)) {
+                groupsMap.set(r.hash, {
+                    hash: r.hash,
+                    size: r.size,
+                    sources: [],
+                    _content: r.content // interne, retiré à la fin si includeContent=false
+                });
+            }
+            groupsMap.get(r.hash).sources.push(r.origin);
+        }
+
+        const groups = Array.from(groupsMap.values())
+            // le groupe le plus répandu en premier (majorité = référence probable)
+            .sort((a, b) => b.sources.length - a.sources.length);
+
+        const drift = groups.length > 1;
+
+        // Marque le groupe de référence (majoritaire)
+        groups.forEach((g, i) => { g.isReference = i === 0; });
+        const reference = groups.length > 0
+            ? { label: groups[0].sources[0].label, sources: groups[0].sources }
+            : null;
+
+        // Génère les diffs référence → chaque groupe divergent
+        const drifts = [];
+        if (drift && includeDiff) {
+            const ref = groups[0];
+            const refLabel = ref.sources[0].label;
+            for (let i = 1; i < groups.length; i++) {
+                const g = groups[i];
+                const gLabel = g.sources[0].label;
+                try {
+                    const patch = createTwoFilesPatch(
+                        refLabel, gLabel,
+                        ref._content, g._content,
+                        'référence', 'divergent'
+                    );
+                    let added = 0, removed = 0;
+                    for (const line of patch.split('\n')) {
+                        if (line.startsWith('+') && !line.startsWith('+++')) added++;
+                        else if (line.startsWith('-') && !line.startsWith('---')) removed++;
+                    }
+                    drifts.push({
+                        from: refLabel,
+                        to: gLabel,
+                        affectedSources: g.sources.map(s => s.label),
+                        added,
+                        removed,
+                        diff: patch
+                    });
+                } catch (e) {
+                    drifts.push({ from: refLabel, to: gLabel, note: 'diff indisponible (binaire ?)' });
+                }
+            }
+        }
+
+        // Nettoie le contenu interne (ou l'expose si demandé)
+        for (const g of groups) {
+            if (includeContent) g.content = g._content;
+            delete g._content;
+        }
+
+        return {
+            drift,
+            reference,
+            groups,
+            drifts,
+            errors,
+            stats: {
+                totalSources: sources.length,
+                successfulReads: results.length,
+                uniqueVersions: groups.length,
+                unreadable: errors.length
+            }
+        };
+    }
+};

package/config.js

@@ -21,13 +21,44 @@ const args = process.argv.slice(2).reduce((acc, arg) => {
 }, {});
 
 const config = {
-    // La hiérarchie reste la même : les arguments en ligne de commande écrasent le .env, qui écrase le défaut.
     dataDir: args['data-dir'] || process.env.MCP_DATA_DIR || path.join(os.homedir(), '.config', 'mcp-orchestrator'),
-    syncTimeout: parseInt(args['sync-timeout'] || process.env.MCP_SYNC_TIMEOUT_S || '10', 10) * 1000,
-    defaultCommandTimeout: parseInt(process.env.MCP_DEFAULT_CMD_TIMEOUT_MS || '300000', 10),
-    interactiveCommandTimeout: parseInt(process.env.MCP_INTERACTIVE_CMD_TIMEOUT_MS || '120000', 10)
+    
+    // Timeouts en millisecondes (plus cohérent)
+    syncTimeout: parseInt(args['sync-timeout'] || process.env.MCP_SYNC_TIMEOUT_S || '120', 10) * 1000,
+    defaultCommandTimeout: parseInt(process.env.MCP_DEFAULT_CMD_TIMEOUT_S || '600', 10) * 1000,
+    interactiveCommandTimeout: parseInt(process.env.MCP_INTERACTIVE_CMD_TIMEOUT_S || '300', 10) * 1000,
+    maxWaitTimeout: parseInt(process.env.MCP_MAX_WAIT_TIMEOUT_S || '600', 10) * 1000,
+    
+    // Configuration Pool SSH
+    maxConnectionsPerServer: parseInt(process.env.MAX_CONNECTIONS_PER_SERVER || '5', 10),
+    minConnectionsPerServer: parseInt(process.env.MIN_CONNECTIONS_PER_SERVER || '1', 10),
+    idleTimeout: parseInt(process.env.IDLE_TIMEOUT || '300000', 10),
+    keepAliveInterval: parseInt(process.env.KEEP_ALIVE_INTERVAL || '30000', 10),
+    
+    // Sécurité
+    allowedRoots: (process.env.MCP_ALLOWED_ROOTS || '').split(',').map(s => s.trim()).filter(Boolean),
+    
+    // Configuration Queue
+    maxQueueSize: parseInt(process.env.MAX_QUEUE_SIZE || '1000', 10),
+    saveInterval: parseInt(process.env.SAVE_INTERVAL || '5000', 10),
+    historyRetention: parseInt(process.env.HISTORY_RETENTION || '2678400000', 10), // 31 jours
 };
 
+// Validation
+if (config.syncTimeout < 1000) {
+    if (process.env.MCP_DEBUG === 'true') {
+        console.error('⚠️ syncTimeout trop court, minimum 1000ms');
+    }
+    config.syncTimeout = 1000;
+}
+
+if (config.maxConnectionsPerServer < config.minConnectionsPerServer) {
+    if (process.env.MCP_DEBUG === 'true') {
+        console.error('⚠️ maxConnections < minConnections, ajustement automatique');
+    }
+    config.maxConnectionsPerServer = config.minConnectionsPerServer;
+}
+
 // Créer le dossier de données s'il n'existe pas
 fs.mkdirSync(config.dataDir, { recursive: true });