@aaarc/handfree-ssh-mcp 1.0.0

package/build/config/server.js

@@ -0,0 +1,25 @@
+export const SERVER_CONFIG = {
+    name: "ssh-mcp-server",
+    version: "1.4.0",
+};
+export const SERVER_INSTRUCTIONS = `This server provides SSH access to servers loaded from OpenSSH config (~/.ssh/config by default) and optional YAML config/policy overlays.
+
+Recommended workflow:
+1. Call list-servers first to discover which server names are available, enabled, and currently connected.
+2. Use show-whitelist before execute-command when you are unsure whether a command is allowed.
+3. Use execute-command for remote shell commands. Prefer a single command per call. Compound commands such as "cmd1 && cmd2" may be rejected by whitelist rules even if each subcommand is individually safe.
+4. Use stream=false for short commands that should finish quickly, such as pwd, ls, cat, head, tail, git status, or docker ps.
+5. Use stream=true for commands that may take longer or where incremental output is useful.
+6. Use upload and download for single-file SFTP transfers. Use transfer for recursive directory transfers or cross-server relay.
+7. Call help or help { tool: "<name>" } for detailed per-tool parameter docs and examples.
+
+Server targeting:
+- When only one server is enabled, connectionName can be omitted and the server is auto-selected.
+- When multiple servers are enabled, connectionName is REQUIRED on execute-command, upload, download, show-whitelist, and transfer (upload/download mode). Omitting it returns an error listing the available names.
+
+Behavior notes:
+- A tool may automatically establish the SSH connection on first use.
+- Command execution is restricted by the configured whitelist and blacklist. If a command is rejected, inspect the whitelist rather than retrying the same command repeatedly.
+- Some commands return no output on success; this is normal.
+- File transfer tools use SFTP and can fail if the remote path is missing or permissions are insufficient.
+- OpenSSH/YAML config changes are hot-reloaded without restarting the server. Connection-field changes close the old client so the next tool call reconnects with fresh settings.`;

package/build/config/ssh-config-loader.js

