@yawlabs/ssh-mcp 0.14.1 → 0.15.1

package/dist/ssh-config.d.ts

@@ -0,0 +1,4 @@
+export declare function parseSshConfigOutput(stdout: string): {
+    all: Record<string, string>;
+    identityFiles: string[];
+};

package/dist/ssh.d.ts

@@ -0,0 +1,217 @@
+import { Client, type ConnectConfig } from "ssh2";
+export interface SSHConfig {
+    host: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    password?: string;
+    agent?: string;
+}
+export interface ExecResult {
+    stdout: string;
+    stderr: string;
+    code: number;
+    /** True when stdout was truncated at the byte cap. */
+    stdoutTruncated?: boolean;
+    /** True when stderr was truncated at the byte cap. */
+    stderrTruncated?: boolean;
+    /** Signal name (e.g. "TERM") if the remote channel closed via signal instead of exit. */
+    signal?: string;
+}
+/** Why the hostVerifier turned a server's host key down. */
+export type HostKeyRejectionReason = 
+/** No known_hosts entry at all, and SSH_MCP_STRICT_HOST_KEY=1. */
+"unknown-host-strict"
+/** known_hosts has entries for this host, but none of the algorithm the server offered. */
+ | "algorithm-not-in-known-hosts"
+/** known_hosts has an entry of the offered algorithm and the bytes differ. */
+ | "key-mismatch";
+export interface HostKeyRejection {
+    reason: HostKeyRejectionReason;
+    message: string;
+}
+export interface ResolvedConfig {
+    connectConfig: ConnectConfig;
+    proxyJump?: string;
+    /**
+     * Side channel written by `connectConfig.hostVerifier` when it rejects a key.
+     * ssh2 reports every rejection with the same opaque "Host denied (verification
+     * failed)" string (lib/protocol/kex.js), so the verifier records the reason here
+     * and `enhanceSshError` folds it into the thrown error.
+     */
+    hostKeyRejection?: {
+        current: HostKeyRejection | null;
+    };
+    /**
+     * Materializes `connectConfig.algorithms` (the host-key preference order).
+     * DELIBERATELY LAZY -- see the comment at its definition in `resolveConfig`.
+     * `connectWithProxy` calls it immediately before dialing; nothing else should,
+     * because nothing else can use the answer. Idempotent, and absent on a
+     * hand-built ResolvedConfig, so callers use `?.()`.
+     */
+    applyHostKeyAlgorithms?: () => void;
+}
+/** Test-only: drop memoized `ssh -G` results so a suite can vary ssh_config. */
+export declare function clearSshConfigCache(): void;
+/**
+ * Strip the brackets off an IPv6 literal. Both spellings reach us: a caller may
+ * pass `[::1]` (the form `isValidHostname` accepts), while `ssh -G '[::1]'`
+ * answers `hostname ::1`, so `resolveConfig` also carries the bare form.
+ */
+export declare function unbracketHost(host: string): string;
+/**
+ * The known_hosts spellings `ssh-keygen -F` will actually match, in lookup order.
+ *
+ * Verified against OpenSSH's ssh-keygen: for a default-port entry the address is
+ * stored (and looked up) BARE -- `-F '::1'` hits a `::1` line while `-F '[::1]'`
+ * misses it -- and for a non-default port it is `[::1]:2222`, never the
+ * double-bracketed `[[::1]]:2222` the old `[${host}]:${port}` template produced
+ * when handed an already-bracketed host.
+ *
+ * Returns [] when the host fails injection validation. IPv6 is validated in its
+ * bracketed form because that is the only shape `isValidHostname` recognizes
+ * (its plain-host regex has no ':'), which is why a bare `::1` -- the exact
+ * string `ssh -G` hands back -- used to fail validation and silently yield no
+ * known_hosts keys at all.
+ */
+export declare function knownHostsTargets(host: string, port?: number): string[];
+export interface KnownHostEntry {
+    /** Host key type as recorded in known_hosts, e.g. "ssh-ed25519" or "ssh-rsa". */
+    type: string;
+    /** Raw public key blob (base64-decoded). */
+    key: Buffer;
+}
+export declare function readKnownHostsEntries(host: string, port?: number): KnownHostEntry[];
+export declare function readKnownHostsKeys(host: string, port?: number): Buffer[];
+/**
+ * Parse the algorithm name out of an SSH public-key blob. The wire format always
+ * begins with an SSH string: a uint32 big-endian length followed by that many
+ * bytes, e.g. "ssh-ed25519". Returns null if the blob is not shaped like one.
+ */
+export declare function hostKeyBlobType(key: Buffer): string | null;
+/**
+ * Order the host-key algorithms so the ones we hold a known_hosts entry for are
+ * negotiated first -- what OpenSSH does, and the reason it does not reject a host
+ * whose known_hosts line is ecdsa while the server would rather offer ed25519.
+ *
+ * This is a PREFERENCE, never a restriction: the result is a permutation of
+ * ssh2's own default list, so exactly the same algorithm set stays negotiable and
+ * no reachable host becomes unconnectable. Deliberately built from ssh2's DEFAULT
+ * list rather than its SUPPORTED list -- the latter additionally contains ssh-dss,
+ * which ssh2 disables by default and we are not in the business of re-enabling.
+ *
+ * Returns null when there is nothing to do (no known_hosts types, ssh2's list
+ * unreadable, or the preferred set already covers all-or-none of the defaults),
+ * in which case the caller leaves `algorithms` unset.
+ */
+export declare function hostKeyAlgorithmOrder(knownHostTypes: ReadonlyArray<string>): string[] | null;
+/** Test-only: drop the memoized known_hosts key types. */
+export declare function clearKnownHostTypeCache(): void;
+export declare function resolveConfig(config: SSHConfig): ResolvedConfig;
+export declare function formatDiagnostics(host: string): string;
+export declare function connectRaw(connectConfig: ConnectConfig): Promise<Client>;
+/** One hop of a ProxyJump chain, split into the fields `resolveConfig` accepts. */
+export interface JumpHop {
+    /** Hostname or ssh_config alias. IPv6 literals are UNBRACKETED, as `ssh -G` reports them. */
+    host: string;
+    /** Port from the spec; undefined leaves the choice to ssh_config / the default. */
+    port?: number;
+    /** Login from the spec; undefined leaves the choice to ssh_config / the environment. */
+    username?: string;
+}
+/**
+ * Parse an OpenSSH ProxyJump value into its hops.
+ *
+ * `ssh -G <host>` prints the ProxyJump value VERBATIM -- it is the one field ssh
+ * does not resolve for us -- so everything OpenSSH accepts in `ProxyJump` / `-J`
+ * arrives here as one raw string and has to be split apart before any of it can be
+ * handed to `resolveConfig`. Feeding the whole string back in as a `host` (what
+ * this replaced) mangles every form but the bare hostname:
+ *
+ *   - "jeff@bastion.example.com:2222" resolved to hostname "bastion.example.com:2222"
+ *     on port 22 -- DNS fails before a byte is sent.
+ *   - "[2001:db8::1]:2222" resolved to host 2001:db8::1 on port 22 -- WORSE than
+ *     failing: it connects, silently, to the wrong port.
+ *   - a comma list ("first:2201,second:2202") was treated as a single hostname.
+ *
+ * It is also a host-key issue, not only a connectivity one: `knownHostsTargets`
+ * rejects those mangled spellings and returns [], and a verifier with zero known
+ * entries accepts ANY key unless SSH_MCP_STRICT_HOST_KEY=1. Parsing correctly is
+ * what puts the bastion hop back under real known_hosts checking.
+ *
+ * Grammar (OpenSSH ssh_config(5)): `[user@]host[:port]`, or the equivalent
+ * `ssh://[user@]host[:port]` URI, with multiple hops separated by commas and
+ * visited left to right. Rules that matter:
+ *   - the login is split at the LAST "@" (an IPv6 literal has no "@", and a
+ *     password-style "user@domain@host" spelling keeps the trailing host).
+ *   - brackets come off FIRST, so only a ":port" that follows "]" is a port. A
+ *     BARE IPv6 literal is all colons and no port -- never split it.
+ *   - a ":" suffix that is not a valid port number is left as part of the host, so
+ *     a typo fails loudly instead of quietly dialing somewhere else.
+ */
+export declare function parseJumpSpec(spec: string): JumpHop[];
+/**
+ * Render a hop back into ProxyJump spelling. Round-trips through `parseJumpSpec`
+ * (re-bracketing IPv6 so a port stays unambiguous), which is what lets a multi-hop
+ * chain be handed to the recursion below as a plain `proxyJump` string, and what
+ * makes the jump-host label in an error read the way the user wrote it.
+ */
+export declare function formatJumpHop(hop: JumpHop): string;
+export declare function connectWithProxy(resolved: ResolvedConfig): Promise<Client>;
+/**
+ * The single shape for turning an SSH failure into the diagnosed error this server
+ * advertises. Used by `connect()` and by `ConnectionPool.acquire()` for BOTH the
+ * config-resolution and the connect step, so there is one implementation rather
+ * than a copy per call site.
+ *
+ * Attaches, when available: the host-key rejection reason recorded by our
+ * hostVerifier (ssh2 itself only ever says "Host denied (verification failed)"),
+ * then the local SSH environment diagnostics. Returns the original error untouched
+ * when there is nothing to add, so `cause` chains stay short.
+ */
+export declare function enhanceSshError(err: unknown, host: string, resolved?: ResolvedConfig): unknown;
+export declare function connect(config: SSHConfig): Promise<Client>;
+export declare const DEFAULT_MAX_EXEC_BYTES: number;
+export declare function exec(client: Client, command: string, timeoutMs?: number, maxBytes?: number): Promise<ExecResult>;
+export declare function readFile(client: Client, remotePath: string, maxBytes?: number): Promise<string>;
+export declare function writeFile(client: Client, remotePath: string, content: string): Promise<void>;
+export declare function uploadFile(client: Client, localPath: string, remotePath: string): Promise<void>;
+export declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;
+export declare function listDir(client: Client, remotePath: string): Promise<string[]>;
+export interface FileStats {
+    size: number;
+    /** POSIX mode as a decimal number. Use modeOctal for the human-readable form. */
+    mode: number;
+    /** POSIX mode formatted as a 4-digit octal string (e.g. "0755"). */
+    modeOctal: string;
+    uid: number;
+    gid: number;
+    /** Unix timestamp (seconds since epoch) of last modification. */
+    mtime: number;
+    /** Unix timestamp (seconds since epoch) of last access. */
+    atime: number;
+    isFile: boolean;
+    isDirectory: boolean;
+    isSymbolicLink: boolean;
+}
+/**
+ * Two calls, deliberately, because one cannot answer both questions.
+ *
+ * TYPE comes from `lstat`, which reports on the path itself. SFTP `stat` FOLLOWS
+ * symlinks, so it can never report `isSymbolicLink: true` -- the flag this function
+ * has always returned, and which `ssh_stat` advertises, was dead: a symlink to a
+ * directory arrived as `isDirectory` and a dangling one rejected ENOENT before
+ * anything was formatted. `deleteFile` below already uses `lstat` for exactly this
+ * distinction.
+ *
+ * SIZE and the rest come from `stat`, the TARGET's metadata, because "how big is
+ * this" means the target -- a symlink's own size is the length of its path string,
+ * which is never the answer anyone wants. When the target cannot be resolved (a
+ * dangling link) we fall back to the link's own stats and still report it, rather
+ * than failing the call the way `stat` alone did.
+ *
+ * For a non-symlink the two calls agree by definition, so nothing changes there.
+ */
+export declare function statFile(client: Client, remotePath: string): Promise<FileStats>;
+export declare function deleteFile(client: Client, remotePath: string): Promise<void>;
+export declare function makeDir(client: Client, remotePath: string, recursive?: boolean): Promise<void>;

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { ConnectionPool } from "./pool.js";
+export declare function registerTools(server: McpServer, pool?: ConnectionPool): void;

