ssh-mcp 2.3.4 → 2.4.0

package/README.md

@@ -23,6 +23,10 @@ npm install -g ssh-mcp
 
 ### 2. Configure
 
+Without a config the server still starts, so a client or directory can complete the MCP
+handshake and read `tools/list` — but **every tool call is refused** until you configure it,
+with a message naming the path below. Nothing runs on a host until this step is done.
+
 Create the config file at the path for your platform:
 
 | Platform | Path |
@@ -98,6 +102,12 @@ nothing. Neither combination leaves you without an exit, which is the lesson of
 A supervisor that treats any non-zero status as a failure needs no change. One
 that matched on `1` to detect a startup problem should match on `2` as well.
 
+Starting with nothing configured is **not** an exit-2 condition, as of the release that
+added introspection without a config: the server starts so it can be described, and
+refuses each tool call instead. A supervisor that used a non-zero exit to catch an
+unconfigured deployment should watch for `starting unconfigured` on stderr, or read
+`configured` from `GET /health` when running the HTTP transport.
+
 ### 3. Set credentials via environment variables
 
 ```bash
@@ -565,6 +575,12 @@ ssh-mcp --transport=http --httpPort=3000 --bearerToken=secret --rateLimit=60
 
 Endpoints: `POST /` (MCP Streamable HTTP), `GET /status`, `GET /health`
 
+`GET /health` answers `{"healthy": true, "configured": <bool>}`. It stays `200` either way —
+`healthy` is liveness — while `configured` is false when no profile is set, which is the
+case of a config bind mount that silently did not attach: the server binds the port and
+refuses every tool call. `GET /status` carries the profile list itself and stays behind the
+bearer token.
+
 When rate limit is exceeded, the server returns HTTP 429 with `Retry-After` header and a JSON-RPC error body so MCP clients can handle it gracefully.
 
 **Always terminate TLS at a reverse proxy** (Caddy/nginx). The server listens on `127.0.0.1` only.

package/build/cli.js

@@ -14,8 +14,23 @@
  * escape the boot gate to be testable.
  */
 import { loadConfig, getConfigPath } from './config/loader.js';
-import { OperatorError, ConfigNotFoundError } from './errors.js';
+import { OperatorError, ConfigNotFoundError, UnconfiguredError } from './errors.js';
 import { HOST_GROUPS } from './policy/engine.js';
+/**
+ * Whether the operator asked for a quick start at all.
+ *
+ * Presence, not truthiness — the same #91 trap `flagEnabled` was written for. `parseArgv`
+ * stores `null` for a flag written without `=` and drops bare words, so all three of
+ * `--host example.com --user root` (space instead of `=`, the commonest slip), `--host`
+ * alone, and `--host= --user=` (a wrapper interpolating unset env vars) produce falsy
+ * values while the flags were plainly given. Testing truthiness sent every one of them
+ * down the soft path: a server that starts and looks healthy, with the explanation only
+ * on a stderr stream an MCP client typically swallows. Only "asked for nothing" softens;
+ * a half-given or empty-valued quick start is a typo and still refuses.
+ */
+function nothingRequested(argv) {
+    return !('host' in argv) && !('user' in argv);
+}
 export function parseArgv(args = process.argv.slice(2)) {
     const config = {};
     for (const arg of args) {
@@ -120,6 +135,26 @@ export function resolveHostGroup(argv) {
     // operator would read the refusal as policy rather than as their own slip.
     throw new OperatorError(`Invalid --group=${group}. Expected one of: ${HOST_GROUPS.join(', ')}.`);
 }
+/**
+ * The defaults a quick-start profile inherits, from flags alone.
+ *
+ * Named because an unconfigured start needs them too — `approvalGrantTtlMs` is read while
+ * wiring the tools, long before any profile exists, so the two paths have to agree.
+ */
+export function defaultsFromArgv(argv) {
+    return {
+        sessionMaxPerConnection: parseInt(argv.sessionMax) || 5,
+        sessionIdleTimeoutMs: parseInt(argv.sessionTtl) || 600_000,
+        sessionBackgroundMaxMs: 3_600_000,
+        commandTimeoutMs: parseInt(argv.timeout) || 60_000,
+        commandMaxChars: parseMaxChars(argv.maxChars),
+        commandMaxOutputBytes: 1_048_576,
+        connectionIdleReapMs: 900_000,
+        commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
+        approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
+        approvalMode: 'ask-destructive',
+    };
+}
 export async function buildAppConfig(argv) {
     // The way past an ACL that could not be read, rather than an operator with no
     // exit. See assertPrivateOnWindows.
@@ -176,25 +211,28 @@ export async function buildAppConfig(argv) {
         if (!(err instanceof ConfigNotFoundError))
             throw err;
     }
+    // Nothing configured, and nothing named on the command line either. Start anyway, with
+    // no profiles: an MCP client or directory can then complete the handshake and read
+    // `tools/list`, and every tool call is refused by `ConnectionRegistry` with the message
+    // below — including `list-connections`, which resolves no profile and so had to be told.
+    //
+    // Measured before this: `initialize` and `tools/list` against our own image drew no
+    // JSON-RPC response at all — the process exited on this check first — so every directory
+    // and every "add this server" flow saw a crash. Tool definitions are static metadata and
+    // the config decides what they may *reach*, so coupling the two bought no safety.
+    //
+    // A half-given quick start is not this case: `--host` without `--user` is a typo, and an
+    // explicit `--config` that points nowhere already threw above. Only "configured nothing"
+    // softens — see `nothingRequested`, which tests for the flags being absent rather than
+    // falsy so that a valueless or space-separated one stays a typo.
+    if (nothingRequested(argv)) {
+        console.error(`Warning: starting unconfigured — every tool call will be refused.\n${new UnconfiguredError(getConfigPath()).message}`);
+        return { defaults: defaultsFromArgv(argv), profiles: [] };
+    }
     if (!argv.host || !argv.user) {
-        throw new OperatorError('No config file found and missing required --host/--user.\n' +
-            // Was hardcoded to ~/.config/ssh-mcp/config.toml on every platform, so on
-            // Windows and macOS it named a path this code never reads.
-            `Either create a config file at ${getConfigPath()} or pass --config <path>.\n` +
-            'For quick start: --host=<host> --user=<user> (credentials via env vars).');
+        throw new UnconfiguredError(getConfigPath());
     }
-    const defaults = {
-        sessionMaxPerConnection: parseInt(argv.sessionMax) || 5,
-        sessionIdleTimeoutMs: parseInt(argv.sessionTtl) || 600_000,
-        sessionBackgroundMaxMs: 3_600_000,
-        commandTimeoutMs: parseInt(argv.timeout) || 60_000,
-        commandMaxChars: parseMaxChars(argv.maxChars),
-        commandMaxOutputBytes: 1_048_576,
-        connectionIdleReapMs: 900_000,
-        commandQuotaPerDay: parseInt(argv.commandQuota) || 0,
-        approvalGrantTtlMs: parseInt(argv.approvalGrantTtl) || 0,
-        approvalMode: 'ask-destructive',
-    };
+    const defaults = defaultsFromArgv(argv);
     const profile = {
         name: 'default',
         host: argv.host,

package/build/config/loader.js

@@ -3,7 +3,7 @@ import { homedir, platform } from 'os';
 import { join, dirname } from 'path';
 import { parse as parseTOML } from 'smol-toml';
 import { configSchema } from './schema.js';
-import { OperatorError, ConfigNotFoundError } from '../errors.js';
+import { OperatorError, ConfigNotFoundError, UnconfiguredError } from '../errors.js';
 import { assertPrivateOnWindows } from './windows-acl.js';
 export function getConfigPath(customPath) {
     if (customPath)
@@ -188,6 +188,14 @@ export function getProfile(config, name) {
             throw new OperatorError(`No profile selected and no default configured, but ${config.profiles.length} profiles exist: ${names}. ` +
                 `Pass a "profile" argument, or set defaults.defaultProfile in the config.`);
         }
+        // Defensive: a lookup helper must not hand back `undefined` typed as `Profile`, which
+        // is what `profiles[0]` on an empty list used to do — a TypeError somewhere downstream
+        // rather than an explanation here. This is the invariant, not the product rule. The
+        // decision that an unconfigured server refuses work lives in `ConnectionRegistry`,
+        // which guards this branch AND the named-profile one below; reaching this line means
+        // a caller went around the registry.
+        if (config.profiles.length === 0)
+            throw new UnconfiguredError(getConfigPath());
         return config.profiles[0];
     }
     const profile = config.profiles.find((p) => p.name === targetName);

package/build/errors.js

@@ -65,6 +65,29 @@ export class ConfigNotFoundError extends OperatorError {
         this.name = 'ConfigNotFoundError';
     }
 }
+/**
+ * Nothing is configured: no config file, and no `--host`/`--user` on the command line.
+ *
+ * A type rather than a bare `OperatorError` for the reason `ConfigNotFoundError` is one —
+ * two layers have to agree on this state without agreeing on a string. `cli.ts` prints it
+ * as a startup warning and the server keeps running; `ConnectionRegistry` throws it at
+ * every tool call. Those are different audiences reached through different channels, and
+ * a wording edit in one must not quietly stop matching the other.
+ *
+ * The path is a constructor argument rather than a `getConfigPath()` call inside the
+ * message, so this file stays free of the config layer and the text is testable without
+ * stubbing `os.platform()`.
+ */
+export class UnconfiguredError extends OperatorError {
+    configPath;
+    constructor(configPath) {
+        super('No config file found and missing required --host/--user.\n' +
+            `Either create a config file at ${configPath} or pass --config <path>.\n` +
+            'For quick start: --host=<host> --user=<user> (credentials via env vars).');
+        this.configPath = configPath;
+        this.name = 'UnconfiguredError';
+    }
+}
 /** Exit status for an operator error, so a supervisor can tell it from a crash. */
 export const EXIT_OPERATOR_ERROR = 2;
 /** Exit status for anything else. */

package/build/ssh/connection-registry.js

@@ -1,4 +1,5 @@
-import { getProfile as getConfigProfile } from '../config/loader.js';
+import { getProfile as getConfigProfile, getConfigPath } from '../config/loader.js';
+import { UnconfiguredError } from '../errors.js';
 import { resolveCredentials } from '../config/credential-resolver.js';
 import { SSHConnection } from './connection.js';
 export class ConnectionRegistry {
@@ -69,7 +70,25 @@ export class ConnectionRegistry {
         const profile = this.getProfile(profileName);
         return this.connections.get(profile.name);
     }
+    /**
+     * Refuse everything while nothing is configured.
+     *
+     * The server now starts with `profiles: []` so a directory or a client's "add server"
+     * flow can read `tools/list` (see cli.ts). This is where that state stops being
+     * readable and starts being refused, and it sits here rather than in the loader's
+     * `getProfile` for one measured reason: the loader's empty check can only live in the
+     * no-profile-named branch, so a client calling `run-command` with `profile: "prod"`
+     * against an unconfigured server got `Profile "prod" not found` — a message telling the
+     * operator they mistyped a name when in fact they have no config at all, and omitting
+     * the config path this whole change exists to deliver. Checking before the lookup
+     * covers both.
+     */
+    assertConfigured() {
+        if (this.config.profiles.length === 0)
+            throw new UnconfiguredError(getConfigPath());
+    }
     getProfile(profileName) {
+        this.assertConfigured();
         return getConfigProfile(this.config, profileName);
     }
     listConnections() {

package/build/tools/command-tools.js

@@ -42,7 +42,6 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
         command: z.string().describe('Command to execute with sudo'),
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ command, profile }, extra) => {
-        const profileName = defaultProfileName(profile);
         return runAudited(command, {
             toolName: 'privileged-command',
             failureClass: 'privileged',
@@ -51,7 +50,11 @@ export function registerCommandTools({ server, registry, policy }, pipeline) {
             // Evaluate the bare command too: the sudo wrapper would otherwise
             // hide a forbidden command inside a quoted `sh -c` argument.
             preCheck: (cleanCmd) => {
-                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(profileName), 'privileged-command');
+                // Resolved here rather than before `runAudited`: `defaultProfileName` reaches
+                // `registry.getProfile()`, which refuses on an unconfigured server, and outside
+                // the pipeline's try that refusal escaped without an audit record. `preCheck`
+                // runs inside it.
+                const rawEval = policy.evaluate(cleanCmd, registry.getProfile(defaultProfileName(profile)), 'privileged-command');
                 if (rawEval.decision === 'deny') {
                     throw new PolicyRefusedError(`POLICY_DENIED: ${rawEval.reason || 'Command not allowed'}`, rawEval);
                 }

package/build/tools/pipeline.js

@@ -75,7 +75,12 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
         await audit.record({
             mcpRequestId: ctx.requestId,
             profile: profileName,
-            user: registry.getProfile(profileName).user,
+            // Looked up without throwing. This used to be `registry.getProfile(profileName).user`,
+            // which throws for exactly the reason the tool call is being audited as a failure —
+            // an unconfigured server, or a profile name that does not exist — and `auditFailure`
+            // swallows that by design. The record the operator most needs was the one record that
+            // could not be written.
+            user: profileUser(profileName),
             command,
             commandClass: evaluation.commandClass,
             binary: evaluation.binary,
@@ -113,6 +118,10 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
     function defaultProfileName(profile) {
         return profile || registry.getProfile().name;
     }
+    /** The profile's SSH user, or a placeholder — never throws, so an audit write cannot fail. */
+    function profileUser(profileName) {
+        return registry.listAllProfiles().find((p) => p.name === profileName)?.user ?? '(unresolved)';
+    }
     function makeProgressSender(extra) {
         const token = extra?._meta?.progressToken;
         if (token === undefined)
@@ -135,15 +144,21 @@ export function createPipeline({ server, registry, policy, audit, approvalGrantT
      */
     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.
+        // Named before the try because `auditFailure` needs something to file the record
+        // under even when resolution itself is what failed. Reassigned to the resolved name as
+        // the first statement inside, so the quota key and the audit record are unchanged on
+        // every path that gets that far.
+        let profileName = opts.profile ?? '(default)';
+        // Profile resolution and sanitization both run inside the try, so a rejected call
+        // still leaves an audit trail — a client probing with malformed payloads, or probing
+        // a server that has no config at all, used to leave none. The unconfigured refusal
+        // reaches this the same way a bad command does.
         const state = { command };
         try {
+            profileName = defaultProfileName(opts.profile);
+            const profile = registry.getProfile(profileName);
             let effective = opts.synthetic ? command : sanitizeCommand(command, profile.maxChars);
             state.command = effective;
             opts.preCheck?.(effective);

package/build/tools/session-tools.js

@@ -38,6 +38,14 @@ export function registerSessionTools({ server, registry }, pipeline) {
     const { runAudited, resolveConn, auditResult, auditFailure, makeCtx, defaultProfileName } = pipeline;
     // ─── list-connections ──────────────────────────────────────────────────
     server.tool('list-connections', D["list-connections"], {}, { readOnlyHint: true }, async () => {
+        // The one tool that reads only `listAllProfiles()` and so never touches
+        // `getProfile`. Without this it answered an unconfigured server with a
+        // zero-length success — on the tool whose own description sends an agent here
+        // first ("discover available hosts before running commands"), and on the one
+        // channel where the startup stderr warning is not visible. The agent saw "no
+        // hosts" rather than "not configured". Refusing here is what makes the claim in
+        // the README, the changeset and the startup warning true of all eleven tools.
+        registry.assertConfigured();
         const connections = registry.listConnections();
         const profiles = registry.listAllProfiles();
         const lines = profiles.map((p) => {
@@ -104,19 +112,27 @@ export function registerSessionTools({ server, registry }, pipeline) {
         profile: z.string().optional().describe('Profile name'),
     }, { destructiveHint: true }, async ({ name, profile }, extra) => {
         const cleanName = sanitizeSessionName(name);
-        const profileName = defaultProfileName(profile);
+        // Both the profile name and the connection are resolved inside the try below. They
+        // used to be resolved above it, so a refusal — an unconfigured server, an unknown
+        // profile name — escaped before `auditFailure` could record that a release was
+        // attempted. The placeholders are what the record is filed under if resolution is
+        // itself what failed.
+        let profileName = profile ?? '(default)';
         const ctx = makeCtx(extra, profileName, cleanName);
-        const conn = await resolveConn(profile);
-        // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
-        // distinguishable from ending a local shell — `open-session` encodes its type the
-        // same way.
-        // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
-        // tool handler reaching for a constructor identity is the layer leak this repo's own
-        // rules call out.
-        const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
-        const command = `session:close ${kind} ${cleanName}`;
+        let command = `session:close unknown ${cleanName}`;
         const startedAt = Date.now();
         try {
+            profileName = defaultProfileName(profile);
+            ctx.profile = profileName;
+            const conn = await resolveConn(profile);
+            // Recorded with the session's kind, so a remote SIGKILL is greppable in the log and
+            // distinguishable from ending a local shell — `open-session` encodes its type the
+            // same way.
+            // Through `toInfo()` rather than an `instanceof` check: the type is public API, and a
+            // tool handler reaching for a constructor identity is the layer leak this repo's own
+            // rules call out.
+            const kind = conn.getSession(cleanName)?.toInfo().type ?? 'unknown';
+            command = `session:close ${kind} ${cleanName}`;
             const outcome = await conn.closeSession(cleanName);
             await auditResult(ctx, profileName, command, RELEASE, {
                 stdout: '',

package/build/transport/http.js

@@ -98,7 +98,8 @@ export async function startHttpServer(createMcpServer, opts) {
     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".
+        // /health without an auth caveat. It exposes "process is up" and whether any profile
+        // is configured — see the handler below for why that second bit is not a secret.
         const isHealthProbe = req.method === 'GET' && url.pathname === '/health';
         if (!isHealthProbe) {
             const auth = req.headers.authorization || '';
@@ -210,8 +211,18 @@ export async function startHttpServer(createMcpServer, opts) {
             return;
         }
         if (req.method === 'GET' && url.pathname === '/health') {
+            // `configured` is liveness telling the truth about readiness. Since the server
+            // learned to start with nothing configured, an HTTP deployment whose config bind
+            // mount silently did not attach comes up, binds the port, and fails 100% of tool
+            // calls — while this probe said `healthy: true` and the explaining stderr warning
+            // scrolled past at boot. The status stays 200 so an existing probe does not start
+            // failing on upgrade; the field is what an operator can alert on.
+            //
+            // It widens what this unauthenticated route discloses by exactly one bit, and that
+            // bit is worth little to anyone: a server with no profile is one that cannot reach
+            // any host. `/status` carries the profile list itself and stays behind the token.
             res.writeHead(200, { 'Content-Type': 'application/json' });
-            res.end(JSON.stringify({ healthy: true }));
+            res.end(JSON.stringify({ healthy: true, configured: registry.listAllProfiles().length > 0 }));
             return;
         }
         res.writeHead(404, { 'Content-Type': 'application/json' });

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "ssh-mcp",
   "license": "MIT",
-  "version": "2.3.4",
+  "version": "2.4.0",
   "description": "MCP server exposing policy-gated, audited SSH access for Linux and Windows hosts via the Model Context Protocol.",
   "mcpName": "io.github.tufantunc/ssh-mcp",
   "type": "module",