@aaarc/handfree-ssh-mcp 1.0.0

package/build/utils/output-log-writer.js

@@ -0,0 +1,232 @@
+import fs from "fs";
+import path from "path";
+import { Logger } from "./logger.js";
+export class OutputLogWriter {
+    filePath;
+    stdoutPartPath;
+    stderrPartPath;
+    serverName;
+    username;
+    command;
+    startedAt;
+    stdoutBytes = 0;
+    stderrBytes = 0;
+    stdoutFd = null;
+    stderrFd = null;
+    dirEnsured = false;
+    closed = false;
+    writeFailed = false;
+    constructor(opts) {
+        this.serverName = sanitizeSegment(opts.serverName) || "unknown";
+        this.username = sanitizeSegment(opts.username) || "unknown";
+        this.command = opts.command;
+        this.startedAt = opts.startedAt ?? new Date();
+        const dir = path.join(opts.rootDir, this.serverName, this.username);
+        const fileName = makeLogFileName(this.startedAt);
+        this.filePath = path.join(dir, fileName);
+        this.stdoutPartPath = `${this.filePath}.stdout.part`;
+        this.stderrPartPath = `${this.filePath}.stderr.part`;
+    }
+    /**
+     * The absolute path the log will (or did) live at.
+     */
+    getPath() {
+        return this.filePath;
+    }
+    appendStdout(chunk) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        if (buf.length === 0 || this.writeFailed || this.closed)
+            return;
+        const fd = this.openPartLazily("stdout");
+        if (fd === null)
+            return;
+        try {
+            fs.writeSync(fd, buf);
+            this.stdoutBytes += buf.length;
+        }
+        catch (err) {
+            this.markFailed(`stdout write: ${err.message}`);
+        }
+    }
+    appendStderr(chunk) {
+        const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk, "utf8");
+        if (buf.length === 0 || this.writeFailed || this.closed)
+            return;
+        const fd = this.openPartLazily("stderr");
+        if (fd === null)
+            return;
+        try {
+            fs.writeSync(fd, buf);
+            this.stderrBytes += buf.length;
+        }
+        catch (err) {
+            this.markFailed(`stderr write: ${err.message}`);
+        }
+    }
+    /**
+     * Finalize the log: assemble header + stdout part + stderr part + footer
+     * into the final file, then delete the parts. Safe to call multiple
+     * times; only the first call performs work.
+     */
+    close(meta) {
+        if (this.closed)
+            return;
+        this.closed = true;
+        // Always close FDs first so the parts are flushed on disk.
+        this.closeFd("stdout");
+        this.closeFd("stderr");
+        if (this.writeFailed) {
+            // Best-effort: clean up any partial parts so we don't leave junk.
+            this.unlinkQuiet(this.stdoutPartPath);
+            this.unlinkQuiet(this.stderrPartPath);
+            return;
+        }
+        const finishedAt = meta.finishedAt ?? new Date();
+        try {
+            this.ensureDir();
+            const header = `=== META ===\n` +
+                `server: ${this.serverName}\n` +
+                `user: ${this.username}\n` +
+                `command: ${this.command}\n` +
+                `started: ${this.startedAt.toISOString()}\n` +
+                `=== STDOUT ===\n`;
+            const stderrMarker = `\n=== STDERR ===\n`;
+            const footer = `\n=== END ===\n` +
+                `exitCode: ${meta.exitCode === null ? "null" : meta.exitCode}\n` +
+                `durationMs: ${meta.durationMs}\n` +
+                `stdoutBytes: ${this.stdoutBytes}\n` +
+                `stderrBytes: ${this.stderrBytes}\n` +
+                `finished: ${finishedAt.toISOString()}\n`;
+            const outFd = fs.openSync(this.filePath, "w");
+            try {
+                fs.writeSync(outFd, header);
+                this.appendPartTo(outFd, this.stdoutPartPath);
+                fs.writeSync(outFd, stderrMarker);
+                this.appendPartTo(outFd, this.stderrPartPath);
+                fs.writeSync(outFd, footer);
+            }
+            finally {
+                fs.closeSync(outFd);
+            }
+        }
+        catch (err) {
+            this.markFailed(`finalize: ${err.message}`);
+        }
+        finally {
+            this.unlinkQuiet(this.stdoutPartPath);
+            this.unlinkQuiet(this.stderrPartPath);
+        }
+    }
+    didWriteFail() {
+        return this.writeFailed;
+    }
+    /**
+     * Open the stdout/stderr part file on first use. Returns the FD or null
+     * if the open failed (in which case the writer is marked failed).
+     */
+    openPartLazily(which) {
+        const existing = which === "stdout" ? this.stdoutFd : this.stderrFd;
+        if (existing !== null)
+            return existing;
+        try {
+            this.ensureDir();
+            const partPath = which === "stdout" ? this.stdoutPartPath : this.stderrPartPath;
+            const fd = fs.openSync(partPath, "w");
+            if (which === "stdout")
+                this.stdoutFd = fd;
+            else
+                this.stderrFd = fd;
+            return fd;
+        }
+        catch (err) {
+            this.markFailed(`open ${which} part: ${err.message}`);
+            return null;
+        }
+    }
+    closeFd(which) {
+        const fd = which === "stdout" ? this.stdoutFd : this.stderrFd;
+        if (fd === null)
+            return;
+        try {
+            fs.closeSync(fd);
+        }
+        catch {
+            // Ignore close errors — we still want to attempt finalization.
+        }
+        if (which === "stdout")
+            this.stdoutFd = null;
+        else
+            this.stderrFd = null;
+    }
+    ensureDir() {
+        if (this.dirEnsured)
+            return;
+        fs.mkdirSync(path.dirname(this.filePath), { recursive: true });
+        this.dirEnsured = true;
+    }
+    /**
+     * Stream the contents of a part file into the given output FD, 64 KiB at
+     * a time. Missing parts are silently skipped (they just mean that stream
+     * never produced any bytes).
+     */
+    appendPartTo(outFd, partPath) {
+        let inFd;
+        try {
+            inFd = fs.openSync(partPath, "r");
+        }
+        catch {
+            return; // part never created
+        }
+        try {
+            const chunk = Buffer.allocUnsafe(64 * 1024);
+            while (true) {
+                const n = fs.readSync(inFd, chunk, 0, chunk.length, null);
+                if (n <= 0)
+                    break;
+                fs.writeSync(outFd, chunk, 0, n);
+            }
+        }
+        finally {
+            fs.closeSync(inFd);
+        }
+    }
+    unlinkQuiet(p) {
+        try {
+            fs.unlinkSync(p);
+        }
+        catch {
+            // Missing or in-use: ignore. Cleanup is best-effort.
+        }
+    }
+    markFailed(reason) {
+        this.writeFailed = true;
+        Logger.log(`OutputLogWriter failure for ${this.filePath}: ${reason}`, "error");
+    }
+}
+/**
+ * Build a filename like `20250516T021530Z-12345-ab12cd34.log` so concurrent
+ * commands never collide and the names sort chronologically.
+ */
+function makeLogFileName(startedAt) {
+    const iso = startedAt.toISOString().replace(/[-:.]/g, "").replace(/Z$/, "Z");
+    // iso is now like "20250516T021530123Z"; trim millis for brevity
+    const ts = iso.replace(/(\d{8}T\d{6})\d*Z$/, "$1Z");
+    const pid = process.pid;
+    const rand = Math.floor(Math.random() * 0x100000000).toString(16).padStart(8, "0");
+    return `${ts}-${pid}-${rand}.log`;
+}
+/**
+ * Sanitize a server / user name into a safe path segment. Replaces anything
+ * outside [A-Za-z0-9._-] with `_` and forbids `..` / leading dots so the
+ * result can never escape the root dir.
+ */
+function sanitizeSegment(seg) {
+    if (!seg)
+        return "";
+    let cleaned = seg.replace(/[^A-Za-z0-9._-]/g, "_");
+    // Collapse leading dots so we can't accidentally produce ".." or a hidden segment.
+    cleaned = cleaned.replace(/^\.+/, "");
+    if (cleaned === "" || cleaned === "..")
+        return "";
+    return cleaned;
+}

