refactor(mcp): adopt Clack gutter/rail conventions for install/list/uninstall

Follow the patterns the #305 Clack migration established: wrap install/list/uninstall human flows in withGutter() (guaranteed intro/outro cleanup, paused/failed outros on abort/error), render next steps via outro([...]) instead of a custom printNextSteps helper, and render the list table through the ui.* prompt rail (ui.message) like apps/list. No behavior change to JSON/agent output.

Author: rafa-thayto

packages/cli-core/src/commands/mcp/install.test.ts

@@ -171,21 +171,21 @@ describe("mcp install", () => {
 
   test("prints next steps with a sign-in reminder after a human-mode install", async () => {
     await mcpInstall({ client: ["cursor"], url: URL_A });
-    expect(captured.err).toContain("Next steps:");
+    expect(captured.err).toContain("Next steps");
     expect(captured.err).toContain("Reload Cursor");
     expect(captured.err).toContain("sign in");
   });
 
   test("omits next steps from JSON output", async () => {
     await mcpInstall({ client: ["cursor"], url: URL_A, json: true });
-    expect(captured.err).not.toContain("Next steps:");
+    expect(captured.err).not.toContain("Next steps");
   });
 
   test("does not print next steps when the entry was unchanged", async () => {
     await mcpInstall({ client: ["cursor"], url: URL_A });
     captured.clear();
     await mcpInstall({ client: ["cursor"], url: URL_A });
-    expect(captured.err).not.toContain("Next steps:");
+    expect(captured.err).not.toContain("Next steps");
   });
 
   test("rejects an unknown --client id", async () => {

packages/cli-core/src/commands/mcp/install.ts

@@ -8,11 +8,10 @@
 
 import { log } from "../../lib/log.ts";
 import { cyan, dim, green, yellow } from "../../lib/color.ts";
-import { isAgent, isHuman } from "../../mode.ts";
-import { intro, outro } from "../../lib/spinner.ts";
+import { isAgent } from "../../mode.ts";
+import { withGutter } from "../../lib/spinner.ts";
 import {
   pickClients,
-  printNextSteps,
   resolveName,
   resolveUrl,
   settleClients,
@@ -55,18 +54,15 @@ type ClientUpsert = { client: McpClient; result: UpsertResult };
 // Writing the config isn't enough — the editor must reload before it connects
 // (and sign in, if the server requires it). Surface that for every client we
 // just wrote, so "added" doesn't read as "done and working".
-function printInstallNextSteps(settled: ClientUpsert[]): void {
+function installNextSteps(settled: ClientUpsert[]): string[] {
   const activated = settled.filter(
     ({ result }) => result.status === "added" || result.status === "updated",
   );
-  if (activated.length === 0) return;
-
-  printNextSteps(activated.map(({ client }) => `${client.displayName}: ${client.activation}`));
-  log.info(
-    dim(
-      "If the server requires authentication, your editor opens a browser to sign in on first connect.",
-    ),
-  );
+  if (activated.length === 0) return [];
+  return [
+    ...activated.map(({ client }) => `${client.displayName}: ${client.activation}`),
+    "If the server requires authentication, your editor opens a browser to sign in on first connect.",
+  ];
 }
 
 export async function mcpInstall(options: McpOptions = {}): Promise<void> {
@@ -77,26 +73,24 @@ export async function mcpInstall(options: McpOptions = {}): Promise<void> {
   const force = Boolean(options.force);
   const json = wantsJson(options);
 
-  if (clients.length === 0 && json) {
-    log.data(JSON.stringify({ url, name, results: [] }, null, 2));
-    return;
-  }
   if (clients.length === 0) {
-    log.warn("No MCP clients selected.");
-    return;
-  }
-
-  if (isHuman() && !json) intro(`Installing Clerk MCP (${cyan(url)})`);
-
-  const settled = await settleClients(clients, (c) => c.upsert({ name, url }, cwd, force));
-  const results = settled.map((s) => s.result);
-
-  if (json) {
-    log.data(JSON.stringify({ url, name, results }, null, 2));
+    if (json) log.data(JSON.stringify({ url, name, results: [] }, null, 2));
+    else log.warn("No MCP clients selected.");
     return;
   }
 
-  settled.forEach(({ client, result }) => printResult(client, result));
-  printInstallNextSteps(settled);
-  outro("Done");
+  await withGutter(
+    `Installing Clerk MCP (${cyan(url)})`,
+    async ({ setNextSteps }) => {
+      const settled = await settleClients(clients, (c) => c.upsert({ name, url }, cwd, force));
+      if (json) {
+        log.data(JSON.stringify({ url, name, results: settled.map((s) => s.result) }, null, 2));
+        return;
+      }
+      settled.forEach(({ client, result }) => printResult(client, result));
+      const steps = installNextSteps(settled);
+      if (steps.length > 0) setNextSteps(steps);
+    },
+    { skip: json },
+  );
 }

packages/cli-core/src/commands/mcp/list.test.ts

@@ -2,7 +2,7 @@ import { afterEach, beforeEach, describe, expect, mock, test } from "bun:test";
 import { mkdtemp, rm } from "node:fs/promises";
 import * as realOs from "node:os";
 import { join } from "node:path";
-import { useCaptureLog } from "../../test/lib/stubs.ts";
+import { captureUi, useCaptureLog } from "../../test/lib/stubs.ts";
 
 const mockIsAgent = mock();
 mock.module("../../mode.ts", () => ({
@@ -24,6 +24,7 @@ const URL = "https://mcp.clerk.com/mcp";
 
 describe("mcp list", () => {
   const captured = useCaptureLog();
+  let uiCapture: ReturnType<typeof captureUi>;
   let cwd: string;
   let originalCwd: string;
 
@@ -32,10 +33,13 @@ describe("mcp list", () => {
     cwd = await mkdtemp(join(realOs.tmpdir(), "clerk-mcp-list-"));
     mockHome = cwd;
     process.chdir(cwd);
+    uiCapture = captureUi();
+    uiCapture.install();
     mockIsAgent.mockReturnValue(true);
   });
 
   afterEach(async () => {
+    uiCapture.teardown();
     process.chdir(originalCwd);
     await rm(cwd, { recursive: true, force: true });
     mockIsAgent.mockReset();
@@ -60,25 +64,27 @@ describe("mcp list", () => {
     ]);
   });
 
-  test("human-mode empty state writes the hint to stderr, nothing to stdout", async () => {
+  test("human-mode empty state shows the hint on the prompt rail, nothing to stdout", async () => {
     mockIsAgent.mockReturnValue(false);
     await mcpList({});
     expect(captured.out).toBe("");
-    expect(captured.err).toContain("No Clerk MCP entries");
+    expect(uiCapture.out).toContain("No Clerk MCP entries");
   });
 
-  test("human-mode prints the formatted table to stdout after an install", async () => {
+  test("human-mode renders the table and next steps after an install", async () => {
     mockIsAgent.mockReturnValue(true);
     await mcpInstall({ client: ["cursor"], url: URL });
     mockIsAgent.mockReturnValue(false);
     captured.clear();
     await mcpList({});
 
-    expect(captured.out).toContain("cursor");
-    expect(captured.out).toContain("clerk");
-    expect(captured.out).toContain(URL);
-    expect(captured.err).toContain("1 entry");
-    expect(captured.err).toContain("Next steps:");
-    expect(captured.err).toContain("clerk doctor");
+    // Table, count, and the outro next-steps all render on the clack prompt
+    // rail; with captureUi installed, intro/outro write to that stream too.
+    expect(uiCapture.out).toContain("cursor");
+    expect(uiCapture.out).toContain("clerk");
+    expect(uiCapture.out).toContain(URL);
+    expect(uiCapture.out).toContain("1 entry");
+    expect(uiCapture.out).toContain("Next steps");
+    expect(uiCapture.out).toContain("clerk doctor");
   });
 });

packages/cli-core/src/commands/mcp/list.ts

@@ -7,9 +7,11 @@
 
 import { cyan, dim } from "../../lib/color.ts";
 import { log } from "../../lib/log.ts";
+import { withGutter } from "../../lib/spinner.ts";
+import { ui } from "../../lib/ui.ts";
 import type { ListEntry } from "./clients/types.ts";
 import { collectEntries } from "./collect.ts";
-import { printNextSteps, wantsJson, type McpOptions } from "./shared.ts";
+import { wantsJson, type McpOptions } from "./shared.ts";
 
 const COLUMN_PADDING = 2;
 
@@ -31,36 +33,35 @@ function formatTable(entries: ListEntry[]): void {
     entries.map((e) => e.url),
   );
 
-  log.data(
-    dim(`${"CLIENT".padEnd(clientWidth)}${"NAME".padEnd(nameWidth)}${"URL".padEnd(urlWidth)}PATH`),
-  );
-  for (const entry of entries) {
-    const client = cyan(entry.client.padEnd(clientWidth));
-    const name = entry.name.padEnd(nameWidth);
-    const url = entry.url.padEnd(urlWidth);
-    log.data(`${client}${name}${url}${dim(entry.configPath)}`);
-  }
+  const header = `${"CLIENT".padEnd(clientWidth)}${"NAME".padEnd(nameWidth)}${"URL".padEnd(urlWidth)}PATH`;
+  const rows = entries.map((e) => {
+    const client = cyan(e.client.padEnd(clientWidth));
+    const name = e.name.padEnd(nameWidth);
+    const url = e.url.padEnd(urlWidth);
+    return `${client}${name}${url}${dim(e.configPath)}`;
+  });
+
+  ui.message([dim(header), ...rows]);
 }
 
 export async function mcpList(options: McpOptions = {}): Promise<void> {
-  const cwd = process.cwd();
-  const all: ListEntry[] = await collectEntries(cwd);
+  const all: ListEntry[] = await collectEntries(process.cwd());
 
   if (wantsJson(options)) {
     log.data(JSON.stringify(all, null, 2));
     return;
   }
 
-  if (all.length === 0) {
-    log.warn("No Clerk MCP entries found. Run `clerk mcp install` to register one.");
-    return;
-  }
-
-  formatTable(all);
-  log.info(`\n${all.length} entr${all.length === 1 ? "y" : "ies"}`);
-
-  printNextSteps([
-    "Verify a server is reachable with `clerk doctor`.",
-    "Remove an entry with `clerk mcp uninstall`.",
-  ]);
+  await withGutter("Listing Clerk MCP entries", async ({ setNextSteps }) => {
+    if (all.length === 0) {
+      ui.warn("No Clerk MCP entries found. Run `clerk mcp install` to register one.");
+      return;
+    }
+    formatTable(all);
+    ui.message(`${all.length} entr${all.length === 1 ? "y" : "ies"}`);
+    setNextSteps([
+      "Verify a server is reachable with `clerk doctor`.",
+      "Remove an entry with `clerk mcp uninstall`.",
+    ]);
+  });
 }

packages/cli-core/src/commands/mcp/shared.ts

@@ -98,14 +98,6 @@ export function wantsJson(options: McpOptions): boolean {
   return Boolean(options.json) || isAgent();
 }
 
-/** Render a "Next steps:" block to stderr (human mode). No-op for an empty list. */
-export function printNextSteps(lines: string[]): void {
-  if (lines.length === 0) return;
-  log.blank();
-  log.info("Next steps:");
-  for (const line of lines) log.info(`  ${line}`);
-}
-
 /**
  * Run an async op against each client without letting one client's failure
  * abort the rest — `Promise.all` is fail-fast and would discard every other

packages/cli-core/src/commands/mcp/uninstall.test.ts

@@ -101,7 +101,7 @@ describe("mcp uninstall", () => {
     mockIsAgent.mockReturnValue(false);
     captured.clear();
     await mcpUninstall({ client: ["cursor"] });
-    expect(captured.err).toContain("Next steps:");
+    expect(captured.err).toContain("Next steps");
     expect(captured.err).toContain("Reload Cursor");
   });
 });

packages/cli-core/src/commands/mcp/uninstall.ts

@@ -5,12 +5,10 @@
 import { cyan, dim, green, yellow } from "../../lib/color.ts";
 import { CliError, ERROR_CODE } from "../../lib/errors.ts";
 import { log } from "../../lib/log.ts";
-import { isHuman } from "../../mode.ts";
-import { intro, outro } from "../../lib/spinner.ts";
+import { withGutter } from "../../lib/spinner.ts";
 import { CLIENTS } from "./clients/registry.ts";
 import type { McpClient, RemoveResult } from "./clients/types.ts";
 import {
-  printNextSteps,
   resolveClients,
   resolveName,
   settleClients,
@@ -32,12 +30,8 @@ export async function mcpUninstall(options: McpOptions = {}): Promise<void> {
       : Array.from(CLIENTS);
   const json = wantsJson(options);
 
-  if (isHuman() && !json) intro(`Removing MCP entry ${cyan(name)}`);
-
   const settled = await settleClients(clients, (c) => c.remove(name, cwd));
   const results = settled.map((s) => s.result);
-  if (isHuman() && !json) settled.forEach(({ client, result }) => printResult(client, result));
-
   const removedCount = results.filter((r) => r.removed).length;
   const notInstalled = new CliError(`No MCP entry named "${name}" found in any client.`, {
     code: ERROR_CODE.MCP_NOT_INSTALLED,
@@ -49,14 +43,15 @@ export async function mcpUninstall(options: McpOptions = {}): Promise<void> {
     return;
   }
 
-  if (removedCount === 0) throw notInstalled;
-
   // Removing the config entry doesn't drop a live editor session — it lingers
-  // until the editor reloads. Tell the user for each client we removed from.
-  printNextSteps(
-    settled
-      .filter(({ result }) => result.removed)
-      .map(({ client }) => `Reload ${client.displayName} to drop the active connection.`),
-  );
-  outro("Done");
+  // until the editor reloads. Surface that as a next step per removed client.
+  await withGutter(`Removing MCP entry ${cyan(name)}`, async ({ setNextSteps }) => {
+    if (removedCount === 0) throw notInstalled;
+    settled.forEach(({ client, result }) => printResult(client, result));
+    setNextSteps(
+      settled
+        .filter(({ result }) => result.removed)
+        .map(({ client }) => `Reload ${client.displayName} to drop the active connection.`),
+    );
+  });
 }