feat(mcp): interactive uninstall picker + rename claude-code client to claude

rafa-thayto · rafa-thayto · commit e1fcabbac558 · 2026-06-09T10:34:31.000-03:00
Uninstall: in human mode with no --client/--all, prompt with a multiselect of the clients that actually have the entry, so you choose exactly which to remove from (mirrors the install picker). Add --all to remove from every client without prompting; agent mode still targets all. --client still targets specific clients.

Rename the Claude Code client id from `claude-code` to `claude` (shorter `--client claude`); the file and export follow (claude.ts / claudeClient). Display name stays "Claude Code". Help examples now lead with `--client claude`.
diff --git a/packages/cli-core/src/cli-program.ts b/packages/cli-core/src/cli-program.ts
@@ -472,7 +472,10 @@ export function createProgram() {
     .description("Manage the Clerk remote MCP server connection for AI editors and CLIs")
     .setExamples([
       { command: "clerk mcp install", description: "Install into all detected MCP clients" },
-      { command: "clerk mcp install --client cursor", description: "Install into Cursor only" },
+      {
+        command: "clerk mcp install --client claude",
+        description: "Install into Claude Code only",
+      },
       { command: "clerk mcp list", description: "Show registered Clerk entries" },
       { command: "clerk mcp uninstall", description: "Remove the Clerk entry from all clients" },
     ]);
@@ -498,7 +501,7 @@ export function createProgram() {
       },
       { command: "clerk mcp install --all", description: "Install into every detected client" },
       {
-        command: "clerk mcp install --client cursor --client vscode",
+        command: "clerk mcp install --client claude --client vscode",
         description: "Install into specific clients",
       },
     ])
@@ -515,16 +518,27 @@ export function createProgram() {
     .command("uninstall")
     .description("Remove the Clerk MCP entry from supported clients")
     .addOption(
-      createOption("--client <id>", "MCP client to target (repeatable). Default: all clients.")
+      createOption(
+        "--client <id>",
+        "MCP client to target (repeatable). Default in human mode: pick from installed; in agent mode: all clients.",
+      )
         .choices([...MCP_CLIENT_IDS])
         .argParser(collectOptionValues)
         .default([] as string[]),
     )
+    .option("--all", "Remove from every client without prompting")
     .option("--name <name>", 'Entry name to remove (default: "clerk")')
     .option("--json", "Output as JSON")
     .setExamples([
-      { command: "clerk mcp uninstall", description: "Remove from every client" },
-      { command: "clerk mcp uninstall --client cursor", description: "Remove from Cursor only" },
+      {
+        command: "clerk mcp uninstall",
+        description: "Pick which installed clients to remove from",
+      },
+      { command: "clerk mcp uninstall --all", description: "Remove from every client" },
+      {
+        command: "clerk mcp uninstall --client claude",
+        description: "Remove from Claude Code only",
+      },
     ])
     .action((options) => mcpHandlers.uninstall(options));
 
diff --git a/packages/cli-core/src/commands/mcp/README.md b/packages/cli-core/src/commands/mcp/README.md
@@ -23,13 +23,13 @@ All entries are written to each client's **user-global** config, so the server
 is available in every project (no per-project approval, no dependence on which
 directory you run the CLI from).
 
-| ID            | Client                   | Scope | Config file                             |
-| ------------- | ------------------------ | ----- | --------------------------------------- |
-| `claude-code` | Claude Code              | user  | `~/.claude.json` (`mcpServers`)         |
-| `cursor`      | Cursor                   | user  | `~/.cursor/mcp.json`                    |
-| `vscode`      | VS Code (Copilot)        | user  | VS Code user `mcp.json` (per-OS, below) |
-| `windsurf`    | Windsurf                 | user  | `~/.codeium/windsurf/mcp_config.json`   |
-| `gemini`      | Gemini Code Assist / CLI | user  | `~/.gemini/settings.json`               |
+| ID         | Client                   | Scope | Config file                             |
+| ---------- | ------------------------ | ----- | --------------------------------------- |
+| `claude`   | Claude Code              | user  | `~/.claude.json` (`mcpServers`)         |
+| `cursor`   | Cursor                   | user  | `~/.cursor/mcp.json`                    |
+| `vscode`   | VS Code (Copilot)        | user  | VS Code user `mcp.json` (per-OS, below) |
+| `windsurf` | Windsurf                 | user  | `~/.codeium/windsurf/mcp_config.json`   |
+| `gemini`   | Gemini Code Assist / CLI | user  | `~/.gemini/settings.json`               |
 
 VS Code's user config dir is OS-specific: `~/Library/Application Support/Code/User/mcp.json`
 (macOS), `%APPDATA%\Code\User\mcp.json` (Windows), `$XDG_CONFIG_HOME/Code/User/mcp.json`
@@ -68,9 +68,13 @@ named `clerk` or pointing at any `*.clerk.com` host).
 
 ### `clerk mcp uninstall`
 
