@cruxy/cli 0.20.0 → 0.21.0

package/dist/approval/classify.js

@@ -22,6 +22,8 @@ export function classify(action, cwd) {
             return vcsRequest(action, root);
         case "rollback":
             return rollbackRequest(action, root);
+        case "mcp":
+            return mcpRequest(action, root);
         default:
             return {
                 action,
@@ -132,6 +134,28 @@ function rollbackRequest(action, root) {
         cwd: root,
     };
 }
+// ── mcp (call an external MCP server's tool, C.27) ──────────────────────────────
+/**
+ * An MCP tool call. Always `destructive` — the tool is arbitrary code in a
+ * trusted-but-external server, running UNSANDBOXED. Crucially, the classifier
+ * NEVER consults the server's `readOnlyHint` (or any server-supplied
+ * annotation): a server cannot mark its own tool low-risk, so this can only ever
+ * be destructive. Grantable at the tightest scope — the exact server+tool pair —
+ * so approving one MCP tool for the session never widens to any other tool.
+ */
+function mcpRequest(action, root) {
+    const server = action.server ?? "";
+    const tool = action.tool ?? "";
+    const grantable = server !== "" && tool !== "";
+    return {
+        action,
+        tier: "destructive",
+        scope: grantable ? { kind: "mcp-tool", server, tool } : { kind: "none" },
+        summary: `call MCP tool ${tool || "(unknown)"} on server ${server || "(unknown)"}`,
+        targets: [],
+        cwd: root,
+    };
+}
 // ── file (write / edit / patch) ────────────────────────────────────────────────
 function fileRequest(action, tier, root) {
     const targets = fileTargets(action, root);

package/dist/approval/policy.js

@@ -44,6 +44,13 @@ export function scopeCovers(scope, request) {
         return (request.action.kind === "test" &&
             (request.action.command ?? "").trim() === scope.command);
     }
+    if (scope.kind === "mcp-tool") {
+        // MCP grants (C.27): the exact server+tool pair, mcp actions only — a grant
+        // for one server's tool can never cover another tool or another server.
+        return (request.action.kind === "mcp" &&
+            request.action.server === scope.server &&
+            request.action.tool === scope.tool);
+    }
     // file-subtree
     return (request.targets.length > 0 &&
         request.targets.every((t) => isInside(scope.root, t)));

package/dist/approval/prompt.js

@@ -69,6 +69,11 @@ function detail(request, t) {
             `  ${t.muted(`in ${request.cwd}`)}`,
         ].join("\n");
     }
+    if (request.action.kind === "mcp") {
+        // The server runs UNSANDBOXED with the user's privileges — say so at the
+        // point of the call, not just at trust time.
+        return `  ${t.muted(`external MCP server "${request.action.server ?? ""}" — runs unsandboxed with your privileges`)}`;
+    }
     return renderActionPreview(request.action.preview, t);
 }
 /** The choices line, including a short label of what an `a` grant would cover. */
@@ -87,6 +92,8 @@ function scopeLabel(scope) {
         return `re-runs of \`${scope.command}\``;
     if (scope.kind === "file-subtree")
         return `changes under ${path.basename(scope.root)}/`;
+    if (scope.kind === "mcp-tool")
+        return `re-calls of \`${scope.tool}\` on ${scope.server}`;
     return null;
 }
 // ── default stdin-backed PromptIO ──────────────────────────────────────────────

package/dist/approval/types.d.ts

@@ -21,6 +21,8 @@ export type RiskTier = "read" | "mutate" | "destructive";
  *   a grant covers re-runs of precisely that test command, nothing else.
  * - `file-subtree` — an absolute directory (or, under the root-cap, an exact
  *   file path); matches targets that resolve inside it.