package/build/utils/status-collector.js

@@ -0,0 +1,212 @@
+import { Logger } from "./logger.js";
+/**
+ * Collect system status information from remote server
+ */
+export async function collectSystemStatus(client, connectionName) {
+    const status = {
+        reachable: true,
+        lastUpdated: new Date().toISOString(),
+    };
+    try {
+        // Helper function to execute command and parse output
+        const execCommand = (command) => {
+            return new Promise((resolve, reject) => {
+                client.exec(command, (err, stream) => {
+                    if (err) {
+                        reject(err);
+                        return;
+                    }
+                    let data = "";
+                    stream.on("data", (chunk) => {
+                        data += chunk.toString();
+                    });
+                    stream.on("close", (code) => {
+                        if (code === 0) {
+                            resolve(data.trim());
+                        }
+                        else {
+                            reject(new Error(`Command exited with code ${code}`));
+                        }
+                    });
+                    stream.stderr.on("data", (chunk) => {
+                        // Collect stderr but don't fail on it
+                        data += chunk.toString();
+                    });
+                });
+            });
+        };
+        // Collect all status information in parallel where possible
+        const commands = {
+            hostname: "hostname",
+            ipAddresses: "ip -o addr show | awk '{print $4}' | grep -v '^127\\.' | cut -d'/' -f1",
+            osName: "uname -s",
+            osVersion: "cat /etc/os-release 2>/dev/null | grep '^PRETTY_NAME=' | cut -d'=' -f2 | tr -d '\"' || uname -o",
+            kernelVersion: "uname -r",
+            uptime: "uptime -p 2>/dev/null || uptime | awk -F'up ' '{print $2}' | awk -F',' '{print $1}'",
+            diskSpace: "df -h / | tail -1 | awk '{print \"free:\" $4 \" total:\" $2}'",
+            memory: "free -h | grep '^Mem:' | awk '{print \"free:\" $7 \" total:\" $2}'",
+            cpuName: "sh -c '(lscpu 2>/dev/null | grep \"^Model name:\" | cut -d\":\" -f2 | xargs || cat /proc/cpuinfo 2>/dev/null | grep \"model name\" | head -1 | cut -d\":\" -f2 | xargs || echo \"$(nproc 2>/dev/null || echo '\''?'\'')-core $(uname -m 2>/dev/null || echo '\''unknown'\'') processor\") || true'",
+            cpuUsage: "top -bn1 | grep 'Cpu(s)' | sed 's/.*, *\\([0-9.]*\\)%* id.*/\\1/' | awk '{print 100 - $1}'",
+            gpus: "sh -c '(nvidia-smi --query-gpu=name,utilization.gpu --format=csv,noheader,nounits 2>/dev/null | while IFS=\",\" read -r name usage; do echo \"NVIDIA|${name}|${usage}\"; done || lspci | grep -iE \"vga|3d|display\" | while read -r line; do gpu_name=$(echo \"$line\" | cut -d\":\" -f3 | xargs); echo \"OTHER|${gpu_name}|\"; done) || true'",
+            gpuPaths: "ls -1 /dev/dri/card* 2>/dev/null | sort -V || echo ''",
+            drives: "df -h | awk 'NR>1 && $1 !~ /^(tmpfs|devtmpfs|overlay|shfs|rootfs)$/ && $6 !~ /^(\\/dev|\\/run|\\/sys|\\/proc|\\/boot|\\/usr|\\/lib)$/ && $6 != \"\" {print $1\"|\"$2\"|\"$3\"|\"$4\"|\"$5\"|\"$6}'",
+            // Old gpuPaths: "sh -c '(nvidia-smi --query-gpu=utilization.gpu --format=csv,noheader,nounits 2>/dev/null | head -1 || rocm-smi --showuse 2>/dev/null | grep -i \"GPU use\" | head -1 | awk \"{print \\$NF}\" | tr -d \"%\" || radeontop -l 1 -d - 2>/dev/null | tail -1 | sed -n \"s/.*gpu \\([0-9.]*\\)%.*/\\1/p\" || intel_gpu_top -l 1 -o - 2>/dev/null | tail -1 | awk \"{print \\$NF}\" | tr -d \"%\" || echo \"N/A\") || echo \"N/A\"'",
+            processes: "ps aux | wc -l",
+            threads: "ps -eLf | wc -l",
+            servicesRunning: "systemctl list-units --type=service --state=running 2>/dev/null | wc -l || service --status-all 2>/dev/null | grep running | wc -l || echo '0'",
+            servicesInstalled: "systemctl list-unit-files --type=service 2>/dev/null | wc -l || ls /etc/init.d/ 2>/dev/null | wc -l || echo '0'",
+        };
+        // Execute commands and collect results
+        const results = await Promise.allSettled([
+            execCommand(commands.hostname).catch(() => ""),
+            execCommand(commands.ipAddresses).catch(() => ""),
+            execCommand(commands.osName).catch(() => ""),
+            execCommand(commands.osVersion).catch(() => ""),
+            execCommand(commands.kernelVersion).catch(() => ""),
+            execCommand(commands.uptime).catch(() => ""),
+            execCommand(commands.diskSpace).catch(() => ""),
+            execCommand(commands.memory).catch(() => ""),
+            execCommand(commands.cpuName).catch(() => ""),
+            execCommand(commands.cpuUsage).catch(() => ""),
+            execCommand(commands.gpus).catch(() => ""),
+            execCommand(commands.gpuPaths).catch(() => ""),
+            execCommand(commands.drives).catch(() => ""),
+            execCommand(commands.processes).catch(() => "0"),
+            execCommand(commands.threads).catch(() => "0"),
+            execCommand(commands.servicesRunning).catch(() => "0"),
+            execCommand(commands.servicesInstalled).catch(() => "0"),
+        ]);
+        // Parse results
+        const [hostnameResult, ipAddressesResult, osNameResult, osVersionResult, kernelVersionResult, uptimeResult, diskSpaceResult, memoryResult, cpuNameResult, cpuUsageResult, gpusResult, gpuPathsResult, drivesResult, processesResult, threadsResult, servicesRunningResult, servicesInstalledResult,] = results;
+        if (hostnameResult.status === "fulfilled" && hostnameResult.value) {
+            status.hostname = hostnameResult.value;
+        }
+        if (ipAddressesResult.status === "fulfilled" && ipAddressesResult.value) {
+            status.ipAddresses = ipAddressesResult.value
+                .split("\n")
+                .filter((ip) => ip.trim() && !ip.includes("127.0.0.1"));
+        }
+        if (osNameResult.status === "fulfilled" && osNameResult.value) {
+            status.osName = osNameResult.value;
+        }
+        if (osVersionResult.status === "fulfilled" && osVersionResult.value) {
+            status.osVersion = osVersionResult.value;
+        }
+        if (kernelVersionResult.status === "fulfilled" && kernelVersionResult.value) {
+            status.kernelVersion = kernelVersionResult.value;
+        }
+        if (uptimeResult.status === "fulfilled" && uptimeResult.value) {
+            status.uptime = uptimeResult.value;
+        }
+        if (diskSpaceResult.status === "fulfilled" && diskSpaceResult.value) {
+            const diskMatch = diskSpaceResult.value.match(/free:(\S+)\s+total:(\S+)/);
+            if (diskMatch) {
+                status.diskSpace = {
+                    free: diskMatch[1],
+                    total: diskMatch[2],
+                };
+            }
+        }
+        if (memoryResult.status === "fulfilled" && memoryResult.value) {
+            const memMatch = memoryResult.value.match(/free:(\S+)\s+total:(\S+)/);
+            if (memMatch) {
+                status.memory = {
+                    free: memMatch[1],
+                    total: memMatch[2],
+                };
+            }
+        }
+        // Handle CPU name
+        if (cpuNameResult.status === "fulfilled" && cpuNameResult.value && cpuNameResult.value.trim()) {
+            status.cpu = {
+                name: cpuNameResult.value.trim(),
+            };
+        }
+        if (status.cpu && cpuUsageResult.status === "fulfilled" && cpuUsageResult.value && cpuUsageResult.value !== "N/A") {
+            status.cpu.usage = `${parseFloat(cpuUsageResult.value).toFixed(1)}%`;
+        }
+        // Handle GPUs
+        if (gpusResult.status === "fulfilled" && gpusResult.value && gpusResult.value.trim()) {
+            const gpuPaths = [];
+            if (gpuPathsResult.status === "fulfilled" && gpuPathsResult.value) {
+                gpuPaths.push(...gpuPathsResult.value.split("\n").filter((p) => p.trim()));
+            }
+            const gpuLines = gpusResult.value.split("\n").filter((line) => line.trim());
+            const gpus = [];
+            gpuLines.forEach((line, index) => {
+                const parts = line.split("|");
+                if (parts.length >= 2) {
+                    const vendor = parts[0].trim();
+                    const name = parts[1].trim();
+                    const usage = parts[2]?.trim();
+                    if (name && name !== "N/A") {
+                        const gpu = {
+                            name: name,
+                        };
+                        if (usage && usage.trim() !== "" && usage.trim() !== "N/A" && !isNaN(parseFloat(usage.trim()))) {
+                            gpu.usage = `${parseFloat(usage.trim()).toFixed(1)}%`;
+                        }
+                        // Assign path if available
+                        if (gpuPaths[index]) {
+                            gpu.path = gpuPaths[index];
+                        }
+                        gpus.push(gpu);
+                    }
+                }
+            });
+            if (gpus.length > 0) {
+                status.gpus = gpus;
+            }
+        }
+        // Handle drives
+        if (drivesResult.status === "fulfilled" && drivesResult.value && drivesResult.value.trim()) {
+            const driveLines = drivesResult.value.split("\n").filter((line) => line.trim());
+            const drives = [];
+            driveLines.forEach((line) => {
+                const parts = line.split("|");
+                if (parts.length >= 6) {
+                    const device = parts[0].trim();
+                    const total = parts[1].trim();
+                    const used = parts[2].trim();
+                    const free = parts[3].trim();
+                    const usagePercent = parts[4].trim();
+                    const mountPoint = parts[5].trim();
+                    if (device && mountPoint) {
+                        drives.push({
+                            device,
+                            mountPoint,
+                            total,
+                            used,
+                            free,
+                            usagePercent,
+                        });
+                    }
+                }
+            });
+            if (drives.length > 0) {
+                status.drives = drives;
+            }
+        }
+        if (processesResult.status === "fulfilled" && threadsResult.status === "fulfilled") {
+            const processCount = parseInt(processesResult.value, 10) - 1; // Subtract header line
+            const threadCount = parseInt(threadsResult.value, 10) - 1; // Subtract header line
+            status.processes = {
+                running: Math.max(0, processCount),
+                threads: Math.max(0, threadCount),
+            };
+        }
+        if (servicesRunningResult.status === "fulfilled" && servicesInstalledResult.status === "fulfilled") {
+            const runningCount = parseInt(servicesRunningResult.value, 10) - 1; // Subtract header line
+            const installedCount = parseInt(servicesInstalledResult.value, 10) - 1; // Subtract header line
+            status.services = {
+                running: Math.max(0, runningCount),
+                installed: Math.max(0, installedCount),
+            };
+        }
+    }
+    catch (error) {
+        Logger.log(`Failed to collect system status for [${connectionName}]: ${error.message}`, "error");
+        status.reachable = false;
+    }
+    return status;
+}