-Remove the named entry from each client. Throws `mcp_not_installed` (exit
-code 1) when nothing was removed. Removing the entry doesn't drop a live editor
-session, so (in human mode) it prints a next step to reload each affected editor.
+Remove the named entry. In human mode with no `--client`/`--all`, it prompts
+with a multiselect of the clients that **currently have the entry**, so you
+choose exactly which to remove from. `--all` removes from every client without
+prompting; agent mode targets all clients; `--client <id>` (repeatable) targets
+specific clients. Throws `mcp_not_installed` (exit code 1) when nothing matched.
+Removing the entry doesn't drop a live editor session, so (in human mode) it
+prints a next step to reload each affected editor.
 
 > **Reachability:** there is no `mcp doctor` subcommand. Server health is part
 > of `clerk doctor`, which probes the configured MCP URL via the `initialize`
diff --git a/packages/cli-core/src/commands/mcp/clients/claude.ts b/packages/cli-core/src/commands/mcp/clients/claude.ts
@@ -8,8 +8,8 @@
 import { hasStringProp, makeJsonClient } from "./make-json-client.ts";
 import { pathExists, userPath } from "./paths.ts";
 
-export const claudeCodeClient = makeJsonClient({
-  id: "claude-code",
+export const claudeClient = makeJsonClient({
+  id: "claude",
   displayName: "Claude Code",
   scope: "user",
   activation: "Restart Claude Code, then run `/mcp` to connect (sign in if prompted).",
diff --git a/packages/cli-core/src/commands/mcp/clients/clients.test.ts b/packages/cli-core/src/commands/mcp/clients/clients.test.ts
@@ -11,7 +11,7 @@ let mockHome = realOs.tmpdir();
 mock.module("node:os", () => ({ ...realOs, homedir: () => mockHome }));
 afterAll(() => mock.restore());
 
-const { claudeCodeClient } = await import("./claude-code.ts");
+const { claudeClient } = await import("./claude.ts");
 const { cursorClient } = await import("./cursor.ts");
 const { vscodeClient } = await import("./vscode.ts");
 const { windsurfClient } = await import("./windsurf.ts");
@@ -26,8 +26,8 @@ const URL = "https://mcp.clerk.com/mcp";
 // specific user-global config file and encodes the server its own way.
 const cases = [
   {
-    name: "claude-code",
-    client: claudeCodeClient,
+    name: "claude",
+    client: claudeClient,
     expectedPath: () => join(mockHome, ".claude.json"),
     topKey: "mcpServers",
     shape: { type: "http", url: URL },
diff --git a/packages/cli-core/src/commands/mcp/clients/registry.ts b/packages/cli-core/src/commands/mcp/clients/registry.ts
@@ -3,15 +3,15 @@
  * human-mode multiselect picker.
  */
 
-import { claudeCodeClient } from "./claude-code.ts";
+import { claudeClient } from "./claude.ts";
 import { cursorClient } from "./cursor.ts";
 import { geminiClient } from "./gemini.ts";
 import type { ClientId, McpClient } from "./types.ts";
 import { vscodeClient } from "./vscode.ts";
 import { windsurfClient } from "./windsurf.ts";
 
 export const CLIENTS: readonly McpClient[] = [
-  claudeCodeClient,
+  claudeClient,
   cursorClient,
   vscodeClient,
   windsurfClient,
diff --git a/packages/cli-core/src/commands/mcp/clients/types.ts b/packages/cli-core/src/commands/mcp/clients/types.ts
@@ -6,7 +6,7 @@
  * the `clerk` server entry in its own config file format.
  */
 
-export type ClientId = "claude-code" | "cursor" | "vscode" | "windsurf" | "gemini";
+export type ClientId = "claude" | "cursor" | "vscode" | "windsurf" | "gemini";
 
 /** Where the client config file lives relative to the user / project. */
 export type Scope = "project" | "user";
diff --git a/packages/cli-core/src/commands/mcp/clients/user-scope.test.ts b/packages/cli-core/src/commands/mcp/clients/user-scope.test.ts
@@ -30,7 +30,7 @@ const { checkMcp } = await import("../../doctor/check-mcp.ts");
 const captured = useCaptureLog();
 
 const URL = "https://mcp.clerk.com/mcp";
-const ALL_CLIENT_IDS = ["claude-code", "cursor", "vscode", "windsurf", "gemini"];
+const ALL_CLIENT_IDS = ["claude", "cursor", "vscode", "windsurf", "gemini"];
 
 describe("user-scope MCP clients (homedir redirected to a tmpdir)", () => {
   beforeEach(async () => {
diff --git a/packages/cli-core/src/commands/mcp/install.test.ts b/packages/cli-core/src/commands/mcp/install.test.ts
@@ -200,11 +200,11 @@ describe("mcp install", () => {
     await mkdir(join(cwd, ".cursor"), { recursive: true });
     await writeFile(join(cwd, ".cursor", "mcp.json"), "{ not json");
 
-    await mcpInstall({ client: ["cursor", "claude-code"], url: URL_A });
+    await mcpInstall({ client: ["cursor", "claude"], url: URL_A });
 
     const payload = JSON.parse(captured.out) as { results: { client: string; status: string }[] };
     expect(payload.results).toEqual([
-      expect.objectContaining({ client: "claude-code", status: "added" }),
+      expect.objectContaining({ client: "claude", status: "added" }),
     ]);
     expect(captured.err).toContain("Cursor"); // per-client warning for the failure
   });
diff --git a/packages/cli-core/src/commands/mcp/install.ts b/packages/cli-core/src/commands/mcp/install.ts
@@ -24,7 +24,9 @@ import type { McpClient, UpsertResult } from "./clients/types.ts";
 
 async function chooseClients(options: McpOptions, cwd: string): Promise<McpClient[]> {
   if (options.client?.length || options.all || isAgent()) return targetClients(options, cwd);
-  return pickClients(await detectInstalledClients(cwd));
+  return pickClients(await detectInstalledClients(cwd), "Select MCP clients to install into:", {
+    autoSelectSingle: true,
+  });
 }
 
 function statusLabel(status: UpsertResult["status"]): string {
diff --git a/packages/cli-core/src/commands/mcp/shared.ts b/packages/cli-core/src/commands/mcp/shared.ts
@@ -63,14 +63,18 @@ export function resolveClients(ids: readonly string[]): McpClient[] {
   });
 }
 
-export async function pickClients(detected: McpClient[]): Promise<McpClient[]> {
+export async function pickClients(
+  detected: McpClient[],
+  message: string,
+  options: { autoSelectSingle?: boolean } = {},
+): Promise<McpClient[]> {
   if (detected.length === 0) return [];
-  if (detected.length === 1) return detected;
+  if (detected.length === 1 && options.autoSelectSingle) return detected;
   // Imported lazily (like `doctor` does) so the prompt layer stays off the
   // module-load path for non-interactive callers and tests.
   const { multiselect } = await import("../../lib/prompts.ts");
   const selected = await multiselect<ClientId>({
-    message: "Select MCP clients to install into:",
+    message,
     options: detected.map((c) => ({ value: c.id, label: `${c.displayName} (${c.scope})` })),
     initialValues: detected.map((c) => c.id),
     required: true,
diff --git a/packages/cli-core/src/commands/mcp/uninstall.test.ts b/packages/cli-core/src/commands/mcp/uninstall.test.ts
@@ -17,6 +17,13 @@ mock.module("../../mode.ts", () => ({
 let mockHome = realOs.tmpdir();
 mock.module("node:os", () => ({ ...realOs, homedir: () => mockHome }));
 
+// The human picker resolves the Clack multiselect lazily from lib/prompts.ts;
+// stub it so tests drive which clients get selected without a real prompt.
+const mockMultiselect = mock();
+mock.module("../../lib/prompts.ts", () => ({
+  multiselect: (...args: unknown[]) => mockMultiselect(...args),
+}));
+
 const { mcpInstall } = await import("./install.ts");
 const { mcpUninstall } = await import("./uninstall.ts");
 
@@ -39,6 +46,7 @@ describe("mcp uninstall", () => {
     process.chdir(originalCwd);
     await rm(cwd, { recursive: true, force: true });
     mockIsAgent.mockReset();
+    mockMultiselect.mockReset();
   });
 
   test("removes the entry an install-uninstall round-trip leaves no trace under mcpServers", async () => {
@@ -104,4 +112,37 @@ describe("mcp uninstall", () => {
     expect(captured.err).toContain("Next steps");
     expect(captured.err).toContain("Reload Cursor");
   });
+
+  test("human mode: prompts to pick which installed clients to remove from", async () => {
+    await mcpInstall({ client: ["cursor", "claude"], url: URL });
+    mockIsAgent.mockReturnValue(false);
+    mockMultiselect.mockResolvedValueOnce(["cursor"]); // pick only Cursor
+    captured.clear();
+
+    await mcpUninstall({});
+
+    expect(mockMultiselect).toHaveBeenCalledTimes(1);
+    const cursorCfg = JSON.parse(await readFile(join(cwd, ".cursor", "mcp.json"), "utf8")) as {
+      mcpServers: Record<string, unknown>;
+    };
+    expect(cursorCfg.mcpServers.clerk).toBeUndefined(); // removed
+    const claudeCfg = JSON.parse(await readFile(join(cwd, ".claude.json"), "utf8")) as {
+      mcpServers: Record<string, unknown>;
+    };
+    expect(claudeCfg.mcpServers.clerk).toBeDefined(); // untouched
+  });
+
+  test("human mode: --all removes from every client without prompting", async () => {
+    await mcpInstall({ client: ["cursor", "claude"], url: URL });
+    mockIsAgent.mockReturnValue(false);
+    captured.clear();
+
+    await mcpUninstall({ all: true });
+
+    expect(mockMultiselect).not.toHaveBeenCalled();
+    const cursorCfg = JSON.parse(await readFile(join(cwd, ".cursor", "mcp.json"), "utf8")) as {
+      mcpServers: Record<string, unknown>;
+    };
+    expect(cursorCfg.mcpServers.clerk).toBeUndefined();
+  });
 });
diff --git a/packages/cli-core/src/commands/mcp/uninstall.ts b/packages/cli-core/src/commands/mcp/uninstall.ts
@@ -5,10 +5,12 @@
 import { cyan, dim, green, yellow } from "../../lib/color.ts";
 import { CliError, ERROR_CODE } from "../../lib/errors.ts";
 import { log } from "../../lib/log.ts";
+import { isAgent } from "../../mode.ts";
 import { withGutter } from "../../lib/spinner.ts";
 import { CLIENTS } from "./clients/registry.ts";
 import type { McpClient, RemoveResult } from "./clients/types.ts";
 import {
+  pickClients,
   resolveClients,
   resolveName,
   settleClients,
@@ -21,21 +23,37 @@ function printResult(client: McpClient, result: RemoveResult): void {
   log.info(`${label}: ${result.removed ? green("removed") : yellow("not present")}`);
 }
 
+/** Supported clients that currently have the `name` entry registered. */
+async function installedClients(name: string, cwd: string): Promise<McpClient[]> {
+  const present = await Promise.all(
+    CLIENTS.map(async (client) => (await client.list(cwd)).some((entry) => entry.name === name)),
+  );
+  return CLIENTS.filter((_, i) => present[i]);
+}
+
+// `--client` targets exactly those; `--all` (and agent mode, which can't
+// prompt) targets every client; otherwise the human picks which of the clients
+// that actually have the entry to remove it from.
+async function chooseClients(options: McpOptions, name: string, cwd: string): Promise<McpClient[]> {
+  if (options.client && options.client.length > 0) return resolveClients(options.client);
+  if (options.all || isAgent()) return Array.from(CLIENTS);
+  return pickClients(await installedClients(name, cwd), `Select clients to remove "${name}" from:`);
+}
+
 export async function mcpUninstall(options: McpOptions = {}): Promise<void> {
   const name = resolveName(options);
   const cwd = process.cwd();
-  const clients =
-    options.client && options.client.length > 0
-      ? resolveClients(options.client)
-      : Array.from(CLIENTS);
   const json = wantsJson(options);
+  const notInstalled = new CliError(`No MCP entry named "${name}" found in any client.`, {
+    code: ERROR_CODE.MCP_NOT_INSTALLED,
+  });
+
+  const clients = await chooseClients(options, name, cwd);
+  if (clients.length === 0) throw notInstalled;
 
   const settled = await settleClients(clients, (c) => c.remove(name, cwd));
   const results = settled.map((s) => s.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,
-  });
 
   if (json) {
     log.data(JSON.stringify({ name, results }, null, 2));

Original file line number	Diff line number	Diff line change
`@@ -24,7 +24,9 @@ import type { McpClient, UpsertResult } from "./clients/types.ts";`
`24`	`24`
`25`	`25`	`async function chooseClients(options: McpOptions, cwd: string): Promise<McpClient[]> {`
`26`	`26`	`if (options.client?.length \|\| options.all \|\| isAgent()) return targetClients(options, cwd);`
`27`		`- return pickClients(await detectInstalledClients(cwd));`
	`27`	`+ return pickClients(await detectInstalledClients(cwd), "Select MCP clients to install into:", {`
	`28`	`+ autoSelectSingle: true,`
	`29`	`+ });`
`28`	`30`	`}`
`29`	`31`
`30`	`32`	`function statusLabel(status: UpsertResult["status"]): string {`