@zereight/mcp-gitlab 2.1.68 → 2.1.70

package/README.pt-BR.md

@@ -17,7 +17,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 
 ### Por que usar este GitLab MCP?
 
-- **261 ferramentas + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
+- **267 ferramentas + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
 - **Revisão de MR em 2 etapas** — `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote
 - **Agent Skill integrado** — orientação de workflows em `skills/gitlab-mcp/`
 - **Autenticação flexível** — Personal Access Token, fluxo OAuth2 local no navegador, proxy MCP OAuth e autorização remota por requisição
@@ -31,7 +31,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 |                           | @zereight/mcp-gitlab                           | GitLab MCP A (comunidade, estilo CQRS)                    |
 | ------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
 | **Mais indicado para**    | Workflows de agentes de IA                     | Múltiplas instâncias corporativas / ferramentas agrupadas |
-| **Modelo de ferramentas** | ~261 ferramentas granulares + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      |
+| **Modelo de ferramentas** | ~267 ferramentas granulares + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      |
 | **Revisão de MR**         | Diff em lote em 2 etapas                       | Varia                                                     |
 | **Node.js**               | >=18.17                                        | Frequentemente >=24                                       |
 | **Licença**               | MIT                                            | Varia                                                     |
@@ -111,7 +111,7 @@ O caminho no store é fixado pelo seu lock file; atualize-o com `nix flake updat
 
 Os exemplos usam `zereight-mcp-gitlab`, um alias com menor chance de conflito que o binário legado `mcp-gitlab`. Se o seu cliente MCP não o encontrar, use o caminho absoluto retornado por `which zereight-mcp-gitlab`.
 
-Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.1.67`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
+Não quer instalar globalmente? Fixe o `npx` na versão estável anterior (a versão recomendada por esta documentação), por exemplo `npx -y @zereight/mcp-gitlab@2.1.69`. Se quiser sempre a versão mais recente, use `npx -y @zereight/mcp-gitlab@latest`. O servidor exibe um aviso no stderr durante a inicialização quando existe uma versão mais nova disponível (desative com `GITLAB_DISABLE_VERSION_CHECK=true`).
 
 #### Usando argumentos de CLI (para clientes com problemas com variáveis de ambiente)
 
@@ -143,11 +143,15 @@ Alguns clientes MCP, como o GitHub Copilot CLI, têm problemas com variáveis de
 - `--masking-config` - caminho para um arquivo de configuração de mascaramento (substitui `GITLAB_MASKING_CONFIG`)
 - `--masking-policy-file` - caminho para um arquivo protegido de política gerenciada (substitui `GITLAB_MASKING_POLICY_FILE`)
 - `--masking-workspace-dir` - diretório usado para resolver arquivos de mascaramento (substitui `GITLAB_MASKING_WORKSPACE_DIR`)
+- `--compact-results=true` - trunca respostas muito grandes de ferramentas MCP e anexa um comando CLI para a carga completa (substitui `GITLAB_MCP_COMPACT_RESULTS`; desativado por padrão)
+- `--compact-result-chars` - limite de caracteres para compactação (substitui `GITLAB_MCP_COMPACT_RESULT_CHARS`; padrão `4000`)
 
 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).
+
 > **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`,
 > `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`) —
@@ -519,7 +523,7 @@ Não é necessário definir `headers`. O Claude.ai obtém o token via OAuth.
 | `STREAMABLE_HTTP`                           | sim         | Deve ser `true` (SSE não é suportado)                                                                                                                                                                                                            |
 | `GITLAB_OAUTH_SCOPES`                       | não         | Scopes do GitLab a solicitar, separados por vírgula. O padrão é `api`, ou `read_api` quando `GITLAB_READ_ONLY_MODE=true`. O aplicativo previamente registrado deve ter pelo menos esses scopes configurados.                                     |
 | `OAUTH_REGISTER_RATE_LIMIT_PER_HOUR`        | não         | Limite rolling de Dynamic Client Registration (`POST /register`) por IP do cliente. Padrão `20`/hora, intervalo `1`–`1000`. Aumente se múltiplas janelas de IDE estiverem atingindo o limite. Não está relacionado aos limites da API do GitLab. |
-| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | não         | Apenas para desenvolvimento local via HTTP |
+| `MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL` | não         | Apenas para desenvolvimento local via HTTP                                                                                                                                                                                                       |
 
 **Observações importantes:**
 

package/README.zh-CN.md

@@ -17,7 +17,7 @@
 
 ### 为什么使用这个 GitLab MCP？
 
-- **266 个工具 + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **267 个工具 + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
 - **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
 - **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
 - **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
@@ -31,7 +31,7 @@
 | | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） |
 |---|----------------------|------------------------------|
 | **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 |
