ssh-mcp 1.5.0 → 2.0.1

package/build/tools/pipeline.js

@@ -0,0 +1,185 @@
+import { tracer } from '../observability/tracer.js';
+import { sanitizeCommand } from '../guard/sanitizer.js';
+import { requestApproval } from '../guard/elicitation.js';
+import { commandOutput } from './results.js';
+import { CommandQuota } from '../policy/quota.js';
+import { ApprovalGrants } from '../guard/approval-grants.js';
+/** Policy never ran — the input was rejected at the boundary. */
+function rejectedEvaluation(commandClass) {
+    return { decision: 'deny', commandClass, binary: '', ruleId: 'input-rejected' };
+}
+/**
+ * Carries the policy decision that caused a refusal, so the audit record shows
+ * the real rule and class instead of a synthetic placeholder.
+ */
+export class PolicyRefusedError extends Error {
+    evaluation;
+    constructor(message, evaluation) {
+        super(message);
+        this.evaluation = evaluation;
+        this.name = 'PolicyRefusedError';
+    }
+}
+/**
+ * Builds the audited execution pipeline every tool handler runs through.
+ *
+ * A factory rather than free functions because the pipeline closes over the
+ * server (approval prompts), registry (connections and profiles), policy engine
+ * and audit store. Tool groups receive the result and never touch those four
+ * directly, so there is exactly one path from caller input to a remote command.
+ */
+export function createPipeline({ server, registry, policy, audit, approvalGrantTtlMs = 0 }) {
+    const quota = new CommandQuota();
+    const grants = new ApprovalGrants(approvalGrantTtlMs);
+    async function resolveConn(profileName) {
+        return registry.getOrCreate(profileName);
+    }
+    async function checkPolicyAndApprove(command, profileName, toolName) {
+        const span = tracer.startSpan('policy.evaluate');
+        span.setAttribute('tool.name', toolName);
+        span.setAttribute('ssh.profile', profileName);
+        try {
+            const conn = await resolveConn(profileName);
+            const evaluation = await policy.evaluateWithOpa(command, conn.profile, toolName);
+            span.setAttribute('policy.decision', evaluation.decision);
+            span.setAttribute('command.class', evaluation.commandClass);
+            span.setAttribute('command.binary', evaluation.binary);
+            if (evaluation.decision === 'deny') {
+                throw new PolicyRefusedError(`POLICY_DENIED: ${evaluation.reason || 'Command not allowed'}`, evaluation);
+            }
+            if (evaluation.decision === 'require-approval') {
+                // A live grant from an earlier explicit approval of this exact command.
+                if (grants.has(conn.profile.name, command, evaluation.commandClass)) {
+                    span.setAttribute('policy.grant', 'reused');
+                    return { conn, evaluation, approver: 'jit-grant' };
+                }
+                const approval = await requestApproval(server, command, conn.profile.name, evaluation);
+                if (!approval.approved) {
+                    throw new PolicyRefusedError('APPROVAL_DENIED: User did not approve this command', evaluation);
+                }
+                grants.record(conn.profile.name, command, evaluation.commandClass);
+                return { conn, evaluation, approver: approval.approver };
+            }
+            return { conn, evaluation, approver: undefined };
+        }
+        finally {
+            span.end();
+        }
+    }
+    async function auditResult(ctx, profileName, command, evaluation, result, approver) {
+        await audit.record({
+            mcpRequestId: ctx.requestId,
+            profile: profileName,
+            user: registry.getProfile(profileName).user,
+            command,
+            commandClass: evaluation.commandClass,
+            binary: evaluation.binary,
+            decision: evaluation.decision,
+            ruleId: evaluation.ruleId,
+            exitCode: 'exitCode' in result ? result.exitCode : undefined,
+            durationMs: 'durationMs' in result ? result.durationMs : undefined,
+            error: 'error' in result ? result.error : undefined,
+            approver,
+        });
+    }
+    function makeCtx(extra, profile, session) {
+        return { requestId: extra?.requestId ?? 0, profile, session };
+    }
+    /**
+     * Audit a failed tool call with the real policy decision when there was one.
+     *
+     * Never throws: an audit write error must not replace the error the caller
+     * actually needs to see (and on the success path, must not make an agent
+     * think a non-idempotent command failed after it already ran).
+     */
+    async function auditFailure(ctx, profileName, state, failureClass, err) {
+        const evaluation = (err instanceof PolicyRefusedError ? err.evaluation : undefined)
+            ?? state.evaluation
+            ?? rejectedEvaluation(failureClass);
+        try {
+            await auditResult(ctx, profileName, state.command, evaluation, {
+                error: err?.message ?? String(err),
+            });
+        }
+        catch (auditErr) {
+            console.error('Audit write failed while recording a tool failure:', auditErr);
+        }
+    }
+    function defaultProfileName(profile) {
+        return profile || registry.getProfile().name;
+    }
+    function makeProgressSender(extra) {
+        const token = extra?._meta?.progressToken;
+        if (token === undefined)
+            return undefined;
+        return (bytes, tail) => {
+            extra.sendNotification({
+                method: 'notifications/progress',
+                params: { progressToken: token, progress: bytes, message: tail },
+            }).catch(() => { });
+        };
+    }
+    /**
+     * The one place the sanitize → policy → approve → run → audit pipeline lives.
+     *
+     * Five of the six audited handlers used to inline their own copy of this, and
+     * they had already drifted apart: one dropped abort/progress support, one
+     * audited a different command string on success than on failure, one carried
+     * a dead `?? command` fallback. Every audit-semantics fix had to be made six
+     * times, so they were never all correct at once.
+     */
+    async function runAudited(command, opts, run) {
+        const ctx = makeCtx(opts.extra, opts.profile, opts.session);
+        const profileName = defaultProfileName(opts.profile);
+        const profile = registry.getProfile(profileName);
+        const onProgress = makeProgressSender(opts.extra);
+        const abortSignal = opts.extra?.signal;
+        // Sanitization runs inside the try so a rejected (empty, control-char-only,
+        // over-length) command still leaves an audit trail — a client probing with
+        // malformed payloads used to leave none.
+        const state = { command };
+        try {
+            let effective = opts.synthetic ? command : sanitizeCommand(command, profile.maxChars);
+            state.command = effective;
+            opts.preCheck?.(effective);
+            if (opts.wrap) {
+                effective = opts.wrap(effective);
+                state.command = effective;
+            }
+            const { conn, evaluation, approver } = await checkPolicyAndApprove(effective, profileName, opts.toolName);
+            state.evaluation = evaluation;
+            if (opts.enforceClass && evaluation.commandClass !== opts.enforceClass) {
+                throw new Error(`${opts.toolName} only accepts ${opts.enforceClass} commands, got: ${evaluation.commandClass}`);
+            }
+            // Counted after the policy allowed it and before it runs: a denied
+            // command should not burn quota, and an allowed one should be counted
+            // even if it later fails on the host — the work was still spent.
+            const budget = quota.consume(profileName, profile.commandQuotaPerDay);
+            if (!budget.allowed) {
+                throw new PolicyRefusedError(`QUOTA_EXCEEDED: profile "${profileName}" has used its ${profile.commandQuotaPerDay} commands ` +
+                    `for the last 24h. Next slot frees at ${budget.retryAt?.toISOString()}.`, { ...evaluation, decision: 'deny', ruleId: 'command-quota' });
+            }
+            const { audited, output } = await run({
+                conn, command: effective, profileName, onProgress, abortSignal, extra: opts.extra,
+            });
+            await auditResult(ctx, profileName, effective, evaluation, audited, approver);
+            return output;
+        }
+        catch (err) {
+            await auditFailure(ctx, profileName, state, opts.failureClass, err);
+            throw err;
+        }
+    }
+    /** Run a command over the connection and report it verbatim to the client. */
+    function execAndReport(opts = {}) {
+        return async (rt) => {
+            const audited = await rt.conn.exec(rt.command, {
+                stdin: opts.stdin,
+                onProgress: rt.onProgress,
+                abortSignal: rt.abortSignal,
+            });
+            return { audited, output: commandOutput(audited) };
+        };
+    }
+    return { runAudited, execAndReport, defaultProfileName, makeCtx, auditResult, auditFailure, resolveConn, quota, grants };
+}

