@cruxy/cli 0.20.0 → 0.21.0

package/dist/config/schema.d.ts

@@ -446,16 +446,16 @@ export declare const LspConfigSchema: z.ZodObject<{
 }, "strict", z.ZodTypeAny, {
     startupTimeout: number;
     requestTimeout: number;
-    enabled: boolean;
     servers: Record<string, string>;
+    enabled: boolean;
     maxServers: number;
     idleTimeout: number;
     maxResults: number;
 }, {
     startupTimeout?: number | undefined;
     requestTimeout?: number | undefined;
-    enabled?: boolean | undefined;
     servers?: Record<string, string> | undefined;
+    enabled?: boolean | undefined;
     maxServers?: number | undefined;
     idleTimeout?: number | undefined;
     maxResults?: number | undefined;
@@ -593,20 +593,135 @@ export declare const UsageConfigSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type UsageConfig = z.infer<typeof UsageConfigSchema>;
-/** MCP server entry — stdio or URL transport (wired up in a later phase). */
-export declare const McpServerSchema: z.ZodObject<{
+/**
+ * One MCP server entry (C.27). A `command` (+ optional `args`/`env`) is a stdio
+ * server cruxy spawns as a child process; a `url` names a remote server. Exactly
+ * one transport must be given. Trusting a stdio server runs its code UNSANDBOXED
+ * with your privileges, which is why connection is gated by an explicit,
+ * fingerprinted trust decision (see `mcp/trust.ts`).
+ */
+export declare const McpServerSchema: z.ZodEffects<z.ZodObject<{
+    /** stdio transport: the server program to spawn. */
     command: z.ZodOptional<z.ZodString>;
-    args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    /** Arguments for `command`. */
+    args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    /** Extra environment variables for the spawned server (stdio only). */
+    env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Remote transport: the server URL (mutually exclusive with `command`). */
     url: z.ZodOptional<z.ZodString>;
 }, "strict", z.ZodTypeAny, {
+    args: string[];
+    env: Record<string, string>;
+    command?: string | undefined;
+    url?: string | undefined;
+}, {
     command?: string | undefined;
     url?: string | undefined;
     args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+}>, {
+    args: string[];
+    env: Record<string, string>;
+    command?: string | undefined;
+    url?: string | undefined;
 }, {
     command?: string | undefined;
     url?: string | undefined;
     args?: string[] | undefined;
+    env?: Record<string, string> | undefined;
+}>;
+export type McpServerConfig = z.infer<typeof McpServerSchema>;
+/**
+ * MCP client integration (C.27): connect to trusted MCP servers and expose their
+ * tools to the agent. OFF by default — like the sandbox, LSP, and hooks, it runs
+ * EXTERNAL code (a stdio server executes UNSANDBOXED with your privileges), a
+ * real execution surface you opt into explicitly. When off, nothing connects or
+ * spawns and no MCP tool is ever registered. Every server-advertised tool is
+ * gated (destructive tier — a server can never self-declare a tool "safe"), its
+ * description and results are demarcated as untrusted external data with upstream
+ * model names scrubbed, and results are NEVER persisted. The tool list a server
+ * advertises is bounded (count + per-tool description/schema size) so a hostile
+ * server can't blow the context budget.
+ */
+export declare const McpConfigSchema: z.ZodObject<{
+    /** Master switch. When false, no server is connected/spawned and no MCP tool
+     * is registered (the feature stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Named MCP servers, keyed by a short server id used as the tool prefix
+     * (`mcp__<server>__<tool>`) and in the trust prompt. */
+    servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+        /** stdio transport: the server program to spawn. */
+        command: z.ZodOptional<z.ZodString>;
+        /** Arguments for `command`. */
+        args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+        /** Extra environment variables for the spawned server (stdio only). */
+        env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Remote transport: the server URL (mutually exclusive with `command`). */
+        url: z.ZodOptional<z.ZodString>;
+    }, "strict", z.ZodTypeAny, {
+        args: string[];
+        env: Record<string, string>;
+        command?: string | undefined;
+        url?: string | undefined;
+    }, {
+        command?: string | undefined;
+        url?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>, {
+        args: string[];
+        env: Record<string, string>;
+        command?: string | undefined;
+        url?: string | undefined;
+    }, {
+        command?: string | undefined;
+        url?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }>>>;
+    /** Fail a server's `initialize` handshake (its tools are skipped) if it does
+     * not complete within this many ms. */
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Fail a single `tools/call` if the server does not respond within this many
+     * ms — the connection is kept, only the one call errors. */
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Max tools accepted from ONE server; extras are dropped with a visible note
+     * (a hostile server can't advertise thousands of tools to flood context). */
+    maxToolsPerServer: z.ZodDefault<z.ZodNumber>;
+    /** Max characters kept from a single tool's description; the rest is truncated
+     * with a visible marker. */
+    maxDescriptionChars: z.ZodDefault<z.ZodNumber>;
+    /** Max bytes kept from a single tool's advertised JSON input schema; an
+     * over-cap schema is replaced with a permissive one and a visible note. */
+    maxSchemaBytes: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    startupTimeout: number;
+    requestTimeout: number;
+    servers: Record<string, {
+        args: string[];
+        env: Record<string, string>;
+        command?: string | undefined;
+        url?: string | undefined;
+    }>;
+    enabled: boolean;
+    maxToolsPerServer: number;
+    maxDescriptionChars: number;
+    maxSchemaBytes: number;
+}, {
+    startupTimeout?: number | undefined;
+    requestTimeout?: number | undefined;
+    servers?: Record<string, {
+        command?: string | undefined;
+        url?: string | undefined;
+        args?: string[] | undefined;
+        env?: Record<string, string> | undefined;
+    }> | undefined;
+    enabled?: boolean | undefined;
+    maxToolsPerServer?: number | undefined;
+    maxDescriptionChars?: number | undefined;
+    maxSchemaBytes?: number | undefined;
 }>;
+export type McpConfig = z.infer<typeof McpConfigSchema>;
 export declare const CruxyConfigSchema: z.ZodObject<{
     model: z.ZodDefault<z.ZodObject<{
         provider: z.ZodDefault<z.ZodEnum<["cruxy", "anthropic", "openai", "custom"]>>;
@@ -823,16 +938,16 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }, "strict", z.ZodTypeAny, {
         startupTimeout: number;
         requestTimeout: number;
-        enabled: boolean;
         servers: Record<string, string>;
+        enabled: boolean;
         maxServers: number;
         idleTimeout: number;
         maxResults: number;
     }, {
         startupTimeout?: number | undefined;
         requestTimeout?: number | undefined;
-        enabled?: boolean | undefined;
         servers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
         maxServers?: number | undefined;
         idleTimeout?: number | undefined;
         maxResults?: number | undefined;
@@ -1104,19 +1219,84 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             } | undefined;
         } | undefined;
     }>>;
-    mcpServers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodObject<{
-        command: z.ZodOptional<z.ZodString>;
-        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
-        url: z.ZodOptional<z.ZodString>;
+    mcp: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, no server is connected/spawned and no MCP tool
+         * is registered (the feature stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Named MCP servers, keyed by a short server id used as the tool prefix
+         * (`mcp__<server>__<tool>`) and in the trust prompt. */
+        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodEffects<z.ZodObject<{
+            /** stdio transport: the server program to spawn. */
+            command: z.ZodOptional<z.ZodString>;
+            /** Arguments for `command`. */
+            args: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+            /** Extra environment variables for the spawned server (stdio only). */
+            env: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+            /** Remote transport: the server URL (mutually exclusive with `command`). */
+            url: z.ZodOptional<z.ZodString>;
+        }, "strict", z.ZodTypeAny, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            url?: string | undefined;
+        }, {
+            command?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        }>, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            url?: string | undefined;
+        }, {
+            command?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        }>>>;
+        /** Fail a server's `initialize` handshake (its tools are skipped) if it does
+         * not complete within this many ms. */
+        startupTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Fail a single `tools/call` if the server does not respond within this many
+         * ms — the connection is kept, only the one call errors. */
+        requestTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Max tools accepted from ONE server; extras are dropped with a visible note
+         * (a hostile server can't advertise thousands of tools to flood context). */
+        maxToolsPerServer: z.ZodDefault<z.ZodNumber>;
+        /** Max characters kept from a single tool's description; the rest is truncated
+         * with a visible marker. */
+        maxDescriptionChars: z.ZodDefault<z.ZodNumber>;
+        /** Max bytes kept from a single tool's advertised JSON input schema; an
+         * over-cap schema is replaced with a permissive one and a visible note. */
+        maxSchemaBytes: z.ZodDefault<z.ZodNumber>;
     }, "strict", z.ZodTypeAny, {
-        command?: string | undefined;
-        url?: string | undefined;
-        args?: string[] | undefined;
+        startupTimeout: number;
+        requestTimeout: number;
+        servers: Record<string, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            url?: string | undefined;
+        }>;
+        enabled: boolean;
+        maxToolsPerServer: number;
+        maxDescriptionChars: number;
+        maxSchemaBytes: number;
     }, {
-        command?: string | undefined;
-        url?: string | undefined;
-        args?: string[] | undefined;
-    }>>>;
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        servers?: Record<string, {
+            command?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        }> | undefined;
+        enabled?: boolean | undefined;
+        maxToolsPerServer?: number | undefined;
+        maxDescriptionChars?: number | undefined;
+        maxSchemaBytes?: number | undefined;
+    }>>;
     logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error", "silent"]>>;
 }, "strict", z.ZodTypeAny, {
     cruxy: {
@@ -1218,8 +1398,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     lsp: {
         startupTimeout: number;
         requestTimeout: number;
-        enabled: boolean;
         servers: Record<string, string>;
+        enabled: boolean;
         maxServers: number;
         idleTimeout: number;
         maxResults: number;
@@ -1237,11 +1417,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         map: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">>;
         default?: "kavi" | "vaani" | "mira" | undefined;
     };
-    mcpServers: Record<string, {
-        command?: string | undefined;
-        url?: string | undefined;
-        args?: string[] | undefined;
-    }>;
+    mcp: {
+        startupTimeout: number;
+        requestTimeout: number;
+        servers: Record<string, {
+            args: string[];
+            env: Record<string, string>;
+            command?: string | undefined;
+            url?: string | undefined;
+        }>;
+        enabled: boolean;
+        maxToolsPerServer: number;
+        maxDescriptionChars: number;
+        maxSchemaBytes: number;
+    };
     logLevel: "debug" | "info" | "warn" | "error" | "silent";
 }, {
     cruxy?: {
@@ -1343,8 +1532,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     lsp?: {
         startupTimeout?: number | undefined;
         requestTimeout?: number | undefined;
-        enabled?: boolean | undefined;
         servers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
         maxServers?: number | undefined;
         idleTimeout?: number | undefined;
         maxResults?: number | undefined;
@@ -1362,11 +1551,20 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         map?: Partial<Record<"main-turn" | "subagent" | "plan" | "commit-msg" | "classify" | "summarize", "kavi" | "vaani" | "mira">> | undefined;
         default?: "kavi" | "vaani" | "mira" | undefined;
     } | undefined;
-    mcpServers?: Record<string, {
-        command?: string | undefined;
-        url?: string | undefined;
-        args?: string[] | undefined;
-    }> | undefined;
+    mcp?: {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        servers?: Record<string, {
+            command?: string | undefined;
+            url?: string | undefined;
+            args?: string[] | undefined;
+            env?: Record<string, string> | undefined;
+        }> | undefined;
+        enabled?: boolean | undefined;
+        maxToolsPerServer?: number | undefined;
+        maxDescriptionChars?: number | undefined;
+        maxSchemaBytes?: number | undefined;
+    } | undefined;
     logLevel?: "debug" | "info" | "warn" | "error" | "silent" | undefined;
 }>;
 export type CruxyConfig = z.infer<typeof CruxyConfigSchema>;

package/dist/config/schema.js

@@ -365,12 +365,63 @@ export const UsageConfigSchema = z
         .default({}),
 })
     .strict();