+ * - `mcp-tool` — one exact MCP server+tool pair (C.27): a grant covers re-calls
+ *   of precisely that tool on that server, and never any other MCP tool.
  * - `none` — nothing safe to grant (e.g. a multi-file patch spanning the root).
  */
 export type Scope = {
@@ -32,6 +34,10 @@ export type Scope = {
 } | {
     readonly kind: "file-subtree";
     readonly root: string;
+} | {
+    readonly kind: "mcp-tool";
+    readonly server: string;
+    readonly tool: string;
 } | {
     readonly kind: "none";
 };

package/dist/brand/voice.d.ts

@@ -49,7 +49,7 @@ export interface ForbiddenTerm {
  * Deprecated synonyms banned from user-facing copy. Scoped to the curated
  * surfaces the lexicon test scans (command descriptions, error output, brand +
  * onboarding constants) — NOT a raw source grep — so legitimate internal uses
- * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * (`mcp.servers` config key, docker `.Server.Version`, code comments) never
  * false-trip, while every string a user reads is covered.
  */
 export declare const FORBIDDEN_TERMS: readonly ForbiddenTerm[];

package/dist/brand/voice.js

@@ -40,7 +40,7 @@ export const CANONICAL_TERMS = {
  * Deprecated synonyms banned from user-facing copy. Scoped to the curated
  * surfaces the lexicon test scans (command descriptions, error output, brand +
  * onboarding constants) — NOT a raw source grep — so legitimate internal uses
- * (`mcpServers` config key, docker `.Server.Version`, code comments) never
+ * (`mcp.servers` config key, docker `.Server.Version`, code comments) never
  * false-trip, while every string a user reads is covered.
  */
 export const FORBIDDEN_TERMS = [

package/dist/cli/commands/mcp.d.ts

@@ -0,0 +1,9 @@
+import { Command } from "commander";
+/**
+ * `cruxy mcp` — inspect and control MCP server integration (C.27). `list` shows
+ * the configured servers and whether this repo's config is trusted; `trust`
+ * records the explicit decision to connect them, bound to the current config
+ * fingerprint. Trusting a server runs its code UNSANDBOXED with your privileges,
+ * so `trust` restates that plainly before recording.
+ */
+export declare function mcpCommand(): Command;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,87 @@
+import path from "node:path";
+import { Command } from "commander";
+import { loadConfig } from "../../config/index.js";
+import { shouldUseColor } from "../../errors/index.js";
+import { themeForColor } from "../../theme/index.js";
+import { fileMcpTrustStore, fingerprintMcpServers, isMcpTrusted, } from "../../mcp/index.js";
+import { logger } from "../../utils/logger.js";
+/**
+ * `cruxy mcp` — inspect and control MCP server integration (C.27). `list` shows
+ * the configured servers and whether this repo's config is trusted; `trust`
+ * records the explicit decision to connect them, bound to the current config
+ * fingerprint. Trusting a server runs its code UNSANDBOXED with your privileges,
+ * so `trust` restates that plainly before recording.
+ */
+export function mcpCommand() {
+    const cmd = new Command("mcp").description("inspect and control MCP integrations");
+    cmd
+        .command("list", { isDefault: true })
+        .description("list configured MCP integrations and their trust status")
+        .action(() => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const servers = config.mcp.servers;
+        const names = Object.keys(servers);
+        logger.print(`${t.strong("mcp:")} ${config.mcp.enabled ? t.success("enabled") : t.warning("disabled (mcp.enabled = false)")}`);
+        if (names.length === 0) {
+            logger.print(t.muted("\nno MCP servers configured (mcp.servers)"));
+            return;
+        }
+        const root = path.resolve(process.cwd());
+        const trusted = isMcpTrusted(fileMcpTrustStore(), root, fingerprintMcpServers(servers));
+        const trustLabel = trusted
+            ? t.success("trusted — will connect")
+            : t.danger("NOT trusted — will not connect; run `cruxy mcp trust .`");
+        logger.print(`\n${t.heading("servers")} ${trustLabel}`);
+        for (const [name, cfg] of Object.entries(servers)) {
+            logger.print(`  ${t.strong(name)} ${t.muted(describeServer(cfg))}`);
+        }
+    });
+    cmd
+        .command("trust [path]")
+        .description("trust this repo's MCP integrations (they run with your full privileges)")
+        .action((target) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const { config } = loadConfig();
+        const servers = config.mcp.servers;
+        const root = path.resolve(target ?? process.cwd());
+        const names = Object.keys(servers);
+        if (names.length === 0) {
+            logger.print(t.muted(`no MCP servers configured under ${root}`));
+            return;
+        }
+        logger.print(t.danger(t.strong(`trusting ${names.length} MCP server${names.length === 1 ? "" : "s"} — these run their own code UNSANDBOXED with your privileges:`)));
+        for (const [name, cfg] of Object.entries(servers)) {
+            logger.print(`  ${t.strong(name)} ${t.muted(describeServer(cfg))}`);
+        }
+        fileMcpTrustStore().record({
+            root,
+            fingerprint: fingerprintMcpServers(servers),
+            at: new Date().toISOString(),
+        });
+        logger.print(`${t.success("trusted")} — cruxy will connect these servers for ${root}. ` +
+            t.muted("changing the config will require re-trusting."));
+    });
+    cmd
+        .command("untrust [path]")
+        .description("clear MCP trust for this repo so cruxy stops connecting")
+        .action((target) => {
+        const t = themeForColor(shouldUseColor(process.stdout));
+        const root = path.resolve(target ?? process.cwd());
+        // Recording an unmatchable fingerprint makes the current config stale
+        // (isMcpTrusted requires an exact match), so servers stop connecting.
+        fileMcpTrustStore().record({
+            root,
+            fingerprint: "revoked",
+            at: new Date().toISOString(),
+        });
+        logger.print(`${t.success("untrusted")} — MCP servers for ${root} will no longer connect until re-trusted`);
+    });
+    return cmd;
+}
+function describeServer(cfg) {
+    if (cfg.command) {
+        return `(stdio: ${[cfg.command, ...(cfg.args ?? [])].join(" ")})`;
+    }
+    return cfg.url ? `(url: ${cfg.url})` : "(no transport)";
+}

package/dist/cli/commands/run.js

@@ -12,6 +12,8 @@ import { runInteractive } from "../repl.js";
 import { buildAgentSession } from "../session-factory.js";
 import { apiKeyEnvVar, maybeRunOnboarding } from "../onboard.js";
 import { resetLspServices } from "../../lsp/index.js";
+import { connectMcpTools, resetMcpServices } from "../../mcp/index.js";
+import { defaultPromptIO } from "../../approval/index.js";
 export function runCommand() {
     return new Command("run")
         .description("run a task once, or start an interactive session")
@@ -91,15 +93,28 @@ export function runCommand() {
             interactive: Boolean(process.stdin.isTTY),
             logger,
         });
-        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner);
+        // MCP servers (C.27): connect + trust-gate BEFORE building the session so
+        // the tool catalogue is complete when the model first runs. Off by
+        // default (no servers connect). A non-interactive run with an untrusted
+        // config THROWS CRUXY_E_MCP_UNTRUSTED here — before any server spawns.
+        const mcp = await connectMcpTools({
+            cwd: process.cwd(),
+            config,
+            logger,
+            interactive: Boolean(process.stdin.isTTY),
+            io: defaultPromptIO(shouldUseColor()),
+        });
+        const session = buildAgentSession(config, apiKey, process.cwd(), Boolean(process.stdin.isTTY), planMode, renderer, checkpoints, sandbox, hooksService.runner, mcp.tools);
         if (interactive) {
             try {
                 await runInteractive(session, undefined, renderer, checkpoints, hooksService.commands);
             }
             finally {
-                // LSP (C.12): gracefully shut down any language servers spawned
-                // during the session (the process-exit kill-tree is the fail-safe).
+                // LSP (C.12) + MCP (C.27): gracefully shut down any external server
+                // processes spawned during the session (the shared process-exit
+                // kill-tree is the fail-safe for a hard kill).
                 await resetLspServices();
+                await resetMcpServices();
             }
             return;
         }
@@ -118,9 +133,11 @@ export function runCommand() {
         }
         finally {
             renderer.close();
-            // LSP (C.12): gracefully shut down any language servers spawned during
-            // the run (the process-exit kill-tree is the fail-safe for a hard kill).
+            // LSP (C.12) + MCP (C.27): gracefully shut down any external server
+            // processes spawned during the run (the shared process-exit kill-tree
+            // is the fail-safe for a hard kill).
             await resetLspServices();
+            await resetMcpServices();
         }
         // End-of-run usage summary (C.22): honest tokens + per-tier breakdown +
         // cost (only when priced). Printed after the live region is torn down.

package/dist/cli/program.js

@@ -17,6 +17,7 @@ import { testCommand } from "./commands/test.js";
 import { hooksCommand } from "./commands/hooks.js";
 import { memoryCommand } from "./commands/memory.js";
 import { usageCommand } from "./commands/usage.js";
+import { mcpCommand } from "./commands/mcp.js";
 import { loadConfig } from "../config/index.js";
 import { maybeRunOnboarding } from "./onboard.js";
 export function buildProgram() {
@@ -49,6 +50,7 @@ export function buildProgram() {
     program.addCommand(hooksCommand());
     program.addCommand(memoryCommand());
     program.addCommand(usageCommand());
+    program.addCommand(mcpCommand());
     // Default action: bare `cruxy` -> entrypoint. An unrecognized first operand
     // means an unknown command (Commander runs the default action with it as an
     // operand rather than erroring), so reject it as a usage error.

package/dist/cli/session-factory.d.ts

@@ -3,7 +3,7 @@ import type { ApprovalDecision } from "../approval/index.js";
 import type { CheckpointService } from "../checkpoint/index.js";
 import type { SandboxService } from "../sandbox/index.js";
 import type { StreamRenderer } from "../render/index.js";
-import { type ApproveAction } from "../tools/index.js";
+import { type ApproveAction, type Tool } from "../tools/index.js";
 import { Session, type LifecycleHookRunner } from "../agent/index.js";
 /**
  * Wrap the approval gate with the C.32 auto-checkpoint hook. Ordering is the
@@ -24,4 +24,4 @@ export declare function withCheckpointGate(requestApproval: (action: ApproveActi
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner): Session;
+export declare function buildAgentSession(config: CruxyConfig, apiKey: string, cwd: string, ttyInteractive: boolean, planMode?: boolean, renderer?: StreamRenderer, checkpoints?: CheckpointService, sandbox?: SandboxService, hooks?: LifecycleHookRunner, mcpTools?: Tool[]): Session;

package/dist/cli/session-factory.js

@@ -4,7 +4,7 @@ import { logger } from "../utils/logger.js";
 import { getGitInfo } from "../utils/git.js";
 import { ApprovalService, InteractivePolicy, SessionAllowlist, classify, defaultPromptIO, } from "../approval/index.js";
 import { shouldUseColor } from "../errors/index.js";
-import { buildDefaultRegistry } from "../tools/index.js";
+import { buildDefaultRegistry, } from "../tools/index.js";
 import { Session, } from "../agent/index.js";
 import { PlanExecutionPolicy, runPlanSession } from "../plan/index.js";
 import { routerForConfig } from "../routing/index.js";
@@ -91,7 +91,7 @@ export function withCheckpointGate(requestApproval, checkpoints, cwd) {
  * over the shared U.3 allowlist and a `planRunner` so `session.send` proposes →
  * approves → executes. Plan mode is fully opt-in; the default path is unchanged.
  */
-export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks) {
+export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode = false, renderer, checkpoints, sandbox, hooks, mcpTools = []) {
     const provider = createProvider({
         provider: config.model.provider,
         apiKey,
@@ -148,6 +148,13 @@ export function buildAgentSession(config, apiKey, cwd, ttyInteractive, planMode
         execRegistry.register(getDiagnosticsTool);
         execRegistry.register(hoverTool);
     }
+    // MCP servers (C.27): the caller connected + trusted the servers and produced
+    // these tools through the single adapter seam BEFORE building the session, so
+    // registration here is a plain hand-off — every one is destructive-gated,
+    // demarcated, and bounded by construction. Empty unless `mcp.enabled` and at
+    // least one trusted server produced tools, so the default path is unchanged.
+    for (const tool of mcpTools)
+        execRegistry.register(tool);
     // One io shared by every prompt in the session (plan approval, the U.3 gate,
     // and any gate inside a subagent), so they all coordinate with the same live
     // region. The full wrapper stack around an ApprovalService is factored here