package/build/tools/registry.js

@@ -0,0 +1,23 @@
+import { createPipeline } from './pipeline.js';
+import { registerSessionTools } from './session-tools.js';
+import { registerCommandTools } from './command-tools.js';
+import { registerFileTools } from './file-tools.js';
+// Re-exported so existing importers keep a single entry point for the tool layer.
+export { TOOL_DESCRIPTIONS, getToolHashes } from './descriptions.js';
+export { registerResources } from './resources.js';
+/**
+ * Wire every MCP tool onto the server.
+ *
+ * The handlers live in three groups by subject (sessions, commands, files) and
+ * share one audited pipeline, built here. Splitting them up is what keeps the
+ * pipeline the only route from caller input to a remote command: a handler that
+ * wanted to bypass policy or audit would have to reach past `pipeline` for the
+ * registry, which it is not given.
+ */
+export function registerTools(server, registry, policy, audit, opts = {}) {
+    const deps = { server, registry, policy, audit, ...opts };
+    const pipeline = createPipeline(deps);
+    registerSessionTools(deps, pipeline);
+    registerCommandTools(deps, pipeline);
+    registerFileTools(deps, pipeline);
+}

package/build/tools/resources.js

@@ -0,0 +1,73 @@
+import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+export function registerResources(server, registry) {
+    function jsonResource(uri, data) {
+        return {
+            contents: [{
+                    uri,
+                    mimeType: 'application/json',
+                    text: JSON.stringify(data, null, 2),
+                }],
+        };
+    }
+    server.resource('connections', 'ssh://connections', { description: 'List all SSH profiles and their connection status', mimeType: 'application/json' }, async () => {
+        const connections = registry.listConnections();
+        const profiles = registry.listAllProfiles().map((p) => {
+            const conn = connections.find((c) => c.profile === p.name);
+            return {
+                name: p.name,
+                host: p.host,
+                port: p.port,
+                user: p.user,
+                role: p.role,
+                readOnly: p.readOnly,
+                approvalPolicy: p.approvalPolicy,
+                status: conn?.status || 'disconnected',
+                sessions: conn?.sessionCount || 0,
+            };
+        });
+        return jsonResource('ssh://connections', { profiles });
+    });
+    server.resource('profile', new ResourceTemplate('ssh://connections/{profile}', { list: undefined }), { description: 'Get details for a specific SSH profile', mimeType: 'application/json' }, async (uri, variables) => {
+        const profileName = variables.profile;
+        const profile = registry.listAllProfiles().find((p) => p.name === profileName);
+        if (!profile) {
+            return jsonResource(uri.href, { error: `Profile "${profileName}" not found` });
+        }
+        const conn = registry.get(profileName);
+        const sessions = conn?.listSessions().map((s) => s.toInfo()) || [];
+        return jsonResource(uri.href, {
+            profile: {
+                name: profile.name,
+                host: profile.host,
+                port: profile.port,
+                user: profile.user,
+                role: profile.role,
+                readOnly: profile.readOnly,
+                auth: profile.auth,
+                approvalPolicy: profile.approvalPolicy,
+                via: profile.via,
+                workdir: profile.workdir,
+                tty: profile.tty,
+                timeout: profile.timeout,
+                maxChars: profile.maxChars,
+                sessionMaxPerConnection: profile.sessionMaxPerConnection,
+                sessionIdleTimeoutMs: profile.sessionIdleTimeoutMs,
+            },
+            connection: conn?.toInfo() || null,
+            sessions,
+        });
+    });
+    server.resource('session', new ResourceTemplate('ssh://sessions/{profile}/{session}', { list: undefined }), { description: 'Get metadata for a specific session', mimeType: 'application/json' }, async (uri, variables) => {
+        const profileName = variables.profile;
+        const sessionName = variables.session;
+        const conn = registry.get(profileName);
+        if (!conn) {
+            return jsonResource(uri.href, { error: `Profile "${profileName}" not connected` });
+        }
+        const session = conn.getSession(sessionName);
+        if (!session) {
+            return jsonResource(uri.href, { error: `Session "${sessionName}" not found on ${profileName}` });
+        }
+        return jsonResource(uri.href, session.toInfo());
+    });
+}