-/** MCP server entry — stdio or URL transport (wired up in a later phase). */
+/**
+ * One MCP server entry (C.27). A `command` (+ optional `args`/`env`) is a stdio
+ * server cruxy spawns as a child process; a `url` names a remote server. Exactly
+ * one transport must be given. Trusting a stdio server runs its code UNSANDBOXED
+ * with your privileges, which is why connection is gated by an explicit,
+ * fingerprinted trust decision (see `mcp/trust.ts`).
+ */
 export const McpServerSchema = z
     .object({
-    command: z.string().optional(),
-    args: z.array(z.string()).optional(),
+    /** stdio transport: the server program to spawn. */
+    command: z.string().min(1).optional(),
+    /** Arguments for `command`. */
+    args: z.array(z.string()).default([]),
+    /** Extra environment variables for the spawned server (stdio only). */
+    env: z.record(z.string(), z.string()).default({}),
+    /** Remote transport: the server URL (mutually exclusive with `command`). */
     url: z.string().url().optional(),
+})
+    .strict()
+    .refine((s) => Boolean(s.command) !== Boolean(s.url), {
+    message: "an MCP server needs exactly one of `command` (stdio) or `url`",
+});
+/**
+ * MCP client integration (C.27): connect to trusted MCP servers and expose their
+ * tools to the agent. OFF by default — like the sandbox, LSP, and hooks, it runs
+ * EXTERNAL code (a stdio server executes UNSANDBOXED with your privileges), a
+ * real execution surface you opt into explicitly. When off, nothing connects or
+ * spawns and no MCP tool is ever registered. Every server-advertised tool is
+ * gated (destructive tier — a server can never self-declare a tool "safe"), its
+ * description and results are demarcated as untrusted external data with upstream
+ * model names scrubbed, and results are NEVER persisted. The tool list a server
+ * advertises is bounded (count + per-tool description/schema size) so a hostile
+ * server can't blow the context budget.
+ */
+export const McpConfigSchema = z
+    .object({
+    /** Master switch. When false, no server is connected/spawned and no MCP tool
+     * is registered (the feature stays fully inert). */
+    enabled: z.boolean().default(false),
+    /** Named MCP servers, keyed by a short server id used as the tool prefix
+     * (`mcp__<server>__<tool>`) and in the trust prompt. */
+    servers: z.record(z.string(), McpServerSchema).default({}),
+    /** Fail a server's `initialize` handshake (its tools are skipped) if it does
+     * not complete within this many ms. */
+    startupTimeout: z.number().int().positive().default(15000),
+    /** Fail a single `tools/call` if the server does not respond within this many
+     * ms — the connection is kept, only the one call errors. */
+    requestTimeout: z.number().int().positive().default(30000),
+    /** Max tools accepted from ONE server; extras are dropped with a visible note
+     * (a hostile server can't advertise thousands of tools to flood context). */
+    maxToolsPerServer: z.number().int().positive().default(32),
+    /** Max characters kept from a single tool's description; the rest is truncated
+     * with a visible marker. */
+    maxDescriptionChars: z.number().int().positive().default(1024),
+    /** Max bytes kept from a single tool's advertised JSON input schema; an
+     * over-cap schema is replaced with a permissive one and a visible note. */
+    maxSchemaBytes: z.number().int().positive().default(8192),
 })
     .strict();
 export const CruxyConfigSchema = z
