@zereight/mcp-gitlab 2.3.8-next.144 → 2.3.8-next.145

package/README.ko.md

@@ -10,7 +10,7 @@
 
 `@zereight/mcp-gitlab`의 권장 로컬 PAT 설치입니다. 명령 인자는 [Claude Code](./docs/clients/claude-code.md)와 [Codex](./docs/clients/codex.md) 가이드와 같습니다.
 
-`zereight-mcp-gitlab` 바이너리를 먼저 설치하세요. `npm install -g @zereight/mcp-gitlab`, 또는 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 다음 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`.
+`zereight-mcp-gitlab` 바이너리를 먼저 설치하세요. `npm install -g @zereight/mcp-gitlab`, 또는 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 다음 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. 공식 MCP Registry 항목: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). 한 줄 설치: `npx -y @zereight/mcp-gitlab@latest`.
 
 토큰을 화면에 표시하지 않고 읽은 다음 export 하세요. 셸 기록에는 변수 이름만 남습니다.
 
@@ -202,7 +202,7 @@ CLI 인자는 환경 변수보다 우선합니다.
 
 `zereight-mcp-gitlab auth`는 MCP 서버 플래그가 아니라 서브커맨드입니다. GitLab device flow를 실행한 뒤 종료합니다. [CLI 인자](./docs/getting-started/cli-arguments.md#auth)를 참고하세요.
 
-같은 바이너리는 `gh` 스타일 GitLab CLI이기도 합니다 (`tool <name>` 또는 `mr list` 같은 curated 명령). **MCP 등록은 필요 없습니다** — PAT를 설정하거나, `auth`를 실행한 뒤 `GITLAB_USE_OAUTH=true`를 설정하면 됩니다: [MCP 없이 CLI 사용하기](./docs/getting-started/cli-without-mcp.md). 전체 페이로드는 터미널에서 이 CLI로 읽습니다. MCP 응답은 대화에 남습니다. `GITLAB_MCP_COMPACT_RESULTS=true`(또는 `--compact-results`)를 켜면 큰 도구 응답이 미리보기와 CLI 명령으로 바뀝니다. Human CLI 자체는 compact 되지 않습니다. permission mode, toolsets, denied-tools regex, tool-policy는 MCP와 같습니다. destructive 도구와 `GITLAB_TOOL_POLICY_APPROVE` 도구는 `--yes`가 필요합니다. [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)를 참고하세요.
+같은 바이너리는 `gh` 스타일 GitLab CLI이기도 합니다 (`tool <name>` 또는 `mr list` 같은 curated 명령). **MCP 등록은 필요 없습니다** — PAT를 설정하거나, `auth`를 실행한 뒤 `GITLAB_USE_OAUTH=true`를 설정하면 됩니다: [MCP 없이 CLI 사용하기](./docs/getting-started/cli-without-mcp.md). `setup --cursor` / `setup --claude`는 클라이언트 설정을 출력하고, `doctor`는 토큰·API URL·toolset·버전을 점검합니다. 전체 페이로드는 터미널에서 이 CLI로 읽습니다. MCP 응답은 대화에 남습니다. `GITLAB_MCP_COMPACT_RESULTS=true`(또는 `--compact-results`)를 켜면 큰 도구 응답이 미리보기와 CLI 명령으로 바뀝니다. Human CLI 자체는 compact 되지 않습니다. permission mode, toolsets, denied-tools regex, tool-policy는 MCP와 같습니다. destructive 도구와 `GITLAB_TOOL_POLICY_APPROVE` 도구는 `--yes`가 필요합니다. [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)를 참고하세요.
 
 > **세밀한 도구 필터링:** `GITLAB_PERMISSION_MODE=modify`로 생성/수정은 허용하고 모든 삭제 도구와
 > 파괴적인 중단(teardown) 도구(`cancel_pipeline`, `cancel_pipeline_job`, `stop_environment`,

package/README.md

@@ -15,7 +15,7 @@
 
 Install `@zereight/mcp-gitlab` with the recommended local personal-access-token setup. These commands use the same arguments as the [Claude Code](./docs/clients/claude-code.md) and [Codex](./docs/clients/codex.md) guides.
 
-Install the `zereight-mcp-gitlab` binary first with `npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` and `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`.
+Install the `zereight-mcp-gitlab` binary first with `npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` and `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. Official MCP Registry listing: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). One-liner: `npx -y @zereight/mcp-gitlab@latest`.
 
 Read the token without echo, then export it. The shell history keeps the variable name.
 
