@aaarc/handfree-ssh-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,16 @@
+ISC License
+
+Copyright (c) 2025 junki.cn (original ssh-mcp-server)
+Copyright (c) 2026 woqucc (handfree-ssh-mcp modifications)
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 

package/README.md

@@ -0,0 +1,329 @@
+# 🤖 handfree-ssh-mcp
+
+**Configure once. Let the LLM handle the rest.**
+
+> 🧪 99.9% AI-coded [Include this Readme]. No artisanal hand-crafted code here.
+
+A hands-free SSH automation tool via MCP. Fork of [ssh-mcp-server](https://github.com/classfang/ssh-mcp-server) designed for autonomous AI agent operations.
+
+## 🎯 Philosophy
+
+The original ssh-mcp-server requires passing credentials and options via CLI arguments every time. That's tedious.
+
+**handfree-ssh-mcp** takes a different approach:
+
+1. **Reuse your existing `~/.ssh/config`** automatically, or configure servers once in YAML
+2. **Set your security whitelists** per server through a YAML overlay
+3. **Let the LLM call whatever it needs** - hands-free
+
+Less manual interventions. Just autonomous SSH execution with safeguards.
+
+## ✨ What's New
+
+| Feature | Original | handfree-ssh-mcp |
+|---------|----------|------------------|
+| Configuration | CLI args | **OpenSSH `~/.ssh/config` + optional YAML overlay** |
+| Multi-server | Messy `--ssh` flags | **Clean YAML structure** |
+| Whitelists | Single comma-separated string | **Per-server arrays** |
+| Streaming | Not supported | **Real-time output with `stream` param** |
+| Discoverability | None | **`show-whitelist` tool for LLM** |
+
+## 🚀 Quick Start
+
+### 1. Use your existing `~/.ssh/config`
+
+If you already have:
+
+```sshconfig
+Host dev
+  HostName 192.168.1.100
+  User root
+  IdentityFile ~/.ssh/id_ed25519
+```
+
+you can start the MCP without a YAML file:
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "npx",
+      "args": ["-y", "handfree-ssh-mcp", "--enable-servers", "dev"]
+    }
+  }
+}
+```
+
+`--enable-servers` is optional. If you omit it, every concrete `Host` entry loaded from `~/.ssh/config` (plus YAML entries, if any) is enabled.
+
+### 2. Optional: create `servers.yaml` for policies or overrides
+
+```yaml
+sshConfig: true  # default; loads ~/.ssh/config before applying this YAML
+
+servers:
+  dev:  # Server name - use this in --enable-servers
+    # host / port / username / privateKey can be omitted when dev exists in ~/.ssh/config.
+    # Values here override the OpenSSH config entry when present.
+    whitelist:
+      - "^ls.*$"
+      - "^cat.*$"
+      - "^pwd$"
+      - "^docker.*$"
+      - "^git.*$"
+      # Add whatever commands you trust the LLM to run
+
+  prod:
+    host: XXXXX
+    port: 22
+    username: deploy
+    privateKey: ~/.ssh/id_rsa
+    whitelist:
+      - "^ls.*$"        # Read only
+      - "^cat.*$"
+      - "^tail.*$"
+    blacklist:
+      - "^rm.*$"        # Never allow delete
+      - "^shutdown.*$"
+      - "^reboot.*$"
+```
+
+### 3. Add to MCP Config
+
+```json
+{
+  "mcpServers": {
+    "ssh": {
+      "command": "node",
+      "args": [
+        "/path/to/handfree-ssh-mcp/build/index.js",
+        "--config", "/path/to/servers.yaml",
+        "--enable-servers", "dev,prod"
+      ]
+    }
+  }
+}
+```
+
+### 4. Done. Let the LLM Work.
+
+The AI can now execute commands on your servers. All within your defined security boundaries.
+
+---
+
+## 🛠️ Available Tools
+
+| Tool | Description |
+|------|-------------|
+| `execute-command` | Run SSH command (with optional `stream` for real-time output) |
+| `show-whitelist` | Show allowed commands + SFTP policy + output-log path for a server |
+| `upload` | Upload local file to a remote server (CRLF-fix for shell scripts, skip-if-identical) |
+| `download` | Download remote file to local disk |
+| `transfer` | Unified upload / download / server-to-server relay (`mode`: `upload` / `download` / `relay`, optional `recursive`, optional `skipIfIdentical`) |
+| `list-servers` | List configured (enabled) servers |
+| `help` | Self-describing help text for the MCP client |
+
+### show-whitelist
+
+**Use this first!** Let the LLM know what it's allowed to do:
+
+```json
+{
+  "tool": "show-whitelist",
+  "params": {
+    "connectionName": "dev"
+  }
+}
+```
+
+Returns a formatted list of allowed command patterns with examples.
+
+### execute-command
+
+```json
+{
+  "tool": "execute-command",
+  "params": {
+    "cmdString": "docker ps",
+    "connectionName": "dev",
+    "timeout": 300000,
+    "stream": true
+  }
+}
+```
+
+| Param | Required | Default | Description |
+|-------|----------|---------|-------------|
+| `cmdString` | ✅ | - | Command to execute |
+| `connectionName` | ❌ | First in `--enable-servers` | Which server to run on |
+| `timeout` | ❌ | 300000ms (stream) / 30000ms (no stream) | Timeout in ms |
+| `stream` | ❌ | `true` | Real-time streaming output |
+
+**When to use `stream: false`:**
+- Simple, fast commands (ls, pwd, cat)
+- When you don't need real-time feedback
+
+## 📄 YAML Config Reference
+
+```yaml
+# OpenSSH config loading is enabled by default.
+# true = load ~/.ssh/config, false = use YAML only.
+# You can also provide explicit paths:
+sshConfig:
+  enabled: true
+  paths:
+    - ~/.ssh/config
+    - ~/.ssh/config.d/work
+
+# Eagerly connect to all enabled servers on startup.
+# false (default) = lazy connect on first tool call.
+preConnect: false
+
+# Optional: root dir for execute-command full-output logs.
+# Per-call logs land under <outputLogDir>/<server>/<user>/<ts>-<pid>-<rand>.log.
+# Defaults to <cwd>/.handfree-output when unset. Supports ~ and relative paths.
+outputLogDir: ~/handfree-logs
+
+servers:
+  server_name:
+    # Required only for YAML-only servers. If a same-named Host exists in
+    # ~/.ssh/config, these fields are optional overrides.
+    host: 192.168.1.1
+    port: 22
+    username: root
+    
+    # Auth: use ONE of these. Omit agent to use SSH_AUTH_SOCK when present;
+    # set agent only when you need a specific socket path.
+    password: xxx
+    privateKey: ~/.ssh/id_rsa
+    agent: /path/to/ssh-agent.sock
+    passphrase: key_password    # If privateKey is encrypted
+    
+    # Network
+    socksProxy: socks5://host:port
+    
+    # Security (regex patterns)
+    whitelist:                  # Only allow matching commands
+      - "^ls.*$"
+      - "^cat.*$"
+    blacklist:                  # Block matching commands
+      - "^rm -rf.*$"
+    
+    # Safe directory for destructive commands (rm, etc.)
+    safeDirectory: /home/user   # rm allowed only within this path
+
+    # SFTP path policy — applies ONLY to upload / download / transfer.
+    # execute-command is NOT affected by these lists.
+    # If `allowedRemoteDirectories` is unset or empty, SFTP is DISABLED for the server.
+    allowedRemoteDirectories:
+      - /home/user
+      - /tmp
+    # Extra local dirs allowed as SFTP source/target.
+    # The MCP working directory is always permitted implicitly.
+    allowedLocalDirectories:
+      - /path/to/extra/local/dir
+```
+
+### Security note: command whitelist
+
+If a server's YAML omits `whitelist:` (or sets it to an empty list), `execute-command` falls back to a built-in default whitelist. That default covers common read-mostly tools like `git .*`, `curl .*`, `find .*`, `awk .*`, `sed .*` — broad enough that a determined LLM could write to disk via `awk 'BEGIN{system(...)}'` or similar. It is **strongly recommended to provide an explicit per-server `whitelist:`** narrowed to the commands you actually need. Startup logs a warning whenever a server is running on the default whitelist. See `show-whitelist` to inspect the effective whitelist at runtime.
+
+### SFTP path policy
+
+| Field | Scope | Default behavior |
+|---|---|---|
+| `allowedRemoteDirectories` | `upload` / `download` / `transfer` only | **Unset = SFTP disabled.** Must list absolute POSIX directories. |
+| `allowedLocalDirectories` | `upload` / `download` only | Unset = only the MCP working directory is allowed. |
+
+Path matching is exact-equal or `dir + separator` prefix. `..` segments and null bytes are rejected. Use `show-whitelist` to inspect a server's current SFTP policy.
+
+### Connection lifecycle (connect / reconnect)
+
+- **Lazy by default.** A server's SSH client is created on its first tool call via `ensureConnected()`. Set `preConnect: true` (or pass `--pre-connect`) to open all enabled servers at startup in parallel; failures are logged but don't block startup.
+- **Auto-reconnect on `execute-command`.** Every command runs inside a retry loop (default 3 attempts: 1 initial + 2 retries) with exponential backoff. If the underlying error matches a connection-shaped pattern (`econnreset`, `epipe`, `socket`, `closed`, `channel`, `end of stream`, or a `SSH_CONNECTION_FAILED` ToolError), the manager closes the dead client, reconnects, and retries the command. Non-connection errors (permission denied, validation, command-not-found) are returned immediately without retry.
+- **SFTP transfers do NOT auto-retry.** `upload` / `download` / `transfer` lazy-connect via the same path, but a mid-transfer disconnect surfaces as a single failure — re-issue the call manually. This is a known gap.
+- **No background keepalive or health probe.** Dead connections are only discovered on the next tool call. If you idle for hours through a NATed network, expect the first call after the gap to fail-then-reconnect on its own (you'll see one retry in the logs).
+
+### Upload behaviors
+
+- **CRLF auto-fix for shell scripts.** When uploading a `.sh`, `.bash`, or `.zsh` file, any `\r\n` line endings are automatically converted to `\n` before the bytes are sent. The response notes when this happens and how many line endings were rewritten. The local file on disk is left untouched.
+- **Skip-if-identical (default on).** Before transferring, `upload` checks whether the remote file already matches the local payload. Files ≤ 256 MiB are compared byte-for-byte; larger files are compared via MD5 (using `md5sum` on the remote host). **Shell scripts (`.sh` / `.bash` / `.zsh`) are compared in a line-ending-agnostic way — both sides are LF-normalized before the comparison, so a CRLF-only diff is treated as identical and the upload is still skipped.** If they match, the upload is skipped and the response says so. Pass `skipIfIdentical: false` to force a re-upload. Recursive `transfer` (`mode: upload`, `recursive: true`) applies the same check per file.
+- **Relay skip-if-identical (default on).** `transfer mode=relay` does the same check between two remote servers: matching size on both sides plus matching `md5sum` skips the transfer. If `md5sum` is missing on either server, the check falls back to a normal transfer.
+
+### `execute-command` output capping & full logs
+
+`execute-command` always persists the FULL stdout and stderr of every invocation to a local plain-text log file, then returns only a tail-truncated view to the caller. This keeps the LLM-visible payload small without losing any data.
+
+- **Default cap:** 65536 bytes (64 KiB) per stream, tail-only. Set `maxOutputBytes` on the tool call to raise/lower the cap.
+- **Streaming is unaffected.** When `stream: true`, every chunk still reaches the progress channel live; only the final aggregated return value is capped.
+- **Log path:** `<outputLogDir>/<server-name>/<username>/<timestamp>-<pid>-<rand>.log`. Default `outputLogDir` is `<cwd>/.handfree-output`. Override with a top-level `outputLogDir:` entry in `servers.yaml` (supports `~` and relative paths).
+- **Log format:** plain UTF-8 text with `=== META ===` / `=== STDOUT ===` / `=== STDERR ===` / `=== END ===` separators. Tail with `tail -f` while a command is running? Not yet — the file is finalized on close.
+- **Truncation marker:** when output is trimmed, the returned text starts with an `[OUTPUT TRUNCATED]` header that lists total bytes, bytes dropped, and the on-disk log path. When output fits within the cap, no header is added and no log path is reported (the file is still written).
+- **Retention:** none. Manage cleanup yourself (e.g. `find .handfree-output -mtime +7 -delete`).
+- **Failures are non-fatal.** If the log file cannot be written, the command still completes and the failure is logged as an MCP-side warning.
+
+```yaml
+# servers.yaml
+outputLogDir: ~/handfree-logs  # optional; defaults to <cwd>/.handfree-output
+servers:
+  dev: { ... }
+```
+
+## ⚙️ CLI Options
+
+```text
+--config          Optional path to YAML config/policy overlay
+--ssh-config      Optional OpenSSH config path(s), comma-separated or repeated
+--no-ssh-config   Disable automatic ~/.ssh/config loading
+--enable-servers  Optional comma-separated list of servers to enable
+--pre-connect     Eagerly connect to all enabled servers on startup
+                  (overrides `preConnect` in YAML). Default: lazy connect.
+```
+
+> **Note**: `--enable-servers` controls which servers are available. The first server listed becomes the default when `connectionName` is not specified.
+> If `--enable-servers` is omitted, all loaded servers are enabled; when more than one server is enabled, tools require `connectionName`.
+
+### OpenSSH config support
+
+The loader understands concrete `Host` entries and applies normal OpenSSH-style first-value matching against wildcard defaults. It supports `HostName`, `User`, `Port`, `IdentityFile`, `IdentityAgent`, `Include`, and common tokens such as `%h`, `%n`, `%p`, `%r`, `%u`, `%d`, and `%%`. Wildcard-only `Host *` blocks are used as defaults but are not exposed as runnable server names. `Match` blocks are ignored.
+
+Connection settings are hot-reloaded when the loaded YAML/OpenSSH config files change. If host, user, port, identity, agent, passphrase, or proxy settings change, the existing SSH client for that server is closed and the next tool call reconnects with the new values. Whitelist, blacklist, SFTP policy, and output log settings also update live.
+
+Example with selective servers:
+
+```json
+{
+  "args": [
+    "--config", "servers.yaml",
+    "--enable-servers", "dev,staging"
+  ]
+}
+```
+
+## 🛡️ Security
+
+- **Whitelist everything**: Define exactly what commands are allowed
+- **Keep secrets safe**: Add `servers.yaml` to `.gitignore`
+- **Per-server control**: Prod can be locked down, dev can be permissive
+
+## 📋 TODO & PLAN
+
+### High Priority
+- [x] **Complete test coverage**: Add tests for `list-servers`, `upload`, `download`, `show-whitelist`, streaming mode, timeout/kill
+- [ ] **Session support**: Add tools to list/create/resume/close persistent SSH sessions (for multi-command workflows)
+- [ ] **LLM-based whitelist**: Allow LLM to propose commands, with human approval adding to dynamic whitelist
+
+### Nice to Have
+- [x] **Command history / output archive**: full stdout/stderr of every `execute-command` is persisted under `<outputLogDir>/<server>/<user>/*.log`
+- [x] **Multi-command execution**: Execute multiple commands in sequence with `&&` or `;` safely (fixed: `2>/dev/null` now allowed)
+- [x] **Connection auto-recovery**: `execute-command` retries with exponential backoff and forced reconnect on connection-shaped errors
+- [ ] **SFTP retry parity**: extend the retry-with-reconnect loop to `upload` / `download` / `transfer`
+- [ ] **TCP keepalive**: pass `keepaliveInterval` / `keepaliveCountMax` to `ssh2.Client` so half-open connections are detected without waiting for the next command
+- [ ] **Server health check**: optional periodic ping to detect drops proactively
+
+## 📄 License
+
+ISC License
+
+- Original work: © 2025 junki.cn ([ssh-mcp-server](https://github.com/classfang/ssh-mcp-server))
+- Modifications: © 2026 woqucc (handfree-ssh-mcp)

package/build/config/config-loader.js

@@ -0,0 +1,329 @@
+import fs from "fs";
+import path from "path";
+import os from "os";
+import yaml from "js-yaml";
+import { Logger } from "../utils/logger.js";
+import { getDefaultUserSshConfigPath, loadSshConfigFiles, } from "./ssh-config-loader.js";
+/**
+ * Expand ~ to home directory in paths
+ */
+function expandTilde(filePath) {
+    if (filePath.startsWith("~")) {
+        return path.join(os.homedir(), filePath.slice(1));
+    }
+    return filePath;
+}
+/**
+ * Load and parse YAML config file
+ */
+export function loadConfigFromYaml(configPath) {
+    return loadYamlConfig(configPath, { requireServers: true });
+}
+export function loadConfigFromSources(options = {}) {
+    const yamlConfigPath = options.yamlConfigPath ?? null;
+    const yamlParsed = yamlConfigPath
+        ? loadYamlConfig(yamlConfigPath, { requireServers: false })
+        : null;
+    const resolvedYamlConfigPath = yamlConfigPath ? resolveConfigPath(yamlConfigPath) : undefined;
+    const sshConfigEnabled = resolveSshConfigEnabled(options, yamlParsed);
+    const sshConfigPaths = sshConfigEnabled
+        ? resolveSshConfigPaths(options.sshConfigPaths, yamlParsed)
+        : [];
+    const sshConfigResult = sshConfigEnabled
+        ? loadSshConfigFiles(sshConfigPaths)
+        : { configs: {}, files: [] };
+    const configs = mergeConfigMaps(sshConfigResult.configs, yamlParsed?.configs ?? {});
+    if (Object.keys(configs).length === 0) {
+        throw new Error("No SSH servers loaded. Add Host entries to ~/.ssh/config, pass --ssh-config <path>, or provide --config <servers.yaml>.");
+    }
+    validateMergedConfigs(configs);
+    return {
+        configs,
+        preConnect: yamlParsed?.preConnect === true,
+        outputLogDir: yamlParsed?.outputLogDir,
+        watchPaths: [
+            ...(resolvedYamlConfigPath ? [resolvedYamlConfigPath] : []),
+            ...sshConfigResult.files,
+        ],
+        loadedSshConfigPaths: sshConfigResult.files,
+        loadedYamlConfigPath: resolvedYamlConfigPath,
+    };
+}
+function loadYamlConfig(configPath, options) {
+    const expandedPath = expandTilde(configPath);
+    const absolutePath = resolveConfigPath(expandedPath);
+    Logger.log(`Loading config from: ${absolutePath}`, "info");
+    if (!fs.existsSync(absolutePath)) {
+        throw new Error(`Config file not found: ${absolutePath}`);
+    }
+    const fileContent = fs.readFileSync(absolutePath, "utf8");
+    let config;
+    try {
+        config = yaml.load(fileContent);
+    }
+    catch (error) {
+        throw new Error(`Failed to parse YAML config: ${error.message}`);
+    }
+    if (!config || (options.requireServers && !config.servers)) {
+        throw new Error("Invalid config: 'servers' section is required");
+    }
+    const configMap = {};
+    for (const [name, serverConfig] of Object.entries(config.servers ?? {})) {
+        configMap[name] = buildYamlServerConfig(name, serverConfig, {
+            allowPartial: !options.requireServers,
+        });
+    }
+    if (options.requireServers && Object.keys(configMap).length === 0) {
+        throw new Error("No servers defined in config file");
+    }
+    Logger.log(`Total YAML servers loaded: ${Object.keys(configMap).length}`, "info");
+    // Resolve outputLogDir if provided. Default applied later (in ssh-connection-manager)
+    // so it always tracks the current cwd at execution time.
+    let outputLogDir;
+    if (config.outputLogDir !== undefined) {
+        if (typeof config.outputLogDir !== "string" || config.outputLogDir.length === 0) {
+            throw new Error("'outputLogDir' must be a non-empty string");
+        }
+        outputLogDir = path.resolve(expandTilde(config.outputLogDir));
+        Logger.log(`Output log dir (from YAML): ${outputLogDir}`, "info");
+    }
+    return {
+        configs: configMap,
+        preConnect: config.preConnect === true,
+        outputLogDir,
+        sshConfig: config.sshConfig,
+    };
+}
+function buildYamlServerConfig(name, serverConfig, options = {}) {
+    const allowPartial = options.allowPartial === true;
+    if (!allowPartial && !serverConfig.host) {
+        throw new Error(`Server '${name}': 'host' is required`);
+    }
+    if (!allowPartial && !serverConfig.username) {
+        throw new Error(`Server '${name}': 'username' is required`);
+    }
+    if (!allowPartial &&
+        !serverConfig.password &&
+        !serverConfig.privateKey &&
+        !serverConfig.agent) {
+        throw new Error(`Server '${name}': either 'password', 'privateKey', or 'agent' is required`);
+    }
+    const merged = { name };
+    const port = serverConfig.port ?? (allowPartial ? undefined : 22);
+    if (serverConfig.host !== undefined)
+        merged.host = serverConfig.host ?? undefined;
+    if (port !== undefined)
+        merged.port = port;
+    if (serverConfig.username !== undefined)
+        merged.username = serverConfig.username ?? undefined;
+    if (serverConfig.password !== undefined)
+        merged.password = serverConfig.password ?? undefined;
+    if (serverConfig.privateKey)
+        merged.privateKey = expandTilde(serverConfig.privateKey);
+    if (serverConfig.passphrase !== undefined)
+        merged.passphrase = serverConfig.passphrase ?? undefined;
+    if (serverConfig.agent !== undefined) {
+        merged.agent = serverConfig.agent ? expandTilde(serverConfig.agent) : undefined;
+    }
+    if (serverConfig.password || serverConfig.privateKey || serverConfig.agent) {
+        merged.authOptional = false;
+    }
+    if (serverConfig.socksProxy !== undefined)
+        merged.socksProxy = serverConfig.socksProxy ?? undefined;
+    if (serverConfig.whitelist !== undefined) {
+        merged.commandWhitelist = serverConfig.whitelist ?? undefined;
+    }
+    if (serverConfig.blacklist !== undefined) {
+        merged.commandBlacklist = serverConfig.blacklist ?? undefined;
+    }
+    if (serverConfig.safeDirectory !== undefined) {
+        merged.safeDirectory = serverConfig.safeDirectory ?? undefined;
+    }
+    if (serverConfig.allowedRemoteDirectories !== undefined) {
+        merged.allowedRemoteDirectories = normalizeAllowedRemoteDirectories(name, serverConfig.allowedRemoteDirectories);
+    }
+    if (serverConfig.allowedLocalDirectories !== undefined) {
+        merged.allowedLocalDirectories = normalizeAllowedLocalDirectories(name, serverConfig.allowedLocalDirectories);
+    }
+    if (!allowPartial) {
+        Logger.log(`Loaded server config: ${name} -> ${merged.username}@${merged.host}:${merged.port}`, "info");
+    }
+    return merged;
+}
+function mergeConfigMaps(sshConfigs, yamlConfigs) {
+    const merged = { ...sshConfigs };
+    for (const [name, yamlConfig] of Object.entries(yamlConfigs)) {
+        merged[name] = {
+            ...merged[name],
+            ...yamlConfig,
+            name,
+            allowedRemoteDirectories: yamlConfig.allowedRemoteDirectories ?? merged[name]?.allowedRemoteDirectories,
+            allowedLocalDirectories: yamlConfig.allowedLocalDirectories ?? merged[name]?.allowedLocalDirectories,
+            commandWhitelist: yamlConfig.commandWhitelist ?? merged[name]?.commandWhitelist,
+            commandBlacklist: yamlConfig.commandBlacklist ?? merged[name]?.commandBlacklist,
+            safeDirectory: yamlConfig.safeDirectory ?? merged[name]?.safeDirectory,
+        };
+    }
+    return merged;
+}
+function validateMergedConfigs(configs) {
+    for (const [name, config] of Object.entries(configs)) {
+        if (typeof config.host !== "string" || config.host.length === 0) {
+            throw new Error(`Server '${name}': 'host' is required`);
+        }
+        if (typeof config.username !== "string" || config.username.length === 0) {
+            throw new Error(`Server '${name}': 'username' is required`);
+        }
+        if (!Number.isInteger(config.port) ||
+            config.port <= 0 ||
+            config.port > 65535) {
+            throw new Error(`Server '${name}': 'port' must be an integer from 1 to 65535`);
+        }
+        if (!config.authOptional &&
+            !config.password &&
+            !config.privateKey &&
+            !config.agent) {
+            throw new Error(`Server '${name}': either 'password', 'privateKey', 'agent', or OpenSSH/default authentication is required`);
+        }
+    }
+}
+function resolveSshConfigEnabled(options, yamlParsed) {
+    if (options.loadUserSshConfig !== undefined) {
+        return options.loadUserSshConfig;
+    }
+    if (options.sshConfigPaths && options.sshConfigPaths.length > 0) {
+        return true;
+    }
+    if (typeof yamlParsed?.sshConfig === "boolean") {
+        return yamlParsed.sshConfig;
+    }
+    if (typeof yamlParsed?.sshConfig === "object" && yamlParsed.sshConfig.enabled !== undefined) {
+        return yamlParsed.sshConfig.enabled;
+    }
+    return true;
+}
+function resolveSshConfigPaths(cliPaths, yamlParsed) {
+    if (cliPaths && cliPaths.length > 0) {
+        return cliPaths;
+    }
+    if (typeof yamlParsed?.sshConfig === "object" && yamlParsed.sshConfig.paths?.length) {
+        return yamlParsed.sshConfig.paths;
+    }
+    return [getDefaultUserSshConfigPath()];
+}
+/**
+ * Check if --config argument is provided
+ */
+export function getConfigPath(args) {
+    const configIndex = args.indexOf("--config");
+    if (configIndex !== -1 && args[configIndex + 1]) {
+        return args[configIndex + 1];
+    }
+    return null;
+}
+/**
+ * Get --enable-servers argument if provided
+ * Returns array of enabled server names, or null if not specified
+ */
+export function getEnabledServersArg(args) {
+    const index = args.indexOf("--enable-servers");
+    if (index !== -1 && args[index + 1]) {
+        return args[index + 1].split(",").map(s => s.trim()).filter(Boolean);
+    }
+    return null;
+}
+/**
+ * Get optional --ssh-config paths. Accepts comma-separated values and can be repeated.
+ */
+export function getSshConfigPathsArg(args) {
+    const out = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] !== "--ssh-config")
+            continue;
+        const value = args[i + 1];
+        if (!value)
+            continue;
+        out.push(...value.split(",").map((s) => s.trim()).filter(Boolean));
+        i++;
+    }
+    return out.length > 0 ? out : null;
+}
+/**
+ * Disable automatic ~/.ssh/config loading.
+ */
+export function getNoSshConfigFlag(args) {
+    return args.includes("--no-ssh-config");
+}
+/**
+ * Return the CLI override for user OpenSSH config loading.
+ * undefined means "let YAML/defaults decide"; false is the explicit
+ * --no-ssh-config override.
+ */
+export function getLoadUserSshConfigFlag(args) {
+    return getNoSshConfigFlag(args) ? false : undefined;
+}
+/**
+ * Check if --pre-connect flag is present on the CLI.
+ * Overrides the YAML `preConnect` setting when set.
+ */
+export function getPreConnectFlag(args) {
+    return args.includes("--pre-connect");
+}
+/**
+ * Normalize and validate allowedRemoteDirectories.
+ * Each entry must be an absolute POSIX path. Trailing slashes are stripped
+ * (except for the root "/"). ".." segments are rejected after normalization.
+ */
+function normalizeAllowedRemoteDirectories(serverName, raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error(`Server '${serverName}': 'allowedRemoteDirectories' must be a list of absolute POSIX paths`);
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`Server '${serverName}': 'allowedRemoteDirectories' entries must be non-empty strings`);
+        }
+        if (entry.includes("\0")) {
+            throw new Error(`Server '${serverName}': 'allowedRemoteDirectories' entry contains a null byte: ${entry}`);
+        }
+        if (!path.posix.isAbsolute(entry)) {
+            throw new Error(`Server '${serverName}': 'allowedRemoteDirectories' entry must be an absolute POSIX path, got: ${entry}`);
+        }
+        // Reject '..' BEFORE normalization, otherwise '/a/../b' would silently collapse to '/b'.
+        if (entry.split("/").includes("..")) {
+            throw new Error(`Server '${serverName}': 'allowedRemoteDirectories' entry must not contain '..' segments: ${entry}`);
+        }
+        const normalized = path.posix.normalize(entry);
+        const trimmed = normalized.length > 1 && normalized.endsWith("/")
+            ? normalized.slice(0, -1)
+            : normalized;
+        out.push(trimmed);
+    }
+    return out;
+}
+/**
+ * Normalize allowedLocalDirectories. Resolves each entry to an absolute
+ * host path (with ~ expansion). The MCP working directory is implicitly
+ * allowed and does NOT need to appear here.
+ */
+function normalizeAllowedLocalDirectories(serverName, raw) {
+    if (!Array.isArray(raw)) {
+        throw new Error(`Server '${serverName}': 'allowedLocalDirectories' must be a list of paths`);
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (typeof entry !== "string" || entry.length === 0) {
+            throw new Error(`Server '${serverName}': 'allowedLocalDirectories' entries must be non-empty strings`);
+        }
+        const expanded = expandTilde(entry);
+        const resolved = path.resolve(expanded);
+        out.push(resolved);
+    }
+    return out;
+}
+function resolveConfigPath(configPath) {
+    const expandedPath = expandTilde(configPath);
+    return path.isAbsolute(expandedPath)
+        ? path.normalize(expandedPath)
+        : path.resolve(process.cwd(), expandedPath);
+}

package/build/config/index.js

@@ -0,0 +1,5 @@
+/**
+ * Export all configurations
+ */
+export * from './server.js';
+export * from './config-loader.js';