@simplysf/simply-gitlab-mcp 0.6.2 → 0.7.0

package/lib/mcpClients/plan.js.map

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

package/lib/mcpClients/report.d.ts

@@ -0,0 +1,12 @@
+import { type ClientId, type InstallResult, type Launcher } from './types.js';
+/**
+ * Renders results as the text a command prints. Returned rather than printed, so this module never
+ * touches a stream.
+ *
+ * @param results - From `installServer`.
+ * @param launcher - Adds the note about a pinned Node binary when it is `absolute`.
+ * @returns The report, ending with what to do next in each client that changed.
+ */
+export declare function formatInstallReport(results: readonly InstallResult[], launcher?: Launcher): string;
+/** @returns The message for a missing `--client`: every id, marking the ones installed here. */
+export declare function formatClientChoices(installed: readonly ClientId[]): string;

package/lib/mcpClients/report.js

@@ -0,0 +1,63 @@
+/*
+ * 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 } from './clients.js';
+import { CLIENT_IDS } from './types.js';
+const OUTCOME_TEXT = {
+    added: { done: 'added', planned: 'would add' },
+    replaced: { done: 'replaced', planned: 'would replace' },
+    unchanged: { done: 'already installed', planned: 'already installed' },
+    conflict: { done: 'not changed (conflict)', planned: 'would not change (conflict)' },
+    failed: { done: 'failed', planned: 'would fail' },
+};
+/**
+ * Renders results as the text a command prints. Returned rather than printed, so this module never
+ * touches a stream.
+ *
+ * @param results - From `installServer`.
+ * @param launcher - Adds the note about a pinned Node binary when it is `absolute`.
+ * @returns The report, ending with what to do next in each client that changed.
+ */
+export function formatInstallReport(results, launcher) {
+    const lines = [];
+    for (const result of results) {
+        const outcome = OUTCOME_TEXT[result.outcome][result.dryRun ? 'planned' : 'done'];
+        lines.push(`${CLIENTS[result.client].displayName}: ${outcome} "${result.name}"`, `  ${result.target}`);
+        if (result.message)
+            lines.push(...result.message.split('\n').map((line) => `  ${line}`));
+        if (result.dryRun && result.outcome !== 'failed' && result.outcome !== 'unchanged') {
+            lines.push(...result.preview.split('\n').map((line) => `    ${line}`));
+        }
+    }
+    const changed = results.filter((result) => !result.dryRun && ['added', 'replaced'].includes(result.outcome));
+    if (changed.length > 0) {
+        lines.push('', 'Next:');
+        for (const result of changed)
+            lines.push(`  ${CLIENTS[result.client].displayName}: ${CLIENTS[result.client].nextStep}`);
+        if (launcher === 'absolute') {
+            lines.push('', 'These entries start this exact Node binary. If a Node upgrade (nvm, fnm, Volta) moves it, ' +
+                'run this command again with --force.');
+        }
+    }
+    return lines.join('\n');
+}
+/** @returns The message for a missing `--client`: every id, marking the ones installed here. */
+export function formatClientChoices(installed) {
+    return [
+        'Name at least one client with --client. Clients:',
+        ...CLIENT_IDS.map((client) => `  ${client.padEnd(15)} ${CLIENTS[client].displayName}${installed.includes(client) ? ' (found on this machine)' : ''}`),
+    ].join('\n');
+}
+//# sourceMappingURL=report.js.map

package/lib/mcpClients/report.js.map

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

package/lib/mcpClients/runner.d.ts

@@ -0,0 +1,9 @@
+import type { ProcessRunner } from './types.js';
+/**
+ * Runs a client CLI with its output captured. `cross-spawn` rather than `child_process.spawn`
+ * because npm installs `claude` and `codex` as `.cmd` shims on Windows, which plain `spawn` refuses
+ * to start without a shell, and a shell would need the JSON argument quoted for `cmd.exe`.
+ */
+export declare const runProcess: ProcessRunner;
+/** @returns A command line a person can paste: POSIX quoting, or double quotes on Windows. */
+export declare function formatCommandLine(executable: string, args: readonly string[], platform?: NodeJS.Platform): string;