-| **工具模型** | ~266 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
+| **工具模型** | ~267 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
 | **MR 审查** | 两步批量 diff | 因服务器而异 |
 | **Node.js** | >=18.17 | 通常 >=24 |
 | **许可证** | MIT | 因服务器而异 |
@@ -111,7 +111,7 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.67`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.69`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -143,11 +143,15 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 - `--masking-config` - 掩码配置文件路径（替代 `GITLAB_MASKING_CONFIG`）
 - `--masking-policy-file` - 受保护的托管策略文件路径（替代 `GITLAB_MASKING_POLICY_FILE`）
 - `--masking-workspace-dir` - 用于解析掩码文件的目录（替代 `GITLAB_MASKING_WORKSPACE_DIR`）
+- `--compact-results=true` - 将过大的 MCP 工具回复截断为预览并附带 CLI 命令（替代 `GITLAB_MCP_COMPACT_RESULTS`，默认关闭）
+- `--compact-result-chars` - compact 字符阈值（替代 `GITLAB_MCP_COMPACT_RESULT_CHARS`，默认 `4000`）
 
 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)。
+
 > **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新，同时阻止所有删除工具以及
 > 破坏性的拆除（teardown）工具（`cancel_pipeline`、`cancel_pipeline_job`、`stop_environment`、
 > `stop_stale_environments`、`unprotect_branch`）（包括通过 `execute_graphql` 的破坏性 mutation

package/build/cli/args.js

