@simplysf/simply-gitlab-mcp 0.6.2 → 0.7.0

package/README.md

@@ -47,6 +47,10 @@ reads them from a `.env` file instead, and the real environment still wins over
 For a self-signed or internal CA, add `"NODE_EXTRA_CA_CERTS": "/path/to/ca.pem"` to `env`. This
 server always verifies certificates.
 
+With the `simply` CLI, `simply gitlab mcp install --client <id> --env-file ~/gitlab.env` writes the
+entry into Claude Code, Claude Desktop, Cursor, VS Code, Windsurf, Gemini CLI or Codex for you,
+without touching the rest of that client's configuration. See the MCP server guide for the details.
+
 ## Writes
 
 **Only read tools are registered by default.** Add `--allow-writes` to `args` to register the seven

package/docs/guides/mcp-server.md

@@ -55,6 +55,40 @@ slashes or doubled backslashes inside JSON: `"C:/Users/me/gitlab.env"`.
 
 ## Configure a client
 
+### With `simply gitlab mcp install`
+
+One command writes the entry for you. Name each client with `--client`:
+
+```sh
+simply gitlab mcp install --client claude-code --client cursor --env-file ~/gitlab.env
+```
+
+Client ids: `claude-code`, `claude-desktop`, `cursor`, `vscode`, `windsurf`, `gemini`, `codex`.
+Running it without `--client` lists them, and marks the ones found on this machine.
+
+- **Only the entry changes.** In a JSON file, everything else, comments included, is left as it
+  was, and the previous file is kept as `<file>.bak`. Claude Code and Codex are configured through
+  their own `claude mcp` and `codex mcp` commands. If one isn't on `PATH`, you get the exact command
+  to run yourself.
+- **Credentials are never written.** `--env-file` is resolved to an absolute path, checked to exist,
+  and passed to the server. Without it, the entry starts with no settings, because a GUI client
+  doesn't see your shell's environment.
+- **Server flags are passed through.** `--allow-writes` reaches the server.
+  `--allow-writes` also names the entry `simply-gitlab-write`, so it can sit beside the read-only
+  one (see [Let the agent write](#let-the-agent-write)). `--name` overrides the name.
+- **`--scope project`** writes the repository's own file in the current directory instead:
+  `.mcp.json` for Claude Code, `.cursor/mcp.json`, `.vscode/mcp.json` or `.gemini/settings.json`.
+  The entry then runs `simply` from `PATH`, so it works for everyone who clones the repository.
+- **At user scope the entry starts this Node binary and the `simply` CLI's own script.** That works
+  for GUI clients that don't see your `PATH`. If a Node upgrade moves the binary, run the command
+  again with `--force`. `--launcher simply` or `--launcher npx` choose the other forms.
+- **Running it twice is safe.** An identical entry is left alone. An entry that differs is reported
+  as a conflict (exit 2) and is replaced only with `--force`. `--dry-run` shows what would be
+  written, and `--json` returns the per-client results.
+
+Restart Claude Desktop or Windsurf afterwards. In Claude Code or Gemini CLI, run `/mcp`. The
+sections below show what the command writes, for editing by hand or for any other client.
+
 ### Claude Desktop
 
 Edit `claude_desktop_config.json` (macOS: `~/Library/Application Support/Claude/`; Windows:

package/lib/commands/gitlab/mcp/install.d.ts

@@ -0,0 +1,33 @@
+import { Command } from '@oclif/core';
+import { type InstallResult } from '../../../mcpClients/index.js';
+export type GitlabMcpInstallResult = {
+    dryRun: boolean;
+    results: InstallResult[];
+};
+/**
+ * Writes an entry for `simply gitlab mcp` into named MCP clients. Knowledge of the clients lives
+ * in `src/mcpClients`; this command only says what the server is and which of its flags to forward.
+ * See docs/design/0010-mcp-install.md.
+ *
+ * Unlike `gitlab mcp`, this command is not a protocol server, so `--json` is safe here.
+ */
+export default class GitlabMcpInstall extends Command {
+    static enableJsonFlag: boolean;
+    static readonly summary = "Add the GitLab MCP server to MCP clients.";
+    static readonly description: string;
+    static readonly examples: {
+        description: string;
+        command: string;
+    }[];
+    static readonly flags: {
+        client: import("@oclif/core/interfaces").OptionFlag<("cursor" | "claude-code" | "claude-desktop" | "vscode" | "windsurf" | "gemini" | "codex")[] | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        scope: import("@oclif/core/interfaces").OptionFlag<"project" | "user", import("@oclif/core/interfaces").CustomOptions>;
+        'env-file': import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        'allow-writes': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        name: import("@oclif/core/interfaces").OptionFlag<string | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        launcher: import("@oclif/core/interfaces").OptionFlag<"absolute" | "simply" | "npx" | undefined, import("@oclif/core/interfaces").CustomOptions>;
+        force: import("@oclif/core/interfaces").BooleanFlag<boolean>;
+        'dry-run': import("@oclif/core/interfaces").BooleanFlag<boolean>;
+    };
+    run(): Promise<GitlabMcpInstallResult>;
+}

package/lib/commands/gitlab/mcp/install.js

@@ -0,0 +1,123 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import path from 'node:path';
+import { Command, Flags } from '@oclif/core';
+import { buildLaunch, CLIENT_IDS, currentEnvironment, defaultLauncher, detectInstalledClients, exitCodeFor, formatClientChoices, formatInstallReport, installServer, resolveEnvFile, SIMPLY_CLI_PACKAGE, } from '../../../mcpClients/index.js';
+/**
+ * Writes an entry for `simply gitlab mcp` into named MCP clients. Knowledge of the clients lives
+ * in `src/mcpClients`; this command only says what the server is and which of its flags to forward.
+ * See docs/design/0010-mcp-install.md.
+ *
+ * Unlike `gitlab mcp`, this command is not a protocol server, so `--json` is safe here.
+ */
+export default class GitlabMcpInstall extends Command {
+    static enableJsonFlag = true;
+    static summary = 'Add the GitLab MCP server to MCP clients.';
+    static description = 'Writes an entry that launches "simply gitlab mcp" into each client named with --client, ' +
+        'keeping the rest of that client’s configuration as it was. Claude Code and Codex are changed ' +
+        'through their own CLIs; every other client’s JSON file is edited in place, with a .bak copy kept.\n\n' +
+        'Credentials are never written. Give the server its connection settings with --env-file, which is ' +
+        'written as an absolute path and must exist now. A GUI client will not pass on your shell’s ' +
+        'environment, so without --env-file the entry starts with no settings.\n\n' +
+        'Running it again is safe: an identical entry is left alone, and a different one is only replaced ' +
+        'with --force.';
+    static examples = [
+        {
+            description: 'Add the read-only server to Claude Code and Cursor',
+            command: '<%= config.bin %> <%= command.id %> --client claude-code --client cursor --env-file ~/gitlab.env',
+        },
+        {
+            description: 'Add a second, write-enabled entry (named simply-gitlab-write) to Claude Desktop',
+            command: '<%= config.bin %> <%= command.id %> --client claude-desktop --allow-writes --env-file ~/gitlab-write.env',
+        },
+        {
+            description: 'Commit an entry for this repository’s VS Code users',
+            command: '<%= config.bin %> <%= command.id %> --client vscode --scope project',
+        },
+        {
+            description: 'See what would be written, and change nothing',
+            command: '<%= config.bin %> <%= command.id %> --client gemini --dry-run',
+        },
+    ];
+    static flags = {
+        client: Flags.option({
+            options: CLIENT_IDS,
+            multiple: true,
+            summary: 'Client to add the server to. Repeat for several.',
+        })(),
+        scope: Flags.option({
+            options: ['user', 'project'],
+            default: 'user',
+            summary: 'Your own configuration, or the repository-level file in the current directory.',
+        })(),
+        'env-file': Flags.string({
+            char: 'e',
+            summary: 'Connection settings file for the server. Written as an absolute path.',
+        }),
+        'allow-writes': Flags.boolean({
+            summary: 'Register the tools that change data. Also makes the default name simply-gitlab-write.',
+            default: false,
+        }),
+        name: Flags.string({
+            summary: 'Entry name. Default simply-gitlab, or simply-gitlab-write with --allow-writes.',
+        }),
+        launcher: Flags.option({
+            options: ['absolute', 'simply', 'npx'],
+            summary: 'How the entry starts simply. Default absolute for --scope user, simply for --scope project.',
+            description: 'absolute: this Node binary and the simply CLI’s own script, which works for GUI clients that do ' +
+                'not see your PATH (re-run with --force after a Node upgrade moves it). simply: "simply" on PATH, ' +
+                'right for a committed file. npx: "npx -y @simplysf/simply-cli", for machines without a global install.',
+        })(),
+        force: Flags.boolean({ summary: 'Replace an existing entry of the same name that differs.', default: false }),
+        'dry-run': Flags.boolean({ summary: 'Show what would be written, and change nothing.', default: false }),
+    };
+    async run() {
+        const { flags } = await this.parse(GitlabMcpInstall);
+        const environment = currentEnvironment();
+        if (!flags.client?.length) {
+            this.error(formatClientChoices(await detectInstalledClients(environment)), { exit: 2 });
+        }
+        const launcher = flags.launcher ?? defaultLauncher(flags.scope);
+        if (launcher === 'absolute' && this.config.pjson.name !== SIMPLY_CLI_PACKAGE) {
+            this.error(`--launcher absolute starts the simply CLI's own script, but this is running under ${this.config.pjson.name}. ` +
+                'Run it as "simply gitlab mcp install", or pass --launcher simply or --launcher npx.', { exit: 2 });
+        }
+        const simplyArgs = ['gitlab', 'mcp'];
+        if (flags['allow-writes'])
+            simplyArgs.push('--allow-writes');
+        if (flags['env-file']) {
+            const envFile = await resolveEnvFile(flags['env-file'], environment).catch((error) => this.error(error.message, { exit: 2 }));
+            simplyArgs.push('--env-file', envFile);
+        }
+        else {
+            this.warn('No --env-file given. The server will start with only the settings the client puts in the ' +
+                'entry’s "env" block, and a GUI client does not pass on your shell’s environment.');
+        }
+        const launch = buildLaunch(launcher, simplyArgs, {
+            nodePath: process.execPath,
+            runScript: path.join(this.config.root, 'bin', 'run.js'),
+        });
+        const name = flags.name ?? (flags['allow-writes'] ? 'simply-gitlab-write' : 'simply-gitlab');
+        const results = await installServer({ name, ...launch }, flags.client, flags.scope, environment, {
+            force: flags.force,
+            dryRun: flags['dry-run'],
+        });
+        this.log(formatInstallReport(results, launcher));
+        process.exitCode = exitCodeFor(results);
+        return { dryRun: flags['dry-run'], results };
+    }
+}
+//# sourceMappingURL=install.js.map

package/lib/commands/gitlab/mcp/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../../../src/commands/gitlab/mcp/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,IAAI,MAAM,WAAW,CAAC;AAC7B,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,MAAM,aAAa,CAAC;AAC7C,OAAO,EACL,WAAW,EACX,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,sBAAsB,EACtB,WAAW,EACX,mBAAmB,EACnB,mBAAmB,EACnB,aAAa,EACb,cAAc,EACd,kBAAkB,GAEnB,MAAM,8BAA8B,CAAC;AAItC;;;;;;GAMG;AACH,MAAM,CAAC,OAAO,OAAO,gBAAiB,SAAQ,OAAO;IAC5C,MAAM,CAAU,cAAc,GAAG,IAAI,CAAC;IAEtC,MAAM,CAAmB,OAAO,GAAG,2CAA2C,CAAC;IAC/E,MAAM,CAAmB,WAAW,GACzC,0FAA0F;QAC1F,+FAA+F;QAC/F,uGAAuG;QACvG,mGAAmG;QACnG,6FAA6F;QAC7F,2EAA2E;QAC3E,mGAAmG;QACnG,eAAe,CAAC;IAEX,MAAM,CAAmB,QAAQ,GAAG;QACzC;YACE,WAAW,EAAE,oDAAoD;YACjE,OAAO,EAAE,kGAAkG;SAC5G;QACD;YACE,WAAW,EAAE,iFAAiF;YAC9F,OAAO,EACL,0GAA0G;SAC7G;QACD;YACE,WAAW,EAAE,qDAAqD;YAClE,OAAO,EAAE,qEAAqE;SAC/E;QACD;YACE,WAAW,EAAE,+CAA+C;YAC5D,OAAO,EAAE,+DAA+D;SACzE;KACF,CAAC;IAEK,MAAM,CAAmB,KAAK,GAAG;QACtC,MAAM,EAAE,KAAK,CAAC,MAAM,CAAC;YACnB,OAAO,EAAE,UAAU;YACnB,QAAQ,EAAE,IAAI;YACd,OAAO,EAAE,kDAAkD;SAC5D,CAAC,EAAE;QACJ,KAAK,EAAE,KAAK,CAAC,MAAM,CAAC;YAClB,OAAO,EAAE,CAAC,MAAM,EAAE,SAAS,CAAU;YACrC,OAAO,EAAE,MAAe;YACxB,OAAO,EAAE,gFAAgF;SAC1F,CAAC,EAAE;QACJ,UAAU,EAAE,KAAK,CAAC,MAAM,CAAC;YACvB,IAAI,EAAE,GAAG;YACT,OAAO,EAAE,uEAAuE;SACjF,CAAC;QACF,cAAc,EAAE,KAAK,CAAC,OAAO,CAAC;YAC5B,OAAO,EAAE,uFAAuF;YAChG,OAAO,EAAE,KAAK;SACf,CAAC;QACF,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC;YACjB,OAAO,EAAE,gFAAgF;SAC1F,CAAC;QACF,QAAQ,EAAE,KAAK,CAAC,MAAM,CAAC;YACrB,OAAO,EAAE,CAAC,UAAU,EAAE,QAAQ,EAAE,KAAK,CAAU;YAC/C,OAAO,EAAE,6FAA6F;YACtG,WAAW,EACT,kGAAkG;gBAClG,mGAAmG;gBACnG,wGAAwG;SAC3G,CAAC,EAAE;QACJ,KAAK,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,0DAA0D,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;QAC7G,SAAS,EAAE,KAAK,CAAC,OAAO,CAAC,EAAE,OAAO,EAAE,iDAAiD,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;KACzG,CAAC;IAEK,KAAK,CAAC,GAAG;QACd,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,CAAC;QACrD,MAAM,WAAW,GAAG,kBAAkB,EAAE,CAAC;QAEzC,IAAI,CAAC,KAAK,CAAC,MAAM,EAAE,MAAM,EAAE,CAAC;YAC1B,IAAI,CAAC,KAAK,CAAC,mBAAmB,CAAC,MAAM,sBAAsB,CAAC,WAAW,CAAC,CAAC,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CAAC;QAC1F,CAAC;QAED,MAAM,QAAQ,GAAG,KAAK,CAAC,QAAQ,IAAI,eAAe,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC;QAChE,IAAI,QAAQ,KAAK,UAAU,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,KAAK,kBAAkB,EAAE,CAAC;YAC7E,IAAI,CAAC,KAAK,CACR,qFAAqF,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,IAAI;gBAC7G,qFAAqF,EACvF,EAAE,IAAI,EAAE,CAAC,EAAE,CACZ,CAAC;QACJ,CAAC;QAED,MAAM,UAAU,GAAG,CAAC,QAAQ,EAAE,KAAK,CAAC,CAAC;QACrC,IAAI,KAAK,CAAC,cAAc,CAAC;YAAE,UAAU,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC;QAC7D,IAAI,KAAK,CAAC,UAAU,CAAC,EAAE,CAAC;YACtB,MAAM,OAAO,GAAG,MAAM,cAAc,CAAC,KAAK,CAAC,UAAU,CAAC,EAAE,WAAW,CAAC,CAAC,KAAK,CAAC,CAAC,KAAY,EAAE,EAAE,CAC1F,IAAI,CAAC,KAAK,CAAC,KAAK,CAAC,OAAO,EAAE,EAAE,IAAI,EAAE,CAAC,EAAE,CAAC,CACvC,CAAC;YACF,UAAU,CAAC,IAAI,CAAC,YAAY,EAAE,OAAO,CAAC,CAAC;QACzC,CAAC;aAAM,CAAC;YACN,IAAI,CAAC,IAAI,CACP,2FAA2F;gBACzF,kFAAkF,CACrF,CAAC;QACJ,CAAC;QAED,MAAM,MAAM,GAAG,WAAW,CAAC,QAAQ,EAAE,UAAU,EAAE;YAC/C,QAAQ,EAAE,OAAO,CAAC,QAAQ;YAC1B,SAAS,EAAE,IAAI,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC;SACxD,CAAC,CAAC;QACH,MAAM,IAAI,GAAG,KAAK,CAAC,IAAI,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,qBAAqB,CAAC,CAAC,CAAC,eAAe,CAAC,CAAC;QAE7F,MAAM,OAAO,GAAG,MAAM,aAAa,CAAC,EAAE,IAAI,EAAE,GAAG,MAAM,EAAE,EAAE,KAAK,CAAC,MAAM,EAAE,KAAK,CAAC,KAAK,EAAE,WAAW,EAAE;YAC/F,KAAK,EAAE,KAAK,CAAC,KAAK;YAClB,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC;SACzB,CAAC,CAAC;QAEH,IAAI,CAAC,GAAG,CAAC,mBAAmB,CAAC,OAAO,EAAE,QAAQ,CAAC,CAAC,CAAC;QACjD,OAAO,CAAC,QAAQ,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QACxC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,CAAC;IAC/C,CAAC"}

package/lib/mcpClients/apply.d.ts

@@ -0,0 +1,10 @@
+import type { ApplyOptions, InstallPlan, InstallResult } from './types.js';
+/**
+ * Carries out a plan: edits the file or runs the client's CLI. Every failure becomes a `failed`
+ * result rather than a rejection, so one client's problem never stops the others.
+ *
+ * @param plan - From `planInstall`.
+ * @param options - `force` to replace a differing entry, `dryRun` to change nothing.
+ * @returns What happened, or with `dryRun`, what would.
+ */
+export declare function applyPlan(plan: InstallPlan, options?: ApplyOptions): Promise<InstallResult>;

package/lib/mcpClients/apply.js

@@ -0,0 +1,209 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { isDeepStrictEqual } from 'node:util';
+import { parse, printParseErrorCode } from 'jsonc-parser';
+import { CLIENTS } from './clients.js';
+import { compareClaudeEntry, compareCodexEntry } from './existingEntry.js';
+import { setNestedEntry } from './jsonEdit.js';
+import { formatCommandLine, runProcess } from './runner.js';
+/**
+ * Carries out a plan: edits the file or runs the client's CLI. Every failure becomes a `failed`
+ * result rather than a rejection, so one client's problem never stops the others.
+ *
+ * @param plan - From `planInstall`.
+ * @param options - `force` to replace a differing entry, `dryRun` to change nothing.
+ * @returns What happened, or with `dryRun`, what would.
+ */
+export async function applyPlan(plan, options = {}) {
+    switch (plan.kind) {
+        case 'file':
+            return applyFilePlan(plan, options);
+        case 'cli':
+            return applyCliPlan(plan, options);
+        case 'unsupported':
+            return {
+                client: plan.client,
+                name: plan.name,
+                outcome: 'failed',
+                target: CLIENTS[plan.client].displayName,
+                dryRun: Boolean(options.dryRun),
+                exitCode: 2,
+                message: plan.reason,
+                preview: '',
+            };
+    }
+}
+async function applyFilePlan(plan, options) {
+    const dryRun = Boolean(options.dryRun);
+    const result = (outcome, exitCode, message) => ({
+        client: plan.client,
+        name: plan.name,
+        outcome,
+        target: plan.file,
+        dryRun,
+        exitCode,
+        message,
+        preview: JSON.stringify({ [plan.key]: { [plan.name]: plan.entry } }, null, 2),
+    });
+    const config = await readConfigFile(plan);
+    if ('failure' in config)
+        return result('failed', config.exitCode, config.failure);
+    const { text, servers } = config;
+    const existing = servers?.[plan.name];
+    if (existing !== undefined) {
+        if (isDeepStrictEqual(existing, plan.entry))
+            return result('unchanged', 0);
+        if (!options.force)
+            return result('conflict', 2, conflictMessage(plan.name, plan.file));
+    }
+    const outcome = existing === undefined ? 'added' : 'replaced';
+    if (dryRun)
+        return result(outcome, 0);
+    try {
+        const updated = setNestedEntry(text ?? '', plan.key, plan.name, plan.entry);
+        await fs.mkdir(path.dirname(plan.file), { recursive: true });
+        if (text !== undefined)
+            await fs.copyFile(plan.file, `${plan.file}.bak`);
+        await writeAtomically(plan.file, updated);
+    }
+    catch (error) {
+        return result('failed', 1, `Could not write ${plan.file}: ${error.message}`);
+    }
+    return result(outcome, 0);
+}
+/** Reads and checks a client's file: absent is fine, unreadable or not an object is a refusal. */
+async function readConfigFile(plan) {
+    let text;
+    try {
+        text = await fs.readFile(plan.file, 'utf8');
+    }
+    catch (error) {
+        if (!isNotFound(error))
+            return { failure: `Could not read ${plan.file}: ${error.message}`, exitCode: 1 };
+    }
+    if (text === undefined && plan.clientDir && !(await isDirectory(plan.clientDir))) {
+        return {
+            failure: `${CLIENTS[plan.client].displayName} does not appear to be installed: ${plan.clientDir} does not exist.`,
+            exitCode: 2,
+        };
+    }
+    const errors = [];
+    const root = text === undefined || text.trim() === '' ? {} : parse(text, errors, { allowTrailingComma: true });
+    if (errors.length > 0) {
+        const [first] = errors;
+        return {
+            failure: `${plan.file} is not valid JSON (${printParseErrorCode(first.error)} at offset ${first.offset}). ` +
+                'It was left untouched; fix it and run this again.',
+            exitCode: 2,
+        };
+    }
+    if (!isRecord(root) || (root[plan.key] !== undefined && !isRecord(root[plan.key]))) {
+        return {
+            failure: `${plan.file} does not hold an object${isRecord(root) ? ` under "${plan.key}"` : ''}. It was left untouched.`,
+            exitCode: 2,
+        };
+    }
+    return { text, servers: root[plan.key] };
+}
+async function applyCliPlan(plan, options) {
+    const dryRun = Boolean(options.dryRun);
+    const addCommand = formatCommandLine(plan.executable, plan.addArgs);
+    const removeCommand = formatCommandLine(plan.executable, plan.removeArgs);
+    const result = (outcome, exitCode, message, target = addCommand) => ({
+        client: plan.client,
+        name: plan.name,
+        outcome,
+        target,
+        dryRun,
+        exitCode,
+        message,
+        preview: addCommand,
+    });
+    const existing = await readExistingCliEntry(plan);
+    if (existing === 'same')
+        return result('unchanged', 0);
+    if (existing === 'differs' && !options.force)
+        return result('conflict', 2, conflictMessage(plan.name, plan.configFile));
+    const outcome = existing === 'absent' ? 'added' : 'replaced';
+    const commands = existing === 'absent' ? [plan.addArgs] : [plan.removeArgs, plan.addArgs];
+    const target = existing === 'absent' ? addCommand : `${removeCommand} && ${addCommand}`;
+    if (dryRun)
+        return result(outcome, 0, undefined, target);
+    const run = options.runner ?? runProcess;
+    for (const args of commands) {
+        try {
+            // eslint-disable-next-line no-await-in-loop -- the remove must finish before the add, or the add sees the old entry
+            const { exitCode, stderr, stdout } = await run(plan.executable, args);
+            if (exitCode !== 0) {
+                const output = (stderr || stdout).trim();
+                return result('failed', 1, `${formatCommandLine(plan.executable, args)} exited with ${exitCode}${output ? `: ${output}` : '.'}`, target);
+            }
+        }
+        catch (error) {
+            if (isNotFound(error)) {
+                return result('failed', 2, `${plan.executable} is not on PATH, so ${CLIENTS[plan.client].displayName} could not be configured. ` +
+                    `Run this yourself:\n${target}`, target);
+            }
+            return result('failed', 1, `Could not run ${plan.executable}: ${error.message}`, target);
+        }
+    }
+    return result(outcome, 0, undefined, target);
+}
+async function readExistingCliEntry(plan) {
+    let text;
+    try {
+        text = await fs.readFile(plan.configFile, 'utf8');
+    }
+    catch {
+        // No file means no entry; any other read problem is the client's to report when it runs.
+        return 'absent';
+    }
+    return plan.configFormat === 'claude-json'
+        ? compareClaudeEntry(text, plan.name, plan.launch)
+        : compareCodexEntry(text, plan.name, plan.launch);
+}
+/** Writes beside the target and renames over it, so a crash never leaves a half-written file. */
+async function writeAtomically(file, contents) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temporary, contents, 'utf8');
+    try {
+        await fs.rename(temporary, file);
+    }
+    catch (error) {
+        await fs.rm(temporary, { force: true });
+        throw error;
+    }
+}
+function conflictMessage(name, file) {
+    return `An entry named "${name}" already exists in ${file} and is different. Re-run with --force to replace it.`;
+}
+async function isDirectory(dir) {
+    try {
+        return (await fs.stat(dir)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
+function isNotFound(error) {
+    return error?.code === 'ENOENT';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+//# sourceMappingURL=apply.js.map

package/lib/mcpClients/apply.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"apply.js","sourceRoot":"","sources":["../../src/mcpClients/apply.ts"],"names":[],"mappings":"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"}

package/lib/mcpClients/clients.d.ts

@@ -0,0 +1,36 @@
+import path from 'node:path';
+import type { ClientId, InstallEnvironment, ServersKey } from './types.js';
+/** Where a client keeps a JSON configuration file, and what it expects inside it. */
+type FileLocation = {
+    file: string;
+    key: ServersKey;
+    /** Add `"type": "stdio"` to the entry. */
+    typed: boolean;
+    clientDir?: string;
+};
+type ClientDefinition = {
+    displayName: string;
+    /** What to do after installing, since nothing here can tell whether the client noticed. */
+    nextStep: string;
+    /** User scope: a file to edit, or the client's own CLI. */
+    user: (environment: InstallEnvironment) => FileLocation | {
+        cli: 'claude' | 'codex';
+        configFile: string;
+    };
+    /** Project scope, relative to `cwd`; absent where the client has no repo-level file. */
+    project?: {
+        file: string;
+        key: ServersKey;
+        typed: boolean;
+    };
+};
+/** `path` for the target platform, so Windows paths are built with `\` even when planned elsewhere. */
+declare function pathFor(environment: InstallEnvironment): typeof path.posix;
+/**
+ * The client table. A client that moves its file is a one-row change here, which is the reason this
+ * lives in one package rather than in each product.
+ */
+export declare const CLIENTS: Readonly<Record<ClientId, ClientDefinition>>;
+/** @returns The directory whose presence means the client is installed for this user. */
+export declare function clientMarker(client: ClientId, environment: InstallEnvironment): string;
+export { pathFor };

package/lib/mcpClients/clients.js

@@ -0,0 +1,111 @@
+/*
+ * Copyright (c) 2026, SimplySF.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import path from 'node:path';
+/** `path` for the target platform, so Windows paths are built with `\` even when planned elsewhere. */
+function pathFor(environment) {
+    return environment.platform === 'win32' ? path.win32 : path.posix;
+}
+/** The per-user application data directory: `%APPDATA%`, `~/Library/Application Support`, or XDG. */
+function appDataDir(environment) {
+    const p = pathFor(environment);
+    if (environment.platform === 'win32') {
+        return environment.env.APPDATA ?? p.join(environment.homedir, 'AppData', 'Roaming');
+    }
+    if (environment.platform === 'darwin')
+        return p.join(environment.homedir, 'Library', 'Application Support');
+    return environment.env.XDG_CONFIG_HOME ?? p.join(environment.homedir, '.config');
+}
+function dotDirFile(environment, dir, file) {
+    const p = pathFor(environment);
+    const clientDir = p.join(environment.homedir, ...dir);
+    return { file: p.join(clientDir, file), key: 'mcpServers', typed: false, clientDir };
+}
+/**
+ * The client table. A client that moves its file is a one-row change here, which is the reason this
+ * lives in one package rather than in each product.
+ */
+export const CLIENTS = {
+    'claude-code': {
+        displayName: 'Claude Code',
+        nextStep: 'Run /mcp in Claude Code to check the server connects.',
+        user: (environment) => ({
+            cli: 'claude',
+            configFile: pathFor(environment).join(environment.env.CLAUDE_CONFIG_DIR ?? environment.homedir, '.claude.json'),
+        }),
+        project: { file: '.mcp.json', key: 'mcpServers', typed: true },
+    },
+    'claude-desktop': {
+        displayName: 'Claude Desktop',
+        nextStep: 'Quit and restart Claude Desktop.',
+        user: (environment) => {
+            const clientDir = pathFor(environment).join(appDataDir(environment), 'Claude');
+            return {
+                file: pathFor(environment).join(clientDir, 'claude_desktop_config.json'),
+                key: 'mcpServers',
+                typed: false,
+                clientDir,
+            };
+        },
+    },
+    cursor: {
+        displayName: 'Cursor',
+        nextStep: 'Check the server under Cursor Settings > MCP, and reload Cursor if it is not listed.',
+        user: (environment) => dotDirFile(environment, ['.cursor'], 'mcp.json'),
+        project: { file: path.posix.join('.cursor', 'mcp.json'), key: 'mcpServers', typed: false },
+    },
+    vscode: {
+        displayName: 'VS Code',
+        nextStep: 'Run "MCP: List Servers" in VS Code and start the server.',
+        user: (environment) => {
+            const p = pathFor(environment);
+            const clientDir = p.join(appDataDir(environment), 'Code');
+            return { file: p.join(clientDir, 'User', 'mcp.json'), key: 'servers', typed: true, clientDir };
+        },
+        project: { file: path.posix.join('.vscode', 'mcp.json'), key: 'servers', typed: true },
+    },
+    windsurf: {
+        displayName: 'Windsurf',
+        nextStep: "Refresh Windsurf's MCP servers, or restart Windsurf.",
+        user: (environment) => dotDirFile(environment, ['.codeium', 'windsurf'], 'mcp_config.json'),
+    },
+    gemini: {
+        displayName: 'Gemini CLI',
+        nextStep: 'Run /mcp in Gemini CLI to check the server connects.',
+        user: (environment) => dotDirFile(environment, ['.gemini'], 'settings.json'),
+        project: { file: path.posix.join('.gemini', 'settings.json'), key: 'mcpServers', typed: false },
+    },
+    codex: {
+        displayName: 'Codex CLI',
+        nextStep: 'Start a new Codex session.',
+        user: (environment) => ({
+            cli: 'codex',
+            configFile: pathFor(environment).join(environment.env.CODEX_HOME ?? pathFor(environment).join(environment.homedir, '.codex'), 'config.toml'),
+        }),
+    },
+};
+/** @returns The directory whose presence means the client is installed for this user. */
+export function clientMarker(client, environment) {
+    const location = CLIENTS[client].user(environment);
+    if ('cli' in location) {
+        // Claude Code keeps `~/.claude/` (or `$CLAUDE_CONFIG_DIR`); Codex keeps `config.toml` in its home.
+        return location.cli === 'claude'
+            ? (environment.env.CLAUDE_CONFIG_DIR ?? pathFor(environment).join(environment.homedir, '.claude'))
+            : pathFor(environment).dirname(location.configFile);
+    }
+    return location.clientDir ?? pathFor(environment).dirname(location.file);
+}
+export { pathFor };
+//# sourceMappingURL=clients.js.map

package/lib/mcpClients/clients.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"clients.js","sourceRoot":"","sources":["../../src/mcpClients/clients.ts"],"names":[],"mappings":"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"}

package/lib/mcpClients/existingEntry.d.ts

@@ -0,0 +1,16 @@
+/**
+ * What a client already has under an entry name, read from a file this module never writes
+ * (`~/.claude.json`, `config.toml`). `differs` covers anything that isn't provably the same launch,
+ * including an entry this reader can't make sense of: `--force` is then the way through, which is
+ * the safe direction to be wrong in.
+ */
+export type ExistingEntry = 'absent' | 'same' | 'differs';
+type Launch = {
+    command: string;
+    args: readonly string[];
+};
+/** @returns How `launch` compares with the user-scope `mcpServers` entry in Claude Code's `~/.claude.json`. */
+export declare function compareClaudeEntry(text: string, name: string, launch: Launch): ExistingEntry;
+/** @returns How `launch` compares with the `[mcp_servers.<name>]` table in Codex's `config.toml`. */
+export declare function compareCodexEntry(text: string, name: string, launch: Launch): ExistingEntry;
+export {};