@cruxy/cli 0.19.0 → 0.21.0

package/dist/config/schema.d.ts

@@ -236,8 +236,8 @@ export declare const TestConfigSchema: z.ZodObject<{
     captureBytes: number;
     command?: string | undefined;
 }, {
-    maxIterations?: number | undefined;
     command?: string | undefined;
+    maxIterations?: number | undefined;
     captureBytes?: number | undefined;
 }>;
 /**
@@ -264,9 +264,9 @@ export declare const SubagentConfigSchema: z.ZodObject<{
         maxIterations: number;
         timeoutMs?: number | undefined;
     }, {
+        timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
         maxIterations?: number | undefined;
-        timeoutMs?: number | undefined;
     }>>;
 }, "strict", z.ZodTypeAny, {
     maxDepth: number;
@@ -278,9 +278,9 @@ export declare const SubagentConfigSchema: z.ZodObject<{
 }, {
     maxDepth?: number | undefined;
     defaultBudget?: {
+        timeoutMs?: number | undefined;
         maxTokens?: number | undefined;
         maxIterations?: number | undefined;
-        timeoutMs?: number | undefined;
     } | undefined;
 }>;
 /**
@@ -408,6 +408,59 @@ export declare const MemoryConfigSchema: z.ZodObject<{
     maxRecallTokens?: number | undefined;
 }>;
 export type MemoryConfig = z.infer<typeof MemoryConfigSchema>;
+/**
+ * Per-language LSP integration (C.12): read-only, symbol-aware tools
+ * (find_definition, find_references, get_diagnostics, hover) backed by a
+ * managed pool of language servers. OFF by default — like the sandbox and
+ * hooks, it spawns and manages EXTERNAL server processes, a real execution
+ * surface the user opts into explicitly. When on, a missing server binary is
+ * an actionable, coded failure (CRUXY_E_LSP_SERVER_NOT_FOUND), never a silent
+ * empty result. Servers spawn lazily per language, are reused for the session,
+ * and are shut down cleanly (with a process-exit kill-tree backstop).
+ */
+export declare const LspConfigSchema: z.ZodObject<{
+    /** Master switch. When false, the four LSP tools are not registered and no
+     * server ever spawns (the feature stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Per-language command overrides, keyed by language id (e.g. `typescript`,
+     * `python`, `go`, `rust`). The value is the full command line
+     * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+     * falls back to the built-in default table (see `lsp/registry.ts`).
+     */
+    servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+     * not complete within this many ms. */
+    startupTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+     * within this many ms — the server is kept alive, only the request errors. */
+    requestTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Maximum concurrently-running language servers; acquiring past the cap
+     * evicts the idle-oldest server first. */
+    maxServers: z.ZodDefault<z.ZodNumber>;
+    /** Shut a server down after it has been idle this many ms. */
+    idleTimeout: z.ZodDefault<z.ZodNumber>;
+    /** Cap on locations/diagnostics returned by a single tool call; the rest are
+     * summarized as an "N more" note (bounded output). */
+    maxResults: z.ZodDefault<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    startupTimeout: number;
+    requestTimeout: number;
+    servers: Record<string, string>;
+    enabled: boolean;
+    maxServers: number;
+    idleTimeout: number;
+    maxResults: number;
+}, {
+    startupTimeout?: number | undefined;
+    requestTimeout?: number | undefined;
+    servers?: Record<string, string> | undefined;
+    enabled?: boolean | undefined;
+    maxServers?: number | undefined;
+    idleTimeout?: number | undefined;
+    maxResults?: number | undefined;
+}>;
+export type LspConfig = z.infer<typeof LspConfigSchema>;
 /** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
 export declare const TierPriceSchema: z.ZodObject<{
     /** Price per 1,000,000 input tokens. */