@@ -0,0 +1,298 @@
+import { BOOLEAN_CLI_FLAG_NAMES, isBooleanFlagLiteral } from "../cli-boolean-flags.js";
+export class CliUsageError extends Error {
+    exitCode = 2;
+    constructor(message) {
+        super(message);
+        this.name = "CliUsageError";
+    }
+}
+const SCRIPT_PATH_PATTERN = /\.(cjs|mjs|js|cts|mts|ts)$/;
+const FLAGS_WITHOUT_VALUE = new Set(["help", "yes", ...BOOLEAN_CLI_FLAG_NAMES]);
+const GLOBAL_FLAG_NAMES = new Set([
+    "help",
+    "yes",
+    "output",
+    "args-json",
+    "client-id",
+    "token-path",
+    "token",
+    "job-token",
+    "cookie-path",
+    "use-oauth",
+    "is-old",
+    "read-only",
+    "masking-enabled",
+    "masking-config",
+    "masking-policy-file",
+    "masking-workspace-dir",
+    "permission-mode",
+    "use-wiki",
+    "use-milestone",
+    "use-pipeline",
+    "disable-version-check",
+    "toolsets",
+    "tools",
+    "tool-policy-approve",
+    "tool-policy-hidden",
+    "sse",
+    "streamable-http",
+    "remote-auth",
+    "mcp-oauth",
+    "allow-unauthenticated-tool-discovery",
+    "mcp-trust-proxy",
+    "mcp-server-url",
+    "oauth-app-id",
+    "oauth-scopes",
+    "oauth-callback-proxy",
+    "allowed-groups",
+    "oauth-allowed-groups",
+    "enable-dynamic-api-url",
+    "enable-dynamic-project-scope",
+    "enable-strict-project-scope",
+    "oauth-stateless-mode",
+    "oauth-stateless-client-ttl",
+    "oauth-stateless-pending-ttl",
+    "oauth-stateless-stored-ttl",
+    "session-timeout",
+    "oauth-stateless-session-ttl",
+    "host",
+    "port",
+    "http-proxy",
+    "https-proxy",
+    "no-proxy",
+    "tls-reject-unauthorized",
+    "ca-cert-path",
+    "pool-max-size",
+    "api-url",
+    "denied-tools-regex",
+    "compact-results",
+    "compact-result-chars",
+]);
+export function kebabToSnake(value) {
+    return value.replace(/-/g, "_");
+}
+export function snakeToKebab(value) {
+    return value.replace(/_/g, "-");
+}
+export function argvHasHelp(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
+export function parseArgv(argv) {
+    const userArgs = userArgv(argv);
+    const positionals = [];
+    const toolFlags = {};
+    let help = false;
+    let yes = false;
+    let output;
+    let argsJson;
+    for (let i = 0; i < userArgs.length; i += 1) {
+        const current = userArgs[i];
+        const flag = readFlag(current);
+        if (flag === undefined) {
+            if (current.startsWith("-")) {
+                throw new CliUsageError(`Unknown flag: ${current}`);
+            }
+            positionals.push(current);
+            continue;
+        }
+        if (flag.name === "help") {
+            help = true;
+            continue;
+        }
+        if (flag.name === "yes") {
+            if (flag.inline !== undefined) {
+                throw new CliUsageError("--yes does not accept a value");
+            }
+            yes = true;
+            continue;
+        }
+        if (BOOLEAN_CLI_FLAG_NAMES.has(flag.name) && flag.inline === undefined) {
+            if (isBooleanFlagLiteral(userArgs[i + 1])) {
+                i += 1;
+            }
+            continue;
+        }
+        const value = flag.inline ?? takeFlagValue(userArgs, i, flag.name);
+        if (flag.inline === undefined && !FLAGS_WITHOUT_VALUE.has(flag.name)) {
+            i += 1;
+        }
+        if (flag.name === "output") {
+            output = parseOutputMode(value);
+            continue;
+        }
+        if (flag.name === "args-json") {
+            argsJson = parseArgsJson(value);
+            continue;
+        }
+        if (GLOBAL_FLAG_NAMES.has(flag.name)) {
+            continue;
+        }
+        toolFlags[kebabToSnake(flag.name)] = value;
+    }
+    return { positionals, toolFlags, help, yes, output, argsJson };
+}
+export function applyFlagAliases(flags, aliases) {
+    if (aliases === undefined) {
+        return { ...flags };
+    }
+    const mapped = {};
+    for (const [key, value] of Object.entries(flags)) {
+        const target = aliases[key] ?? key;
+        mapped[target] = value;
+    }
+    return mapped;
+}
+export function parseToolArgs(input) {
+    const schema = readObjectSchema(input.schema);
+    const propertyNames = schema.properties === undefined ? new Set() : new Set(Object.keys(schema.properties));
+    const unknownFlags = Object.keys(input.flags).filter(name => !propertyNames.has(name));
+    if (unknownFlags.length > 0) {
+        throw new CliUsageError(`Unknown flag: --${snakeToKebab(unknownFlags[0] ?? "")}`);
+    }
+    const args = {};
+    assignOwn(args, input.argsJson);
+    for (const [key, value] of Object.entries(input.flags)) {
+        args[key] = coerceFlagValue(key, value, schema.properties?.[key]);
+    }
+    assignOwn(args, input.extraArgs);
+    const required = schema.required ?? [];
+    const missing = required.filter(name => args[name] === undefined);
+    if (missing.length === 1) {
+        throw new CliUsageError(`Missing required flag: --${snakeToKebab(missing[0] ?? "")}`);
+    }
+    if (missing.length > 1) {
+        throw new CliUsageError(`Missing required flags: ${missing.map(name => `--${snakeToKebab(name)}`).join(", ")}`);
+    }
+    return args;
+}
+function scalarFlagType(property) {
+    const rawTypes = Array.isArray(property?.type) ? property.type : [property?.type];
+    const types = rawTypes.filter(type => type !== "null");
+    if (types.length !== 1) {
+        return undefined;
+    }
+    const [type] = types;
+    if (type === "number" || type === "integer" || type === "boolean") {
+        return type;
+    }
+    return undefined;
+}
+function coerceFlagValue(name, value, property) {
+    const type = scalarFlagType(property);
+    if (type === undefined) {
+        return value;
+    }
+    const flag = `--${snakeToKebab(name)}`;
+    if (type === "boolean") {
+        const normalized = value.toLowerCase();
+        if (normalized === "true" || normalized === "1") {
+            return true;
+        }
+        if (normalized === "false" || normalized === "0") {
+            return false;
+        }
+        throw new CliUsageError(`${flag} must be true or false`);
+    }
+    const parsed = value.trim() === "" ? Number.NaN : Number(value);
+    if (!Number.isFinite(parsed)) {
+        throw new CliUsageError(`${flag} must be a number`);
+    }
+    if (type === "integer" && !Number.isInteger(parsed)) {
+        throw new CliUsageError(`${flag} must be an integer`);
+    }
+    return parsed;
+}
+export function readObjectSchema(schema) {
+    if (!isObject(schema)) {
+        return {};
+    }
+    const propertiesValue = schema.properties;
+    const requiredValue = schema.required;
+    const properties = isObject(propertiesValue)
+        ? Object.fromEntries(Object.entries(propertiesValue).flatMap(([key, value]) => isObject(value) ? [[key, value]] : []))
+        : undefined;
+    const required = Array.isArray(requiredValue)
+        ? requiredValue.filter((item) => typeof item === "string")
+        : undefined;
+    return {
+        type: schema.type,
+        properties,
+        required,
+        description: schema.description,
+    };
+}
+export function isCliOutputMode(value) {
+    return value === "json" || value === "table";
+}
+function userArgv(argv) {
+    const args = argv.slice(2);
+    const start = args.findIndex(arg => !arg.startsWith("-") && SCRIPT_PATH_PATTERN.test(arg));
+    if (start >= 0) {
+        return args.slice(start + 1);
+    }
+    return args;
+}
+function readFlag(arg) {
+    if (arg === "-h") {
+        return { name: "help", inline: undefined };
+    }
+    if (!arg.startsWith("--") || arg === "--") {
+        return undefined;
+    }
+    const body = arg.slice(2);
+    const separator = body.indexOf("=");
+    if (separator === -1) {
+        return { name: body, inline: undefined };
+    }
+    return {
+        name: body.slice(0, separator),
+        inline: body.slice(separator + 1),
+    };
+}
+function takeFlagValue(args, index, flagName) {
+    if (FLAGS_WITHOUT_VALUE.has(flagName)) {
+        return "true";
+    }
+    const next = args[index + 1];
+    if (next === undefined || next.startsWith("-")) {
+        throw new CliUsageError(`Missing value for --${flagName}`);
+    }
+    return next;
+}
+function parseOutputMode(value) {
+    if (isCliOutputMode(value)) {
+        return value;
+    }
+    throw new CliUsageError("--output must be table or json");
+}
+function parseArgsJson(raw) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (!isObject(parsed)) {
+            throw new CliUsageError("--args-json must be a JSON object");
+        }
+        const copy = {};
+        assignOwn(copy, parsed);
+        return copy;
+    }
+    catch (error) {
+        if (error instanceof CliUsageError) {
+            throw error;
+        }
+        throw new CliUsageError("Invalid --args-json");
+    }
+}
+function assignOwn(target, source) {
+    if (source === undefined) {
+        return;
+    }
+    for (const key of Object.keys(source)) {
+        if (key === "__proto__" || key === "constructor" || key === "prototype") {
+            continue;
+        }
+        target[key] = Reflect.get(source, key);
+    }
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}