package/lib/mcpClients/runner.js

@@ -0,0 +1,38 @@
+/*
+ * 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 spawn from 'cross-spawn';
+/**
+ * Runs a client CLI with its output captured. `cross-spawn` rather than `child_process.spawn`
+ * because npm installs `claude` and `codex` as `.cmd` shims on Windows, which plain `spawn` refuses
+ * to start without a shell, and a shell would need the JSON argument quoted for `cmd.exe`.
+ */
+export const runProcess = (executable, args) => new Promise((resolve, reject) => {
+    const child = spawn(executable, [...args], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+    let stdout = '';
+    let stderr = '';
+    child.stdout?.on('data', (chunk) => (stdout += chunk.toString()));
+    child.stderr?.on('data', (chunk) => (stderr += chunk.toString()));
+    child.on('error', reject);
+    child.on('close', (code) => resolve({ exitCode: code ?? 1, stdout, stderr }));
+});
+/** @returns A command line a person can paste: POSIX quoting, or double quotes on Windows. */
+export function formatCommandLine(executable, args, platform = process.platform) {
+    const quote = platform === 'win32'
+        ? (arg) => (/^[\w@%+=:,./\\-]+$/.test(arg) ? arg : `"${arg.replaceAll('"', '\\"')}"`)
+        : (arg) => (/^[\w@%+=:,./-]+$/.test(arg) ? arg : `'${arg.replaceAll("'", "'\\''")}'`);
+    return [executable, ...args].map(quote).join(' ');
+}
+//# sourceMappingURL=runner.js.map

package/lib/mcpClients/runner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runner.js","sourceRoot":"","sources":["../../src/mcpClients/runner.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,MAAM,aAAa,CAAC;AAGhC;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAkB,CAAC,UAAU,EAAE,IAAI,EAAE,EAAE,CAC5D,IAAI,OAAO,CAAC,CAAC,OAAO,EAAE,MAAM,EAAE,EAAE;IAC9B,MAAM,KAAK,GAAG,KAAK,CAAC,UAAU,EAAE,CAAC,GAAG,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;IACrG,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,IAAI,MAAM,GAAG,EAAE,CAAC;IAChB,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1E,KAAK,CAAC,MAAM,EAAE,EAAE,CAAC,MAAM,EAAE,CAAC,KAAa,EAAE,EAAE,CAAC,CAAC,MAAM,IAAI,KAAK,CAAC,QAAQ,EAAE,CAAC,CAAC,CAAC;IAC1E,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;IAC1B,KAAK,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,IAAI,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,QAAQ,EAAE,IAAI,IAAI,CAAC,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC;AAChF,CAAC,CAAC,CAAC;AAEL,8FAA8F;AAC9F,MAAM,UAAU,iBAAiB,CAC/B,UAAkB,EAClB,IAAuB,EACvB,WAA4B,OAAO,CAAC,QAAQ;IAE5C,MAAM,KAAK,GACT,QAAQ,KAAK,OAAO;QAClB,CAAC,CAAC,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,oBAAoB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,KAAK,CAAC,GAAG,CAAC;QACrG,CAAC,CAAC,CAAC,GAAW,EAAU,EAAE,CAAC,CAAC,kBAAkB,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC,IAAI,GAAG,CAAC,UAAU,CAAC,GAAG,EAAE,OAAO,CAAC,GAAG,CAAC,CAAC;IAC1G,OAAO,CAAC,UAAU,EAAE,GAAG,IAAI,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AACpD,CAAC"}

package/lib/mcpClients/types.d.ts

@@ -0,0 +1,98 @@
+/** Every client this module can install into, by the id `--client` takes. */
+export declare const CLIENT_IDS: readonly ["claude-code", "claude-desktop", "cursor", "vscode", "windsurf", "gemini", "codex"];
+export type ClientId = (typeof CLIENT_IDS)[number];
+/** `user` writes the client's personal configuration; `project` its repo-level file under `cwd`. */
+export type InstallScope = 'user' | 'project';
+/**
+ * How the entry starts the server. `absolute` runs this Node on the host's `bin/run.js`, which
+ * survives a GUI client's missing `PATH` and Windows' `.cmd` shims; `simply` relies on `PATH`, which
+ * is what a committed project file needs; `npx` needs no global install at all.
+ */
+export type Launcher = 'absolute' | 'simply' | 'npx';
+/** The server to install: the entry's name and the process a client should launch. */
+export type ServerSpec = {
+    name: string;
+    command: string;
+    args: string[];
+};
+/**
+ * Everything about the machine the plan depends on, passed in rather than read from `process` so
+ * planning stays pure and every platform's paths can be tested from any one of them.
+ */
+export type InstallEnvironment = {
+    platform: NodeJS.Platform;
+    homedir: string;
+    cwd: string;
+    env: Readonly<Record<string, string | undefined>>;
+};
+/** The top-level key a client keeps its servers under. */
+export type ServersKey = 'mcpServers' | 'servers';
+/** A JSON (or JSONC) configuration file to edit in place. */
+export type FileInstallPlan = {
+    kind: 'file';
+    client: ClientId;
+    scope: InstallScope;
+    name: string;
+    file: string;
+    key: ServersKey;
+    entry: Record<string, unknown>;
+    /** A directory whose absence means the client isn't installed, so the file must not be created. */
+    clientDir?: string;
+};
+/** A client whose configuration is changed through its own CLI. */
+export type CliInstallPlan = {
+    kind: 'cli';
+    client: ClientId;
+    scope: InstallScope;
+    name: string;
+    executable: string;
+    addArgs: string[];
+    removeArgs: string[];
+    /** What the entry launches, compared with what is already configured. */
+    launch: {
+        command: string;
+        args: string[];
+    };
+    /** The file the client keeps its servers in, read (never written) to find an existing entry. */
+    configFile: string;
+    configFormat: 'claude-json' | 'codex-toml';
+};
+/** A client/scope pair that has no configuration to write, e.g. Claude Desktop at project scope. */
+export type UnsupportedInstallPlan = {
+    kind: 'unsupported';
+    client: ClientId;
+    scope: InstallScope;
+    name: string;
+    reason: string;
+};
+export type InstallPlan = FileInstallPlan | CliInstallPlan | UnsupportedInstallPlan;
+export type InstallOutcome = 'added' | 'replaced' | 'unchanged' | 'conflict' | 'failed';
+export type InstallResult = {
+    client: ClientId;
+    name: string;
+    outcome: InstallOutcome;
+    /** The file written, or the command run (or to run). */
+    target: string;
+    /** True when nothing was changed because the caller asked only for the plan. */
+    dryRun: boolean;
+    /** 0 for added/replaced/unchanged, 2 for a conflict or a refused install, 1 for an I/O failure. */
+    exitCode: 0 | 1 | 2;
+    /** Why a `conflict` or `failed` happened, and what to do about it. */
+    message?: string;
+    /** The entry as written (or as it would be written), for display. */
+    preview: string;
+};
+/** Runs a client's CLI. Rejects with `code: 'ENOENT'` when the executable isn't on `PATH`. */
+export type ProcessRunner = (executable: string, args: readonly string[]) => Promise<{
+    exitCode: number;
+    stdout: string;
+    stderr: string;
+}>;
+export type ApplyOptions = {
+    /** Replace an existing entry of the same name that differs. */
+    force?: boolean;
+    /** Work out the outcome and change nothing. */
+    dryRun?: boolean;
+    /** Replaces the real process runner, for tests. */
+    runner?: ProcessRunner;
+};

package/lib/mcpClients/types.js

@@ -0,0 +1,18 @@
+/*
+ * 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.
+ */
+/** Every client this module can install into, by the id `--client` takes. */
+export const CLIENT_IDS = ['claude-code', 'claude-desktop', 'cursor', 'vscode', 'windsurf', 'gemini', 'codex'];
+//# sourceMappingURL=types.js.map

package/lib/mcpClients/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/mcpClients/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,6EAA6E;AAC7E,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,aAAa,EAAE,gBAAgB,EAAE,QAAQ,EAAE,QAAQ,EAAE,UAAU,EAAE,QAAQ,EAAE,OAAO,CAAU,CAAC"}

package/oclif.manifest.json

@@ -59,7 +59,130 @@
         "gitlab",
         "mcp.js"
       ]