@@ -540,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;
-    args?: 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"]>>;
@@ -742,6 +910,48 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     }>>;
+    lsp: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, the four LSP tools are not registered and no
+         * server ever spawns (the feature stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /**
+         * Per-language command overrides, keyed by language id (e.g. `typescript`,
+         * `python`, `go`, `rust`). The value is the full command line
+         * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+         * falls back to the built-in default table (see `lsp/registry.ts`).
+         */
+        servers: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+        /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+         * not complete within this many ms. */
+        startupTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+         * within this many ms — the server is kept alive, only the request errors. */
+        requestTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Maximum concurrently-running language servers; acquiring past the cap
+         * evicts the idle-oldest server first. */
+        maxServers: z.ZodDefault<z.ZodNumber>;
+        /** Shut a server down after it has been idle this many ms. */
+        idleTimeout: z.ZodDefault<z.ZodNumber>;
+        /** Cap on locations/diagnostics returned by a single tool call; the rest are
+         * summarized as an "N more" note (bounded output). */
+        maxResults: z.ZodDefault<z.ZodNumber>;
+    }, "strict", z.ZodTypeAny, {
+        startupTimeout: number;
+        requestTimeout: number;
+        servers: Record<string, string>;
+        enabled: boolean;
+        maxServers: number;
+        idleTimeout: number;
+        maxResults: number;
+    }, {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        servers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        maxServers?: number | undefined;
+        idleTimeout?: number | undefined;
+        maxResults?: number | undefined;
+    }>>;
     checkpoint: z.ZodDefault<z.ZodObject<{
         /** Auto-checkpoint before a run's first mutation (and enable `cruxy rollback`). */
         enabled: z.ZodDefault<z.ZodBoolean>;
@@ -773,9 +983,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             maxIterations: number;
             timeoutMs?: number | undefined;
         }, {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         }>>;
     }, "strict", z.ZodTypeAny, {
         maxDepth: number;
@@ -787,9 +997,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     }, {
         maxDepth?: number | undefined;
         defaultBudget?: {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         } | undefined;
     }>>;
     test: z.ZodDefault<z.ZodObject<{
@@ -804,8 +1014,8 @@ export declare const CruxyConfigSchema: z.ZodObject<{
         captureBytes: number;
         command?: string | undefined;
     }, {
-        maxIterations?: number | undefined;
         command?: string | undefined;
+        maxIterations?: number | undefined;
         captureBytes?: number | undefined;
     }>>;
     sandbox: z.ZodDefault<z.ZodObject<{
@@ -1009,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;
-        args?: string[] | undefined;
-        url?: 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;
-        args?: string[] | undefined;
-        url?: 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: {
@@ -1120,6 +1395,15 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines: number;
         };
     };
+    lsp: {
+        startupTimeout: number;
+        requestTimeout: number;
+        servers: Record<string, string>;
+        enabled: boolean;
+        maxServers: number;
+        idleTimeout: number;
+        maxResults: number;
+    };
     test: {
         maxIterations: number;
         captureBytes: number;
@@ -1133,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;
-        args?: string[] | undefined;
-        url?: 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?: {
@@ -1186,9 +1479,9 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     subagent?: {
         maxDepth?: number | undefined;
         defaultBudget?: {
+            timeoutMs?: number | undefined;
             maxTokens?: number | undefined;
             maxIterations?: number | undefined;
-            timeoutMs?: number | undefined;
         } | undefined;
     } | undefined;
     model?: {
@@ -1236,9 +1529,18 @@ export declare const CruxyConfigSchema: z.ZodObject<{
             overlapLines?: number | undefined;
         } | undefined;
     } | undefined;
+    lsp?: {
+        startupTimeout?: number | undefined;
+        requestTimeout?: number | undefined;
+        servers?: Record<string, string> | undefined;
+        enabled?: boolean | undefined;
+        maxServers?: number | undefined;
+        idleTimeout?: number | undefined;
+        maxResults?: number | undefined;
+    } | undefined;
     test?: {
-        maxIterations?: number | undefined;
         command?: string | undefined;
+        maxIterations?: number | undefined;
         captureBytes?: number | undefined;
     } | undefined;
     hooks?: {
@@ -1249,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;
-        args?: string[] | undefined;
-        url?: 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

@@ -290,6 +290,44 @@ export const MemoryConfigSchema = z
     maxRecallTokens: z.number().int().positive().default(1000),
 })
     .strict();
+/**
+ * Per-language LSP integration (C.12): read-only, symbol-aware tools
+ * (find_definition, find_references, get_diagnostics, hover) backed by a
+ * managed pool of language servers. OFF by default — like the sandbox and
+ * hooks, it spawns and manages EXTERNAL server processes, a real execution
+ * surface the user opts into explicitly. When on, a missing server binary is
+ * an actionable, coded failure (CRUXY_E_LSP_SERVER_NOT_FOUND), never a silent
+ * empty result. Servers spawn lazily per language, are reused for the session,
+ * and are shut down cleanly (with a process-exit kill-tree backstop).
+ */
+export const LspConfigSchema = z
+    .object({
+    /** Master switch. When false, the four LSP tools are not registered and no
+     * server ever spawns (the feature stays fully inert). */
+    enabled: z.boolean().default(false),
+    /**
+     * Per-language command overrides, keyed by language id (e.g. `typescript`,
+     * `python`, `go`, `rust`). The value is the full command line
+     * (`"gopls -remote=auto"`); it is split on whitespace. Anything omitted
+     * falls back to the built-in default table (see `lsp/registry.ts`).
+     */
+    servers: z.record(z.string(), z.string().min(1)).default({}),
+    /** Kill and fail (CRUXY_E_LSP_TIMEOUT) if the `initialize` handshake does
+     * not complete within this many ms. */
+    startupTimeout: z.number().int().positive().default(15000),
+    /** Fail a single query (CRUXY_E_LSP_TIMEOUT) if the server does not respond
+     * within this many ms — the server is kept alive, only the request errors. */
+    requestTimeout: z.number().int().positive().default(10000),
+    /** Maximum concurrently-running language servers; acquiring past the cap
+     * evicts the idle-oldest server first. */
+    maxServers: z.number().int().positive().default(4),
+    /** Shut a server down after it has been idle this many ms. */
+    idleTimeout: z.number().int().positive().default(300000),
+    /** Cap on locations/diagnostics returned by a single tool call; the rest are
+     * summarized as an "N more" note (bounded output). */
+    maxResults: z.number().int().positive().default(100),
+})
+    .strict();
 /** A per-tier price, in the user's own currency, PER MILLION TOKENS (C.22). */
 export const TierPriceSchema = z
     .object({
@@ -327,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
@@ -346,6 +435,7 @@ export const CruxyConfigSchema = z
     context: ContextConfigSchema.default({}),
     approval: ApprovalConfigSchema.default({}),
     index: IndexConfigSchema.default({}),
+    lsp: LspConfigSchema.default({}),
     checkpoint: CheckpointConfigSchema.default({}),
     subagent: SubagentConfigSchema.default({}),
     test: TestConfigSchema.default({}),
@@ -354,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