package/build/tools/results.js

@@ -0,0 +1,31 @@
+import { redactText } from '../guard/redactor.js';
+export function syntheticSuccess(profile) {
+    return { exitCode: 0, stdout: '', stderr: '', durationMs: 0, profile };
+}
+export function textResult(text) {
+    return { content: [{ type: 'text', text }] };
+}
+/**
+ * Render a CommandResult for the client. A non-zero exit (or a kill signal)
+ * is reported as isError with the redacted stderr and the exit status, so a
+ * failed remote command cannot be mistaken for an empty success.
+ */
+export function commandOutput(result) {
+    // ssh2 reports exitCode null when the process died from a signal.
+    const failed = result.exitCode !== 0 || Boolean(result.signal);
+    // entropyScan matches the SFTP and session-output paths. Without it a plain
+    // `env` dump hands high-entropy secrets straight to the model, since the
+    // regex layer only knows a fixed set of token shapes.
+    const stdout = redactText(result.stdout, { entropyScan: true });
+    const stderr = redactText(result.stderr, { entropyScan: true });
+    const parts = [];
+    if (stdout)
+        parts.push(stdout);
+    if (stderr)
+        parts.push(`[stderr]\n${stderr}`);
+    if (failed) {
+        parts.push(result.signal ? `[killed by SIG${result.signal}]` : `[exit ${result.exitCode}]`);
+    }
+    const content = [{ type: 'text', text: parts.join('\n\n') }];
+    return failed ? { content, isError: true } : { content };
+}