package/package.json

@@ -1,8 +1,8 @@
 {
   "name": "@yawlabs/ssh-mcp",
-  "version": "0.14.1",
+  "version": "0.15.1",
   "mcpName": "io.github.YawLabs/ssh-mcp",
-  "description": "MCP server for SSH operations with built-in diagnostics",
+  "description": "SSH MCP server: run remote commands, transfer files over SFTP, manage ssh-agent keys and known_hosts, and auto-diagnose SSH failures.",
   "type": "module",
   "bin": {
     "ssh-mcp": "bin/ssh-mcp.mjs"
@@ -20,10 +20,10 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsup",
+    "build": "tsup && tsc -p tsconfig.build.json --emitDeclarationOnly",
     "dev": "tsup --watch",
-    "lint": "biome check src/",
-    "lint:fix": "biome check --write src/",
+    "lint": "node scripts/lint.mjs check src/",
+    "lint:fix": "node scripts/lint.mjs check --write src/",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
     "test:integration": "docker compose -f test/docker/docker-compose.yml up -d --build --wait && SSH_MCP_INTEGRATION=1 vitest run src/tests/integration.test.ts; docker compose -f test/docker/docker-compose.yml down",
@@ -31,12 +31,22 @@
     "prepublishOnly": "npm run build"
   },
   "keywords": [
-    "mcp",
     "ssh",
-    "remote",
+    "mcp",
     "model-context-protocol",
+    "mcp-server",
+    "sftp",
+    "ssh-agent",
+    "ssh-keys",
+    "known-hosts",
+    "ssh-config",
+    "proxyjump",
+    "remote",
+    "remote-execution",
+    "diagnostics",
+    "devops",
     "ai",
-    "devops"
+    "ai-agents"
   ],
   "author": "Yaw Labs <contact@yaw.sh>",
   "license": "MIT",
@@ -56,6 +66,7 @@
     "@biomejs/biome": "^2.4.15",
     "@types/node": "^26.1.1",
     "@types/ssh2": "^1.15.5",
+    "@vitest/coverage-v8": "^4.1.11",
     "esbuild": "^0.28.1",
     "postject": "^1.0.0-alpha.6",
     "tsup": "^8.5.1",
@@ -64,5 +75,6 @@
   },
   "overrides": {
     "esbuild": "^0.28.1"
-  }
+  },
+  "homepage": "https://yaw.sh/mcp-servers/ssh-mcp/"
 }