package/build/utils/tool-error.js

@@ -0,0 +1,26 @@
+export class ToolError extends Error {
+    code;
+    retriable;
+    constructor(code, message, retriable = false) {
+        super(message);
+        this.code = code;
+        this.retriable = retriable;
+        this.name = "ToolError";
+    }
+}
+export function toToolError(error, fallbackCode) {
+    if (error instanceof ToolError) {
+        return error;
+    }
+    if (error instanceof Error) {
+        return new ToolError(fallbackCode, error.message, false);
+    }
+    return new ToolError(fallbackCode, String(error), false);
+}
+export function formatToolErrorResponse(error) {
+    return JSON.stringify({
+        code: error.code,
+        message: error.message,
+        retriable: error.retriable,
+    }, null, 2);
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@aaarc/handfree-ssh-mcp",
+  "version": "1.0.0",
+  "description": "Handfree SSH MCP Server - A hands-free SSH automation tool via MCP protocol",
+  "main": "build/index.js",
+  "type": "module",
+  "bin": {
+    "handfree-ssh-mcp": "build/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Ironboxplus/handfree-ssh-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/Ironboxplus/handfree-ssh-mcp/issues"
+  },
+  "homepage": "https://github.com/Ironboxplus/handfree-ssh-mcp#readme",
+  "scripts": {
+    "test": "npm run build && node --test build/tests/config.test.js build/tests/command-validation.test.js build/tests/tool-error.test.js build/tests/tools.test.js build/tests/output-collector.test.js build/tests/output-log-writer.test.js build/tests/recent-fixes.test.js",
+    "test:config": "npm run build && node --test build/tests/config.test.js",
+    "test:cmd": "npm run build && node --test build/tests/command-validation.test.js",
+    "test:tools": "npm run build && node --test build/tests/tools.test.js",
+    "test:integration": "npm run build && node build/tests/integration.test.js",
+    "test:all": "npm run test && npm run test:integration",
+    "build": "node scripts/build.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "ssh",
+    "mcp",
+    "server",
+    "cli"
+  ],
+  "author": "Junki",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.17.5",
+    "js-yaml": "^4.1.0",
+    "socks": "^2.8.6",
+    "ssh2": "^1.16.0",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.13.10",
+    "@types/ssh2": "^1.15.5",
+    "typescript": "^5.8.2"
+  },
+  "files": [
+    "build/**/*"
+  ]
+}