@suzko/mcp-server 0.1.0

package/dist/src/tools/server-admin.js

@@ -0,0 +1,738 @@
+import { z } from "zod";
+import { execFile } from "node:child_process";
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { shellQuote, assertSafePath, assertSafeDomain, assertSafeEmail, } from "../security.js";
+// --- Server Registry ---
+const SERVERS_FILE = join(homedir(), ".suzko", "servers.json");
+async function loadServers() {
+    try {
+        const raw = await readFile(SERVERS_FILE, "utf-8");
+        const data = JSON.parse(raw);
+        return data.servers || [];
+    }
+    catch {
+        return [];
+    }
+}
+async function saveServers(servers) {
+    const dir = join(homedir(), ".suzko");
+    await mkdir(dir, { recursive: true });
+    await writeFile(SERVERS_FILE, JSON.stringify({ servers }, null, 2), "utf-8");
+}
+function getServer(servers, alias) {
+    return servers.find((s) => s.alias.toLowerCase() === alias.toLowerCase());
+}
+// --- SSH Execution ---
+function resolveKeyPath(keyPath) {
+    return keyPath.replace(/^~/, homedir());
+}
+async function sshExec(server, command, timeoutMs = 60_000) {
+    const keyPath = resolveKeyPath(server.keyPath);
+    return new Promise((resolve, reject) => {
+        execFile("ssh", [
+            "-i",
+            keyPath,
+            "-p",
+            String(server.port),
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            "ConnectTimeout=10",
+            "-o",
+            "BatchMode=yes",
+            `${server.user}@${server.host}`,
+            command,
+        ], { timeout: timeoutMs }, (error, stdout, stderr) => {
+            if (error && !stdout && !stderr) {
+                reject(new Error(`SSH connection failed: ${error.message}`));
+            }
+            else {
+                resolve({
+                    stdout: stdout?.toString() ?? "",
+                    stderr: stderr?.toString() ?? "",
+                });
+            }
+        });
+    });
+}
+async function scpUpload(server, localPath, remotePath) {
+    const keyPath = resolveKeyPath(server.keyPath);
+    return new Promise((resolve, reject) => {
+        execFile("scp", [
+            "-r",
+            "-i",
+            keyPath,
+            "-P",
+            String(server.port),
+            "-o",
+            "StrictHostKeyChecking=accept-new",
+            "-o",
+            "ConnectTimeout=10",
+            localPath,
+            `${server.user}@${server.host}:${remotePath}`,
+        ], { timeout: 120_000 }, (error, stdout, stderr) => {
+            if (error && !stdout && !stderr) {
+                reject(new Error(`SCP upload failed: ${error.message}`));
+            }
+            else {
+                resolve({
+                    stdout: stdout?.toString() ?? "",
+                    stderr: stderr?.toString() ?? "",
+                });
+            }
+        });
+    });
+}
+// --- Command safety ---
+const DANGEROUS_PATTERNS = [
+    /\brm\s+-rf?\s+\/(\s|$|\*|\.|;|&)/,
+    /\bdd\s+if=/,
+    /\bmkfs(\.|\s)/,
+    /:\(\)\s*\{\s*:\|:&\s*\}\s*;/,
+    />\s*\/dev\/sd[a-z]/,
+    /\bchmod\s+-R\s+777\s+\//,
+    /\bwget\b.*\|\s*(sudo\s+)?sh\b/,
+    /\bcurl\b.*\|\s*(sudo\s+)?sh\b/,
+];
+const WARN_PATTERNS = [
+    /\bshutdown\b/,
+    /\breboot\b/,
+    /\bhalt\b/,
+    /\bpoweroff\b/,
+    /\binit\s+0\b/,
+];
+function checkCommandSafety(command) {
+    if (command.includes("\0")) {
+        return { blocked: true, warning: "Blocked: command contains a NUL byte." };
+    }
+    // Match against canonicalised whitespace + case.
+    const canon = command.replace(/[\t ]+/g, " ").toLowerCase();
+    for (const pattern of DANGEROUS_PATTERNS) {
+        if (pattern.test(canon)) {
+            return {
+                blocked: true,
+                warning: `Blocked: command matches dangerous pattern "${pattern.source}". This command could destroy the server.`,
+            };
+        }
+    }
+    for (const pattern of WARN_PATTERNS) {
+        if (pattern.test(canon)) {
+            return {
+                blocked: false,
+                warning: `⚠️ Warning: this command may shut down or reboot the server. Proceeding anyway.`,
+            };
+        }
+    }
+    return { blocked: false, warning: null };
+}
+// --- Helpers ---
+function text(content) {
+    return { content: [{ type: "text", text: content }] };
+}
+function notFound(alias) {
+    return text(`Server "${alias}" not found. Use list_servers to see registered servers, or connect_server to add one.`);
+}
+// --- Tool Registration ---
+export function registerServerAdminTools(server, _client) {
+    // 1. connect_server — register a new server
+    server.tool("connect_server", "Register a new server in the local server registry (~/.suzko/servers.json) and test the SSH connection. No Suzko authentication required.", {
+        alias: z
+            .string()
+            .describe("Unique alias for this server (e.g. 'my-vps', 'prod-1')"),
+        host: z
+            .string()
+            .describe("Server hostname or IP address"),
+        user: z
+            .string()
+            .default("root")
+            .describe("SSH username (default: root)"),
+        port: z
+            .number()
+            .default(22)
+            .describe("SSH port (default: 22)"),
+        keyPath: z
+            .string()
+            .default("~/.ssh/id_ed25519")
+            .describe("Path to SSH private key (default: ~/.ssh/id_ed25519)"),
+    }, async ({ alias, host, user, port, keyPath }) => {
+        const servers = await loadServers();
+        // Check for duplicate alias
+        if (getServer(servers, alias)) {
+            return text(`Server with alias "${alias}" already exists. Remove it first or use a different alias.`);
+        }
+        const config = { alias, host, user, port, keyPath };
+        // Test connection
+        try {
+            const { stdout } = await sshExec(config, "echo 'SSH_OK' && hostname", 15_000);
+            if (!stdout.includes("SSH_OK")) {
+                return text(`SSH connection to ${user}@${host}:${port} succeeded but produced unexpected output. Server NOT saved.\n\nOutput:\n${stdout}`);
+            }
+            servers.push(config);
+            await saveServers(servers);
+            const hostname = stdout.split("\n")[1]?.trim() || "unknown";
+            return text(`✅ Server "${alias}" registered successfully.\n\n` +
+                `  Host: ${host}\n` +
+                `  User: ${user}\n` +
+                `  Port: ${port}\n` +
+                `  Key:  ${keyPath}\n` +
+                `  Hostname: ${hostname}\n\n` +
+                `Saved to ${SERVERS_FILE}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ SSH connection test failed for ${user}@${host}:${port}\n\n` +
+                `Error: ${msg}\n\n` +
+                `Server was NOT saved. Check:\n` +
+                `  - Host is reachable\n` +
+                `  - SSH key exists at ${keyPath}\n` +
+                `  - Key is authorized on the server\n` +
+                `  - Port ${port} is open`);
+        }
+    });
+    // 2. list_servers — list registered servers
+    server.tool("list_servers", "List all registered servers from the local registry (~/.suzko/servers.json). No Suzko authentication required.", {}, async () => {
+        const servers = await loadServers();
+        if (servers.length === 0) {
+            return text("No servers registered yet. Use connect_server to add one.");
+        }
+        const lines = servers.map((s, i) => `${i + 1}. ${s.alias}\n` +
+            `   Host: ${s.user}@${s.host}:${s.port}\n` +
+            `   Key:  ${s.keyPath}`);
+        return text(`Registered servers (${servers.length}):\n\n${lines.join("\n\n")}`);
+    });
+    // 3. inspect_server — run diagnostic commands
+    server.tool("inspect_server", "SSH into a registered server and run diagnostic commands (uname, uptime, disk, memory, docker status). Returns a formatted system report.", {
+        alias: z.string().describe("Server alias from the registry"),
+    }, async ({ alias }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        const commands = [
+            { label: "System", cmd: "uname -a" },
+            { label: "Uptime", cmd: "uptime" },
+            {
+                label: "CPU",
+                cmd: "nproc && cat /proc/cpuinfo | grep 'model name' | head -1 | cut -d: -f2",
+            },
+            { label: "Memory", cmd: "free -m" },
+            { label: "Disk", cmd: "df -h" },
+            {
+                label: "Docker",
+                cmd: "docker --version 2>/dev/null && docker ps --format 'table {{.Names}}\\t{{.Status}}\\t{{.Ports}}' 2>/dev/null || echo 'Docker not installed'",
+            },
+            {
+                label: "Network",
+                cmd: "ip -4 addr show | grep inet | grep -v '127.0.0.1' | awk '{print $2}'",
+            },
+        ];
+        const sections = [];
+        sections.push(`🖥️  Server Inspection: ${alias} (${srv.host})\n`);
+        for (const { label, cmd } of commands) {
+            try {
+                const { stdout, stderr } = await sshExec(srv, cmd, 15_000);
+                const output = (stdout || stderr).trim() || "(no output)";
+                sections.push(`── ${label} ──\n${output}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                sections.push(`── ${label} ──\n⚠️ Failed: ${msg}`);
+            }
+        }
+        return text(sections.join("\n\n"));
+    });
+    // 4. run_server_command — execute arbitrary command with safety checks
+    server.tool("run_server_command", "Execute an arbitrary shell command on a registered server via SSH. Dangerous commands (rm -rf /, dd, mkfs, fork bombs) are blocked. Shutdown/reboot commands trigger a warning but are allowed.", {
+        alias: z.string().describe("Server alias from the registry"),
+        command: z.string().describe("Shell command to execute"),
+        timeout: z
+            .number()
+            .default(60000)
+            .describe("Timeout in milliseconds (default: 60000)"),
+    }, async ({ alias, command, timeout }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        // Safety check
+        const safety = checkCommandSafety(command);
+        if (safety.blocked) {
+            return text(`🚫 ${safety.warning}`);
+        }
+        const parts = [];
+        if (safety.warning) {
+            parts.push(safety.warning + "\n");
+        }
+        parts.push(`$ ${command}\n`);
+        try {
+            const { stdout, stderr } = await sshExec(srv, command, timeout);
+            if (stdout.trim())
+                parts.push(stdout.trim());
+            if (stderr.trim())
+                parts.push(`[stderr]\n${stderr.trim()}`);
+            if (!stdout.trim() && !stderr.trim())
+                parts.push("(command completed with no output)");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            parts.push(`❌ Error: ${msg}`);
+        }
+        return text(parts.join("\n"));
+    });
+    // 5. install_docker — install Docker via official script
+    server.tool("install_docker", "Install Docker on a registered server using the official convenience script (get.docker.com). Also installs docker compose plugin and adds the SSH user to the docker group.", {
+        alias: z.string().describe("Server alias from the registry"),
+    }, async ({ alias }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        const steps = [
+            {
+                label: "Check existing Docker",
+                cmd: "docker --version 2>/dev/null || echo 'NOT_INSTALLED'",
+            },
+            {
+                label: "Install Docker",
+                cmd: "curl -fsSL https://get.docker.com | sh 2>&1",
+            },
+            {
+                label: "Add user to docker group",
+                cmd: `usermod -aG docker ${srv.user} 2>/dev/null || true`,
+            },
+            {
+                label: "Enable Docker service",
+                cmd: "systemctl enable docker && systemctl start docker",
+            },
+            {
+                label: "Verify installation",
+                cmd: "docker --version && docker compose version 2>/dev/null || docker-compose --version 2>/dev/null || echo 'compose not available'",
+            },
+        ];
+        const output = [];
+        output.push(`🐳 Installing Docker on "${alias}" (${srv.host})...\n`);
+        for (const { label, cmd } of steps) {
+            output.push(`── ${label} ──`);
+            try {
+                const { stdout, stderr } = await sshExec(srv, cmd, 180_000);
+                const result = (stdout || stderr).trim();
+                // Skip actual install if Docker already present
+                if (label === "Install Docker" &&
+                    output.some((l) => l.includes("Docker version"))) {
+                    output.push("Docker already installed, skipping.\n");
+                    continue;
+                }
+                output.push(result.length > 2000
+                    ? result.slice(-2000) + "\n...(truncated)"
+                    : result);
+                output.push("");
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                output.push(`⚠️ Failed: ${msg}\n`);
+            }
+        }
+        return text(output.join("\n"));
+    });
+    // 6. deploy_to_server — upload and docker compose up
+    server.tool("deploy_to_server", "Deploy a local project directory to a registered server. Uploads files via SCP, then runs `docker compose up -d` on the remote path. The local directory should contain a docker-compose.yml.", {
+        alias: z.string().describe("Server alias from the registry"),
+        localPath: z
+            .string()
+            .describe("Local directory path to upload"),
+        remotePath: z
+            .string()
+            .default("/opt/deploy")
+            .describe("Remote directory path to upload to (default: /opt/deploy)"),
+    }, async ({ alias, localPath, remotePath }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        let safeRemote;
+        try {
+            safeRemote = assertSafePath(remotePath, {
+                allowedPrefixes: ["/opt", "/srv", "/home", "/var/www"],
+            });
+        }
+        catch (e) {
+            return text(`❌ Invalid remotePath: ${e instanceof Error ? e.message : String(e)}\n` +
+                `Use an absolute path under /opt, /srv, /home, or /var/www.`);
+        }
+        const qRemote = shellQuote(safeRemote);
+        const output = [];
+        output.push(`🚀 Deploying to "${alias}" (${srv.host})\n` +
+            `   Local:  ${localPath}\n` +
+            `   Remote: ${safeRemote}\n`);
+        // Ensure remote directory exists
+        try {
+            await sshExec(srv, `mkdir -p ${qRemote}`);
+            output.push("✅ Remote directory ready");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to create remote directory: ${msg}`);
+        }
+        // Upload via SCP
+        try {
+            output.push("📦 Uploading files via SCP...");
+            await scpUpload(srv, localPath, safeRemote);
+            output.push("✅ Upload complete");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(output.join("\n") + `\n\n❌ SCP upload failed: ${msg}`);
+        }
+        // Docker compose up
+        try {
+            output.push("🐳 Running docker compose up -d...");
+            const { stdout, stderr } = await sshExec(srv, `cd ${qRemote} && docker compose up -d 2>&1 || docker-compose up -d 2>&1`, 120_000);
+            const result = (stdout || stderr).trim();
+            output.push(result || "(no output)");
+            output.push("\n✅ Deployment complete!");
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            output.push(`\n❌ docker compose failed: ${msg}`);
+        }
+        return text(output.join("\n"));
+    });
+    // 7. list_server_containers — docker ps
+    server.tool("list_server_containers", "List all Docker containers on a registered server (running and stopped).", {
+        alias: z.string().describe("Server alias from the registry"),
+        all: z
+            .boolean()
+            .default(true)
+            .describe("Show all containers including stopped (default: true)"),
+    }, async ({ alias, all }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        const flag = all ? "-a " : "";
+        try {
+            const { stdout, stderr } = await sshExec(srv, `docker ps ${flag}--format 'table {{.Names}}\t{{.Image}}\t{{.Status}}\t{{.Ports}}'`);
+            const result = (stdout || stderr).trim();
+            if (!result || result === "NAMES\tIMAGE\tSTATUS\tPORTS") {
+                return text(`No containers found on "${alias}". Is Docker installed?`);
+            }
+            return text(`🐳 Containers on "${alias}" (${srv.host}):\n\n${result}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to list containers: ${msg}\n\nMake sure Docker is installed (use install_docker).`);
+        }
+    });
+    // 8. manage_server_container — start/stop/restart/remove
+    server.tool("manage_server_container", "Start, stop, restart, or remove a Docker container on a registered server.", {
+        alias: z.string().describe("Server alias from the registry"),
+        container: z.string().describe("Container name or ID"),
+        action: z
+            .enum(["start", "stop", "restart", "remove"])
+            .describe("Action to perform on the container"),
+    }, async ({ alias, container, action }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        // Sanitize container name to prevent injection
+        if (!/^[a-zA-Z0-9_.-]+$/.test(container)) {
+            return text("Invalid container name. Only alphanumeric characters, hyphens, underscores, and dots are allowed.");
+        }
+        const dockerCmd = action === "remove"
+            ? `docker rm -f ${shellQuote(container)}`
+            : `docker ${action} ${shellQuote(container)}`;
+        try {
+            const { stdout, stderr } = await sshExec(srv, dockerCmd);
+            const result = (stdout || stderr).trim();
+            return text(`✅ Container "${container}" — ${action} successful.\n\n${result}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to ${action} container: ${msg}`);
+        }
+    });
+    // 9. setup_ssl — install certbot and get SSL certificate
+    server.tool("setup_ssl", "Install Certbot and obtain an SSL certificate for a domain on a registered server. Supports nginx and standalone modes.", {
+        alias: z.string().describe("Server alias from the registry"),
+        domain: z
+            .string()
+            .describe("Domain name to get SSL certificate for"),
+        email: z
+            .string()
+            .optional()
+            .describe("Email for Let's Encrypt notifications (optional)"),
+        mode: z
+            .enum(["nginx", "standalone"])
+            .default("standalone")
+            .describe("Certbot mode: 'nginx' for nginx plugin, 'standalone' for port 80 binding (default: standalone)"),
+    }, async ({ alias, domain, email, mode }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        // Strict domain + email validation prevents flag smuggling into certbot.
+        let safeDomain;
+        let safeEmail;
+        try {
+            safeDomain = assertSafeDomain(domain);
+            if (email)
+                safeEmail = assertSafeEmail(email);
+        }
+        catch (e) {
+            return text(`❌ ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const emailFlag = safeEmail
+            ? `--email ${shellQuote(safeEmail)}`
+            : "--register-unsafely-without-email";
+        const pluginFlag = mode === "nginx" ? "--nginx" : "--standalone";
+        const qDomain = shellQuote(safeDomain);
+        const steps = [
+            {
+                label: "Install Certbot",
+                cmd: "which certbot >/dev/null 2>&1 && echo 'ALREADY_INSTALLED' || (apt-get update -qq && apt-get install -y -qq certbot" +
+                    (mode === "nginx"
+                        ? " python3-certbot-nginx"
+                        : "") +
+                    " 2>&1 | tail -5)",
+            },
+            {
+                label: "Obtain SSL Certificate",
+                cmd: `certbot certonly ${pluginFlag} -d ${qDomain} ${emailFlag} --agree-tos --non-interactive 2>&1`,
+            },
+            {
+                label: "Verify Certificate",
+                cmd: `certbot certificates -d ${qDomain} 2>&1`,
+            },
+        ];
+        const output = [];
+        output.push(`🔒 Setting up SSL for "${safeDomain}" on "${alias}" (${srv.host})\n`);
+        for (const { label, cmd } of steps) {
+            output.push(`── ${label} ──`);
+            try {
+                const { stdout, stderr } = await sshExec(srv, cmd, 120_000);
+                const result = (stdout || stderr).trim();
+                output.push(result || "(no output)");
+                output.push("");
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                output.push(`⚠️ Failed: ${msg}\n`);
+            }
+        }
+        output.push("💡 Certbot auto-renewal is typically set up via systemd timer.\n" +
+            "   Check with: systemctl list-timers | grep certbot");
+        return text(output.join("\n"));
+    });
+    // 10. get_server_status — system resource status
+    server.tool("get_server_status", "Get current system resource status from a registered server: CPU usage, memory, disk, load average, uptime, and top processes.", {
+        alias: z.string().describe("Server alias from the registry"),
+    }, async ({ alias }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        const script = `
+echo "=== UPTIME ==="
+uptime
+echo ""
+echo "=== LOAD AVERAGE ==="
+cat /proc/loadavg
+echo ""
+echo "=== CPU USAGE ==="
+top -bn1 | head -5
+echo ""
+echo "=== MEMORY ==="
+free -h
+echo ""
+echo "=== DISK ==="
+df -h | grep -E '^/dev|Filesystem'
+echo ""
+echo "=== TOP PROCESSES (by CPU) ==="
+ps aux --sort=-%cpu | head -8
+echo ""
+echo "=== NETWORK CONNECTIONS ==="
+ss -tuln | head -15
+`.trim();
+        try {
+            const { stdout, stderr } = await sshExec(srv, script, 15_000);
+            const result = (stdout || stderr).trim();
+            return text(`📊 Server Status: "${alias}" (${srv.host})\n\n${result}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to get server status: ${msg}`);
+        }
+    });
+    // 11. get_server_logs — read logs from various sources
+    server.tool("get_server_logs", "Read logs from a registered server. Supports journalctl (systemd), docker container logs, or tailing arbitrary log files.", {
+        alias: z.string().describe("Server alias from the registry"),
+        source: z
+            .enum(["journalctl", "docker", "file"])
+            .describe("Log source: 'journalctl' for systemd, 'docker' for container logs, 'file' to tail a log file"),
+        target: z
+            .string()
+            .optional()
+            .describe("For docker: container name. For file: log file path. For journalctl: optional unit name (e.g. 'nginx')."),
+        lines: z
+            .number()
+            .default(50)
+            .describe("Number of log lines to retrieve (default: 50)"),
+    }, async ({ alias, source, target, lines }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        let cmd;
+        switch (source) {
+            case "journalctl":
+                cmd = target
+                    ? `journalctl -u ${target} -n ${lines} --no-pager`
+                    : `journalctl -n ${lines} --no-pager`;
+                break;
+            case "docker":
+                if (!target) {
+                    return text("A container name is required for docker logs. Use list_server_containers to find container names.");
+                }
+                // Sanitize container name
+                if (!/^[a-zA-Z0-9_.-]+$/.test(target)) {
+                    return text("Invalid container name.");
+                }
+                cmd = `docker logs --tail ${lines} ${shellQuote(target)} 2>&1`;
+                break;
+            case "file":
+                if (!target) {
+                    return text("A file path is required. Common locations:\n" +
+                        "  /var/log/syslog\n" +
+                        "  /var/log/nginx/access.log\n" +
+                        "  /var/log/nginx/error.log\n" +
+                        "  /var/log/auth.log");
+                }
+                try {
+                    assertSafePath(target);
+                }
+                catch (e) {
+                    return text(`Invalid file path: ${e instanceof Error ? e.message : String(e)}`);
+                }
+                cmd = `tail -n ${lines} ${shellQuote(target)} 2>&1`;
+                break;
+        }
+        try {
+            const { stdout, stderr } = await sshExec(srv, cmd, 30_000);
+            const result = (stdout || stderr).trim();
+            if (!result) {
+                return text(`No log output from ${source}${target ? ` (${target})` : ""}.`);
+            }
+            return text(`📋 Logs from "${alias}" — ${source}${target ? ` (${target})` : ""} [last ${lines} lines]:\n\n${result}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to read logs: ${msg}`);
+        }
+    });
+    // 12. manage_env_file — read or write .env files on the server
+    server.tool("manage_env_file", "Read or write a .env file on a registered server. In GET mode, reads and displays the file. In SET mode, writes key=value pairs (creates the file if it doesn't exist).", {
+        alias: z.string().describe("Server alias from the registry"),
+        remotePath: z
+            .string()
+            .describe("Path to the .env file on the server (e.g. /opt/myapp/.env)"),
+        mode: z
+            .enum(["get", "set"])
+            .describe("'get' to read the .env file, 'set' to write key=value pairs"),
+        values: z
+            .record(z.string())
+            .optional()
+            .describe("Key-value pairs to write when mode is 'set' (e.g. { \"DB_HOST\": \"localhost\", \"DB_PORT\": \"5432\" })"),
+    }, async ({ alias, remotePath, mode, values }) => {
+        const servers = await loadServers();
+        const srv = getServer(servers, alias);
+        if (!srv)
+            return notFound(alias);
+        let safePath;
+        try {
+            safePath = assertSafePath(remotePath);
+        }
+        catch (e) {
+            return text(`Invalid remotePath: ${e instanceof Error ? e.message : String(e)}`);
+        }
+        const qPath = shellQuote(safePath);
+        if (mode === "get") {
+            try {
+                const { stdout, stderr } = await sshExec(srv, `cat ${qPath} 2>&1`);
+                const result = (stdout || stderr).trim();
+                if (result.includes("No such file") ||
+                    result.includes("Permission denied")) {
+                    return text(`⚠️ ${result}`);
+                }
+                return text(`📄 ${safePath} on "${alias}":\n\n${result}`);
+            }
+            catch (e) {
+                const msg = e instanceof Error ? e.message : String(e);
+                return text(`❌ Failed to read .env file: ${msg}`);
+            }
+        }
+        // mode === "set"
+        if (!values || Object.keys(values).length === 0) {
+            return text("No values provided. Pass key-value pairs in the 'values' parameter.");
+        }
+        // Validate keys — only allow safe env var names
+        for (const key of Object.keys(values)) {
+            if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key)) {
+                return text(`Invalid environment variable name: "${key}". Only letters, numbers, and underscores are allowed.`);
+            }
+        }
+        // Reject control characters in values.
+        for (const [key, value] of Object.entries(values)) {
+            if (/[\0\r\n]/.test(value)) {
+                return text(`Invalid value for "${key}": contains a newline or NUL byte.`);
+            }
+        }
+        // Build the .env content — read existing, merge, write back
+        try {
+            // Read existing
+            let existing = "";
+            try {
+                const { stdout } = await sshExec(srv, `cat ${qPath} 2>/dev/null || true`);
+                existing = stdout;
+            }
+            catch {
+                // File doesn't exist yet, that's fine
+            }
+            // Parse existing key=value pairs
+            const envMap = new Map();
+            for (const line of existing.split("\n")) {
+                const trimmed = line.trim();
+                if (!trimmed || trimmed.startsWith("#"))
+                    continue;
+                const eqIdx = trimmed.indexOf("=");
+                if (eqIdx > 0) {
+                    envMap.set(trimmed.slice(0, eqIdx), trimmed.slice(eqIdx + 1));
+                }
+            }
+            // Merge new values
+            for (const [key, value] of Object.entries(values)) {
+                envMap.set(key, value);
+            }
+            // Build content
+            const content = Array.from(envMap.entries())
+                .map(([k, v]) => `${k}=${v}`)
+                .join("\n");
+            // Write via printf — quote every variable, including the dir and path.
+            const dir = safePath.substring(0, safePath.lastIndexOf("/")) || "/";
+            const escapedContent = content.replace(/'/g, "'\\''");
+            const cmd = `mkdir -p ${shellQuote(dir)} && printf '%s\\n' '${escapedContent}' > ${qPath}`;
+            await sshExec(srv, cmd);
+            const updatedKeys = Object.keys(values).join(", ");
+            return text(`✅ Updated ${safePath} on "${alias}".\n\n` +
+                `Updated keys: ${updatedKeys}\n` +
+                `Total keys: ${envMap.size}\n\n` +
+                `Current contents:\n${content}`);
+        }
+        catch (e) {
+            const msg = e instanceof Error ? e.message : String(e);
+            return text(`❌ Failed to update .env file: ${msg}`);
+        }
+    });
+}