@@ -393,7 +444,7 @@ export const CruxyConfigSchema = z
     routing: RoutingConfigSchema.default({}),
     memory: MemoryConfigSchema.default({}),
     usage: UsageConfigSchema.default({}),
-    mcpServers: z.record(z.string(), McpServerSchema).default({}),
+    mcp: McpConfigSchema.default({}),
     logLevel: z.enum(LOG_LEVELS).default("info"),
 })
     .strict();

package/dist/constants.d.ts

@@ -41,6 +41,14 @@ export declare const MEMORY_FILE_NAME = "entries.json";
  * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
  * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
 export declare const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
+/**
+ * MCP server integration (C.27). Per-repo trust for configured MCP servers, in
+ * the GLOBAL dir only (`~/.cruxy/mcp-trust.json`) — its own file, independent of
+ * hook and memory trust, so cloning a repo carries zero MCP trust. Trusting a
+ * server runs its code UNSANDBOXED with your privileges, so this decision is
+ * fingerprinted and re-checked on every run (C.27 supply-chain safety).
+ */
+export declare const MCP_TRUST_FILE_NAME = "mcp-trust.json";
 /**
  * Usage telemetry + cost tracking (C.22). Per-run/per-session usage records live
  * in the GLOBAL dir only (`~/.cruxy/usage/runs.json`), `0600` — LOCAL accounting

package/dist/constants.js

@@ -61,6 +61,14 @@ export const MEMORY_FILE_NAME = "entries.json";
  * (`~/.cruxy/memory-trust.json`) — its own file, independent of hook trust, so
  * cloning a repo carries zero memory trust (C.29 supply-chain safety). */
 export const MEMORY_TRUST_FILE_NAME = "memory-trust.json";
