@yawlabs/ssh-mcp 0.14.1 → 0.15.0

package/dist/ops.d.ts

@@ -0,0 +1,54 @@
+import type { Client } from "ssh2";
+import type { ConnectionPool } from "./pool.js";
+export declare function shellQuote(s: string): string;
+export interface MultiExecResult {
+    host: string;
+    stdout: string;
+    stderr: string;
+    code: number;
+    /**
+     * Signal name (e.g. "TERM") when the remote channel closed via signal instead of exit --
+     * mirrors ExecResult.signal (src/ssh.ts). A signal-killed command reports `code: -1`, the
+     * same sentinel exec() uses for "no exit code", so without the signal name a caller cannot
+     * tell "the remote was killed" from "the channel died". ssh_exec already surfaces it; this
+     * field is what lets ssh_multi_exec do the same instead of printing a bare `[exit code: -1]`.
+     */
+    signal?: string;
+    error?: string;
+}
+export interface MultiExecHost {
+    host: string;
+    port?: number;
+    username?: string;
+    privateKeyPath?: string;
+    password?: string;
+}
+export declare function multiExec(pool: ConnectionPool, hosts: MultiExecHost[], command: string, timeoutMs?: number): Promise<MultiExecResult[]>;
+export interface FindOptions {
+    path: string;
+    name?: string;
+    type?: "f" | "d" | "l";
+    maxdepth?: number;
+    minsize?: string;
+    maxsize?: string;
+    newer?: string;
+}
+export declare function find(client: Client, options: FindOptions, timeoutMs?: number): Promise<string[]>;
+export declare function tail(client: Client, path: string, lines?: number, grep?: string, timeoutMs?: number): Promise<string>;
+export interface ServiceStatus {
+    name: string;
+    active: boolean;
+    status: string;
+    description?: string;
+    since?: string;
+    pid?: number;
+    raw: string;
+    /**
+     * True when systemctl could not report on the unit at all: no `Active:` line
+     * parseable AND non-zero exit. Typical causes: typo'd unit name, unit file
+     * doesn't exist, systemd unreachable. Distinct from "service exists but is
+     * stopped" (active=false but unknown=false).
+     */
+    unknown: boolean;
+}
+export declare function serviceStatus(client: Client, serviceName: string, timeoutMs?: number): Promise<ServiceStatus>;

package/dist/policy.d.ts

@@ -0,0 +1,22 @@
+export interface PolicyContext {
+    /**
+     * True when `command` carries an env-var prefix (`KEY='value' ...`) built from the
+     * ssh_exec / ssh_multi_exec `env` parameter. Enforcement is identical either way -- this
+     * only adds an explanation to a whitelist rejection, so an operator whose previously
+     * working `^`-anchored pattern just started failing can see why.
+     */
+    envPrefixApplied?: boolean;
+}
+/**
+ * Check a command against the env-configured policy. Throws if blocked.
+ *
+ * Called from MCP tool handlers (ssh_exec, ssh_multi_exec) -- not from `exec()` itself,
+ * so library consumers using the programmatic API don't get policy enforcement (they're
+ * outside the MCP trust boundary and write their own gating).
+ *
+ * See the SCOPE LIMIT block at the top of this file: the SFTP mutation tools are not
+ * routed through here at all.
+ */
+export declare function enforcePolicy(command: string, context?: PolicyContext): void;
+/** Returns true if any policy is currently configured. Used by tool descriptions to surface that. */
+export declare function isPolicyConfigured(): boolean;

package/dist/pool.d.ts

@@ -0,0 +1,34 @@
+import type { Client } from "ssh2";
+import { type SSHConfig } from "./ssh.js";
+export interface PoolOptions {
+    /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
+    idleTtlMs?: number;
+    /**
+     * Maximum number of connections in the pool. Default: 100, overridable via the
+     * `SSH_MCP_MAX_POOL_SIZE` env var. When at capacity, the pool first tries to evict
+     * an idle entry; if every entry is in use, `acquire()` rejects with
+     * "Connection pool is full". Bump this for fan-out workloads against many distinct
+     * hosts (e.g. `ssh_multi_exec` across a large fleet).
+     */
+    maxPoolSize?: number;
+}
+export declare class ConnectionPool {
+    private entries;
+    private pending;
+    private idleTtlMs;
+    private maxPoolSize;
+    private _connectCount;
+    private drained;
+    constructor(options?: PoolOptions);
+    acquire(config: SSHConfig): Promise<Client>;
+    release(client: Client): void;
+    withConnection<T>(config: SSHConfig, fn: (client: Client) => Promise<T>): Promise<T>;
+    drain(): void;
+    get size(): number;
+    get stats(): {
+        active: number;
+        idle: number;
+    };
+    /** Total number of successful SSH connects made by this pool since construction. */
+    get connectCount(): number;
+}