@@ -0,0 +1,376 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import { Logger } from "../utils/logger.js";
+const SUPPORTED_KEYS = new Set([
+    "hostname",
+    "user",
+    "port",
+    "identityfile",
+    "identityagent",
+    "identitiesonly",
+]);
+export function getDefaultUserSshConfigPath() {
+    return path.join(os.homedir(), ".ssh", "config");
+}
+export function loadSshConfigFiles(configPaths = [getDefaultUserSshConfigPath()]) {
+    const directives = [];
+    const loadedFiles = new Set();
+    const visitedFiles = new Set();
+    for (const configPath of configPaths) {
+        parseConfigFile(resolveLocalPath(configPath, process.cwd()), ["*"], directives, loadedFiles, visitedFiles);
+    }
+    const rawHosts = buildRawHostConfigs(directives);
+    const configs = {};
+    for (const raw of rawHosts) {
+        configs[raw.alias] = toSshConfig(raw);
+    }
+    const configCount = Object.keys(configs).length;
+    if (configCount > 0) {
+        Logger.log(`Loaded ${configCount} host(s) from OpenSSH config: ${Array.from(loadedFiles).join(", ")}`, "info");
+    }
+    return {
+        configs,
+        files: Array.from(loadedFiles),
+    };
+}
+function parseConfigFile(filePath, inheritedPatterns, directives, loadedFiles, visitedFiles) {
+    if (!fs.existsSync(filePath)) {
+        return;
+    }
+    let realPath = filePath;
+    try {
+        realPath = fs.realpathSync(filePath);
+    }
+    catch {
+        realPath = path.resolve(filePath);
+    }
+    if (visitedFiles.has(realPath)) {
+        return;
+    }
+    visitedFiles.add(realPath);
+    loadedFiles.add(realPath);
+    const dir = path.dirname(realPath);
+    const lines = fs.readFileSync(realPath, "utf8").split(/\r?\n/);
+    let currentPatterns = inheritedPatterns;
+    for (let i = 0; i < lines.length; i++) {
+        const stripped = stripComment(lines[i]).trim();
+        if (!stripped)
+            continue;
+        const directiveArgs = parseDirectiveArgs(splitSshArgs(stripped));
+        if (!directiveArgs)
+            continue;
+        const key = directiveArgs.key.toLowerCase();
+        const rest = directiveArgs.values;
+        const value = rest.join(" ");
+        if (key === "host") {
+            currentPatterns = rest.length > 0 ? rest : [];
+            directives.push({
+                key,
+                value,
+                patterns: currentPatterns,
+            });
+            continue;
+        }
+        if (key === "match") {
+            currentPatterns = [];
+            continue;
+        }
+        if (key === "include") {
+            for (const includePattern of rest) {
+                for (const includeFile of expandLocalPattern(includePattern, dir)) {
+                    parseConfigFile(includeFile, currentPatterns, directives, loadedFiles, visitedFiles);
+                }
+            }
+            continue;
+        }
+        directives.push({
+            key,
+            value,
+            patterns: currentPatterns,
+        });
+    }
+}
+function buildRawHostConfigs(directives) {
+    const aliases = new Map();
+    for (const directive of directives) {
+        if (directive.key !== "host")
+            continue;
+        for (const pattern of directive.patterns) {
+            if (pattern.startsWith("!"))
+                continue;
+            if (hasWildcard(pattern))
+                continue;
+            const lower = pattern.toLowerCase();
+            if (!aliases.has(lower)) {
+                aliases.set(lower, pattern);
+            }
+        }
+    }
+    const rawHosts = [];
+    for (const alias of aliases.values()) {
+        const options = new Map();
+        for (const directive of directives) {
+            if (directive.key === "host")
+                continue;
+            if (!SUPPORTED_KEYS.has(directive.key))
+                continue;
+            if (!hostPatternsMatch(directive.patterns, alias))
+                continue;
+            const optionKey = directive.key;
+            if (!options.has(optionKey)) {
+                options.set(optionKey, directive.value);
+            }
+        }
+        rawHosts.push({ alias, options });
+    }
+    return rawHosts;
+}
+function toSshConfig(raw) {
+    const rawHost = raw.options.get("hostname") ?? raw.alias;
+    const rawUser = raw.options.get("user") ?? os.userInfo().username;
+    const rawPort = raw.options.get("port") ?? "22";
+    const port = parsePort(raw.alias, rawPort);
+    const context = {
+        alias: raw.alias,
+        host: rawHost,
+        user: rawUser,
+        port: String(port),
+    };
+    const host = expandTokens(rawHost, context);
+    const username = expandTokens(rawUser, { ...context, host });
+    const identityFile = raw.options.get("identityfile");
+    const identityAgent = raw.options.get("identityagent");
+    const identitiesOnly = parseYesNo(raw.alias, "IdentitiesOnly", raw.options.get("identitiesonly"));
+    const resolvedContext = {
+        alias: raw.alias,
+        host,
+        user: username,
+        port: String(port),
+    };
+    const config = {
+        name: raw.alias,
+        host,
+        port,
+        username,
+        authOptional: true,
+    };
+    if (identitiesOnly !== undefined) {
+        config.identitiesOnly = identitiesOnly;
+    }
+    const identityFileDisabled = identityFile?.toLowerCase() === "none";
+    if (identityFile && !identityFileDisabled) {
+        config.privateKey = resolveLocalPath(expandTokens(identityFile, resolvedContext), process.cwd());
+    }
+    else if (!identityFileDisabled && !identitiesOnly) {
+        const defaultIdentity = findDefaultIdentityFile();
+        if (defaultIdentity) {
+            config.privateKey = defaultIdentity;
+        }
+    }
+    if (identityAgent?.toLowerCase() === "none") {
+        config.agent = false;
+    }
+    else if (identityAgent) {
+        config.agent = resolveLocalPath(expandTokens(identityAgent, resolvedContext), process.cwd());
+    }
+    return config;
+}
+function findDefaultIdentityFile() {
+    const sshDir = path.join(os.homedir(), ".ssh");
+    const candidates = [
+        "id_ed25519",
+        "id_ecdsa",
+        "id_ecdsa_sk",
+        "id_ed25519_sk",
+        "id_rsa",
+        "id_dsa",
+    ];
+    return candidates
+        .map((name) => path.join(sshDir, name))
+        .find((candidate) => fs.existsSync(candidate));
+}
+function parsePort(alias, rawPort) {
+    const port = Number.parseInt(rawPort, 10);
+    if (!Number.isInteger(port) || port <= 0 || port > 65535) {
+        throw new Error(`SSH config Host '${alias}': invalid Port '${rawPort}'`);
+    }
+    return port;
+}
+function parseYesNo(alias, optionName, rawValue) {
+    if (rawValue === undefined)
+        return undefined;
+    const normalized = rawValue.toLowerCase();
+    if (normalized === "yes")
+        return true;
+    if (normalized === "no")
+        return false;
+    throw new Error(`SSH config Host '${alias}': invalid ${optionName} '${rawValue}'`);
+}
+function hostPatternsMatch(patterns, alias) {
+    if (patterns.length === 0)
+        return false;
+    let positiveMatch = false;
+    for (const pattern of patterns) {
+        const negated = pattern.startsWith("!");
+        const body = negated ? pattern.slice(1) : pattern;
+        const matched = wildcardMatch(body, alias);
+        if (negated && matched) {
+            return false;
+        }
+        if (!negated && matched) {
+            positiveMatch = true;
+        }
+    }
+    return positiveMatch;
+}
+function wildcardMatch(pattern, value) {
+    return wildcardPatternRegex(pattern).test(value);
+}
+function hasWildcard(value) {
+    return /[*?]/.test(value);
+}
+function splitSshArgs(line) {
+    const out = [];
+    let current = "";
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === quote) {
+                quote = null;
+            }
+            else if (ch === "\\" && i + 1 < line.length && line[i + 1] === quote) {
+                current += line[++i];
+            }
+            else {
+                current += ch;
+            }
+            continue;
+        }
+        if (ch === "'" || ch === "\"") {
+            quote = ch;
+            continue;
+        }
+        if (/\s/.test(ch)) {
+            if (current.length > 0) {
+                out.push(current);
+                current = "";
+            }
+            continue;
+        }
+        current += ch;
+    }
+    if (current.length > 0) {
+        out.push(current);
+    }
+    return out;
+}
+function parseDirectiveArgs(args) {
+    if (args.length === 0)
+        return null;
+    const firstEquals = args[0].indexOf("=");
+    if (firstEquals > 0) {
+        const key = args[0].slice(0, firstEquals);
+        const firstValue = args[0].slice(firstEquals + 1);
+        const values = firstValue ? [firstValue, ...args.slice(1)] : args.slice(1);
+        return values.length > 0 ? { key, values } : null;
+    }
+    if (args.length >= 2 && args[1] === "=") {
+        const values = args.slice(2);
+        return values.length > 0 ? { key: args[0], values } : null;
+    }
+    if (args.length >= 2 && args[1].startsWith("=")) {
+        const firstValue = args[1].slice(1);
+        const values = firstValue ? [firstValue, ...args.slice(2)] : args.slice(2);
+        return values.length > 0 ? { key: args[0], values } : null;
+    }
+    return args.length > 1 ? { key: args[0], values: args.slice(1) } : null;
+}
+function stripComment(line) {
+    let quote = null;
+    for (let i = 0; i < line.length; i++) {
+        const ch = line[i];
+        if (quote) {
+            if (ch === quote)
+                quote = null;
+            if (ch === "\\" && i + 1 < line.length)
+                i++;
+            continue;
+        }
+        if (ch === "'" || ch === "\"") {
+            quote = ch;
+            continue;
+        }
+        if (ch === "#") {
+            return line.slice(0, i);
+        }
+    }
+    return line;
+}
+function expandLocalPattern(patternText, baseDir) {
+    const resolved = resolveLocalPath(patternText, baseDir);
+    if (!hasWildcard(resolved)) {
+        return [resolved];
+    }
+    return expandGlobSegments(resolved);
+}
+function expandGlobSegments(patternText) {
+    const parsed = path.parse(patternText);
+    const relative = patternText.slice(parsed.root.length);
+    const parts = relative.split(/[\\/]+/).filter(Boolean);
+    let current = [parsed.root || process.cwd()];
+    for (const part of parts) {
+        const next = [];
+        const partHasGlob = hasWildcard(part);
+        const partRegex = partHasGlob ? wildcardPatternRegex(part) : null;
+        for (const dir of current) {
+            if (!partHasGlob) {
+                next.push(path.join(dir, part));
+                continue;
+            }
+            try {
+                for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+                    if (partRegex?.test(entry.name)) {
+                        next.push(path.join(dir, entry.name));
+                    }
+                }
+            }
+            catch {
+                // Ignore unreadable glob roots, matching OpenSSH's permissive Include behavior.
+            }
+        }
+        current = next;
+    }
+    return current.filter((candidate) => fs.existsSync(candidate));
+}
+function resolveLocalPath(filePath, baseDir) {
+    const expanded = expandHome(filePath);
+    if (path.isAbsolute(expanded)) {
+        return path.normalize(expanded);
+    }
+    return path.resolve(baseDir, expanded);
+}
+function wildcardPatternRegex(pattern) {
+    const escaped = pattern.replace(/[.+^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`^${escaped.replace(/\*/g, ".*").replace(/\?/g, ".")}$`, "i");
+}
+function expandHome(filePath) {
+    if (filePath === "~")
+        return os.homedir();
+    if (filePath.startsWith("~/") || filePath.startsWith("~\\")) {
+        return path.join(os.homedir(), filePath.slice(2));
+    }
+    return filePath;
+}
+function expandTokens(value, context) {
+    return value
+        .replace(/%%/g, "\0PERCENT\0")
+        .replace(/%d/g, os.homedir())
+        .replace(/%h/g, context.host)
+        .replace(/%n/g, context.alias)
+        .replace(/%p/g, context.port)
+        .replace(/%r/g, context.user)
+        .replace(/%u/g, os.userInfo().username)
+        .replace(/\0PERCENT\0/g, "%");
+}

package/build/core/mcp-server.js

@@ -0,0 +1,176 @@
+import fs from "fs";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSHConnectionManager } from "../services/ssh-connection-manager.js";
+import { Logger } from "../utils/logger.js";
+import { registerAllTools } from "../tools/index.js";
+import { SERVER_CONFIG, SERVER_INSTRUCTIONS } from "../config/server.js";
+import { getConfigPath, getEnabledServersArg, getLoadUserSshConfigFlag, getPreConnectFlag, getSshConfigPathsArg, loadConfigFromSources, } from "../config/config-loader.js";
+/**
+ * MCP Server class
+ *
+ * handfree-ssh-mcp: Configure once via YAML, let the LLM handle the rest.
+ */
+export class SshMcpServer {
+    server;
+    sshManager;
+    configWatchers = new Map();
+    configWatchersToRefresh = new Set();
+    configReloadTimer = null;
+    constructor() {
+        this.server = new McpServer(SERVER_CONFIG, {
+            instructions: SERVER_INSTRUCTIONS,
+        });
+        this.sshManager = SSHConnectionManager.getInstance();
+    }
+    /**
+     * Register tools
+     */
+    registerTools() {
+        registerAllTools(this.server);
+    }
+    /**
+     * Load configuration from OpenSSH config and optional YAML overlay.
+     *
+     * Optional: --config <path-to-yaml>
+     * Optional: --ssh-config <path-to-openssh-config>
+     * Optional: --enable-servers <server1,server2,...>
+     */
+    loadConfig() {
+        const args = process.argv.slice(2);
+        const parsedArgs = loadConfigFromSources(this.getConfigSourceOptions(args));
+        const enabledServers = getEnabledServersArg(args);
+        if (enabledServers && enabledServers.length > 0) {
+            // Validate that all enabled servers exist in config
+            for (const serverName of enabledServers) {
+                if (!parsedArgs.configs[serverName]) {
+                    throw new Error(`Server '${serverName}' not found in config.\n\n` +
+                        "Available servers: " + Object.keys(parsedArgs.configs).join(", "));
+                }
+            }
+            Logger.log(`Enabled servers: ${enabledServers.join(", ")}`, "info");
+            parsedArgs.enabledServers = enabledServers;
+        }
+        else {
+            Logger.log("No --enable-servers provided; all loaded servers are enabled", "info");
+        }
+        // CLI --pre-connect overrides YAML preConnect (CLI wins when present)
+        if (getPreConnectFlag(args)) {
+            parsedArgs.preConnect = true;
+        }
+        return parsedArgs;
+    }
+    getConfigSourceOptions(args) {
+        return {
+            yamlConfigPath: getConfigPath(args),
+            sshConfigPaths: getSshConfigPathsArg(args),
+            loadUserSshConfig: getLoadUserSshConfigFlag(args),
+        };
+    }
+    /**
+     * Watch loaded config files for changes and hot-reload connection settings
+     * plus policies without restarting the MCP process.
+     */
+    watchConfig(config) {
+        const args = process.argv.slice(2);
+        const enabledServers = config.enabledServers;
+        const scheduleReload = () => {
+            if (this.configReloadTimer)
+                clearTimeout(this.configReloadTimer);
+            this.configReloadTimer = setTimeout(reload, 500);
+        };
+        const reload = () => {
+            try {
+                Logger.log("Config file changed, hot-reloading SSH config...", "info");
+                const fresh = loadConfigFromSources(this.getConfigSourceOptions(args));
+                if (enabledServers) {
+                    for (const serverName of enabledServers) {
+                        if (!fresh.configs[serverName]) {
+                            throw new Error(`Enabled server '${serverName}' no longer exists after reload. Available servers: ${Object.keys(fresh.configs).join(", ")}`);
+                        }
+                    }
+                    fresh.enabledServers = enabledServers;
+                }
+                this.sshManager.replaceConfig(fresh.configs, fresh.enabledServers);
+                this.sshManager.setOutputLogRoot(fresh.outputLogDir);
+                this.reconcileConfigWatchers(fresh.watchPaths, scheduleReload);
+            }
+            catch (error) {
+                Logger.log(`Failed to hot-reload config: ${error.message}`, "error");
+            }
+        };
+        this.reconcileConfigWatchers(config.watchPaths, scheduleReload);
+    }
+    reconcileConfigWatchers(watchPaths, scheduleReload) {
+        if (watchPaths.length === 0) {
+            Logger.log("No config files to watch for live updates", "info");
+        }
+        const nextPaths = new Set(watchPaths);
+        for (const [configPath, watcher] of this.configWatchers) {
+            if (nextPaths.has(configPath) &&
+                !this.configWatchersToRefresh.has(configPath)) {
+                continue;
+            }
+            try {
+                watcher.close();
+            }
+            catch {
+                // Ignore close errors for already-dead watchers.
+            }
+            this.configWatchers.delete(configPath);
+        }
+        for (const configPath of nextPaths) {
+            if (this.configWatchers.has(configPath))
+                continue;
+            try {
+                const watcher = fs.watch(configPath, (eventType) => {
+                    if (eventType !== "change" && eventType !== "rename")
+                        return;
+                    if (eventType === "rename") {
+                        this.configWatchersToRefresh.add(configPath);
+                    }
+                    scheduleReload();
+                });
+                this.configWatchers.set(configPath, watcher);
+                this.configWatchersToRefresh.delete(configPath);
+                Logger.log(`Watching config file for live updates: ${configPath}`, "info");
+            }
+            catch (error) {
+                Logger.log(`Could not watch config file ${configPath} (hot-reload disabled for this file): ${error.message}`, "error");
+            }
+        }
+    }
+    /**
+     * Run the server
+     */
+    async run() {
+        // Initialize SSH configuration
+        const parsedArgs = this.loadConfig();
+        this.sshManager.setConfig(parsedArgs.configs, parsedArgs.enabledServers);
+        this.sshManager.setOutputLogRoot(parsedArgs.outputLogDir);
+        // Security warning
+        const allConfigs = Object.values(parsedArgs.configs);
+        if (allConfigs.some((c) => !c.commandWhitelist || c.commandWhitelist.length === 0)) {
+            Logger.log("WARNING: Running without a command whitelist is strongly discouraged. Please configure a whitelist to restrict the commands that can be executed.", "info");
+        }
+        // Pre-connect to enabled servers if flag is set
+        if (parsedArgs.preConnect) {
+            Logger.log("Pre-connecting to enabled SSH servers...", "info");
+            try {
+                await this.sshManager.connectAll();
+                Logger.log("Successfully pre-connected to enabled SSH servers", "info");
+            }
+            catch (error) {
+                Logger.log(`Warning: Some SSH connections failed during pre-connect: ${error.message}`, "error");
+            }
+        }
+        // Watch config files for live hot-reload
+        this.watchConfig(parsedArgs);
+        // Register tools
+        this.registerTools();
+        // Create transport instance and connect
+        const transport = new StdioServerTransport();
+        await this.server.connect(transport);
+        Logger.log("MCP server connection established");
+    }
+}

package/build/index.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+import { SshMcpServer } from "./core/mcp-server.js";
+import { Logger } from "./utils/logger.js";
+/**
+ * Main program entry
+ */
+async function main() {
+    const sshMcpServer = new SshMcpServer();
+    await sshMcpServer.run();
+}
+main().catch((error) => Logger.handleError(error, "【SSH MCP Server Error】", true));

package/build/models/types.js

@@ -0,0 +1 @@
+export {};