@cruxy/cli 0.20.0 → 0.22.0

package/dist/config/schema.d.ts

@@ -44,15 +44,12 @@ export declare const AgentConfigSchema: z.ZodObject<{
 export declare const ToolsConfigSchema: z.ZodObject<{
     fileEdit: z.ZodDefault<z.ZodBoolean>;
     shell: z.ZodDefault<z.ZodBoolean>;
-    webSearch: z.ZodDefault<z.ZodBoolean>;
 }, "strict", z.ZodTypeAny, {
     fileEdit: boolean;
     shell: boolean;
-    webSearch: boolean;
 }, {
     fileEdit?: boolean | undefined;
     shell?: boolean | undefined;
-    webSearch?: boolean | undefined;
 }>;
 export declare const GitConfigSchema: z.ZodObject<{
     autoCommit: z.ZodDefault<z.ZodBoolean>;
@@ -446,16 +443,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 +590,198 @@ 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>;
+/**
+ * Web-search + web-fetch subtool (C.20). OFF by default. When enabled, the agent
+ * gets a bounded `web_search` (query → ranked title/url/snippet) and a `web_fetch`
+ * (read one URL as text). Both surface EXTERNAL, attacker-controllable data:
+ * results and fetched pages are wrapped as untrusted data (do-not-follow-instructions
+ * envelope, fence-forgery neutralized) with upstream model names scrubbed, and
+ * are NEVER persisted to memory/index/checkpoint. `web_fetch` refuses non-http(s)
+ * schemes and any host that resolves into a private/loopback/link-local range
+ * (SSRF guard) — the request is never dispatched. No provider is constructed and
+ * no tool is registered while this is off. Search runs through a swappable
+ * `SearchProvider` seam; the direct provider's API key comes from the environment
+ * (`apiKeyEnv`), never from config-in-repo and never logged.
+ */
+export declare const WebConfigSchema: z.ZodObject<{
+    /** Master switch. When false, neither tool is registered and no provider is
+     * constructed (the feature stays fully inert). */
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    /** Which search backend to use behind the `SearchProvider` seam. A gateway
+     * provider slots in here first-class if the backend ever proxies search. */
+    provider: z.ZodDefault<z.ZodEnum<["tavily"]>>;
+    /** Environment variable holding the direct provider's API key. The key is
+     * read at call time, sent only in the provider's auth field, and never
+     * logged or written to the repo. */
+    apiKeyEnv: z.ZodDefault<z.ZodString>;
+    /** Max search results returned to the model (top-N; the rest are dropped). */
+    maxResults: z.ZodDefault<z.ZodNumber>;
+    /** Max characters kept from a single result's snippet; the rest is truncated
+     * with a visible marker. */
+    snippetMaxChars: z.ZodDefault<z.ZodNumber>;
+    /** Max bytes read from a single `web_fetch` page; the rest is truncated with
+     * a visible marker (a hostile/huge page can't blow the context budget). */
+    fetchMaxBytes: z.ZodDefault<z.ZodNumber>;
+    /** Per-request timeout (search and fetch) — a slow host errors, never hangs. */
+    timeoutMs: z.ZodDefault<z.ZodNumber>;
+    /** Max HTTP redirects `web_fetch` follows; each hop is re-checked by the SSRF
+     * guard so a 3xx can't bounce the request into a private range. */
+    maxRedirects: z.ZodDefault<z.ZodNumber>;
+    /** Escape hatch: allow `web_fetch` to reach private/loopback/link-local hosts.
+     * OFF by default (SSRF-safe); only set true for a deliberate internal-network
+     * use case. */
+    allowPrivateHosts: z.ZodDefault<z.ZodBoolean>;
+}, "strict", z.ZodTypeAny, {
+    provider: "tavily";
+    timeoutMs: number;
+    apiKeyEnv: string;
+    enabled: boolean;
+    maxResults: number;
+    snippetMaxChars: number;
+    fetchMaxBytes: number;
+    maxRedirects: number;
+    allowPrivateHosts: boolean;
+}, {
+    provider?: "tavily" | undefined;
+    timeoutMs?: number | undefined;
+    apiKeyEnv?: string | undefined;
+    enabled?: boolean | undefined;
+    maxResults?: number | undefined;
+    snippetMaxChars?: number | undefined;
+    fetchMaxBytes?: number | undefined;
+    maxRedirects?: number | undefined;
+    allowPrivateHosts?: boolean | undefined;
+}>;
+export type WebConfig = z.infer<typeof WebConfigSchema>;
 export declare const CruxyConfigSchema: z.ZodObject<{
     model: z.ZodDefault<z.ZodObject<{
         provider: z.ZodDefault<z.ZodEnum<["cruxy", "anthropic", "openai", "custom"]>>;
@@ -650,15 +825,12 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     tools: z.ZodDefault<z.ZodObject<{
         fileEdit: z.ZodDefault<z.ZodBoolean>;
         shell: z.ZodDefault<z.ZodBoolean>;
-        webSearch: z.ZodDefault<z.ZodBoolean>;
     }, "strict", z.ZodTypeAny, {
         fileEdit: boolean;
         shell: boolean;
-        webSearch: boolean;
     }, {
         fileEdit?: boolean | undefined;
         shell?: boolean | undefined;
-        webSearch?: boolean | undefined;
     }>>;
     git: z.ZodDefault<z.ZodObject<{
         autoCommit: z.ZodDefault<z.ZodBoolean>;
@@ -823,16 +995,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 +1276,133 @@ 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;
+    }>>;
+    web: z.ZodDefault<z.ZodObject<{
+        /** Master switch. When false, neither tool is registered and no provider is
+         * constructed (the feature stays fully inert). */
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        /** Which search backend to use behind the `SearchProvider` seam. A gateway
+         * provider slots in here first-class if the backend ever proxies search. */
+        provider: z.ZodDefault<z.ZodEnum<["tavily"]>>;
+        /** Environment variable holding the direct provider's API key. The key is
+         * read at call time, sent only in the provider's auth field, and never
+         * logged or written to the repo. */
+        apiKeyEnv: z.ZodDefault<z.ZodString>;
+        /** Max search results returned to the model (top-N; the rest are dropped). */
+        maxResults: z.ZodDefault<z.ZodNumber>;
+        /** Max characters kept from a single result's snippet; the rest is truncated
+         * with a visible marker. */
+        snippetMaxChars: z.ZodDefault<z.ZodNumber>;
+        /** Max bytes read from a single `web_fetch` page; the rest is truncated with
+         * a visible marker (a hostile/huge page can't blow the context budget). */
+        fetchMaxBytes: z.ZodDefault<z.ZodNumber>;
+        /** Per-request timeout (search and fetch) — a slow host errors, never hangs. */
+        timeoutMs: z.ZodDefault<z.ZodNumber>;
+        /** Max HTTP redirects `web_fetch` follows; each hop is re-checked by the SSRF
+         * guard so a 3xx can't bounce the request into a private range. */
+        maxRedirects: z.ZodDefault<z.ZodNumber>;
+        /** Escape hatch: allow `web_fetch` to reach private/loopback/link-local hosts.
+         * OFF by default (SSRF-safe); only set true for a deliberate internal-network
+         * use case. */
+        allowPrivateHosts: z.ZodDefault<z.ZodBoolean>;
+    }, "strict", z.ZodTypeAny, {
+        provider: "tavily";
+        timeoutMs: number;
+        apiKeyEnv: string;
+        enabled: boolean;
+        maxResults: number;
+        snippetMaxChars: number;
+        fetchMaxBytes: number;
+        maxRedirects: number;
+        allowPrivateHosts: boolean;
+    }, {
+        provider?: "tavily" | undefined;
+        timeoutMs?: number | undefined;
+        apiKeyEnv?: string | undefined;
+        enabled?: boolean | undefined;
+        maxResults?: number | undefined;
+        snippetMaxChars?: number | undefined;
+        fetchMaxBytes?: number | undefined;
+        maxRedirects?: number | undefined;
+        allowPrivateHosts?: boolean | undefined;
+    }>>;
     logLevel: z.ZodDefault<z.ZodEnum<["debug", "info", "warn", "error", "silent"]>>;
 }, "strict", z.ZodTypeAny, {
     cruxy: {
@@ -1188,7 +1474,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     tools: {
         fileEdit: boolean;
         shell: boolean;
-        webSearch: boolean;
     };
     git: {
         autoCommit: boolean;
@@ -1218,8 +1503,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 +1522,31 @@ 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;
+    };
+    web: {
+        provider: "tavily";
+        timeoutMs: number;
+        apiKeyEnv: string;
+        enabled: boolean;
+        maxResults: number;
+        snippetMaxChars: number;
+        fetchMaxBytes: number;
+        maxRedirects: number;
+        allowPrivateHosts: boolean;
+    };
     logLevel: "debug" | "info" | "warn" | "error" | "silent";
 }, {
     cruxy?: {
@@ -1313,7 +1618,6 @@ export declare const CruxyConfigSchema: z.ZodObject<{
     tools?: {
         fileEdit?: boolean | undefined;
         shell?: boolean | undefined;
-        webSearch?: boolean | undefined;
     } | undefined;
     git?: {
         autoCommit?: boolean | undefined;
@@ -1343,8 +1647,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 +1666,31 @@ 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;
+    web?: {
+        provider?: "tavily" | undefined;
+        timeoutMs?: number | undefined;
+        apiKeyEnv?: string | undefined;
+        enabled?: boolean | undefined;
+        maxResults?: number | undefined;
+        snippetMaxChars?: number | undefined;
+        fetchMaxBytes?: number | undefined;
+        maxRedirects?: number | undefined;
+        allowPrivateHosts?: boolean | undefined;
+    } | undefined;
     logLevel?: "debug" | "info" | "warn" | "error" | "silent" | undefined;
 }>;
 export type CruxyConfig = z.infer<typeof CruxyConfigSchema>;

package/dist/config/schema.js

@@ -38,7 +38,6 @@ export const ToolsConfigSchema = z
     .object({
     fileEdit: z.boolean().default(true),
     shell: z.boolean().default(true),
-    webSearch: z.boolean().default(false), // C.17
 })
     .strict();
 export const GitConfigSchema = z
@@ -365,12 +364,107 @@ 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();
+/**
+ * Web-search + web-fetch subtool (C.20). OFF by default. When enabled, the agent
+ * gets a bounded `web_search` (query → ranked title/url/snippet) and a `web_fetch`
+ * (read one URL as text). Both surface EXTERNAL, attacker-controllable data:
+ * results and fetched pages are wrapped as untrusted data (do-not-follow-instructions
+ * envelope, fence-forgery neutralized) with upstream model names scrubbed, and
+ * are NEVER persisted to memory/index/checkpoint. `web_fetch` refuses non-http(s)
+ * schemes and any host that resolves into a private/loopback/link-local range
+ * (SSRF guard) — the request is never dispatched. No provider is constructed and
+ * no tool is registered while this is off. Search runs through a swappable
+ * `SearchProvider` seam; the direct provider's API key comes from the environment
+ * (`apiKeyEnv`), never from config-in-repo and never logged.
+ */
+export const WebConfigSchema = z
+    .object({
+    /** Master switch. When false, neither tool is registered and no provider is
+     * constructed (the feature stays fully inert). */
+    enabled: z.boolean().default(false),
+    /** Which search backend to use behind the `SearchProvider` seam. A gateway
+     * provider slots in here first-class if the backend ever proxies search. */
+    provider: z.enum(["tavily"]).default("tavily"),
+    /** Environment variable holding the direct provider's API key. The key is
+     * read at call time, sent only in the provider's auth field, and never
+     * logged or written to the repo. */
+    apiKeyEnv: z.string().min(1).default("TAVILY_API_KEY"),
+    /** Max search results returned to the model (top-N; the rest are dropped). */
+    maxResults: z.number().int().positive().max(20).default(5),
+    /** Max characters kept from a single result's snippet; the rest is truncated
+     * with a visible marker. */
+    snippetMaxChars: z.number().int().positive().default(500),
+    /** Max bytes read from a single `web_fetch` page; the rest is truncated with
+     * a visible marker (a hostile/huge page can't blow the context budget). */
+    fetchMaxBytes: z.number().int().positive().default(524288),
+    /** Per-request timeout (search and fetch) — a slow host errors, never hangs. */
+    timeoutMs: z.number().int().positive().default(15000),
+    /** Max HTTP redirects `web_fetch` follows; each hop is re-checked by the SSRF
+     * guard so a 3xx can't bounce the request into a private range. */
+    maxRedirects: z.number().int().min(0).default(3),
+    /** Escape hatch: allow `web_fetch` to reach private/loopback/link-local hosts.
+     * OFF by default (SSRF-safe); only set true for a deliberate internal-network
+     * use case. */
+    allowPrivateHosts: z.boolean().default(false),
 })
     .strict();
 export const CruxyConfigSchema = z
@@ -393,7 +487,8 @@ export const CruxyConfigSchema = z
     routing: RoutingConfigSchema.default({}),
     memory: MemoryConfigSchema.default({}),
     usage: UsageConfigSchema.default({}),
-    mcpServers: z.record(z.string(), McpServerSchema).default({}),
+    mcp: McpConfigSchema.default({}),
+    web: WebConfigSchema.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