package/dist/server.d.ts

@@ -1,223 +1,17 @@
-import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { ConnectConfig, Client } from 'ssh2';
-
-interface SSHConfig {
-    host: string;
-    port?: number;
-    username?: string;
-    privateKeyPath?: string;
-    password?: string;
-    agent?: string;
-}
-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;
-}
-interface ResolvedConfig {
-    connectConfig: ConnectConfig;
-    proxyJump?: string;
-}
-declare function readKnownHostsKeys(host: string, port?: number): Buffer[];
-declare function resolveConfig(config: SSHConfig): ResolvedConfig;
-declare function formatDiagnostics(host: string): string;
-declare function connectRaw(connectConfig: ConnectConfig): Promise<Client>;
-declare function connectWithProxy(resolved: ResolvedConfig): Promise<Client>;
-declare function connect(config: SSHConfig): Promise<Client>;
-declare function exec(client: Client, command: string, timeoutMs?: number, maxBytes?: number): Promise<ExecResult>;
-declare function readFile(client: Client, remotePath: string, maxBytes?: number): Promise<string>;
-declare function writeFile(client: Client, remotePath: string, content: string): Promise<void>;
-declare function uploadFile(client: Client, localPath: string, remotePath: string): Promise<void>;
-declare function downloadFile(client: Client, remotePath: string, localPath: string): Promise<void>;
-declare function listDir(client: Client, remotePath: string): Promise<string[]>;
-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;
-}
-declare function statFile(client: Client, remotePath: string): Promise<FileStats>;
-declare function deleteFile(client: Client, remotePath: string): Promise<void>;
-declare function makeDir(client: Client, remotePath: string, recursive?: boolean): Promise<void>;
-
-interface PoolOptions {
-    /** Milliseconds before an idle connection is closed. Default: 60000 (60s) */
-    idleTtlMs?: number;
-    /**
-     * Maximum number of connections in the pool. Default: 100, overridable via the
-     * `SSH_MCP_MAX_POOL_SIZE` env var. When at capacity, the pool first tries to evict
-     * an idle entry; if every entry is in use, `acquire()` rejects with
-     * "Connection pool is full". Bump this for fan-out workloads against many distinct
-     * hosts (e.g. `ssh_multi_exec` across a large fleet).
-     */
-    maxPoolSize?: number;
-}
-declare class ConnectionPool {
-    private entries;
-    private pending;
-    private idleTtlMs;
-    private maxPoolSize;
-    private _connectCount;
-    private drained;
-    constructor(options?: PoolOptions);
-    acquire(config: SSHConfig): Promise<Client>;
-    release(client: Client): void;
-    withConnection<T>(config: SSHConfig, fn: (client: Client) => Promise<T>): Promise<T>;
-    drain(): void;
-    get size(): number;
-    get stats(): {
-        active: number;
-        idle: number;
-    };
-    /** Total number of successful SSH connects made by this pool since construction. */
-    get connectCount(): number;
-}
-
-interface DiagnosticResult {
-    status: "ok" | "warning" | "error";
-    message: string;
-}
-interface DiagnosticReport {
-    overall: "ok" | "warning" | "error";
-    checks: Array<{
-        name: string;
-    } & DiagnosticResult>;
-    suggestions: string[];
-}
-declare function checkSshAgent(): DiagnosticResult;
-declare function checkSshKeys(): DiagnosticResult;
-declare function checkKnownHosts(host: string): DiagnosticResult;
-declare function checkConnectivity(host: string, port?: number): DiagnosticResult;
-declare function checkSshConfig(host: string): DiagnosticResult;
-declare function diagnose(host: string, port?: number): DiagnosticReport;
-
-interface KeyInfo {
-    name: string;
-    path: string;
-    type: string;
-    fingerprint?: string;
-    loadedInAgent: boolean;
-}
-interface AgentResult {
-    running: boolean;
-    reachable: boolean;
-    socket?: string;
-    keys: string[];
-    started: boolean;
-    env?: {
-        SSH_AUTH_SOCK?: string;
-        SSH_AGENT_PID?: string;
-    };
-    message: string;
-}
-declare function ensureAgent(): AgentResult;
-declare function listSshKeys(): KeyInfo[];
-declare function loadKey(keyPath: string): {
-    status: "ok" | "error";
-    message: string;
-};
-interface ConfigLookupResult {
-    hostname: string;
-    user: string;
-    port: string;
-    identityFile: string[];
-    proxyJump?: string;
-    proxyCommand?: string;
-    all: Record<string, string>;
-    raw: string;
-}
-declare function configLookup(host: string): ConfigLookupResult | {
-    error: string;
-};
-declare function fixKnownHosts(host: string, port?: number): {
-    status: "ok" | "error";
-    message: string;
-    actions: string[];
-};
-declare function checkGitSsh(host?: string, user?: string): {
-    status: "ok" | "error";
-    message: string;
-    authenticatedAs?: string;
-};
-declare function testConnection(host: string, port?: number): {
-    status: "ok" | "warning" | "error";
-    message: string;
-};
-
-interface MultiExecResult {
-    host: string;
-    stdout: string;
-    stderr: string;
-    code: number;
-    error?: string;
-}
-interface MultiExecHost {
-    host: string;
-    port?: number;
-    username?: string;
-    privateKeyPath?: string;
-    password?: string;
-}
-declare function multiExec(pool: ConnectionPool, hosts: MultiExecHost[], command: string, timeoutMs?: number): Promise<MultiExecResult[]>;
-interface FindOptions {
-    path: string;
-    name?: string;
-    type?: "f" | "d" | "l";
-    maxdepth?: number;
-    minsize?: string;
-    maxsize?: string;
-    newer?: string;
-}
-declare function find(client: Client, options: FindOptions, timeoutMs?: number): Promise<string[]>;
-declare function tail(client: Client, path: string, lines?: number, grep?: string, timeoutMs?: number): Promise<string>;
-interface ServiceStatus {
-    name: string;
-    active: boolean;
-    status: string;
-    description?: string;
-    since?: string;
-    pid?: number;
-    raw: string;
-    /**
-     * True when systemctl could not report on the unit at all: no `Active:` line
-     * parseable AND non-zero exit. Typical causes: typo'd unit name, unit file
-     * doesn't exist, systemd unreachable. Distinct from "service exists but is
-     * stopped" (active=false but unknown=false).
-     */
-    unknown: boolean;
-}
-declare function serviceStatus(client: Client, serviceName: string, timeoutMs?: number): Promise<ServiceStatus>;
-
-/**
- * Check a command against the env-configured policy. Throws if blocked.
- *
- * Called from MCP tool handlers (ssh_exec, ssh_multi_exec) -- not from `exec()` itself,
- * so library consumers using the programmatic API don't get policy enforcement (they're
- * outside the MCP trust boundary and write their own gating).
- */
-declare function enforcePolicy(command: string): void;
-/** Returns true if any policy is currently configured. Used by tool descriptions to surface that. */
-declare function isPolicyConfigured(): boolean;
-
-declare function registerTools(server: McpServer, pool?: ConnectionPool): void;
-
-declare const version: string;
-declare function createServer(pool?: ConnectionPool): McpServer;
-
-export { type AgentResult, type ConfigLookupResult, ConnectionPool, type DiagnosticReport, type DiagnosticResult, type ExecResult, type FileStats, type FindOptions, type KeyInfo, type MultiExecHost, type MultiExecResult, type PoolOptions, type ResolvedConfig, type SSHConfig, type ServiceStatus, checkConnectivity, checkGitSsh, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, configLookup, connect, connectRaw, connectWithProxy, createServer, deleteFile, diagnose, downloadFile, enforcePolicy, ensureAgent, exec, find, fixKnownHosts, formatDiagnostics, isPolicyConfigured, listDir, listSshKeys, loadKey, makeDir, multiExec, readFile, readKnownHostsKeys, registerTools, resolveConfig, serviceStatus, statFile, tail, testConnection, uploadFile, version, writeFile };
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ConnectionPool } from "./pool.js";
+export declare const version: string;
+export declare function createServer(pool?: ConnectionPool): McpServer;
+export type { DiagnosticReport, DiagnosticResult } from "./diagnose.js";
+export { checkConnectivity, checkKnownHosts, checkSshAgent, checkSshConfig, checkSshKeys, diagnose, } from "./diagnose.js";
+export type { AgentResult, ConfigLookupResult, KeyInfo } from "./env.js";
+export { checkGitSsh, configLookup, ensureAgent, fixKnownHosts, listSshKeys, loadKey, testConnection, } from "./env.js";
+export type { FindOptions, MultiExecHost, MultiExecResult, ServiceStatus } from "./ops.js";
+export { find, multiExec, serviceStatus, tail } from "./ops.js";
+export type { PolicyContext } from "./policy.js";
+export { enforcePolicy, isPolicyConfigured } from "./policy.js";
+export type { PoolOptions } from "./pool.js";
+export { ConnectionPool } from "./pool.js";
+export type { ExecResult, FileStats, HostKeyRejection, HostKeyRejectionReason, ResolvedConfig, SSHConfig, } from "./ssh.js";
+export { connect, connectRaw, connectWithProxy, deleteFile, downloadFile, exec, formatDiagnostics, listDir, makeDir, readFile, readKnownHostsKeys, resolveConfig, statFile, uploadFile, writeFile, } from "./ssh.js";
+export { registerTools } from "./tools.js";