package/build/tools/session-tools.js

@@ -0,0 +1,97 @@
+import { z } from 'zod';
+import { sanitizeSessionName } from '../guard/sanitizer.js';
+import { redactText } from '../guard/redactor.js';
+import { BackgroundSession } from '../ssh/session.js';
+import { TOOL_DESCRIPTIONS as D } from './descriptions.js';
+import { syntheticSuccess, textResult } from './results.js';
+/** Connection and session discovery/lifecycle tools. */
+export function registerSessionTools({ server, registry }, pipeline) {
+    const { runAudited, resolveConn } = pipeline;
+    // ─── list-connections ──────────────────────────────────────────────────
+    server.tool('list-connections', D["list-connections"], {}, { readOnlyHint: true }, async () => {
+        const connections = registry.listConnections();
+        const profiles = registry.listAllProfiles();
+        const lines = profiles.map((p) => {
+            const conn = connections.find((c) => c.profile === p.name);
+            const status = conn?.status || 'disconnected';
+            const sessions = conn?.sessionCount || 0;
+            return `${p.name}: ${p.user}@${p.host}:${p.port} [${status}] sessions=${sessions} role=${p.role}`;
+        });
+        return textResult(lines.join('\n'));
+    });
+    // ─── list-sessions ─────────────────────────────────────────────────────
+    server.tool('list-sessions', D["list-sessions"], { profile: z.string().optional().describe('Profile name (uses default if omitted)') }, { readOnlyHint: true }, async ({ profile }) => {
+        const conn = registry.get(profile);
+        if (!conn || conn.listSessions().length === 0) {
+            return textResult('No active sessions.');
+        }
+        const sessions = conn.listSessions().map((s) => {
+            const info = s.toInfo();
+            return `${info.name} [${info.type}] status=${info.status} idle=${Math.round((Date.now() - info.lastActivity.getTime()) / 1000)}s`;
+        });
+        return textResult(sessions.join('\n'));
+    });
+    // ─── open-session ──────────────────────────────────────────────────────
+    server.tool('open-session', D["open-session"], {
+        name: z.string().describe('Session name (alphanumeric, dash, underscore, max 64 chars)'),
+        type: z.enum(['interactive', 'background']).default('interactive').describe('Session type'),
+        command: z.string().optional().describe('Command for background sessions'),
+        profile: z.string().optional().describe('Profile name (uses default if omitted)'),
+    }, 
+    // No annotations object here on purpose. The SDK's overload resolution
+    // treats an EMPTY object as a Zod raw shape (isZodRawShape returns true for
+    // `{}`), so passing `{}` in the annotations slot made it consume the
+    // callback slot instead — leaving this tool registered with no handler and
+    // failing every call with "cb is not a function".
+    async ({ name, type, command, profile }, extra) => {
+        const cleanName = sanitizeSessionName(name);
+        const isBackground = type === 'background' && Boolean(command);
+        // A background session runs a caller-supplied command, so that command is
+        // what policy must evaluate. An interactive session runs no command yet,
+        // but opening a stateful shell is still a lifecycle event worth auditing
+        // — that branch used to produce no record at all.
+        return runAudited(isBackground ? command : `session:open ${type} ${cleanName}`, {
+            toolName: 'open-session',
+            failureClass: isBackground ? 'destructive' : 'safe',
+            profile,
+            session: cleanName,
+            extra,
+            synthetic: !isBackground,
+        }, async (rt) => {
+            await rt.conn.openSession({
+                name: cleanName,
+                type,
+                command: isBackground ? rt.command : command,
+            });
+            return {
+                audited: syntheticSuccess(rt.profileName),
+                output: textResult(`Session "${cleanName}" opened on ${rt.conn.profile.name} (${type}).`),
+            };
+        });
+    });
+    // ─── close-session ─────────────────────────────────────────────────────
+    server.tool('close-session', D["close-session"], {
+        name: z.string().describe('Session name to close'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { destructiveHint: true }, async ({ name, profile }) => {
+        const conn = await resolveConn(profile);
+        await conn.closeSession(name);
+        return textResult(`Session "${name}" closed.`);
+    });
+    // ─── read-session-output ───────────────────────────────────────────────
+    server.tool('read-session-output', D["read-session-output"], {
+        name: z.string().describe('Background session name'),
+        lines: z.number().optional().default(50).describe('Number of recent lines to read'),
+        profile: z.string().optional().describe('Profile name'),
+    }, { readOnlyHint: true }, async ({ name, lines, profile }) => {
+        const conn = await resolveConn(profile);
+        const session = conn.getSession(name);
+        if (!session || session.type !== 'background') {
+            return textResult(`Background session "${name}" not found.`);
+        }
+        if (session instanceof BackgroundSession) {
+            return textResult(redactText(session.readOutput(lines), { entropyScan: true }));
+        }
+        return textResult(`Session "${name}" is not a background session.`);
+    });
+}

package/build/transport/http.js

@@ -0,0 +1,237 @@
+import { createServer } from 'http';
+import { randomUUID, timingSafeEqual } from 'crypto';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import { isInitializeRequest } from '@modelcontextprotocol/sdk/types.js';
+import { SERVER_VERSION } from '../version.js';
+const MAX_BODY_SIZE = 1_048_576; // 1MB
+/** Cap on concurrent MCP sessions, so unauthenticated-adjacent churn can't grow the map without bound. */
+const MAX_SESSIONS = 64;
+class RateLimiter {
+    tokens;
+    lastRefill;
+    maxTokens;
+    refillIntervalMs;
+    constructor(maxRequestsPerMinute) {
+        this.maxTokens = maxRequestsPerMinute;
+        this.tokens = maxRequestsPerMinute;
+        this.lastRefill = Date.now();
+        this.refillIntervalMs = 60_000;
+    }
+    tryConsume() {
+        const now = Date.now();
+        const elapsed = now - this.lastRefill;
+        const refilled = Math.floor((elapsed / this.refillIntervalMs) * this.maxTokens);
+        if (refilled > 0) {
+            this.tokens = Math.min(this.maxTokens, this.tokens + refilled);
+            this.lastRefill += Math.round((refilled / this.maxTokens) * this.refillIntervalMs);
+        }
+        if (this.tokens > 0) {
+            this.tokens--;
+            return { allowed: true, retryAfterMs: 0 };
+        }
+        const retryAfterMs = Math.ceil(this.refillIntervalMs / this.maxTokens);
+        return { allowed: false, retryAfterMs };
+    }
+}
+function jsonRpcError(res, status, code, message) {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code, message }, id: null }));
+}
+/**
+ * @param createMcpServer Builds a fresh McpServer per MCP session. An McpServer
+ *   binds to exactly one transport, so a shared instance would let only the
+ *   first client initialize — and would stay unusable after that client left.
+ */
+export async function startHttpServer(createMcpServer, opts) {
+    const { port, host = '127.0.0.1', bearerToken, registry } = opts;
+    if (!bearerToken) {
+        throw new Error('HTTP transport requires --bearerToken. Example: --transport=http --bearerToken=secret\n' +
+            'Without authentication, any network client can execute SSH commands on your hosts.');
+    }
+    const rateLimiter = opts.rateLimit && opts.rateLimit > 0
+        ? new RateLimiter(opts.rateLimit)
+        : null;
+    // DNS rebinding: a page the user visits can make their browser POST to a
+    // localhost server, and the bearer token does not help if the browser is
+    // tricked into attaching it. Validating the Host header is what stops it.
+    // GHSA-w48q-cv73-mx4w is exactly this, and the SDK leaves it to the caller.
+    const allowedHosts = opts.allowedHosts?.length
+        ? opts.allowedHosts
+        : [`${host}:${port}`, `localhost:${port}`, `127.0.0.1:${port}`, `[::1]:${port}`];
+    const transports = new Map();
+    /** Route to the session's transport, or start a new session on `initialize`. */
+    async function resolveTransport(req, res, parsedBody) {
+        const sessionId = req.headers['mcp-session-id'];
+        if (sessionId) {
+            const existing = transports.get(sessionId);
+            if (existing)
+                return existing;
+            jsonRpcError(res, 404, -32001, 'Session not found or expired. Re-initialize to obtain a new session.');
+            return null;
+        }
+        const body = Array.isArray(parsedBody) ? parsedBody : [parsedBody];
+        if (!body.some((m) => isInitializeRequest(m))) {
+            jsonRpcError(res, 400, -32000, 'Missing mcp-session-id header. Send an initialize request first.');
+            return null;
+        }
+        if (transports.size >= MAX_SESSIONS) {
+            jsonRpcError(res, 503, -32000, `Server is at its session limit (${MAX_SESSIONS}). Close an existing session and retry.`);
+            return null;
+        }
+        const transport = new StreamableHTTPServerTransport({
+            sessionIdGenerator: () => randomUUID(),
+            enableDnsRebindingProtection: true,
+            allowedHosts,
+            onsessioninitialized: (id) => { transports.set(id, transport); },
+            onsessionclosed: (id) => { transports.delete(id); },
+        });
+        // Covers transport teardown that isn't a DELETE (client disconnect, error).
+        transport.onclose = () => {
+            if (transport.sessionId)
+                transports.delete(transport.sessionId);
+        };
+        const mcp = await createMcpServer();
+        await mcp.connect(transport);
+        return transport;
+    }
+    const httpServer = createServer(async (req, res) => {
+        const url = new URL(req.url || '/', `http://${req.headers.host}`);
+        // Liveness probes are conventionally unauthenticated, and the README lists
+        // /health without an auth caveat. It exposes nothing beyond "process is up".
+        const isHealthProbe = req.method === 'GET' && url.pathname === '/health';
+        if (!isHealthProbe) {
+            const auth = req.headers.authorization || '';
+            const expected = `Bearer ${bearerToken}`;
+            const authBuf = Buffer.from(auth);
+            const expectedBuf = Buffer.from(expected);
+            const match = authBuf.length === expectedBuf.length &&
+                timingSafeEqual(authBuf, expectedBuf);
+            if (!match) {
+                // RFC 7235: a 401 must say how to authenticate. MCP clients also parse
+                // JSON-RPC envelopes on this route, so 401 speaks the same dialect as
+                // the 429 and 413 responses rather than a bare {error}.
+                res.writeHead(401, {
+                    'Content-Type': 'application/json',
+                    'WWW-Authenticate': 'Bearer realm="ssh-mcp"',
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: { code: -32001, message: 'Unauthorized' },
+                    id: null,
+                }));
+                return;
+            }
+        }
+        if (rateLimiter && url.pathname === '/' && (req.method === 'POST' || req.method === 'GET' || req.method === 'DELETE')) {
+            const { allowed, retryAfterMs } = rateLimiter.tryConsume();
+            if (!allowed) {
+                const retryAfterSec = Math.ceil(retryAfterMs / 1000);
+                res.writeHead(429, {
+                    'Content-Type': 'application/json',
+                    'Retry-After': String(retryAfterSec),
+                });
+                res.end(JSON.stringify({
+                    jsonrpc: '2.0',
+                    error: {
+                        code: -32604,
+                        message: `Rate limit exceeded. Retry after ${retryAfterSec}s.`,
+                    },
+                }));
+                return;
+            }
+        }
+        if (req.method === 'POST' && url.pathname === '/') {
+            let body = '';
+            let bodyTooLarge = false;
+            req.on('data', (chunk) => {
+                body += chunk;
+                if (body.length > MAX_BODY_SIZE) {
+                    if (!bodyTooLarge) {
+                        bodyTooLarge = true;
+                        // Connection: close is load-bearing, not cosmetic. Without it a
+                        // keep-alive client (Node's default agent since v19) returns this
+                        // socket to its pool, and the destroy below then kills the pooled
+                        // socket — so the client's *next* request fails with EPIPE.
+                        res.writeHead(413, {
+                            'Content-Type': 'application/json',
+                            'Connection': 'close',
+                        });
+                        // Destroy only once the 413 has flushed; destroying immediately
+                        // races the response and the client sees a bare connection reset
+                        // instead of the status telling it what went wrong.
+                        res.end(JSON.stringify({
+                            jsonrpc: '2.0',
+                            error: { code: -32600, message: 'Request body too large (max 1MB)' },
+                            id: null,
+                        }), () => req.destroy());
+                    }
+                }
+            });
+            req.on('end', async () => {
+                if (bodyTooLarge)
+                    return;
+                let parsed;
+                try {
+                    parsed = JSON.parse(body);
+                }
+                catch {
+                    jsonRpcError(res, 400, -32700, 'Parse error: invalid JSON');
+                    return;
+                }
+                const transport = await resolveTransport(req, res, parsed);
+                if (!transport)
+                    return;
+                await transport.handleRequest(req, res, parsed);
+            });
+            return;
+        }
+        if ((req.method === 'GET' || req.method === 'DELETE') && url.pathname === '/') {
+            const transport = await resolveTransport(req, res);
+            if (!transport)
+                return;
+            await transport.handleRequest(req, res);
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/status') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'running',
+                version: SERVER_VERSION,
+                connections: registry.listConnections(),
+                profiles: registry.listAllProfiles().map((p) => ({
+                    name: p.name,
+                    host: p.host,
+                    user: p.user,
+                    role: p.role,
+                    readOnly: p.readOnly,
+                })),
+            }));
+            return;
+        }
+        if (req.method === 'GET' && url.pathname === '/health') {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ healthy: true }));
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: 'Not found' }));
+    });
+    // Previously listen() had no error handler, so EADDRINUSE surfaced as an
+    // unhandled 'error' event and a raw stack — and startHttpServer resolved
+    // immediately regardless, so the caller carried on as if the server was up.
+    await new Promise((resolve, reject) => {
+        httpServer.once('error', (err) => {
+            reject(err.code === 'EADDRINUSE'
+                ? new Error(`Cannot bind ${host}:${port} — address already in use.`)
+                : err);
+        });
+        httpServer.listen(port, host, () => {
+            console.error(`SSH MCP Server v2 (HTTP) listening on http://${host}:${port}`);
+            console.error('Endpoints: POST / (MCP), GET /status, GET /health');
+            if (rateLimiter) {
+                console.error(`Rate limit: ${opts.rateLimit} req/min`);
+            }
+            resolve();
+        });
+    });
+}

package/build/types.js

@@ -0,0 +1,2 @@
+// ─── Config Types ───────────────────────────────────────────────────────────
+export {};

package/build/version.js

@@ -0,0 +1,9 @@
+import { createRequire } from 'module';
+const require = createRequire(import.meta.url);
+/**
+ * Single source of truth for the version reported over MCP (`initialize`) and
+ * on `GET /status`. Read from package.json at runtime so a changesets release
+ * bump can't leave hardcoded literals behind, disagreeing with the installed
+ * package. Resolves to the repo root from both `src/` and `build/`.
+ */
+export const SERVER_VERSION = require('../package.json').version;