From b0e32578ae2cd01e704cce8ac20c7ee3a332d719 Mon Sep 17 00:00:00 2001 From: morluto <76467478+morluto@users.noreply.github.com> Date: Sun, 15 Nov 2026 15:43:55 +0800 Subject: [PATCH] feat(cli): warn after mcp add writes Claude Desktop's configuration (#10696) * feat(cli): warn after mcp add writes Claude Desktop's configuration rea mcp add resolves Claude Desktop from the client table, whose row says a running app can rewrite its configuration from memory, but the command never told the caller. Print that notice on stderr when it writes the file. Backup notices now use the client's display name instead of special-casing Amp. * fix(cli): warn about Claude Desktop whenever mcp add wrote its file Address review findings: a registration that failed after publication, such as cancellation during verification, still left the file written, so the running-app notice now follows the registration owner's written fact instead of overall success. The CLI test compares the delivered notice with its owner instead of freezing the sentence. --- docs/getting-started/installation.md | 4 ++ src/application/McpClientRegistration.test.ts | 8 +++ src/application/McpClientRegistration.ts | 11 ++++ src/application/SupportedClients.ts | 12 ++++ src/cli/mcpRegistration.ts | 53 +++++++++++----- .../cli/mcpAddRunningClientNotice.test.ts | 62 +++++++++++++++++++ 6 files changed, 135 insertions(+), 15 deletions(-) create mode 100644 tests/boundary/cli/mcpAddRunningClientNotice.test.ts diff --git a/docs/getting-started/installation.md b/docs/getting-started/installation.md index 345d337015..ad03bf7c8f 100644 --- a/docs/getting-started/installation.md +++ b/docs/getting-started/installation.md @@ -1283,6 +1283,10 @@ workspace settings exclude `rea`, leave it off a nonempty allowlist, or define a different `rea` entry with higher precedence. On Windows, registration refuses to write a Claude Desktop MSIX configuration the running app could overwrite, or any file this process's MSIX AppData redirection would divert. +Because `rea mcp add` writes without an approval step, after it changes Claude +Desktop's configuration it prints a notice on stderr: a running Claude Desktop +can rewrite the file from memory and drop the registration, so quit it fully, +rerun `rea mcp add`, then start it again. The JSON report is unchanged. `--no-global` writes only project-level settings. A selection containing Amp or another client without project storage fails before any writes; select those diff --git a/src/application/McpClientRegistration.test.ts b/src/application/McpClientRegistration.test.ts index 05ebf88849..48c710a974 100644 --- a/src/application/McpClientRegistration.test.ts +++ b/src/application/McpClientRegistration.test.ts @@ -21,6 +21,7 @@ beforeEach(() => { }); import { OwnedStagedOutput } from "../filesystem/OwnedStagedOutput.js"; import { + mcpClientRegistrationWritten, registerMcpClient, registerMcpClients, } from "./McpClientRegistration.js"; @@ -534,6 +535,13 @@ describe("Registration cancellation and mixed outcomes", () => { _tag: "AnalysisCancelledError", diagnostics: { configured: true }, }); + // Callers that warn about written settings still see this write. + expect(mcpClientRegistrationWritten(result)).toBe(true); + expect( + mcpClientRegistrationWritten( + await register(path, launcher, before.signal), + ), + ).toBe(false); expect(JSON.parse(await readFile(path, "utf8"))).toEqual({ "amp.mcpServers": { rea: launcher }, }); diff --git a/src/application/McpClientRegistration.ts b/src/application/McpClientRegistration.ts index fd2ec53724..22fd2983ad 100644 --- a/src/application/McpClientRegistration.ts +++ b/src/application/McpClientRegistration.ts @@ -73,6 +73,17 @@ export type McpClientRegistrationOutcome = OutcomeLabels & | { readonly status: "not_started" } ); +/** + * Whether a registration's settings were published, including a failure that + * arrived after publication (for example cancellation during verification). + */ +export const mcpClientRegistrationWritten = ( + result: Result, +): boolean => + result.ok + ? result.value.status === "configured" + : result.error.diagnostics?.["configured"] === true; + /** Preserve every selected client's outcome, including work never started after cancellation. */ export const registerMcpClients = async ( clients: readonly McpRegistrationClient[], diff --git a/src/application/SupportedClients.ts b/src/application/SupportedClients.ts index b271ba0869..7a90dd57c2 100644 --- a/src/application/SupportedClients.ts +++ b/src/application/SupportedClients.ts @@ -323,6 +323,18 @@ export const registrationPersistenceDetail = ( return details.length === 0 ? undefined : details.join(" "); }; +/** + * What a direct registration (no approval step) must tell the caller after it + * wrote a client that can rewrite its configuration from memory. + */ +export const runningClientRewriteNotice = ( + client: Pick, +): string | undefined => { + if (client.quitBeforeSetup !== true) return undefined; + const name = client.displayName ?? client.name; + return `A running ${name} can rewrite its configuration from memory and drop the registration. If ${name} was running, quit it fully (closing its window is not enough), rerun rea mcp add, then start ${name} again.`; +}; + /** * Why this process must not change an MSIX client's configuration. A process * the running app started sees its redirected AppData, and the app would diff --git a/src/cli/mcpRegistration.ts b/src/cli/mcpRegistration.ts index 00cf8fe807..5519245136 100644 --- a/src/cli/mcpRegistration.ts +++ b/src/cli/mcpRegistration.ts @@ -3,10 +3,15 @@ import { Writable } from "node:stream"; import { Help, z } from "incur"; import { + mcpClientRegistrationWritten, registerMcpClients, type McpClientRegistrationOutcome, } from "../application/McpClientRegistration.js"; -import { resolveMcpRegistrationClients } from "../application/McpRegistrationCatalog.js"; +import { + resolveMcpRegistrationClients, + type McpRegistrationClient, +} from "../application/McpRegistrationCatalog.js"; +import { runningClientRewriteNotice } from "../application/SupportedClients.js"; import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js"; import { ArtifactResourceScope } from "../artifacts/ArtifactResourceScope.js"; import { @@ -322,12 +327,15 @@ const executeRegistration = async ( ); return undefined; } - return registerMcpClients( - targets.value, - request.launcher, - signal, - resources, - ); + return { + targets: targets.value, + outcomes: await registerMcpClients( + targets.value, + request.launcher, + signal, + resources, + ), + }; }) .catch(async (cause: unknown) => { if (!(cause instanceof ArtifactReaderFailure)) throw cause; @@ -345,7 +353,12 @@ const executeRegistration = async ( return undefined; }); if (outcomes !== undefined) - await presentRegistration(outcomes, request.launcher, presentation); + await presentRegistration( + outcomes.outcomes, + outcomes.targets, + request.launcher, + presentation, + ); }; const clientReport = ( @@ -386,6 +399,7 @@ const clientReport = ( const presentRegistration = async ( outcomes: readonly McpClientRegistrationOutcome[], + targets: readonly McpRegistrationClient[], launcher: ClientRegistrationCommand, presentation: RegistrationPresentation, ): Promise => { @@ -401,14 +415,23 @@ const presentRegistration = async ( clients, }; await presentation.document(report, !report.ok); - for (const outcome of outcomes) - if ( - outcome.status === "completed" && - outcome.result.ok && - outcome.result.value.backupPath !== undefined - ) + for (const outcome of outcomes) { + if (outcome.status !== "completed") continue; + const target = targets.find( + ({ id, configPath }) => + id === outcome.client && configPath === outcome.configPath, + ); + const name = target?.displayName ?? outcome.client; + const { result } = outcome; + if (result.ok && result.value.backupPath !== undefined) process.stderr.write( - `${outcome.client === "amp" ? "Amp" : outcome.client} MCP registration backup retained at ${outcome.result.value.backupPath}\n`, + `${name} MCP registration backup retained at ${result.value.backupPath}\n`, ); + const notice = + mcpClientRegistrationWritten(result) && target?.setupClient !== undefined + ? runningClientRewriteNotice(target.setupClient) + : undefined; + if (notice !== undefined) process.stderr.write(`${notice}\n`); + } if (!report.ok) presentation.fail(); }; diff --git a/tests/boundary/cli/mcpAddRunningClientNotice.test.ts b/tests/boundary/cli/mcpAddRunningClientNotice.test.ts new file mode 100644 index 0000000000..ce57221625 --- /dev/null +++ b/tests/boundary/cli/mcpAddRunningClientNotice.test.ts @@ -0,0 +1,62 @@ +import { expect } from "vitest"; + +import { runningClientRewriteNotice } from "../../../src/application/SupportedClients.js"; +import { mcpRegistrationReportSchema } from "../../../src/contracts/mcpRegistration.js"; + +import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js"; +import { cliTest } from "../../support/cli/cliFixture.js"; +import { registrationEnvironment } from "../../support/cli/registrationEnvironment.js"; + +// The owner's own text; this test checks delivery, not wording. +const QUIT_NOTICE = runningClientRewriteNotice({ + name: "claude_desktop", + displayName: "Claude Desktop", + quitBeforeSetup: true, +}); + +cliTest.skipIf(process.platform === "win32")( + "mcp add tells the caller to quit Claude Desktop only when it wrote that client", + async ({ cli }) => { + const home = await createTestTempDirectory("rea-mcp-add-quit-notice-"); + const environment = await registrationEnvironment(home); + const run = (agent: string) => + cli.run({ + arguments: [ + "mcp", + "add", + "--agent", + agent, + "--command", + "fixture-server --mcp", + "--json", + ], + cwd: home, + environment, + }); + + if (QUIT_NOTICE === undefined) + throw new Error("Claude Desktop has no notice"); + const first = await run("claude-desktop"); + expect(first.exitCode, first.stderr).toBe(0); + expect( + mcpRegistrationReportSchema.parse(JSON.parse(first.stdout)).clients, + ).toEqual([ + expect.objectContaining({ + client: "claude-desktop", + status: "configured", + }), + ]); + expect(first.stderr).toContain(QUIT_NOTICE); + // The JSON report is unchanged: the notice is advice on stderr. + expect(first.stdout).not.toContain(QUIT_NOTICE); + + // An identical repeat writes nothing, so there is nothing to lose. + const repeated = await run("claude-desktop"); + expect(repeated.exitCode, repeated.stderr).toBe(0); + expect(repeated.stderr).not.toContain(QUIT_NOTICE); + + const other = await run("cursor"); + expect(other.exitCode, other.stderr).toBe(0); + expect(other.stderr).not.toContain(QUIT_NOTICE); + }, +);