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); + }, +);