+/**
+ * MCP server integration (C.27). Per-repo trust for configured MCP servers, in
+ * the GLOBAL dir only (`~/.cruxy/mcp-trust.json`) — its own file, independent of
+ * hook and memory trust, so cloning a repo carries zero MCP trust. Trusting a
+ * server runs its code UNSANDBOXED with your privileges, so this decision is
+ * fingerprinted and re-checked on every run (C.27 supply-chain safety).
+ */
+export const MCP_TRUST_FILE_NAME = "mcp-trust.json";
 /**
  * Usage telemetry + cost tracking (C.22). Per-run/per-session usage records live
  * in the GLOBAL dir only (`~/.cruxy/usage/runs.json`), `0600` — LOCAL accounting

package/dist/errors/constructors.d.ts

@@ -180,6 +180,23 @@ export declare function lspTimeout(language: string, phase: "startup" | "request
  * that answered with zero results (that is an ordinary, non-error outcome).
  */
 export declare function lspCrashed(language: string, detail?: string): CruxyError;
+/**
+ * A project configures MCP servers that this repo has not trusted, and cruxy is
+ * running non-interactively so it cannot ask. Fail closed BEFORE any server is
+ * spawned: trusting a server runs its code UNSANDBOXED with the user's full
+ * privileges (a stdio server's own side effects can't be contained by the shell
+ * sandbox), so an untrusted config must never connect silently. The wording says
+ * this plainly — it is a real escalation, not a "gated shell in a box".
+ */
+export declare function mcpUntrusted(root: string, servers: string[]): CruxyError;
+/**
+ * A trusted MCP server could not be reached — spawn failed, the `initialize`
+ * handshake errored/timed out, or `tools/list` failed. That server simply
+ * contributes no tools (the run continues); the coded reason is surfaced so a
+ * misconfigured server is visible, not a silent absence. External server text is
+ * gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export declare function mcpConnect(server: string, underlying?: unknown): CruxyError;
 export declare function internal(underlying?: unknown): CruxyError;
 /**
  * Map a known provider/transport error (from `@cruxy/sdk`) to a typed

package/dist/errors/constructors.js

@@ -733,6 +733,52 @@ export function lspCrashed(language, detail) {
         meta: { language },
     });
 }
+// ── MCP client (exit 16) — C.27 ───────────────────────────────────────────────
+/**
+ * A project configures MCP servers that this repo has not trusted, and cruxy is
+ * running non-interactively so it cannot ask. Fail closed BEFORE any server is
+ * spawned: trusting a server runs its code UNSANDBOXED with the user's full
+ * privileges (a stdio server's own side effects can't be contained by the shell
+ * sandbox), so an untrusted config must never connect silently. The wording says
+ * this plainly — it is a real escalation, not a "gated shell in a box".
+ */
+export function mcpUntrusted(root, servers) {
+    const list = servers.join(", ");
+    return new CruxyError({
+        code: ErrorCode.McpUntrusted,
+        title: "this project's MCP servers have not been trusted",
+        cause: `${servers.length} configured server${servers.length === 1 ? "" : "s"} (${list}) ` +
+            "would run UNSANDBOXED with your full privileges — cruxy will not connect to them " +
+            "non-interactively without an explicit, recorded trust decision",
+        nextSteps: [
+            "review the servers with `cruxy mcp list`",
+            "then trust them with `cruxy mcp trust .` (re-trust is required if the config changes)",
+            "or set `mcp.enabled = false` to disable MCP for this project",
+        ],
+        meta: { root, servers },
+    });
+}
+/**
+ * A trusted MCP server could not be reached — spawn failed, the `initialize`
+ * handshake errored/timed out, or `tools/list` failed. That server simply
+ * contributes no tools (the run continues); the coded reason is surfaced so a
+ * misconfigured server is visible, not a silent absence. External server text is
+ * gag-scrubbed (U.8) before it reaches the user-facing cause.
+ */
+export function mcpConnect(server, underlying) {
+    return new CruxyError({
+        code: ErrorCode.McpConnect,
+        title: `could not connect to MCP server "${server}"`,
+        cause: scrubbedMessageOf(underlying) ??
+            "the server failed to start, handshake, or list its tools",
+        nextSteps: [
+            "re-run with --verbose to see the server's error",
+            `verify the command in \`mcp.servers.${server}\` runs standalone`,
+        ],
+        meta: { server },
+        underlying,
+    });
+}
 // ── internal (exit 1) ─────────────────────────────────────────────────────────
 export function internal(underlying) {
     return new CruxyError({

package/dist/errors/types.d.ts

@@ -93,6 +93,15 @@ export declare const ErrorCode: {
     /** A language server crashed (and, where applicable, a single restart also
      * failed). Distinct from "server returned no results". */
     readonly LspCrashed: "CRUXY_E_LSP_CRASHED";
+    /** A project configures MCP servers that have not been trusted for this repo.
+     * Trusting a server runs its code UNSANDBOXED with your privileges, so an
+     * untrusted config is never connected silently — and in non-interactive mode
+     * it fails closed BEFORE any server is spawned (supply-chain safety). */
+    readonly McpUntrusted: "CRUXY_E_MCP_UNTRUSTED";
+    /** A trusted MCP server failed to spawn, complete the `initialize` handshake,
+     * or list its tools. Surfaced (that server contributes no tools) rather than
+     * silently swallowed; never fatal to the run. */
+    readonly McpConnect: "CRUXY_E_MCP_CONNECT";
 };
 export type ErrorCode = (typeof ErrorCode)[keyof typeof ErrorCode];
 /** The process exit code for an error code (defaults to 1 for safety). */

package/dist/errors/types.js

@@ -110,6 +110,16 @@ export const ErrorCode = {
     /** A language server crashed (and, where applicable, a single restart also
      * failed). Distinct from "server returned no results". */
     LspCrashed: "CRUXY_E_LSP_CRASHED",
+    // MCP client (exit 16) — C.27
+    /** A project configures MCP servers that have not been trusted for this repo.
+     * Trusting a server runs its code UNSANDBOXED with your privileges, so an
+     * untrusted config is never connected silently — and in non-interactive mode
+     * it fails closed BEFORE any server is spawned (supply-chain safety). */
+    McpUntrusted: "CRUXY_E_MCP_UNTRUSTED",
+    /** A trusted MCP server failed to spawn, complete the `initialize` handshake,
+     * or list its tools. Surfaced (that server contributes no tools) rather than
+     * silently swallowed; never fatal to the run. */
+    McpConnect: "CRUXY_E_MCP_CONNECT",
 };
 /**
  * Category exit codes. Distinct per category so a caller (CI, a script) can
@@ -187,6 +197,11 @@ const EXIT_CODES = {
     [ErrorCode.LspServerNotFound]: 15,
     [ErrorCode.LspTimeout]: 15,
     [ErrorCode.LspCrashed]: 15,
+    // MCP client (C.27). An untrusted MCP config is an execution-safety stop that
+    // fails closed before any spawn; a connect failure surfaces per-server and is
+    // never fatal on its own. Grouped for a greppable exit code.
+    [ErrorCode.McpUntrusted]: 16,
+    [ErrorCode.McpConnect]: 16,
 };
 /** The process exit code for an error code (defaults to 1 for safety). */
 export function exitCodeFor(code) {

package/dist/lsp/transport.d.ts

@@ -1,4 +1,10 @@
+import { killTree, killTrackedTrees, trackedTreeCount } from "../utils/child-tree.js";
 import type { LspTransport, ServerSpec } from "./types.js";
+export { killTree };
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const killTrackedServers: typeof killTrackedTrees;
+/** @deprecated Use the shared backstop; kept for LSP tests. */
+export declare const trackedServerCount: typeof trackedTreeCount;
 export declare class StdioTransport implements LspTransport {
     private readonly child;
     private nextId;
@@ -31,18 +37,3 @@ export declare class TransportTimeoutError extends Error {
     readonly timeoutMs: number;
     constructor(method: string, timeoutMs: number);
 }
-/**
- * Kill the process's entire group (POSIX negative-PID `SIGKILL`), same helper
- * shape as run_command's `killTree`. Swallows errors — the process may be gone.
- */
-export declare function killTree(pid: number | undefined): void;
-/**
- * Force-kill the process group of every tracked-but-not-yet-shut-down server,
- * then forget them. This is exactly what the `exit`/`SIGINT`/`SIGTERM`/`SIGHUP`
- * handlers run — the last line against orphaned language servers on a hard exit.
- * Exported so it is directly testable (like `resetIndexServices`) without having
- * to raise real process signals. Idempotent: a second call is a no-op.
- */
-export declare function killTrackedServers(): void;
-/** Number of servers currently tracked by the exit backstop (for tests). */
-export declare function trackedServerCount(): number;