@zereight/mcp-gitlab 2.1.69 → 2.2.0

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.68`. 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.70`. 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)
 
@@ -150,7 +150,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`). 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). 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

@@ -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.68`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.70`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -135,6 +135,8 @@ command = lib.getExe inputs.gitlab-mcp.packages.${system}.default;
 - `--api-url` - GitLab API URL（替代 `GITLAB_API_URL`）
 - `--read-only=true` - 启用只读模式（替代 `GITLAB_READ_ONLY_MODE`，已弃用 — 推荐 `--permission-mode=readonly`）
 - `--permission-mode` - 权限级别：`readonly`、`modify`（禁用删除/拆除工具）或 `full`（替代 `GITLAB_PERMISSION_MODE`，默认 `full`）
+- `--toolsets=all` - 启用指定工具集（替代 `GITLAB_TOOLSETS`；未设置时使用精简 `core` 默认值）
+- `--tools=list_issues` - 添加单个工具（替代 `GITLAB_TOOLS`）
 - `--use-wiki=true` - 启用 Wiki API（替代 `USE_GITLAB_WIKI`，旧版 — 推荐 `GITLAB_TOOLSETS=wiki`）
 - `--use-milestone=true` - 启用里程碑 API（替代 `USE_MILESTONE`，旧版 — 推荐 `GITLAB_TOOLSETS=milestones`）
 - `--use-pipeline=true` - 启用流水线 API（替代 `USE_PIPELINE`，旧版 — 推荐 `GITLAB_TOOLSETS=pipelines`）
@@ -150,7 +152,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 命令）。完整结果在终端用 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)。完整结果在终端用 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/config.js

@@ -1,4 +1,6 @@
 import { BOOLEAN_CLI_FLAG_NAMES, nextBooleanFlagValue } from "./cli-boolean-flags.js";
+import { parseToolProfile } from "./tools/tool-profile.js";
+import { parseCompactToolAllowlist } from "./utils/compact-tool-allowlist.js";
 // Parse CLI arguments before anything else
 const args = process.argv.slice(2);
 export const cliArgs = {};
@@ -51,8 +53,9 @@ export const GITLAB_MASKING_CONFIG = getConfig("masking-config", "GITLAB_MASKING
 export const GITLAB_MASKING_POLICY_FILE = getConfig("masking-policy-file", "GITLAB_MASKING_POLICY_FILE");
 export const GITLAB_MASKING_WORKSPACE_DIR = getConfig("masking-workspace-dir", "GITLAB_MASKING_WORKSPACE_DIR");
 const PERMISSION_MODES = ["readonly", "modify", "full"];
+export const GITLAB_PERMISSION_MODE_RAW = getConfig("permission-mode", "GITLAB_PERMISSION_MODE");
 export const GITLAB_PERMISSION_MODE = (() => {
-    const raw = getConfig("permission-mode", "GITLAB_PERMISSION_MODE");
+    const raw = GITLAB_PERMISSION_MODE_RAW;
     if (raw !== undefined && !PERMISSION_MODES.includes(raw)) {
         throw new Error(`Invalid GITLAB_PERMISSION_MODE: "${raw}". Expected one of: ${PERMISSION_MODES.join(", ")}`);
     }
@@ -62,15 +65,19 @@ export const GITLAB_PERMISSION_MODE = (() => {
     }
     return raw ?? "full";
 })();
-export const USE_GITLAB_WIKI = getConfig("use-wiki", "USE_GITLAB_WIKI") === "true";
-export const USE_MILESTONE = getConfig("use-milestone", "USE_MILESTONE") === "true";
-export const USE_PIPELINE = getConfig("use-pipeline", "USE_PIPELINE") === "true";
+export const USE_GITLAB_WIKI_RAW = getConfig("use-wiki", "USE_GITLAB_WIKI");
+export const USE_GITLAB_WIKI = USE_GITLAB_WIKI_RAW === "true";
+export const USE_MILESTONE_RAW = getConfig("use-milestone", "USE_MILESTONE");
+export const USE_MILESTONE = USE_MILESTONE_RAW === "true";
+export const USE_PIPELINE_RAW = getConfig("use-pipeline", "USE_PIPELINE");
+export const USE_PIPELINE = USE_PIPELINE_RAW === "true";
 export const GITLAB_DISABLE_VERSION_CHECK = getConfig("disable-version-check", "GITLAB_DISABLE_VERSION_CHECK") === "true";
 // ---------------------------------------------------------------------------
 // Tool filtering
 // ---------------------------------------------------------------------------
 export const GITLAB_TOOLSETS_RAW = getConfig("toolsets", "GITLAB_TOOLSETS");
 export const GITLAB_TOOLS_RAW = getConfig("tools", "GITLAB_TOOLS");
+export const GITLAB_TOOL_PROFILE = parseToolProfile(getConfig("tool-profile", "GITLAB_TOOL_PROFILE"));
 // Tool policy: comma-separated tool names
 // approve = exposed but requires confirmation; hidden = not exposed at all
 export const GITLAB_TOOL_POLICY_APPROVE_RAW = getConfig("tool-policy-approve", "GITLAB_TOOL_POLICY_APPROVE");
@@ -185,6 +192,7 @@ const _PORT_DEFAULT = 3002;
 export const PORT = _intEnv("PORT", "port", _PORT_DEFAULT);
 /** When true, oversized MCP tool replies are replaced with a preview plus a CLI replay command. */
 export const GITLAB_MCP_COMPACT_RESULTS = getConfig("compact-results", "GITLAB_MCP_COMPACT_RESULTS") === "true";
+export const GITLAB_MCP_COMPACT_TOOL_NAMES = parseCompactToolAllowlist(getConfig("compact-tools", "GITLAB_MCP_COMPACT_TOOLS"));
 export const GITLAB_MCP_COMPACT_RESULT_CHARS = _intEnv("GITLAB_MCP_COMPACT_RESULT_CHARS", "compact-result-chars", 4000);
 // ---------------------------------------------------------------------------
 // Proxy configuration

package/build/deprecated-env.js

@@ -0,0 +1,47 @@
+function shownEnvValue(rawValue) {
+    const singleLine = rawValue.replace(/[\r\n]/g, " ");
+    if (singleLine.length <= 80) {
+        return singleLine;
+    }
+    return `${singleLine.slice(0, 77)}...`;
+}
+function legacyToolsetWarning(envName, rawValue, toolset) {
+    if (rawValue === "true") {
+        return (`${envName} is deprecated and will be removed in the next major version. ` +
+            `Use GITLAB_TOOLSETS=${toolset} instead.`);
+    }
+    const shown = shownEnvValue(rawValue);
+    return (`${envName} is set to "${shown}" and is deprecated. ` +
+        `This value does not enable the ${toolset} toolset. Remove it. ` +
+        `Set GITLAB_TOOLSETS=${toolset} only if you want those tools enabled.`);
+}
+/**
+ * Builds startup warnings for deprecated env vars / CLI flags.
+ * Pure function so the messages and conflict detection are unit-testable.
+ */
+export function getDeprecatedEnvWarnings(input) {
+    const warnings = [];
+    if (input.readOnlyMode) {
+        const conflict = input.permissionModeRaw !== undefined && input.permissionModeRaw !== "readonly"
+            ? ` It OVERRIDES the configured permission mode "${input.permissionModeRaw}"; the server runs as "readonly".`
+            : "";
+        warnings.push("GITLAB_READ_ONLY_MODE is deprecated and will be removed in the next major version. " +
+            `Use GITLAB_PERMISSION_MODE=readonly or --permission-mode=readonly instead.${conflict}`);
+    }
+    if (input.allowedGroupsRaw) {
+        warnings.push(input.oauthAllowedGroupsRaw
+            ? "GITLAB_ALLOWED_GROUPS is deprecated and ignored because GITLAB_OAUTH_ALLOWED_GROUPS is set. Remove it."
+            : "GITLAB_ALLOWED_GROUPS is deprecated and will be removed in the next major version. Use GITLAB_OAUTH_ALLOWED_GROUPS instead.");
+    }
+    const legacyToolsetFlags = [
+        [input.useWikiRaw, "USE_GITLAB_WIKI", "wiki"],
+        [input.useMilestoneRaw, "USE_MILESTONE", "milestones"],
+        [input.usePipelineRaw, "USE_PIPELINE", "pipelines"],
+    ];
+    for (const [rawValue, envName, toolset] of legacyToolsetFlags) {
+        if (rawValue !== undefined) {
+            warnings.push(legacyToolsetWarning(envName, rawValue, toolset));
+        }
+    }
+    return warnings;
+}