@simplysf/simply-gitlab-mcp 0.6.2 → 0.7.0

package/lib/mcpClients/existingEntry.js

@@ -0,0 +1,140 @@
+/*
+ * 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 { isDeepStrictEqual } from 'node:util';
+import { parse } from 'jsonc-parser';
+/** @returns How `launch` compares with the user-scope `mcpServers` entry in Claude Code's `~/.claude.json`. */
+export function compareClaudeEntry(text, name, launch) {
+    const errors = [];
+    const root = parse(text, errors, { allowTrailingComma: true });
+    // An unreadable file can't show an entry; `claude` itself reports whatever is wrong with it.
+    if (errors.length > 0 || !isRecord(root) || !isRecord(root.mcpServers))
+        return 'absent';
+    const entry = root.mcpServers[name];
+    if (entry === undefined)
+        return 'absent';
+    if (!isRecord(entry))
+        return 'differs';
+    const { type = 'stdio', command, args = [], env = {}, ...rest } = entry;
+    const same = type === 'stdio' &&
+        command === launch.command &&
+        isDeepStrictEqual(args, launch.args) &&
+        isDeepStrictEqual(env, {}) &&
+        Object.keys(rest).length === 0;
+    return same ? 'same' : 'differs';
+}
+/** @returns How `launch` compares with the `[mcp_servers.<name>]` table in Codex's `config.toml`. */
+export function compareCodexEntry(text, name, launch) {
+    const lines = text.split(/\r?\n/);
+    const header = lines.findIndex((line) => tableName(line) === `mcp_servers.${name}`);
+    if (header === -1)
+        return 'absent';
+    const body = [];
+    for (const line of lines.slice(header + 1)) {
+        const table = tableName(line);
+        if (table !== undefined) {
+            // A sub-table such as `[mcp_servers.<name>.env]` is more than a bare launch.
+            if (table.startsWith(`mcp_servers.${name}.`))
+                return 'differs';
+            break;
+        }
+        body.push(line);
+    }
+    const values = parseKeyValues(body.join('\n'));
+    if (!values)
+        return 'differs';
+    const { command, args = [], ...rest } = values;
+    const same = command === launch.command && isDeepStrictEqual(args, launch.args) && Object.keys(rest).length === 0;
+    return same ? 'same' : 'differs';
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** @returns The dotted name of a `[table]` header line, with quoted keys unquoted, or undefined. */
+function tableName(line) {
+    const match = /^\s*\[([^[\]]+)\]\s*(#.*)?$/.exec(line);
+    if (!match)
+        return undefined;
+    return match[1]
+        .split('.')
+        .map((part) => part.trim().replace(/^"(.*)"$|^'(.*)'$/, '$1$2'))
+        .join('.');
+}
+/**
+ * Reads `key = "string"` and `key = ["string", …]` pairs, which is all a launch-only server table
+ * holds. Anything else makes the whole table unreadable, so the caller treats it as different.
+ *
+ * @returns The pairs, or undefined if the text holds anything else.
+ */
+function parseKeyValues(text) {
+    const tokens = tokenize(text);
+    if (!tokens)
+        return undefined;
+    const values = {};
+    let i = 0;
+    while (i < tokens.length) {
+        const key = tokens[i];
+        if (key.kind !== 'key' || tokens[i + 1]?.kind !== '=')
+            return undefined;
+        i += 2;
+        const value = tokens[i];
+        if (value?.kind === 'string') {
+            values[key.value] = value.value;
+            i += 1;
+            continue;
+        }
+        if (value?.kind !== '[')
+            return undefined;
+        i += 1;
+        const items = [];
+        while (tokens[i]?.kind === 'string') {
+            items.push(tokens[i].value);
+            i += 1;
+            if (tokens[i]?.kind === ',')
+                i += 1;
+        }
+        if (tokens[i]?.kind !== ']')
+            return undefined;
+        values[key.value] = items;
+        i += 1;
+    }
+    return values;
+}
+function tokenize(text) {
+    const tokens = [];
+    const pattern = /\s+|#[^\n]*|([A-Za-z0-9_-]+)|("(?:[^"\\\n]|\\.)*")|'([^'\n]*)'|([=[\],])|(.)/gy;
+    for (const match of text.matchAll(pattern)) {
+        const [, key, basic, literal, punctuation, unexpected] = match;
+        if (unexpected !== undefined)
+            return undefined;
+        if (key !== undefined)
+            tokens.push({ kind: 'key', value: key });
+        else if (literal !== undefined)
+            tokens.push({ kind: 'string', value: literal });
+        else if (punctuation !== undefined)
+            tokens.push({ kind: punctuation, value: '' });
+        else if (basic !== undefined) {
+            try {
+                // TOML basic strings use JSON's escapes for everything a launch line needs.
+                tokens.push({ kind: 'string', value: JSON.parse(basic) });
+            }
+            catch {
+                return undefined;
+            }
+        }
+    }
+    return tokens;
+}
+//# sourceMappingURL=existingEntry.js.map

package/lib/mcpClients/existingEntry.js.map

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

package/lib/mcpClients/index.d.ts

@@ -0,0 +1,8 @@
+export { CLIENT_IDS, type ApplyOptions, type ClientId, type CliInstallPlan, type FileInstallPlan, type InstallEnvironment, type InstallOutcome, type InstallPlan, type InstallResult, type InstallScope, type Launcher, type ProcessRunner, type ServerSpec, type ServersKey, type UnsupportedInstallPlan, } from './types.js';
+export { CLIENTS } from './clients.js';
+export { planInstall, isValidServerName } from './plan.js';
+export { applyPlan } from './apply.js';
+export { installServer, exitCodeFor, detectInstalledClients, isClientId } from './install.js';
+export { buildLaunch, currentEnvironment, defaultLauncher, resolveEnvFile, SIMPLY_CLI_PACKAGE } from './launch.js';
+export { formatInstallReport, formatClientChoices } from './report.js';
+export { formatCommandLine, runProcess } from './runner.js';

package/lib/mcpClients/index.js

@@ -0,0 +1,29 @@
+/*
+ * 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.
+ */
+// The knowledge of MCP clients — where each keeps its configuration, what shape it wants, and how to
+// edit it without destroying the rest — behind `gitlab mcp install`. See
+// docs/design/0010-mcp-install.md. simply-atlassian keeps an identical copy for `atlassian mcp install`:
+// change both together. Like the core package, nothing here writes to stdout or stderr or reads
+// process.argv: it plans, applies, and returns text for the caller to print.
+export { CLIENT_IDS, } from './types.js';
+export { CLIENTS } from './clients.js';
+export { planInstall, isValidServerName } from './plan.js';
+export { applyPlan } from './apply.js';
+export { installServer, exitCodeFor, detectInstalledClients, isClientId } from './install.js';
+export { buildLaunch, currentEnvironment, defaultLauncher, resolveEnvFile, SIMPLY_CLI_PACKAGE } from './launch.js';
+export { formatInstallReport, formatClientChoices } from './report.js';
+export { formatCommandLine, runProcess } from './runner.js';
+//# sourceMappingURL=index.js.map

package/lib/mcpClients/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcpClients/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,qGAAqG;AACrG,yEAAyE;AACzE,yGAAyG;AACzG,gGAAgG;AAChG,6EAA6E;AAE7E,OAAO,EACL,UAAU,GAeX,MAAM,YAAY,CAAC;AACpB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AACvC,OAAO,EAAE,WAAW,EAAE,iBAAiB,EAAE,MAAM,WAAW,CAAC;AAC3D,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,sBAAsB,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC9F,OAAO,EAAE,WAAW,EAAE,kBAAkB,EAAE,eAAe,EAAE,cAAc,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AACnH,OAAO,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AACvE,OAAO,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC"}

package/lib/mcpClients/install.d.ts

@@ -0,0 +1,14 @@
+import { type ApplyOptions, type ClientId, type InstallEnvironment, type InstallResult, type InstallScope, type ServerSpec } from './types.js';
+/**
+ * Installs one server into each named client, in order. Every client is attempted whatever happened
+ * to the ones before it.
+ *
+ * @returns One result per client, in the order given.
+ */
+export declare function installServer(spec: ServerSpec, clients: readonly ClientId[], scope: InstallScope, environment: InstallEnvironment, options?: ApplyOptions): Promise<InstallResult[]>;
+/** @returns The exit code for a set of results: the highest any one of them contributes. */
+export declare function exitCodeFor(results: readonly InstallResult[]): 0 | 1 | 2;
+/** @returns The clients whose configuration directory exists for this user. */
+export declare function detectInstalledClients(environment: InstallEnvironment): Promise<ClientId[]>;
+/** @returns Whether `value` is a client id this module knows. */
+export declare function isClientId(value: string): value is ClientId;

package/lib/mcpClients/install.js

@@ -0,0 +1,55 @@
+/*
+ * 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 { applyPlan } from './apply.js';
+import { clientMarker } from './clients.js';
+import { planInstall } from './plan.js';
+import { CLIENT_IDS, } from './types.js';
+/**
+ * Installs one server into each named client, in order. Every client is attempted whatever happened
+ * to the ones before it.
+ *
+ * @returns One result per client, in the order given.
+ */
+export async function installServer(spec, clients, scope, environment, options = {}) {
+    const results = [];
+    for (const client of new Set(clients)) {
+        // eslint-disable-next-line no-await-in-loop -- one client at a time keeps CLI output and file writes in a predictable order
+        results.push(await applyPlan(planInstall(spec, client, scope, environment), options));
+    }
+    return results;
+}
+/** @returns The exit code for a set of results: the highest any one of them contributes. */
+export function exitCodeFor(results) {
+    return results.reduce((highest, result) => (result.exitCode > highest ? result.exitCode : highest), 0);
+}
+/** @returns The clients whose configuration directory exists for this user. */
+export async function detectInstalledClients(environment) {
+    const found = await Promise.all(CLIENT_IDS.map(async (client) => {
+        try {
+            return (await fs.stat(clientMarker(client, environment))).isDirectory();
+        }
+        catch {
+            return false;
+        }
+    }));
+    return CLIENT_IDS.filter((_, index) => found[index]);
+}
+/** @returns Whether `value` is a client id this module knows. */
+export function isClientId(value) {
+    return CLIENT_IDS.includes(value);
+}
+//# sourceMappingURL=install.js.map

package/lib/mcpClients/install.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"install.js","sourceRoot":"","sources":["../../src/mcpClients/install.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AACvC,OAAO,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EACL,UAAU,GAOX,MAAM,YAAY,CAAC;AAEpB;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,IAAgB,EAChB,OAA4B,EAC5B,KAAmB,EACnB,WAA+B,EAC/B,UAAwB,EAAE;IAE1B,MAAM,OAAO,GAAoB,EAAE,CAAC;IACpC,KAAK,MAAM,MAAM,IAAI,IAAI,GAAG,CAAC,OAAO,CAAC,EAAE,CAAC;QACtC,4HAA4H;QAC5H,OAAO,CAAC,IAAI,CAAC,MAAM,SAAS,CAAC,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,WAAW,CAAC,EAAE,OAAO,CAAC,CAAC,CAAC;IACxF,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,4FAA4F;AAC5F,MAAM,UAAU,WAAW,CAAC,OAAiC;IAC3D,OAAO,OAAO,CAAC,MAAM,CAAY,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,GAAG,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,CAAC,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,CAAC;AACpH,CAAC;AAED,+EAA+E;AAC/E,MAAM,CAAC,KAAK,UAAU,sBAAsB,CAAC,WAA+B;IAC1E,MAAM,KAAK,GAAG,MAAM,OAAO,CAAC,GAAG,CAC7B,UAAU,CAAC,GAAG,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE;QAC9B,IAAI,CAAC;YACH,OAAO,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,YAAY,CAAC,MAAM,EAAE,WAAW,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,CAAC;QAC1E,CAAC;QAAC,MAAM,CAAC;YACP,OAAO,KAAK,CAAC;QACf,CAAC;IACH,CAAC,CAAC,CACH,CAAC;IACF,OAAO,UAAU,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,CAAC;AACvD,CAAC;AAED,iEAAiE;AACjE,MAAM,UAAU,UAAU,CAAC,KAAa;IACtC,OAAQ,UAAgC,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC;AAC3D,CAAC"}

package/lib/mcpClients/jsonEdit.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Sets `root[key][name] = value` in JSON or JSONC text, changing no byte outside that entry.
+ *
+ * Not `jsonc-parser`'s `modify`: given formatting options, it reformats the neighbouring entry and
+ * can move a trailing comment onto the new line, and without them it writes the value on one line.
+ * Here the new text is the only text: it takes the file's own indentation and line endings, and a
+ * comment after the previous entry stays on that entry's line.
+ *
+ * @param text - The file, already known to parse to an object whose `key`, if present, is an object.
+ * @returns The new text.
+ */
+export declare function setNestedEntry(text: string, key: string, name: string, value: unknown): string;

package/lib/mcpClients/jsonEdit.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 { findNodeAtLocation, parseTree } from 'jsonc-parser';
+/**
+ * Sets `root[key][name] = value` in JSON or JSONC text, changing no byte outside that entry.
+ *
+ * Not `jsonc-parser`'s `modify`: given formatting options, it reformats the neighbouring entry and
+ * can move a trailing comment onto the new line, and without them it writes the value on one line.
+ * Here the new text is the only text: it takes the file's own indentation and line endings, and a
+ * comment after the previous entry stays on that entry's line.
+ *
+ * @param text - The file, already known to parse to an object whose `key`, if present, is an object.
+ * @returns The new text.
+ */
+export function setNestedEntry(text, key, name, value) {
+    const eol = text.includes('\r\n') ? '\r\n' : '\n';
+    const unit = indentUnit(text);
+    if (text.trim() === '') {
+        return [`{`, `${unit}${property(key, { [name]: value }, unit, unit, eol)}`, `}`, ''].join(eol);
+    }
+    const root = parseTree(text, [], { allowTrailingComma: true });
+    const existing = findNodeAtLocation(root, [key, name]);
+    if (existing) {
+        const indent = lineIndent(text, existing.parent.offset);
+        return applyEdit(text, {
+            offset: existing.offset,
+            length: existing.length,
+            content: formatValue(value, indent, unit, eol),
+        });
+    }
+    const servers = findNodeAtLocation(root, [key]);
+    return servers
+        ? insertProperty(text, servers, name, value, unit, eol)
+        : insertProperty(text, root, key, { [name]: value }, unit, eol);
+}
+function insertProperty(text, object, name, value, unit, eol) {
+    const properties = object.children ?? [];
+    const parentIndent = lineIndent(text, object.offset);
+    if (properties.length === 0) {
+        const indent = parentIndent + unit;
+        const open = object.offset + 1;
+        const close = object.offset + object.length - 1;
+        const inner = text.slice(open, close);
+        const content = `${eol}${indent}${property(name, value, indent, unit, eol)}`;
+        // `{}` becomes a block; anything inside an otherwise empty object (a comment) is kept after it.
+        return inner.trim() === ''
+            ? applyEdit(text, { offset: open, length: close - open, content: `${content}${eol}${parentIndent}` })
+            : applyEdit(text, { offset: open, length: 0, content: `${content},` });
+    }
+    const last = properties.at(-1);
+    const first = properties[0];
+    const indent = startsLine(text, first.offset) ? lineIndent(text, first.offset) : parentIndent + unit;
+    const valueEnd = last.offset + last.length;
+    // A trailing comma already separates the last entry from whatever follows it.
+    const afterValue = /^\s*,/.exec(text.slice(valueEnd));
+    const commaEnd = afterValue ? valueEnd + afterValue[0].length : valueEnd;
+    // The new entry goes after anything else on the last entry's line (a `// comment`), unless that
+    // line also closes the object, as in `{ "a": 1 }`.
+    const lineEnd = endOfLine(text, commaEnd);
+    const restOfLine = text.slice(commaEnd, lineEnd);
+    const at = /^[ \t]*(\/\/.*|\/\*.*?\*\/[ \t]*)?$/.test(restOfLine) ? lineEnd : commaEnd;
+    const entry = `${eol}${indent}${property(name, value, indent, unit, eol)}`;
+    if (afterValue)
+        return applyEdit(text, { offset: at, length: 0, content: entry });
+    if (at === valueEnd)
+        return applyEdit(text, { offset: at, length: 0, content: `,${entry}` });
+    return applyEdits(text, [
+        { offset: valueEnd, length: 0, content: ',' },
+        { offset: at, length: 0, content: entry },
+    ]);
+}
+function property(name, value, indent, unit, eol) {
+    return `${JSON.stringify(name)}: ${formatValue(value, indent, unit, eol)}`;
+}
+/** @returns `value` as JSON, its continuation lines indented from `indent`. */
+function formatValue(value, indent, unit, eol) {
+    return JSON.stringify(value, null, unit).split('\n').join(`${eol}${indent}`);
+}
+/** @returns The file's indentation step: its first indented line's leading tab or spaces, else two spaces. */
+function indentUnit(text) {
+    const indent = /^([ \t]+)\S/m.exec(text)?.[1];
+    if (!indent)
+        return '  ';
+    return indent.startsWith('\t') ? '\t' : indent;
+}
+function lineStart(text, offset) {
+    return text.lastIndexOf('\n', offset - 1) + 1;
+}
+function lineIndent(text, offset) {
+    return /^[ \t]*/.exec(text.slice(lineStart(text, offset)))?.[0] ?? '';
+}
+function startsLine(text, offset) {
+    return text.slice(lineStart(text, offset), offset).trim() === '';
+}
+function endOfLine(text, offset) {
+    const newline = text.indexOf('\n', offset);
+    if (newline === -1)
+        return text.length;
+    return text[newline - 1] === '\r' ? newline - 1 : newline;
+}
+function applyEdit(text, edit) {
+    return applyEdits(text, [edit]);
+}
+/** Applies non-overlapping edits, last first, so earlier offsets stay valid. */
+function applyEdits(text, edits) {
+    return [...edits]
+        .sort((a, b) => b.offset - a.offset)
+        .reduce((result, edit) => result.slice(0, edit.offset) + edit.content + result.slice(edit.offset + edit.length), text);
+}
+//# sourceMappingURL=jsonEdit.js.map

package/lib/mcpClients/jsonEdit.js.map

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

package/lib/mcpClients/launch.d.ts

@@ -0,0 +1,36 @@
+import type { InstallEnvironment, InstallScope, Launcher } from './types.js';
+/** The package `npx` fetches for the `npx` launcher. */
+export declare const SIMPLY_CLI_PACKAGE = "@simplysf/simply-cli";
+/** @returns The environment of the running process, for `planInstall` and friends. */
+export declare function currentEnvironment(): InstallEnvironment;
+/**
+ * `absolute` for personal configuration, where the path is right for the only person who reads it;
+ * `simply` for a committed project file, where an absolute path is wrong for everyone else.
+ *
+ * @returns The launcher to use when the caller didn't name one.
+ */
+export declare function defaultLauncher(scope: InstallScope): Launcher;
+/**
+ * Builds the process an entry launches.
+ *
+ * @param launcher - How to start `simply`.
+ * @param simplyArgs - The `simply` arguments, e.g. `['atlassian', 'mcp', '--allow-writes']`.
+ * @param host - For `absolute`: the Node binary (`process.execPath`) and the host's `bin/run.js`.
+ * @returns The entry's `command` and `args`.
+ */
+export declare function buildLaunch(launcher: Launcher, simplyArgs: readonly string[], host: {
+    nodePath: string;
+    runScript: string;
+}): {
+    command: string;
+    args: string[];
+};
+/**
+ * Makes an `--env-file` path absolute and checks it exists, here, at install time. A client starts
+ * the server from a working directory of its own, so `~` and relative paths written into its
+ * configuration would resolve somewhere else, or nowhere.
+ *
+ * @returns The absolute path.
+ * @throws When the file doesn't exist or isn't a file.
+ */
+export declare function resolveEnvFile(file: string, environment: InstallEnvironment): Promise<string>;

package/lib/mcpClients/launch.js

@@ -0,0 +1,75 @@
+/*
+ * 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 os from 'node:os';
+import { pathFor } from './clients.js';
+/** The package `npx` fetches for the `npx` launcher. */
+export const SIMPLY_CLI_PACKAGE = '@simplysf/simply-cli';
+/** @returns The environment of the running process, for `planInstall` and friends. */
+export function currentEnvironment() {
+    return { platform: process.platform, homedir: os.homedir(), cwd: process.cwd(), env: process.env };
+}
+/**
+ * `absolute` for personal configuration, where the path is right for the only person who reads it;
+ * `simply` for a committed project file, where an absolute path is wrong for everyone else.
+ *
+ * @returns The launcher to use when the caller didn't name one.
+ */
+export function defaultLauncher(scope) {
+    return scope === 'project' ? 'simply' : 'absolute';
+}
+/**
+ * Builds the process an entry launches.
+ *
+ * @param launcher - How to start `simply`.
+ * @param simplyArgs - The `simply` arguments, e.g. `['atlassian', 'mcp', '--allow-writes']`.
+ * @param host - For `absolute`: the Node binary (`process.execPath`) and the host's `bin/run.js`.
+ * @returns The entry's `command` and `args`.
+ */
+export function buildLaunch(launcher, simplyArgs, host) {
+    switch (launcher) {
+        case 'absolute':
+            return { command: host.nodePath, args: [host.runScript, ...simplyArgs] };
+        case 'npx':
+            return { command: 'npx', args: ['-y', SIMPLY_CLI_PACKAGE, ...simplyArgs] };
+        case 'simply':
+            return { command: 'simply', args: [...simplyArgs] };
+    }
+}
+/**
+ * Makes an `--env-file` path absolute and checks it exists, here, at install time. A client starts
+ * the server from a working directory of its own, so `~` and relative paths written into its
+ * configuration would resolve somewhere else, or nowhere.
+ *
+ * @returns The absolute path.
+ * @throws When the file doesn't exist or isn't a file.
+ */
+export async function resolveEnvFile(file, environment) {
+    const p = pathFor(environment);
+    const expanded = /^~(?=$|[/\\])/.test(file) ? p.join(environment.homedir, file.slice(1)) : file;
+    const absolute = p.resolve(environment.cwd, expanded);
+    let isFile = false;
+    try {
+        isFile = (await fs.stat(absolute)).isFile();
+    }
+    catch {
+        // Reported below, with the resolved path, which is the useful part.
+    }
+    if (!isFile)
+        throw new Error(`--env-file ${absolute} does not exist or is not a file.`);
+    return absolute;
+}
+//# sourceMappingURL=launch.js.map

package/lib/mcpClients/launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"launch.js","sourceRoot":"","sources":["../../src/mcpClients/launch.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAE,MAAM,kBAAkB,CAAC;AAClC,OAAO,EAAE,MAAM,SAAS,CAAC;AACzB,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAGvC,wDAAwD;AACxD,MAAM,CAAC,MAAM,kBAAkB,GAAG,sBAAsB,CAAC;AAEzD,sFAAsF;AACtF,MAAM,UAAU,kBAAkB;IAChC,OAAO,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,EAAE,GAAG,EAAE,OAAO,CAAC,GAAG,EAAE,CAAC;AACrG,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,eAAe,CAAC,KAAmB;IACjD,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,UAAU,CAAC;AACrD,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,UAAU,WAAW,CACzB,QAAkB,EAClB,UAA6B,EAC7B,IAA6C;IAE7C,QAAQ,QAAQ,EAAE,CAAC;QACjB,KAAK,UAAU;YACb,OAAO,EAAE,OAAO,EAAE,IAAI,CAAC,QAAQ,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC;QAC3E,KAAK,KAAK;YACR,OAAO,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC,IAAI,EAAE,kBAAkB,EAAE,GAAG,UAAU,CAAC,EAAE,CAAC;QAC7E,KAAK,QAAQ;YACX,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC,GAAG,UAAU,CAAC,EAAE,CAAC;IACxD,CAAC;AACH,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAAC,IAAY,EAAE,WAA+B;IAChF,MAAM,CAAC,GAAG,OAAO,CAAC,WAAW,CAAC,CAAC;IAC/B,MAAM,QAAQ,GAAG,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,WAAW,CAAC,OAAO,EAAE,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC;IAChG,MAAM,QAAQ,GAAG,CAAC,CAAC,OAAO,CAAC,WAAW,CAAC,GAAG,EAAE,QAAQ,CAAC,CAAC;IACtD,IAAI,MAAM,GAAG,KAAK,CAAC;IACnB,IAAI,CAAC;QACH,MAAM,GAAG,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,CAAC,CAAC,MAAM,EAAE,CAAC;IAC9C,CAAC;IAAC,MAAM,CAAC;QACP,oEAAoE;IACtE,CAAC;IACD,IAAI,CAAC,MAAM;QAAE,MAAM,IAAI,KAAK,CAAC,cAAc,QAAQ,mCAAmC,CAAC,CAAC;IACxF,OAAO,QAAQ,CAAC;AAClB,CAAC"}

package/lib/mcpClients/plan.d.ts

@@ -0,0 +1,14 @@
+import type { ClientId, InstallEnvironment, InstallPlan, InstallScope, ServerSpec } from './types.js';
+/** @returns Whether every client accepts `name` as an entry name. */
+export declare function isValidServerName(name: string): boolean;
+/**
+ * Works out what installing `spec` into one client means: which file, or which CLI command. Reads
+ * nothing and writes nothing; `applyPlan` does the rest.
+ *
+ * @param spec - The entry name and the process to launch.
+ * @param client - The client to install into.
+ * @param scope - The client's personal configuration, or its repo-level file under `environment.cwd`.
+ * @param environment - Platform, home directory, working directory and environment variables.
+ * @returns The plan. An unsupported client/scope pair, or an invalid name, plans as `unsupported`.
+ */
+export declare function planInstall(spec: ServerSpec, client: ClientId, scope: InstallScope, environment: InstallEnvironment): InstallPlan;

package/lib/mcpClients/plan.js

@@ -0,0 +1,95 @@
+/*
+ * 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 { CLIENTS, pathFor } from './clients.js';
+/** Entry names every client accepts: Codex, the strictest, takes nothing else as a TOML bare key. */
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+/** @returns Whether every client accepts `name` as an entry name. */
+export function isValidServerName(name) {
+    return SERVER_NAME.test(name);
+}
+/**
+ * Works out what installing `spec` into one client means: which file, or which CLI command. Reads
+ * nothing and writes nothing; `applyPlan` does the rest.
+ *
+ * @param spec - The entry name and the process to launch.
+ * @param client - The client to install into.
+ * @param scope - The client's personal configuration, or its repo-level file under `environment.cwd`.
+ * @param environment - Platform, home directory, working directory and environment variables.
+ * @returns The plan. An unsupported client/scope pair, or an invalid name, plans as `unsupported`.
+ */
+export function planInstall(spec, client, scope, environment) {
+    const base = { client, scope, name: spec.name };
+    const definition = CLIENTS[client];
+    if (!isValidServerName(spec.name)) {
+        return {
+            ...base,
+            kind: 'unsupported',
+            reason: `"${spec.name}" is not a valid server name. Use only letters, digits, "-" and "_".`,
+        };
+    }
+    const launch = { command: spec.command, args: [...spec.args] };
+    if (scope === 'project') {
+        if (!definition.project) {
+            return {
+                ...base,
+                kind: 'unsupported',
+                reason: `${definition.displayName} has no project-level configuration. Use --scope user.`,
+            };
+        }
+        const { file, key, typed } = definition.project;
+        return {
+            ...base,
+            kind: 'file',
+            file: pathFor(environment).resolve(environment.cwd, file),
+            key,
+            entry: typed ? { type: 'stdio', ...launch } : launch,
+        };
+    }
+    const location = definition.user(environment);
+    if ('cli' in location) {
+        if (location.cli === 'claude') {
+            return {
+                ...base,
+                kind: 'cli',
+                executable: 'claude',
+                addArgs: ['mcp', 'add-json', spec.name, JSON.stringify({ type: 'stdio', ...launch }), '--scope', 'user'],
+                removeArgs: ['mcp', 'remove', spec.name, '--scope', 'user'],
+                launch,
+                configFile: location.configFile,
+                configFormat: 'claude-json',
+            };
+        }
+        return {
+            ...base,
+            kind: 'cli',
+            executable: 'codex',
+            addArgs: ['mcp', 'add', spec.name, '--', launch.command, ...launch.args],
+            removeArgs: ['mcp', 'remove', spec.name],
+            launch,
+            configFile: location.configFile,
+            configFormat: 'codex-toml',
+        };
+    }
+    return {
+        ...base,
+        kind: 'file',
+        file: location.file,
+        key: location.key,
+        entry: location.typed ? { type: 'stdio', ...launch } : launch,
+        clientDir: location.clientDir,
+    };
+}
+//# sourceMappingURL=plan.js.map