@@ -207,7 +207,7 @@ CLI arguments take precedence over environment variables.
 
 `zereight-mcp-gitlab auth` is a subcommand (not an MCP server flag). It runs GitLab device flow and exits. See [CLI Arguments](./docs/getting-started/cli-arguments.md#auth).
 
-The same binary is also a `gh`-style GitLab CLI (`tool <name>` or curated forms such as `mr list`). **No MCP registration is needed** — set a PAT, or run `auth` and set `GITLAB_USE_OAUTH=true`: see [CLI without MCP](./docs/getting-started/cli-without-mcp.md). Use it for the full payload in a terminal. MCP replies stay in the chat unless you set `GITLAB_MCP_COMPACT_RESULTS=true` (or `--compact-results`), which replaces oversized tool replies with a preview and a CLI command. Human CLI is never compacted. Same permission mode, toolsets, denied-tools regex, and tool-policy filters. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`. See [Human CLI](./docs/getting-started/cli-arguments.md#human-cli).
+The same binary is also a `gh`-style GitLab CLI (`tool <name>` or curated forms such as `mr list`). **No MCP registration is needed** — set a PAT, or run `auth` and set `GITLAB_USE_OAUTH=true`: see [CLI without MCP](./docs/getting-started/cli-without-mcp.md). `setup --cursor` / `setup --claude` prints client config; `doctor` checks token, API URL, toolsets, and version. Use it for the full payload in a terminal. MCP replies stay in the chat unless you set `GITLAB_MCP_COMPACT_RESULTS=true` (or `--compact-results`), which replaces oversized tool replies with a preview and a CLI command. Human CLI is never compacted. Same permission mode, toolsets, denied-tools regex, and tool-policy filters. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`. See [Human CLI](./docs/getting-started/cli-arguments.md#human-cli).
 
 > **Fine-grained tool filtering:** use `GITLAB_PERMISSION_MODE=modify` to allow create/update while
 > blocking every delete tool and the destructive teardown tools (`cancel_pipeline`,

package/README.pt-BR.md

@@ -10,7 +10,7 @@
 
 Instalação local recomendada com PAT para `@zereight/mcp-gitlab`. Os argumentos são os mesmos dos guias de [Claude Code](./docs/clients/claude-code.md) e [Codex](./docs/clients/codex.md).
 
-Instale o binário `zereight-mcp-gitlab` antes. `npm install -g @zereight/mcp-gitlab`, ou Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` e `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`.
+Instale o binário `zereight-mcp-gitlab` antes. `npm install -g @zereight/mcp-gitlab`, ou Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` e `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`. Listagem oficial no MCP Registry: [`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp). Instalação em uma linha: `npx -y @zereight/mcp-gitlab@latest`.
 
 Leia o token sem eco e exporte. O histórico do shell fica só com o nome da variável.
 
@@ -202,7 +202,7 @@ Os argumentos de CLI têm precedência sobre as variáveis de ambiente.
 
 `zereight-mcp-gitlab auth` é um subcomando, não uma flag do servidor MCP. Ele executa o device flow do GitLab e encerra. Veja [Argumentos de CLI](./docs/getting-started/cli-arguments.md#auth).
 
-O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou formas curadas como `mr list`). **Não é necessário registrar o MCP** — defina um PAT, ou execute `auth` e defina `GITLAB_USE_OAUTH=true`: veja [CLI sem MCP](./docs/getting-started/cli-without-mcp.md). Use-o para ver a carga completa no terminal. As respostas do MCP permanecem no chat, a menos que você defina `GITLAB_MCP_COMPACT_RESULTS=true` (ou `--compact-results`), o que substitui respostas grandes de ferramentas por uma prévia e um comando CLI. A CLI humana nunca é compactada. Os mesmos filtros de permission mode, toolsets, denied-tools regex e tool-policy se aplicam. Ferramentas destrutivas e ferramentas com `GITLAB_TOOL_POLICY_APPROVE` exigem `--yes`. Consulte [CLI Humana](./docs/getting-started/cli-arguments.md#human-cli).
+O mesmo binário também é uma CLI do GitLab no estilo `gh` (`tool <name>` ou formas curadas como `mr list`). **Não é necessário registrar o MCP** — defina um PAT, ou execute `auth` e defina `GITLAB_USE_OAUTH=true`: veja [CLI sem MCP](./docs/getting-started/cli-without-mcp.md). `setup --cursor` / `setup --claude` imprime a configuração do cliente; `doctor` verifica token, URL da API, toolsets e versão. Use-o para ver a carga completa no terminal. As respostas do MCP permanecem no chat, a menos que você defina `GITLAB_MCP_COMPACT_RESULTS=true` (ou `--compact-results`), o que substitui respostas grandes de ferramentas por uma prévia e um comando CLI. A CLI humana nunca é compactada. Os mesmos filtros de permission mode, toolsets, denied-tools regex e tool-policy se aplicam. Ferramentas destrutivas e ferramentas com `GITLAB_TOOL_POLICY_APPROVE` exigem `--yes`. Consulte [CLI Humana](./docs/getting-started/cli-arguments.md#human-cli).
 
 > **Filtragem granular de ferramentas:** use `GITLAB_PERMISSION_MODE=modify` para permitir criação/atualização enquanto
 > bloqueia todas as ferramentas de exclusão e as ferramentas destrutivas de teardown (`cancel_pipeline`,

package/README.zh-CN.md

@@ -10,7 +10,7 @@
 
 下面是 `@zereight/mcp-gitlab` 的推荐本地 PAT 安装。命令参数与 [Claude Code](./docs/clients/claude-code.md) 和 [Codex](./docs/clients/codex.md) 指南相同。
 
-先安装 `zereight-mcp-gitlab` 二进制。`npm install -g @zereight/mcp-gitlab`，或 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 然后 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`。
+先安装 `zereight-mcp-gitlab` 二进制。`npm install -g @zereight/mcp-gitlab`，或 Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` 然后 `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`。官方 MCP Registry 条目：[`io.github.zereight/gitlab-mcp`](https://registry.modelcontextprotocol.io/?q=io.github.zereight%2Fgitlab-mcp)。一键安装：`npx -y @zereight/mcp-gitlab@latest`。
 
 先不回显地读取令牌，再 export。shell 历史里只保留变量名。
 
@@ -202,7 +202,7 @@ CLI 参数优先于环境变量。
 
 `zereight-mcp-gitlab auth` 是子命令，不是 MCP 服务器参数。它运行 GitLab device flow 后退出。参见 [CLI 参数](./docs/getting-started/cli-arguments.md#auth)。
 
-同一二进制也是 `gh` 风格的 GitLab CLI（`tool <name>`，或 `mr list` 这类 curated 命令）。**无需注册 MCP**——设置 PAT，或运行 `auth` 后设置 `GITLAB_USE_OAUTH=true`：参见 [无需 MCP 使用 CLI](./docs/getting-started/cli-without-mcp.md)。完整结果在终端用 CLI 查看。MCP 回复仍进入对话。设置 `GITLAB_MCP_COMPACT_RESULTS=true`（或 `--compact-results`）后，过大的工具回复会变成预览加上 CLI 命令。Human CLI 本身不会被 compact。permission mode、toolsets、denied-tools regex 和 tool-policy 与 MCP 相同。破坏性工具以及 `GITLAB_TOOL_POLICY_APPROVE` 工具需要 `--yes`。参见 [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)。
+同一二进制也是 `gh` 风格的 GitLab CLI（`tool <name>`，或 `mr list` 这类 curated 命令）。**无需注册 MCP**——设置 PAT，或运行 `auth` 后设置 `GITLAB_USE_OAUTH=true`：参见 [无需 MCP 使用 CLI](./docs/getting-started/cli-without-mcp.md)。`setup --cursor` / `setup --claude` 会打印客户端配置；`doctor` 检查 token、API URL、toolset 和版本。完整结果在终端用 CLI 查看。MCP 回复仍进入对话。设置 `GITLAB_MCP_COMPACT_RESULTS=true`（或 `--compact-results`）后，过大的工具回复会变成预览加上 CLI 命令。Human CLI 本身不会被 compact。permission mode、toolsets、denied-tools regex 和 tool-policy 与 MCP 相同。破坏性工具以及 `GITLAB_TOOL_POLICY_APPROVE` 工具需要 `--yes`。参见 [Human CLI](./docs/getting-started/cli-arguments.md#human-cli)。
 
 > **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新，同时阻止所有删除工具以及
 > 破坏性的拆除（teardown）工具（`cancel_pipeline`、`cancel_pipeline_job`、`stop_environment`、

package/build/cli/args.js

@@ -7,7 +7,17 @@ export class CliUsageError extends Error {
     }
 }
 const SCRIPT_PATH_PATTERN = /\.(cjs|mjs|js|cts|mts|ts)$/;
-const FLAGS_WITHOUT_VALUE = new Set(["help", "yes", ...BOOLEAN_CLI_FLAG_NAMES]);
+const FLAGS_WITHOUT_VALUE = new Set([
+    "help",
+    "yes",
+    "cursor",
+    "claude",
+    "write",
+    "skill",
+    "probe",
+    "oauth",
+    ...BOOLEAN_CLI_FLAG_NAMES,
+]);
 const GLOBAL_FLAG_NAMES = new Set([
     "help",
     "yes",

package/build/cli/curated.js

@@ -199,7 +199,11 @@ export function canonicalGroup(name) {
     return GROUP_ALIASES[name];
 }
 export function isKnownCliCommand(name) {
-    return name === "auth" || name === "tool" || canonicalGroup(name) !== undefined;
+    return (name === "auth" ||
+        name === "tool" ||
+        name === "setup" ||
+        name === "doctor" ||
+        canonicalGroup(name) !== undefined);
 }
 export function findCuratedCommand(group, action) {
     const canonical = canonicalGroup(group);

package/build/cli/doctor.js

@@ -0,0 +1,104 @@
+import { SERVER_VERSION } from "../server/version.js";
+export function doctorHelpText() {
+    return `zereight-mcp-gitlab doctor
+
+Check token presence, API URL, permission mode, toolsets, and package version.
+Does not print secret values.
+
+Usage:
+  zereight-mcp-gitlab doctor [--probe]
+  zereight-mcp-gitlab doctor --help
+
+Flags:
+  --probe    GET {apiUrl}/user with the configured credentials (network)
+`;
+}
+export function packageVersion() {
+    return SERVER_VERSION;
+}
+export function runDoctor(input) {
+    const checks = [
+        credentialCheck(input.credentials),
+        apiUrlCheck(input.apiUrl),
+        permissionModeCheck(input.permissionMode),
+        toolsetCheck(input.toolsetsRaw),
+        versionCheck(input.version),
+    ];
+    return formatDoctorReport(checks);
+}
+export async function runDoctorWithOptionalProbe(input) {
+    const report = runDoctor(input);
+    if (input.probe === undefined) {
+        return report;
+    }
+    const probe = await input.probe(input.apiUrl);
+    return formatDoctorReport([
+        ...report.checks,
+        { name: "gitlab_user", ok: probe.ok, detail: probe.detail },
+    ]);
+}
+export function formatDoctorReport(checks) {
+    const ok = checks.every(check => check.ok);
+    const lines = checks.map(check => `${check.ok ? "ok" : "fail"}  ${check.name}: ${check.detail}`);
+    return {
+        checks,
+        ok,
+        text: `${lines.join("\n")}\n`,
+    };
+}
+function credentialCheck(credentials) {
+    const hasAny = credentials.hasPersonalAccessToken ||
+        credentials.hasJobToken ||
+        credentials.hasCookie ||
+        credentials.useOAuth;
+    return {
+        name: "credentials",
+        ok: hasAny,
+        detail: hasAny
+            ? "a token, job token, cookie, or OAuth is configured (value hidden)"
+            : "set GITLAB_PERSONAL_ACCESS_TOKEN or run `zereight-mcp-gitlab auth`",
+    };
+}
+function apiUrlCheck(apiUrl) {
+    try {
+        const parsed = new URL(apiUrl);
+        const hasApi = parsed.pathname.includes("/api/");
+        return {
+            name: "api_url",
+            ok: hasApi,
+            detail: hasApi
+                ? `${parsed.origin}${parsed.pathname}`
+                : `${apiUrl} is missing /api/v4 (use the API URL, not the web root)`,
+        };
+    }
+    catch {
+        return {
+            name: "api_url",
+            ok: false,
+            detail: `${apiUrl} is not a valid URL`,
+        };
+    }
+}
+function permissionModeCheck(mode) {
+    const ok = mode === "readonly" || mode === "modify" || mode === "full";
+    return {
+        name: "permission_mode",
+        ok,
+        detail: ok ? mode : `${mode} is not readonly, modify, or full`,
+    };
+}
+function toolsetCheck(raw) {
+    const value = raw === undefined || raw.trim() === "" ? "core (default)" : raw.trim();
+    return {
+        name: "toolsets",
+        ok: true,
+        detail: value,
+    };
+}
+function versionCheck(version) {
+    return {
+        name: "version",
+        ok: version !== "unknown",
+        detail: version,
+    };
+}

package/build/cli/help.js

@@ -8,6 +8,8 @@ export function globalHelpText() {
 
 Usage:
   ${BINARY} auth [options]
+  ${BINARY} setup --cursor|--claude [options]
+  ${BINARY} doctor [--probe]
   ${BINARY} tool <tool-name> [options]
   ${BINARY} <group> <action> [options]
   ${BINARY} --help

package/build/cli/router.js

@@ -5,6 +5,8 @@ import { applyFlagAliases, argvHasHelp, CliUsageError, parseArgv, parseToolArgs,
 import { liveCliExposure } from "./exposure.js";
 import { canonicalGroup, findCuratedCommand, isKnownCliCommand, resolveScopedTool, } from "./curated.js";
 import { curatedHelpText, globalHelpText, groupHelpText, toolHelpText, toolIndexHelpText, } from "./help.js";
+import { doctorHelpText } from "./doctor.js";
+import { readSetupOptions, setupHelpText } from "./setup.js";
 export function isCliInvocation(argv) {
     if (argvHasHelp(argv)) {
         return true;
@@ -38,6 +40,24 @@ function resolveCliUnsafe(argv, permissionMode, exposure) {
     if (head === "auth") {
         return { kind: "auth" };
     }
+    if (head === "setup") {
+        if (action !== undefined) {
+            return { kind: "usage", message: `Unexpected extra arguments: ${parsed.positionals.slice(1).join(" ")}` };
+        }
+        if (parsed.help) {
+            return { kind: "help", text: setupHelpText() };
+        }
+        return { kind: "setup", options: readSetupOptions(parsed.toolFlags) };
+    }
+    if (head === "doctor") {
+        if (action !== undefined) {
+            return { kind: "usage", message: `Unexpected extra arguments: ${parsed.positionals.slice(1).join(" ")}` };
+        }
+        if (parsed.help) {
+            return { kind: "help", text: doctorHelpText() };
+        }
+        return { kind: "doctor", probe: parsed.toolFlags.probe === "true" };
+    }
     if (head === "tool") {
         if (extra !== undefined) {
             return { kind: "usage", message: `Unexpected extra arguments: ${parsed.positionals.slice(2).join(" ")}` };

package/build/cli/setup.js

@@ -0,0 +1,137 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { CliUsageError } from "./args.js";
+const DEFAULT_API_URL = "https://gitlab.com/api/v4";
+const SKILL_INSTALL = "npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill";
+export function setupHelpText() {
+    return `zereight-mcp-gitlab setup
+
+Print (or write) a local MCP client config. Tokens stay in the environment.
+
+Usage:
+  zereight-mcp-gitlab setup --cursor [--oauth] [--write] [--dir PATH]
+  zereight-mcp-gitlab setup --claude [--oauth] [--write]
+  zereight-mcp-gitlab setup --help
+
+Flags:
+  --cursor    Cursor mcp.json snippet (default path .cursor/mcp.json)
+  --claude    Claude Code one-liner (claude mcp add)
+  --oauth     Use GITLAB_USE_OAUTH instead of a PAT
+  --write     Write the Cursor file or print the Claude command as the install step
+  --skill     Also print the Agent Skill install command
+  --dir PATH  Directory that contains .cursor/mcp.json (default: cwd)
+  --api-url   GitLab API URL (default ${DEFAULT_API_URL})
+
+Dry-run is the default. --write is required to create or merge .cursor/mcp.json.
+`;
+}
+export function readSetupOptions(flags, directory = process.cwd()) {
+    const cursor = flags.cursor === "true";
+    const claude = flags.claude === "true";
+    if (cursor === claude) {
+        throw new CliUsageError("setup requires exactly one of --cursor or --claude");
+    }
+    return {
+        client: cursor ? "cursor" : "claude",
+        oauth: flags.oauth === "true" || flags.use_oauth === "true",
+        write: flags.write === "true",
+        skill: flags.skill === "true",
+        directory: flags.dir ?? directory,
+        apiUrl: flags.api_url ?? DEFAULT_API_URL,
+    };
+}
+export function cursorMcpConfig(options) {
+    const env = {
+        GITLAB_API_URL: options.apiUrl,
+    };
+    if (options.oauth) {
+        env.GITLAB_USE_OAUTH = "true";
+    }
+    else {
+        env.GITLAB_PERSONAL_ACCESS_TOKEN = "${env:GITLAB_PERSONAL_ACCESS_TOKEN}";
+    }
+    return {
+        mcpServers: {
+            gitlab: {
+                command: "zereight-mcp-gitlab",
+                env,
+            },
+        },
+    };
+}
+export function claudeMcpAddCommand(options) {
+    const envFlags = options.oauth
+        ? `--env GITLAB_USE_OAUTH=true --env GITLAB_API_URL=${options.apiUrl}`
+        : `--env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=${options.apiUrl}`;
+    return `claude mcp add gitlab --transport stdio --scope local ${envFlags} -- zereight-mcp-gitlab`;
+}
+export function runSetup(options) {
+    switch (options.client) {
+        case "cursor":
+            return runCursorSetup(options);
+        case "claude":
+            return runClaudeSetup(options);
+        default: {
+            const exhaustive = options.client;
+            throw new Error(`Unhandled setup client: ${String(exhaustive)}`);
+        }
+    }
+}
+function runCursorSetup(options) {
+    const snippet = cursorMcpConfig(options);
+    const target = join(options.directory, ".cursor", "mcp.json");
+    const body = `${JSON.stringify(snippet, null, 2)}\n`;
+    const skillLine = options.skill ? `\nSkill: ${SKILL_INSTALL}\n` : "";
+    if (!options.write) {
+        return {
+            text: `Dry-run Cursor config (pass --write to merge ${target}):\n${body}` + skillLine,
+        };
+    }
+    const merged = mergeMcpJson(readJsonFile(target), snippet);
+    mkdirSync(dirname(target), { recursive: true });
+    writeFileSync(target, `${JSON.stringify(merged, null, 2)}\n`);
+    return {
+        text: `Wrote ${target}\n${skillLine}`,
+        writtenPath: target,
+    };
+}
+function runClaudeSetup(options) {
+    const command = claudeMcpAddCommand(options);
+    const skillLine = options.skill ? `\nSkill: ${SKILL_INSTALL}\n` : "";
+    return {
+        text: `${command}\n${skillLine}`,
+    };
+}
+function readJsonFile(path) {
+    if (!existsSync(path)) {
+        return {};
+    }
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    if (typeof parsed !== "object" || parsed === null || Array.isArray(parsed)) {
+        throw new CliUsageError(`${path} is not a JSON object`);
+    }
+    const copy = {};
+    for (const [key, value] of Object.entries(parsed)) {
+        copy[key] = value;
+    }
+    return copy;
+}
+function mergeMcpJson(existing, snippet) {
+    const existingServers = typeof existing.mcpServers === "object" &&
+        existing.mcpServers !== null &&
+        !Array.isArray(existing.mcpServers)
+        ? existing.mcpServers
+        : {};
+    const snippetServers = typeof snippet.mcpServers === "object" &&
+        snippet.mcpServers !== null &&
+        !Array.isArray(snippet.mcpServers)
+        ? snippet.mcpServers
+        : {};
+    return {
+        ...existing,
+        mcpServers: {
+            ...existingServers,
+            ...snippetServers,
+        },
+    };
+}

package/build/index.js

@@ -77,6 +77,8 @@ import { createGitLabOAuthClient, ensureOAuthToken } from "./oauth.js";
 import { getPositionalCliCommand } from "./cli-command.js";
 import { runAuthCommandAsync } from "./auth-cli.js";
 import { isCliInvocation, resolveCli } from "./cli/router.js";
+import { runDoctorWithOptionalProbe, packageVersion, } from "./cli/doctor.js";
+import { runSetup } from "./cli/setup.js";
 import { formatCliError, formatToolOutput } from "./cli/output.js";
 import { compactMcpToolResult, readOwnRecord } from "./cli/compact-mcp-result.js";
 import { compileDeniedToolsRegex } from "./tools/denied-regex.js";
@@ -13005,6 +13007,43 @@ async function main() {
         process.stderr.write(`${cli.message}\n`);
         process.exit(2);
     }
+    if (cli.kind === "setup") {
+        try {
+            const result = runSetup({
+                ...cli.options,
+                apiUrl: getConfig("api-url", "GITLAB_API_URL", cli.options.apiUrl),
+            });
+            process.stdout.write(result.text);
+            process.exit(0);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(2);
+        }
+    }
+    if (cli.kind === "doctor") {
+        try {
+            const report = await runDoctorWithOptionalProbe({
+                credentials: {
+                    hasPersonalAccessToken: Boolean(GITLAB_PERSONAL_ACCESS_TOKEN),
+                    hasJobToken: Boolean(GITLAB_JOB_TOKEN),
+                    hasCookie: Boolean(GITLAB_AUTH_COOKIE_PATH),
+                    useOAuth: USE_OAUTH,
+                },
+                apiUrl: GITLAB_API_URL,
+                permissionMode: GITLAB_PERMISSION_MODE,
+                toolsetsRaw: GITLAB_TOOLSETS_RAW,
+                version: packageVersion(),
+                probe: cli.probe ? probeGitLabUser : undefined,
+            });
+            process.stdout.write(report.text);
+            process.exit(report.ok ? 0 : 1);
+        }
+        catch (error) {
+            process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+            process.exit(1);
+        }
+    }
     if (cli.kind === "auth" || getPositionalCliCommand(process.argv) === "auth") {
         try {
             await runAuthCommandAsync();
@@ -13053,6 +13092,32 @@ async function main() {
 function hasCliCredentials() {
     return Boolean(GITLAB_PERSONAL_ACCESS_TOKEN || GITLAB_JOB_TOKEN || GITLAB_AUTH_COOKIE_PATH || USE_OAUTH);
 }
+async function probeGitLabUser(apiUrl) {
+    const headers = { Accept: "application/json" };
+    if (GITLAB_PERSONAL_ACCESS_TOKEN) {
+        headers["PRIVATE-TOKEN"] = GITLAB_PERSONAL_ACCESS_TOKEN;
+    }
+    else if (GITLAB_JOB_TOKEN) {
+        headers["JOB-TOKEN"] = GITLAB_JOB_TOKEN;
+    }
+    try {
+        const response = await fetch(`${apiUrl.replace(/\/$/, "")}/user`, { headers });
+        if (response.ok) {
+            return { ok: true, status: response.status, detail: `GET /user ${response.status}` };
+        }
+        return {
+            ok: false,
+            status: response.status,
+            detail: `GET /user ${response.status} ${response.statusText}`,
+        };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            detail: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.3.8-next.144",
+  "version": "2.3.8-next.145",
   "mcpName": "io.github.zereight/gitlab-mcp",
   "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
   "keywords": [