@akms/mcp-ssh 0.0.1

package/lib/index.d.ts

@@ -0,0 +1,606 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { SFTPWrapper } from 'ssh2';
+import { z } from 'zod';
+
+/**
+ * Guard rules applied to every command / file operation on a host.
+ * Resolved per profile: config `defaults` merged with the profile's own overrides.
+ */
+interface SshPolicy {
+    /** Blocks write-shaped commands, output redirection, uploads and remote writes. */
+    readonly: boolean;
+    /** When false, any segment starting with `sudo` / `su` / `doas` is rejected. */
+    allowSudo: boolean;
+    /** Per-command wall clock limit; the channel is killed once it elapses. */
+    execTimeoutMs: number;
+    /** TCP + handshake limit for opening the connection. */
+    connectTimeoutMs: number;
+    /** stdout and stderr are each truncated past this many characters. */
+    maxOutputCharacters: number;
+    /** Byte ceiling for `ssh_read_file`, guarding against dumping a huge log into context. */
+    maxReadFileBytes: number;
+    /** Allowed command binaries. Empty means "anything that no deny rule matches". */
+    allowCommands: string[];
+    /**
+     * Extra deny rules, compiled at config load so an invalid pattern fails startup
+     * instead of silently not being in force at the moment it matters.
+     */
+    denyPatterns: RegExp[];
+    /** Remote path prefixes the file tools may touch. Empty means unrestricted. */
+    allowedPaths: string[];
+}
+/** One registered host: where to connect, how to authenticate, what is permitted. */
+interface SshHostProfile {
+    /** Profile alias — the `target` argument of every tool. */
+    name: string;
+    host: string;
+    port: number;
+    username: string;
+    description?: string;
+    /** Expanded absolute path to a private key file. */
+    privateKeyPath?: string;
+    /** Private key contents, used when `privateKeyPath` is absent. */
+    privateKey?: string;
+    passphrase?: string;
+    password?: string;
+    /**
+     * Expected server host key, as `SHA256:…` — the string `ssh-keyscan` prints and this
+     * server logs on first connect. When set, a mismatch aborts the connection.
+     */
+    hostKeyFingerprint?: string;
+    /** Directory every session starts in; falls back to the login shell's default. */
+    defaultCwd?: string;
+    policy: SshPolicy;
+}
+/** Loaded profiles, keyed by alias. */
+interface SshMcpConfig {
+    profiles: Map<string, SshHostProfile>;
+    /**
+     * Absolute path the config was read from, or null when it came from inline JSON or
+     * nothing was found. Only a real file needs protecting from the download tool.
+     */
+    sourcePath: string | null;
+    /** Where the config came from, for tool output — a path, "inline", or "none". */
+    sourceLabel: string;
+}
+/** Credential-free view of a profile, safe to hand back to the model. */
+interface SshHostSummary {
+    name: string;
+    host: string;
+    port: number;
+    username: string;
+    description?: string;
+    authMethod: "privateKey" | "password" | "agent";
+    readonly: boolean;
+    allowSudo: boolean;
+    allowedPaths: string[];
+    allowCommands: string[];
+}
+
+/** Outcome of one remote command. */
+interface SshExecResult {
+    stdout: string;
+    stderr: string;
+    /** Remote process exit status; null when the process was killed by a signal. */
+    exitCode: number | null;
+    /** Signal name that killed the remote process, e.g. "TERM". */
+    signal?: string;
+    /** True when the local timeout fired before the remote process finished. */
+    timedOut: boolean;
+    /** True when stdout or stderr hit `maxOutputCharacters` and was cut. */
+    truncated: boolean;
+    /** Working directory after the command ran; only tracked for session-bound execs. */
+    cwd?: string;
+    durationMs: number;
+}
+/** Live session as reported by `ssh_list_sessions`. */
+interface SshSessionInfo {
+    sessionId: string;
+    profileName: string;
+    host: string;
+    username: string;
+    cwd: string;
+    /** ISO-8601 timestamps. */
+    openedAt: string;
+    lastUsedAt: string;
+    execCount: number;
+}
+/** One entry of an SFTP directory listing. */
+interface SshRemoteEntry {
+    name: string;
+    type: "file" | "directory" | "symlink" | "other";
+    sizeBytes: number;
+    /** Octal permission string, e.g. "0644". */
+    mode: string;
+    modifiedAt: string;
+}
+/** Verdict from the command / path guards. */
+interface GuardVerdict {
+    allowed: boolean;
+    /** Human-readable rejection cause; only set when `allowed` is false. */
+    reason?: string;
+    /** The command segment or path that tripped the rule. */
+    offendingText?: string;
+}
+
+interface SshExecOptions {
+    command: string;
+    /** Directory to `cd` into first; the login shell's default is used when absent. */
+    cwd?: string;
+    timeoutMs: number;
+    maxOutputCharacters: number;
+    /** Appends a `$PWD` marker so a session can follow `cd` between commands. */
+    trackCwd: boolean;
+}
+/**
+ * One ssh2 client bound to a profile, plus the exec / SFTP operations run over it.
+ *
+ * This class is the chokepoint: it holds the profile, so it applies the command guard
+ * itself rather than trusting each caller to remember. Enforcement in the tool handlers
+ * was one forgotten line away from shipping an unscreened command — and one such caller
+ * (the `ssh_connect` probe) already existed.
+ */
+declare class SshConnection {
+    readonly profile: SshHostProfile;
+    private client;
+    private pendingClient;
+    private connecting;
+    private disposed;
+    /** Set when the peer closed a previously established connection. */
+    private droppedAfterReady;
+    private observedFingerprint;
+    constructor(profile: SshHostProfile);
+    get isConnected(): boolean;
+    /** Host key the server presented, once a handshake has been attempted. */
+    get hostKeyFingerprint(): string | null;
+    /** True when a connection was established and then lost, so shell state is gone. */
+    get wasDropped(): boolean;
+    /**
+     * Opens the connection, or joins the in-flight attempt when one is already running.
+     *
+     * @throws {Error} If the connection was closed, authentication fails, the host is
+     *                 unreachable, or the handshake times out.
+     */
+    connect(): Promise<void>;
+    /**
+     * Screens a command against this profile's policy, then runs it on its own channel.
+     *
+     * The canonical form is what gets screened *and* what gets sent — validating one
+     * string while executing another is a bypass by construction.
+     *
+     * @throws {GuardRejectionError} If the policy refuses the command or the cwd.
+     * @throws {Error} If the connection is closed or the channel cannot be opened.
+     */
+    exec(options: SshExecOptions): Promise<SshExecResult>;
+    /**
+     * Opens an SFTP channel, hands it to `handler`, and closes it afterwards.
+     *
+     * A channel per operation costs one round trip but keeps a broken transfer from
+     * poisoning later ones — SFTP channels do not recover from a mid-stream error.
+     *
+     * The channel's own `error` event is wired into the returned promise: ssh2 strips its
+     * setup listeners before handing the wrapper over, so an unhandled SFTP protocol error
+     * would otherwise crash the process rather than fail this one call.
+     *
+     * @throws {Error} If the SFTP subsystem cannot be started or the channel errors.
+     */
+    withSftp<T>(handler: (sftp: SFTPWrapper) => Promise<T>): Promise<T>;
+    /** Closes the connection for good; a disposed connection will not re-dial. */
+    disconnect(): void;
+}
+
+/** A connection plus the shell state (working directory) carried across commands. */
+declare class SshSession {
+    readonly sessionId: string;
+    readonly connection: SshConnection;
+    /** Empty until the first command reports `$PWD`; then the real remote path. */
+    cwd: string;
+    lastUsedAt: Date;
+    execCount: number;
+    readonly openedAt: Date;
+    /** Tail of the serialized operation chain; see `runExclusive`. */
+    private operationChain;
+    private activeOperationCount;
+    constructor(sessionId: string, connection: SshConnection);
+    get profile(): SshHostProfile;
+    /** True while an operation is running, so the idle sweeper leaves it alone. */
+    get isBusy(): boolean;
+    /** Marks the session as in use. */
+    touch(): void;
+    /**
+     * Runs `operation` with exclusive use of this session.
+     *
+     * Serialized because `cwd` is read-modify-write across a network round trip: two
+     * concurrent calls both read the old directory, and the one that finishes second
+     * writes it back — silently undoing the other's `cd`. Bracketing with `touch()` also
+     * keeps the idle sweeper off a session that is mid-transfer.
+     */
+    runExclusive<T>(operation: (connection: SshConnection) => Promise<T>): Promise<T>;
+    /**
+     * Runs a command in this session's working directory and adopts wherever it ended up,
+     * so a `cd` in one call is still in effect on the next.
+     *
+     * Passing `cwd` runs this command elsewhere *and* moves the session there — same
+     * result as prefixing `cd <cwd> &&`, which is what a shell user would expect.
+     *
+     * @throws {Error} If the connection was dropped since the session opened. A silent
+     *                 re-dial would hand back a fresh login shell while the model still
+     *                 believes it holds the old one — environment, sudo cache and
+     *                 background jobs all gone with no signal.
+     */
+    exec(command: string, options?: {
+        cwd?: string;
+        timeoutMs?: number;
+    }): Promise<SshExecResult>;
+    toInfo(): SshSessionInfo;
+}
+/** Owns every open session: creation, lookup, idle expiry and shutdown. */
+declare class SshSessionManager {
+    private readonly sessions;
+    private sequence;
+    private pendingOpenCount;
+    private sweepTimer;
+    /**
+     * Opens a connection and registers it as a session.
+     *
+     * `pendingOpenCount` reserves the slot across the `await`: checking `sessions.size`
+     * alone let N concurrent calls all observe the same pre-connect count and blow past
+     * the ceiling together.
+     *
+     * @throws {Error} If the session ceiling is reached or the connection fails.
+     */
+    open(profile: SshHostProfile): Promise<SshSession>;
+    /**
+     * Looks up a session, failing with the list of live ids so the caller can self-correct.
+     *
+     * @throws {Error} If no session matches `sessionId`.
+     */
+    require(sessionId: string): SshSession;
+    close(sessionId: string): boolean;
+    closeAll(): void;
+    list(): SshSessionInfo[];
+    /** Starts the idle sweeper; the timer is unref'd so it never holds the process open. */
+    startIdleSweeper(): void;
+    stopIdleSweeper(): void;
+}
+
+interface RemoteDirectoryListing {
+    entries: SshRemoteEntry[];
+    /** Entries the remote host reported, before the cap was applied. */
+    totalCount: number;
+    truncated: boolean;
+}
+/**
+ * Lists a remote directory, directories first then files, each group alphabetical.
+ *
+ * Capped at `MAX_DIRECTORY_ENTRIES`: this is the one output path with no byte ceiling,
+ * and a spool directory with half a million files would otherwise return megabytes.
+ *
+ * @throws {Error} If the path does not exist or is not readable.
+ */
+declare function listRemoteDirectory(connection: SshConnection, remotePath: string): Promise<RemoteDirectoryListing>;
+interface RemoteFileContent {
+    content: string;
+    /** Size the remote host reported; 0 for virtual files that do not declare one. */
+    sizeBytes: number;
+    /** Bytes actually read. */
+    readBytes: number;
+    truncated: boolean;
+}
+/**
+ * Reads a remote file as UTF-8, stopping after `maxBytes`.
+ *
+ * Oversized files return their leading bytes rather than an error — a 2 GB log is exactly
+ * the case where the first chunk is what you wanted anyway.
+ *
+ * A reported size of 0 does not mean empty: every file under /proc and most of /sys says 0
+ * while holding real content. Those are read unbounded up to `maxBytes` instead of being
+ * range-limited, which previously returned exactly one byte and called it the whole file.
+ *
+ * @throws {Error} If the path is missing, is a directory, or is not readable.
+ */
+declare function readRemoteFile(connection: SshConnection, remotePath: string, maxBytes: number): Promise<RemoteFileContent>;
+/**
+ * Writes UTF-8 text to a remote path, replacing or appending.
+ *
+ * @throws {Error} If the parent directory is missing or the account cannot write there.
+ */
+declare function writeRemoteFile(connection: SshConnection, args: {
+    remotePath: string;
+    content: string;
+    append: boolean;
+}): Promise<number>;
+/**
+ * Uploads a local file with SFTP.
+ *
+ * @returns Bytes transferred.
+ * @throws {Error} If the local file is missing or the remote path is not writable.
+ */
+declare function uploadFile(connection: SshConnection, localPath: string, remotePath: string): Promise<number>;
+/**
+ * Downloads a remote file with SFTP.
+ *
+ * @returns Bytes written locally.
+ * @throws {Error} If the remote file is missing or the local path is not writable.
+ */
+declare function downloadFile(connection: SshConnection, remotePath: string, localPath: string): Promise<number>;
+
+interface SshMcpServerOptions {
+    /** Explicit config path; otherwise `SSH_MCP_CONFIG`, then the home-directory candidates. */
+    configPath?: string;
+}
+interface SshMcpServerInstance {
+    server: McpServer;
+    sessions: SshSessionManager;
+    /** Always the config currently in force, including after a reload. */
+    readonly config: SshMcpConfig;
+    /**
+     * Re-reads the config source and applies it.
+     *
+     * @throws {Error} If the source is now missing or malformed; the previous config
+     *                 stays in force in that case.
+     */
+    reloadConfig(): SshMcpConfig;
+    /** Stops the sweeper and closes every open session. Call before the process exits. */
+    shutdown(): void;
+}
+/**
+ * Builds the MCP server: loads host profiles, wires the session manager, registers tools.
+ *
+ * Transport is deliberately left to the caller — `cli.ts` attaches stdio, tests can attach
+ * an in-memory pair.
+ *
+ * @throws {Error} If a config file exists but is malformed (a bad policy field must not
+ *                 silently degrade into "no guard").
+ */
+declare function createSshMcpServer(options?: SshMcpServerOptions): SshMcpServerInstance;
+
+/**
+ * Loads host profiles from disk.
+ *
+ * A missing config is not an error — the server still starts and reports "no profiles"
+ * through the tools, which is a far clearer signal to the model than a dead server.
+ * A config that exists but is malformed *is* an error: silently ignoring it would let a
+ * typo in a policy field quietly drop a `readonly` guard.
+ *
+ * @throws {Error} If the resolved path is missing, unreadable, not JSON, or fails validation.
+ */
+declare function loadConfig(explicitPath?: string): SshMcpConfig;
+/** Strips every secret so a profile can be described back to the model. */
+declare function toHostSummary(profile: SshHostProfile): SshHostSummary;
+
+/**
+ * Policy knobs, all optional — unset fields fall back to `defaults`, then to the built-ins.
+ *
+ * Strict on purpose. A permissive object *strips* unknown keys, so `readOnly: true`
+ * (capital O) parsed successfully and silently vanished, leaving a host the operator
+ * believed was read-only fully writable. An unknown key must fail startup instead.
+ */
+declare const POLICY_INPUT_SCHEMA: z.ZodObject<{
+    readonly: z.ZodOptional<z.ZodBoolean>;
+    allowSudo: z.ZodOptional<z.ZodBoolean>;
+    execTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxOutputCharacters: z.ZodOptional<z.ZodNumber>;
+    maxReadFileBytes: z.ZodOptional<z.ZodNumber>;
+    allowCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+/** One `hosts` entry: connection fields plus the same policy knobs as an override. */
+declare const HOST_INPUT_SCHEMA: z.ZodObject<{
+    readonly: z.ZodOptional<z.ZodBoolean>;
+    allowSudo: z.ZodOptional<z.ZodBoolean>;
+    execTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+    maxOutputCharacters: z.ZodOptional<z.ZodNumber>;
+    maxReadFileBytes: z.ZodOptional<z.ZodNumber>;
+    allowCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    host: z.ZodString;
+    port: z.ZodOptional<z.ZodNumber>;
+    username: z.ZodString;
+    description: z.ZodOptional<z.ZodString>;
+    privateKeyPath: z.ZodOptional<z.ZodString>;
+    privateKey: z.ZodOptional<z.ZodString>;
+    passphrase: z.ZodOptional<z.ZodString>;
+    passphraseEnv: z.ZodOptional<z.ZodString>;
+    password: z.ZodOptional<z.ZodString>;
+    passwordEnv: z.ZodOptional<z.ZodString>;
+    hostKeyFingerprint: z.ZodOptional<z.ZodString>;
+    defaultCwd: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+declare const CONFIG_INPUT_SCHEMA: z.ZodObject<{
+    $schema: z.ZodOptional<z.ZodString>;
+    defaults: z.ZodOptional<z.ZodObject<{
+        readonly: z.ZodOptional<z.ZodBoolean>;
+        allowSudo: z.ZodOptional<z.ZodBoolean>;
+        execTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        maxOutputCharacters: z.ZodOptional<z.ZodNumber>;
+        maxReadFileBytes: z.ZodOptional<z.ZodNumber>;
+        allowCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    }, z.core.$strict>>;
+    hosts: z.ZodRecord<z.ZodString, z.ZodObject<{
+        readonly: z.ZodOptional<z.ZodBoolean>;
+        allowSudo: z.ZodOptional<z.ZodBoolean>;
+        execTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        connectTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        maxOutputCharacters: z.ZodOptional<z.ZodNumber>;
+        maxReadFileBytes: z.ZodOptional<z.ZodNumber>;
+        allowCommands: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        denyPatterns: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        allowedPaths: z.ZodOptional<z.ZodArray<z.ZodString>>;
+        host: z.ZodString;
+        port: z.ZodOptional<z.ZodNumber>;
+        username: z.ZodString;
+        description: z.ZodOptional<z.ZodString>;
+        privateKeyPath: z.ZodOptional<z.ZodString>;
+        privateKey: z.ZodOptional<z.ZodString>;
+        passphrase: z.ZodOptional<z.ZodString>;
+        passphraseEnv: z.ZodOptional<z.ZodString>;
+        password: z.ZodOptional<z.ZodString>;
+        passwordEnv: z.ZodOptional<z.ZodString>;
+        hostKeyFingerprint: z.ZodOptional<z.ZodString>;
+        defaultCwd: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+type PolicyInput = z.infer<typeof POLICY_INPUT_SCHEMA>;
+type HostInput = z.infer<typeof HOST_INPUT_SCHEMA>;
+type ConfigInput = z.infer<typeof CONFIG_INPUT_SCHEMA>;
+
+/**
+ * Rewrites shell constructs that change how the text tokenizes but not what it runs,
+ * so the rules below see the same command the remote shell will.
+ *
+ * - `\` + newline is a line continuation. POSIX removes it entirely — folding it to a
+ *   space instead would split `r\⏎m` into two words and hide `rm` from every rule, so it
+ *   is removed, and the *canonical* text is what gets executed (see `canonicalizeCommand`).
+ * - `${IFS}` / `$IFS` expand to whitespace, the standard way to write a command with no
+ *   literal spaces in it.
+ */
+declare function normalizeCommandText(command: string): string;
+/**
+ * The exact text that must be sent to the remote shell.
+ *
+ * Validating one string and executing another is a bypass by construction: the guard saw
+ * `r m -rf /` while the host ran `rm -rf /`. Callers run this, then send its result.
+ */
+declare function canonicalizeCommand(command: string): string;
+/**
+ * Splits a command line on `;`, `&&`, `||`, `|`, `&` and newlines, leaving quoted text intact.
+ * `2>&1` keeps its `&` — a `&` directly after `>` is redirection, not a background operator.
+ */
+declare function splitCommandSegments(command: string): string[];
+/**
+ * Drops quoted spans so `echo "a > b"` isn't read as a redirection.
+ *
+ * Quote state is checked *before* the backslash branch: POSIX single quotes take no
+ * escapes, so treating `'x\'` as an escaped quote left the span open and swallowed the
+ * rest of the line — including a real `> /etc/…` redirection.
+ */
+declare function stripQuotedText(segment: string): string;
+/**
+ * Commands nested inside the text: `$(…)`, backticks, and process substitution
+ * `<(…)` / `>(…)`. Each runs as a command in its own right.
+ */
+declare function extractSubstitutions(command: string): string[];
+interface SegmentAnalysis {
+    /** Wrapper binaries preceding the real command, in order — e.g. `["sudo", "env"]`. */
+    wrappers: string[];
+    /** Basename of the binary that actually runs; empty when the segment has no command. */
+    binary: string;
+    /** Flags that follow the binary, unquoted. */
+    flags: string[];
+    /** Non-flag operands that follow the binary, unquoted. */
+    operands: string[];
+    /**
+     * The segment reduced to `<basename> <args…>`, with assignment, redirection, wrapper
+     * and shell-keyword prefixes removed. Rules are `^`-anchored, so they must see the
+     * command at position zero — otherwise `nohup rm -rf /` and `/sbin/reboot` slide past.
+     */
+    normalizedText: string;
+    /** Tokens of the segment, computed once and reused. */
+    tokens: string[];
+}
+/**
+ * Walks past `FOO=bar` assignments, redirection tokens, shell keywords, wrapper binaries,
+ * their flags and their numeric operands (`timeout 30`) to the command that executes.
+ */
+declare function analyzeSegment(segment: string): SegmentAnalysis;
+/**
+ * Decides whether a command may run against a host.
+ *
+ * Ordered cheapest-to-strictest so the reported reason is the most fundamental one:
+ * pipeline-wide disasters → command substitutions → then, per segment, profile deny
+ * patterns → privilege escalation → always-dangerous rules → read-only rules →
+ * allow-list → nested shell payloads.
+ *
+ * **Scope.** This is a mistake-stopper, not a sandbox. It reads the command as text, so
+ * anything that hides the real operation — an interpreter one-liner, an encoded payload,
+ * a tool named something else — runs unexamined, and no amount of pattern-chasing closes
+ * that. The layer that actually contains an agent is the remote account's own permissions.
+ */
+declare function inspectCommand(command: string, policy: SshPolicy, depth?: number): GuardVerdict;
+
+type RemotePathAccess = "read" | "write";
+/**
+ * Decides whether a file tool may touch a remote path.
+ *
+ * With `allowedPaths` set, only absolute paths are accepted: a relative path resolves
+ * against the SFTP session's own working directory, which the guard cannot see, so it
+ * could escape the allow-list without any way to detect it here.
+ *
+ * Symlinks on the remote side are not resolved — the guard has no view of that
+ * filesystem. `allowedPaths` therefore bounds *names*, not inodes.
+ */
+declare function inspectRemotePath(remotePath: string, policy: SshPolicy, access: RemotePathAccess): GuardVerdict;
+/**
+ * Decides whether a file tool may touch a path on the machine running this server.
+ *
+ * Separate from the remote guard because the threat is inverted: here the danger is
+ * reading the operator's own credentials out (upload) or overwriting the files that
+ * define the guards themselves (download).
+ *
+ * @param resolvedLocalPath Absolute path, already `~`-expanded.
+ * @param extraProtectedPaths Runtime-known paths to protect, such as the loaded config file.
+ */
+declare function inspectLocalPath(resolvedLocalPath: string, access: RemotePathAccess, extraProtectedPaths?: string[]): GuardVerdict;
+/**
+ * Decides whether a `cwd` argument is safe to interpolate into the generated `cd` prefix.
+ *
+ * `cwd` never reaches the command guard — it is not a command — yet it lands in the same
+ * remote shell script. Without this check, `cwd: '/tmp"; rm -rf /; #'` executes with every
+ * command guard bypassed.
+ */
+declare function inspectWorkingDirectory(cwd: string): GuardVerdict;
+
+/**
+ * Thrown when a guard refuses an operation.
+ *
+ * A distinct class because callers genuinely branch on it: the tool layer renders a
+ * rejection with `formatGuardRejection` and marks it a policy decision, while any other
+ * error is an operational failure worth retrying. It carries the verdict so that
+ * rendering needs no string parsing.
+ */
+declare class GuardRejectionError extends Error {
+    readonly verdict: GuardVerdict;
+    constructor(verdict: GuardVerdict);
+}
+
+/** Everything the tool handlers share: the loaded profiles and the live sessions. */
+interface ToolContext {
+    config: SshMcpConfig;
+    sessions: SshSessionManager;
+    /**
+     * Re-reads the config source and swaps it in, so `context.config` is always current.
+     * Implemented by the server, which owns the source path.
+     */
+    reloadConfig(): SshMcpConfig;
+}
+
+/** Registers every tool this server exposes, in the order the model should discover them. */
+declare function registerAllTools(server: McpServer, context: ToolContext): void;
+
+type LogLevel = "silent" | "debug" | "info" | "warn" | "error";
+interface Logger {
+    /** Returns a logger that appends `meta` to every record it writes. */
+    child(meta: Record<string, unknown>): Logger;
+    debug(message: string, meta?: Record<string, unknown>): void;
+    info(message: string, meta?: Record<string, unknown>): void;
+    warn(message: string, meta?: Record<string, unknown>): void;
+    error(error: unknown, message: string, meta?: Record<string, unknown>): void;
+}
+declare const $logger: Logger;
+
+/** Env var holding an explicit config file path. */
+declare const CONFIG_PATH_ENV = "SSH_MCP_CONFIG";
+/** Env var overriding the stderr log level ("debug" | "info" | "warn" | "error" | "silent"). */
+declare const LOG_LEVEL_ENV = "SSH_MCP_LOG_LEVEL";
+declare const SERVER_NAME = "akms-ssh";
+declare const SERVER_VERSION = "0.0.1";
+
+export { $logger, CONFIG_INPUT_SCHEMA, CONFIG_PATH_ENV, type ConfigInput, GuardRejectionError, type GuardVerdict, HOST_INPUT_SCHEMA, type HostInput, LOG_LEVEL_ENV, type LogLevel, type Logger, POLICY_INPUT_SCHEMA, type PolicyInput, type RemoteDirectoryListing, type RemoteFileContent, type RemotePathAccess, SERVER_NAME, SERVER_VERSION, type SegmentAnalysis, SshConnection, type SshExecOptions, type SshExecResult, type SshHostProfile, type SshHostSummary, type SshMcpConfig, type SshMcpServerInstance, type SshMcpServerOptions, type SshPolicy, type SshRemoteEntry, SshSession, type SshSessionInfo, SshSessionManager, type ToolContext, analyzeSegment, canonicalizeCommand, createSshMcpServer, downloadFile, extractSubstitutions, inspectCommand, inspectLocalPath, inspectRemotePath, inspectWorkingDirectory, listRemoteDirectory, loadConfig, normalizeCommandText, readRemoteFile, registerAllTools, splitCommandSegments, stripQuotedText, toHostSummary, uploadFile, writeRemoteFile };