+    },
+    "gitlab:mcp:install": {
+      "aliases": [],
+      "args": {},
+      "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\nCredentials 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\nRunning it again is safe: an identical entry is left alone, and a different one is only replaced with --force.",
+      "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"
+        }
+      ],
+      "flags": {
+        "json": {
+          "description": "Format output as json.",
+          "helpGroup": "GLOBAL",
+          "name": "json",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "client": {
+          "name": "client",
+          "summary": "Client to add the server to. Repeat for several.",
+          "hasDynamicHelp": false,
+          "multiple": true,
+          "options": [
+            "claude-code",
+            "claude-desktop",
+            "cursor",
+            "vscode",
+            "windsurf",
+            "gemini",
+            "codex"
+          ],
+          "type": "option"
+        },
+        "scope": {
+          "name": "scope",
+          "summary": "Your own configuration, or the repository-level file in the current directory.",
+          "default": "user",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "user",
+            "project"
+          ],
+          "type": "option"
+        },
+        "env-file": {
+          "char": "e",
+          "name": "env-file",
+          "summary": "Connection settings file for the server. Written as an absolute path.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "allow-writes": {
+          "name": "allow-writes",
+          "summary": "Register the tools that change data. Also makes the default name simply-gitlab-write.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "name": {
+          "name": "name",
+          "summary": "Entry name. Default simply-gitlab, or simply-gitlab-write with --allow-writes.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "type": "option"
+        },
+        "launcher": {
+          "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.",
+          "name": "launcher",
+          "summary": "How the entry starts simply. Default absolute for --scope user, simply for --scope project.",
+          "hasDynamicHelp": false,
+          "multiple": false,
+          "options": [
+            "absolute",
+            "simply",
+            "npx"
+          ],
+          "type": "option"
+        },
+        "force": {
+          "name": "force",
+          "summary": "Replace an existing entry of the same name that differs.",
+          "allowNo": false,
+          "type": "boolean"
+        },
+        "dry-run": {
+          "name": "dry-run",
+          "summary": "Show what would be written, and change nothing.",
+          "allowNo": false,
+          "type": "boolean"
+        }
+      },
+      "hasDynamicHelp": false,
+      "hiddenAliases": [],
+      "id": "gitlab:mcp:install",
+      "pluginAlias": "@simplysf/simply-gitlab-mcp",
+      "pluginName": "@simplysf/simply-gitlab-mcp",
+      "pluginType": "core",
+      "strict": true,
+      "summary": "Add the GitLab MCP server to MCP clients.",
+      "enableJsonFlag": true,
+      "isESM": true,
+      "relativePath": [
+        "lib",
+        "commands",
+        "gitlab",
+        "mcp",
+        "install.js"
+      ]
     }
   },