package/build/cli/compact-mcp-result.js

@@ -0,0 +1,87 @@
+import { buildToolReplayCommand } from "./replay-command.js";
+const PREVIEW_ARRAY_ITEMS = 5;
+const PREVIEW_TEXT_CHARS = 1500;
+const PREVIEW_JSON_CHARS = 2000;
+export function readOwnRecord(value) {
+    if (!isRecord(value)) {
+        return undefined;
+    }
+    const copy = {};
+    for (const key of Object.keys(value)) {
+        copy[key] = Reflect.get(value, key);
+    }
+    return copy;
+}
+export function compactMcpToolResult(input) {
+    if (!input.enabled || input.toolName === "discover_tools") {
+        return toolResultRecord(input.result);
+    }
+    if (!isToolResult(input.result) || input.result.isError === true) {
+        return toolResultRecord(input.result);
+    }
+    const text = unwrapToolText(input.result);
+    if (text.length <= input.maxChars) {
+        return toolResultRecord(input.result);
+    }
+    const compact = {
+        compact: true,
+        tool: input.toolName,
+        original_chars: text.length,
+        ...buildPreview(text),
+        cli: buildToolReplayCommand(input.toolName, input.args),
+    };
+    return {
+        content: [{ type: "text", text: JSON.stringify(compact) }],
+        isError: false,
+    };
+}
+function toolResultRecord(value) {
+    if (isRecord(value)) {
+        return value;
+    }
+    return { content: [{ type: "text", text: stringifyUnknown(value) }] };
+}
+function buildPreview(text) {
+    const parsed = parseJsonValue(text);
+    if (parsed === undefined) {
+        return { preview: text.slice(0, PREVIEW_TEXT_CHARS) };
+    }
+    if (Array.isArray(parsed)) {
+        return { preview: parsed.slice(0, PREVIEW_ARRAY_ITEMS), items_total: parsed.length };
+    }
+    if (typeof parsed === "string") {
+        return { preview: parsed.slice(0, PREVIEW_TEXT_CHARS) };
+    }
+    const encoded = JSON.stringify(parsed);
+    if (encoded.length <= PREVIEW_JSON_CHARS) {
+        return { preview: parsed };
+    }
+    return { preview: encoded.slice(0, PREVIEW_JSON_CHARS) };
+}
+function unwrapToolText(result) {
+    const textBlock = result.content.find(item => isRecord(item) && typeof item.text === "string");
+    if (!isRecord(textBlock) || typeof textBlock.text !== "string") {
+        return stringifyUnknown(result);
+    }
+    return textBlock.text;
+}
+function isToolResult(value) {
+    return isRecord(value) && Array.isArray(value.content);
+}
+function parseJsonValue(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function stringifyUnknown(value) {
+    if (typeof value === "string") {
+        return value;
+    }
+    return JSON.stringify(value);
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}