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

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";
@@ -112,6 +114,8 @@ import { parseGitLabVersionApiResponse, } from "./utils/gitlab-instance-version.
 import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./utils/bulk-publish-options.js";
 import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsernameOptions, dropBlankArrayEntries, isBlankFilterValue, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
 import { applyJmespathToToolResult, getJmespathSyntaxError, JMESPATH_TOOL_ARGUMENT, JMESPATH_TOOL_ARGUMENT_DESCRIPTION, omitJmespathArgument, readJmespathExpression, } from "./utils/jmespath-tool-result.js";
+import { appendRecoveryHint } from "./utils/error-hints.js";
+import { applyListSummaryToToolResult, omitListSummaryArgument, readListSummaryRequested, toolAcceptsDecoratedSummary, } from "./utils/list-summary.js";
 import { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
 import { zodSchemaFor } from "./utils/schema.js";
 import { GitLabClientPool } from "./gitlab-client-pool.js";
@@ -227,14 +231,18 @@ function createServer() {
         const toolName = request.params.name;
         const start = Date.now();
         let maskingEngine;
-        const jmespathExpression = readJmespathExpression(request.params.arguments);
+        const requestArguments = readOwnRecord(request.params.arguments);
+        const jmespathExpression = readJmespathExpression(requestArguments === undefined ? undefined : { ...requestArguments });
+        const listSummaryRequested = toolAcceptsDecoratedSummary(toolName) &&
+            readListSummaryRequested(requestArguments === undefined ? undefined : { ...requestArguments });
         const logCompletion = (result, completionOptions) => {
             const durationMs = Date.now() - start;
             logger.info({ tool: toolName, event: "tool_call_done", durationMs }, `tool_call_done: ${toolName} (${durationMs}ms)`);
             const isPlainTextResult = toolName === "get_pipeline_job_output" ||
                 toolName === "get_job_artifact_file" ||
                 (toolName === "download_release_asset" && !IS_REMOTE);
-            const filtered = applyJmespathToToolResult(redactErrorResultUrls(result), jmespathExpression, {
+            const summarized = applyListSummaryToToolResult(redactErrorResultUrls(result), listSummaryRequested);
+            const filtered = applyJmespathToToolResult(summarized, jmespathExpression, {
                 ...completionOptions,
                 maskValue: maskingEngine
                     ? (value) => maskingEngine.maskValue(value)
@@ -475,8 +483,13 @@ function createServer() {
                 const { _confirmed, ...cleanArgs } = request.params.arguments || {};
                 request.params.arguments = cleanArgs;
             }
-            if (request.params.arguments && typeof request.params.arguments === "object") {
-                request.params.arguments = omitJmespathArgument(request.params.arguments);
+            const ownedArguments = readOwnRecord(request.params.arguments);
+            if (ownedArguments) {
+                let cleanedArguments = omitJmespathArgument({ ...ownedArguments });
+                if (toolAcceptsDecoratedSummary(toolName)) {
+                    cleanedArguments = omitListSummaryArgument(cleanedArguments);
+                }
+                request.params.arguments = cleanedArguments;
             }
             if (sessionContext) {
                 // Policy selection and the tool handler must use the same request-local
@@ -498,7 +511,7 @@ function createServer() {
                     content: [
                         {
                             type: "text",
-                            text: safeError instanceof Error ? safeError.message : String(safeError),
+                            text: appendRecoveryHint(safeError instanceof Error ? safeError.message : String(safeError)),
                         },
                     ],
                     isError: true,
@@ -1416,12 +1429,12 @@ async function handleGitLabError(response) {
             // before the common tool-call boundary returns/logs it.
             logger.error("GitLab API Rate Limit Exceeded");
             logger.error("User API Key Rate limit exceeded. Please try again later.");
-            const error = new GitLabApiError(`GitLab API Rate Limit Exceeded: ${errorBody}`);
+            const error = new GitLabApiError(appendRecoveryHint(`GitLab API Rate Limit Exceeded: ${errorBody}`));
             throw error;
         }
         else {
             // Handle other API errors
-            const error = new GitLabApiError(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
+            const error = new GitLabApiError(appendRecoveryHint(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`));
             throw error;
         }
     }
@@ -7644,7 +7657,7 @@ function getSafeAttachmentFilename(filename) {
     }
     return filename;
 }
-async function downloadAttachment(projectId, secret, filename, localPath) {
+async function downloadAttachment(projectId, secret, filename, localPath, metadataOnly = false) {
     const effectiveProjectId = getEffectiveProjectId(projectId);
     const safeFilename = getSafeAttachmentFilename(filename);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/uploads/${encodeGitLabPathSegment(secret)}/${encodeGitLabPathSegment(safeFilename)}`);
@@ -7653,6 +7666,18 @@ async function downloadAttachment(projectId, secret, filename, localPath) {
         await handleGitLabError(response);
     }
     const mimeType = getImageMimeType(safeFilename);
+    if (metadataOnly) {
+        const headerLength = Number(response.headers.get("content-length"));
+        if (response.body) {
+            await response.body.cancel();
+        }
+        return {
+            buffer: Buffer.alloc(0),
+            filename: safeFilename,
+            mimeType,
+            byteLength: Number.isFinite(headerLength) ? headerLength : undefined,
+        };
+    }
     // Non-image files, and images with local_path, are saved as new files under the
     // download directory. Upload names and local_path come from untrusted content, so
     // dot names (.git, .vscode, .envrc) are refused and existing files are never replaced.
@@ -10716,10 +10741,27 @@ async function handleToolCall(params) {
                     };
                 }
                 // Readonly mode never writes to disk: images still come back inline.
-                if (GITLAB_PERMISSION_MODE === "readonly" && (!mimeType || args.local_path)) {
+                if (GITLAB_PERMISSION_MODE === "readonly" &&
+                    !args.metadata_only &&
+                    (!mimeType || args.local_path)) {
                     throw new Error("download_attachment saves this file to disk, which readonly mode does not allow. Only images without local_path can be downloaded in readonly mode.");
                 }
-                const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path);
+                const result = await downloadAttachment(args.project_id, args.secret, args.filename, args.local_path, args.metadata_only === true);
+                if (args.metadata_only) {
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({
+                                    filename: result.filename,
+                                    mimeType: result.mimeType,
+                                    byte_length: result.byteLength ?? result.buffer.byteLength,
+                                    metadata_only: true,
+                                }),
+                            },
+                        ],
+                    };
+                }
                 if (result.mimeType && !args.local_path) {
                     // Return image inline as base64 so the AI can see it
                     const base64 = result.buffer.toString("base64");
@@ -13005,6 +13047,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 +13132,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/build/schemas.js

@@ -3522,6 +3522,10 @@ export const DownloadAttachmentSchema = z.object({
         .string()
         .optional()
         .describe("Subdirectory of the download directory to save the file in (optional, defaults to the download directory itself). Names starting with a dot are rejected"),
+    metadata_only: z
+        .boolean()
+        .optional()
+        .describe("If true, return filename, mime type, and byte length without inline image bytes or a saved file. Default false keeps the existing download behavior."),
 });
 export const DownloadAttachmentRemoteSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path of the project"),

package/build/tools/discover-activation.js

@@ -1,3 +1,4 @@
+import { appendRecoveryHint } from "../utils/error-hints.js";
 /**
  * Same skips `discover_tools` uses when it adds tools: permission mode, regex
  * denial, hidden policy, and the slim profile. Those tools never join the list.
@@ -22,15 +23,15 @@ export function buildUnavailableToolMessage(input) {
     const base = `Tool "${input.toolName}" is not available on this server`;
     const toolset = input.toolset;
     if (toolset === undefined || input.deniedByRegex) {
-        return base;
+        return appendRecoveryHint(base);
     }
     if (input.excludedBySlimProfile) {
-        return `${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`;
+        return appendRecoveryHint(`${base}. ${slimExclusionGuidance(input.toolName, toolset, input.enabledByCurrentToolsets)}`);
     }
     if (input.explicitToolsetOnly) {
-        return `${base}. The "${toolset}" toolset is not enabled. discover_tools cannot activate it. Add "${toolset}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all, GITLAB_TOOLS, and GITLAB_TOOL_PROFILE do not enable it.`;
+        return appendRecoveryHint(`${base}. The "${toolset}" toolset is not enabled. discover_tools cannot activate it. Add "${toolset}" to GITLAB_TOOLSETS. GITLAB_TOOLSETS=all, GITLAB_TOOLS, and GITLAB_TOOL_PROFILE do not enable it.`);
     }
-    return `${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`;
+    return appendRecoveryHint(`${base}. It belongs to the "${toolset}" toolset, which is not enabled: call discover_tools with category "${toolset}" or add "${toolset}" to GITLAB_TOOLSETS.`);
 }
 function slimExclusionGuidance(toolName, toolset, enabledByCurrentToolsets) {
     const viaToolsets = `add "${toolset}" to GITLAB_TOOLSETS (setting GITLAB_TOOLSETS disables the slim profile)`;

package/build/tools/listed-tools.js

@@ -1,3 +1,4 @@
+import { LIST_SUMMARY_ARGUMENT, LIST_SUMMARY_ARGUMENT_DESCRIPTION, toolAcceptsDecoratedSummary, } from "../utils/list-summary.js";
 const CONFIRMED_ARGUMENT = "_confirmed";
 const CONFIRMED_ARGUMENT_DESCRIPTION = "Set to true to confirm execution of this approval-required tool.";
 function isRecord(value) {
@@ -36,11 +37,29 @@ function withJmespathArgument(schema, context) {
     };
     return { ...schema, properties };
 }
+function withSummaryArgument(schema, toolName) {
+    if (!toolAcceptsDecoratedSummary(toolName) || !isRecord(schema.properties)) {
+        return schema;
+    }
+    if (LIST_SUMMARY_ARGUMENT in schema.properties) {
+        return schema;
+    }
+    return {
+        ...schema,
+        properties: {
+            ...schema.properties,
+            [LIST_SUMMARY_ARGUMENT]: {
+                type: "boolean",
+                description: LIST_SUMMARY_ARGUMENT_DESCRIPTION,
+            },
+        },
+    };
+}
 function decorateInputSchema(schema, toolName, context) {
     if (!isRecord(schema)) {
         return undefined;
     }
-    return withJmespathArgument(withConfirmedArgument(cloneSchema(schema), toolName, context), context);
+    return withSummaryArgument(withJmespathArgument(withConfirmedArgument(cloneSchema(schema), toolName, context), context), toolName);
 }
 export function decorateToolForList(tool, context) {
     const inputSchema = decorateInputSchema(tool.inputSchema, tool.name, context);

package/build/utils/error-hints.js

@@ -0,0 +1,42 @@
+const NEXT_PREFIX = "\nNext: ";
+export function hasRecoveryHint(message) {
+    return message.includes(NEXT_PREFIX);
+}
+export function recoveryHintFor(message) {
+    if (/^Access denied:/i.test(message)) {
+        return undefined;
+    }
+    if (/is not available on this server/i.test(message)) {
+        if (/slim tool profile/i.test(message) || /cannot activate/i.test(message)) {
+            return undefined;
+        }
+        if (/discover_tools|GITLAB_TOOLSETS|GITLAB_TOOLS/.test(message)) {
+            return "call discover_tools with the category, or add it to GITLAB_TOOLSETS.";
+        }
+    }
+    if (/\b401\b/.test(message) || /unauthorized/i.test(message)) {
+        return "set GITLAB_PERSONAL_ACCESS_TOKEN (or run `zereight-mcp-gitlab auth`) and retry.";
+    }
+    if (/rate limit/i.test(message)) {
+        return "wait and retry; lower per_page or paginate if the client is bursting.";
+    }
+    if (/\b403\b/.test(message) ||
+        /forbidden/i.test(message) ||
+        /insufficient_scope/i.test(message)) {
+        return "check token scopes and GITLAB_PERMISSION_MODE; grant read_user or User:Read for whoami.";
+    }
+    if (/\b404\b/.test(message) || /404 not found/i.test(message)) {
+        return "check project_id (numeric ID or group%2Fproject) and the resource iid.";
+    }
+    return undefined;
+}
+export function appendRecoveryHint(message) {
+    if (hasRecoveryHint(message)) {
+        return message;
+    }
+    const hint = recoveryHintFor(message);
+    if (hint === undefined) {
+        return message;
+    }
+    return `${message}${NEXT_PREFIX}${hint}`;
+}

package/build/utils/list-summary.js

@@ -0,0 +1,90 @@
+/** MCP-only argument; stripped before GitLab handlers run. */
+export const LIST_SUMMARY_ARGUMENT = "summary";
+export const LIST_SUMMARY_ARGUMENT_DESCRIPTION = "If true, return only high-signal fields (id, iid, title, state, web_url, …). Default false keeps the full GitLab JSON.";
+const SUMMARY_FIELDS = [
+    "id",
+    "iid",
+    "title",
+    "name",
+    "state",
+    "status",
+    "ref",
+    "web_url",
+    "path_with_namespace",
+    "username",
+    "short_id",
+    "key",
+    "tag_name",
+    "slug",
+    "filename",
+    "new_path",
+];
+const NATIVE_SUMMARY_TOOLS = new Set(["list_webhook_events"]);
+export function toolAcceptsDecoratedSummary(toolName) {
+    if (NATIVE_SUMMARY_TOOLS.has(toolName)) {
+        return false;
+    }
+    return toolName.startsWith("list_") || toolName === "mr_discussions";
+}
+export function readListSummaryRequested(args) {
+    if (!args) {
+        return false;
+    }
+    const raw = args[LIST_SUMMARY_ARGUMENT];
+    return raw === true || raw === "true";
+}
+export function omitListSummaryArgument(args) {
+    if (!(LIST_SUMMARY_ARGUMENT in args)) {
+        return args;
+    }
+    const { [LIST_SUMMARY_ARGUMENT]: _omit, ...rest } = args;
+    return rest;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function summarizeItem(item) {
+    if (!isRecord(item)) {
+        return item;
+    }
+    const summarized = {};
+    for (const field of SUMMARY_FIELDS) {
+        if (field in item) {
+            summarized[field] = item[field];
+        }
+    }
+    return Object.keys(summarized).length > 0 ? summarized : item;
+}
+export function summarizeListPayload(data) {
+    if (Array.isArray(data)) {
+        return data.map(summarizeItem);
+    }
+    if (isRecord(data) && Array.isArray(data.items)) {
+        return { ...data, items: data.items.map(summarizeItem) };
+    }
+    return data;
+}
+function isTextContentBlock(value) {
+    return typeof value === "object" && value !== null;
+}
+export function applyListSummaryToToolResult(result, requested) {
+    if (!requested || result.isError) {
+        return result;
+    }
+    if (!Array.isArray(result.content)) {
+        return result;
+    }
+    const content = result.content.map(block => {
+        if (!isTextContentBlock(block) || block.type !== "text" || typeof block.text !== "string") {
+            return block;
+        }
+        try {
+            const parsed = JSON.parse(block.text);
+            return { ...block, text: JSON.stringify(summarizeListPayload(parsed)) };
+        }
+        catch {
+            return block;
+        }
+    });
+    return { ...result, content };
+}

package/package.json

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