-  "version": "0.6.2"
+  "version": "0.7.0"
 }

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@simplysf/simply-gitlab-mcp",
   "description": "Model Context Protocol server exposing GitLab to AI agents, built on @simplysf/simply-gitlab-core",
-  "version": "0.6.2",
+  "version": "0.7.0",
   "author": "@ClayChipps",
   "homepage": "https://github.com/SimplySF/simply-gitlab",
   "bugs": "https://github.com/SimplySF/simply-gitlab/issues",
@@ -34,12 +34,15 @@
     "simply-gitlab-mcp": "./bin/run.js"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@oclif/core": "^4.11.2",
     "@simplysf/simply-gitlab-core": "^0.5.1",
+    "cross-spawn": "^7.0.6",
+    "jsonc-parser": "^3.3.1",
     "zod": "^4.6.5"
   },
   "devDependencies": {
+    "@types/cross-spawn": "^6.0.6",
     "@vitest/coverage-v8": "^4.1.10",
     "oclif": "^4.23.0",
     "shx": "^0.4.0",
@@ -184,5 +187,5 @@
       }
     }
   },
-  "gitHead": "dc8cdc8e13b8a4053d503cb5efbdb54f637aa19a"
+  "gitHead": "a2b493a11e9a3a2ae363c6728f8dcdc2a39b1f32"
 }