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

package/README.zh-CN.md

@@ -1,30 +1,132 @@
 # GitLab MCP Server
 
 [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
-[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_GitLab_MCP-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=zereight.gitlab-mcp&inputs=%5B%7B%22type%22%3A%22promptString%22%2C%22id%22%3A%22gitlab-token%22%2C%22description%22%3A%22GitLab%20Personal%20Access%20Token%22%2C%22password%22%3Atrue%7D%5D&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40zereight%2Fmcp-gitlab%40latest%22%5D%2C%22env%22%3A%7B%22GITLAB_PERSONAL_ACCESS_TOKEN%22%3A%22%24%7Binput%3Agitlab-token%7D%22%2C%22GITLAB_API_URL%22%3A%22https%3A%2F%2Fgitlab.com%2Fapi%2Fv4%22%7D%7D)
-[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
 
 [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
 
-📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** 设置指南、环境变量和完整工具参考请查看托管文档站点。
+📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
 
-下面是 `@zereight/mcp-gitlab` 的推荐本地 PAT 安装。命令参数与 [Claude Code](./docs/clients/claude-code.md) 和 [Codex](./docs/clients/codex.md) 指南相同。
+**默认暴露 40 个工具**（38 个 `core` + `discover_tools` + `help`）。总共 278 个（toolset 中 275 个 + `execute_graphql` + `discover_tools` + `help`）。先用精简集，再在本会话中用 `discover_tools` 扩展。
 
 先安装 `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 历史里只保留变量名。
+### Without → With
+
+| 没有此 MCP | 有此 MCP |
+| ---------- | -------- |
+| 把 MR URL 和 diff 粘贴进聊天 | `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff` |
+| 在 GitLab UI 里翻 job 日志 | 带分页的 `get_pipeline_job_output` |
+| 每一轮都重新说明项目路径 | `project_id=group%2Fproject` 和 `merge_request_iid=123` |
+
+### 三条安装路径
+
+| 路径 | 适用 | 方式 |
+| ---- | ---- | ---- |
+| 本地 IDE | 本机上的 Cursor、Claude Code、Codex | stdio + PAT 或本地 OAuth |
+| 共享 HTTP | 团队 / 托管 MCP | Streamable HTTP URL + 远程授权或 MCP OAuth |
+| Claude.ai | Claude 网页连接器 | 公网 HTTPS + `GITLAB_MCP_OAUTH` |
+
+### 安装
+
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
+
+先安装二进制（`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`）。不回显地读取令牌：
 
 ```bash
 read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
 ```
 
-| 客户端      | 安装                                                                                                                                                                                             |
-| ----------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Claude Code | `claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab` |
-| Codex       | `codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab`                                  |
-| Cursor      | [Cursor 设置指南](./docs/clients/cursor.md)                                                                                                                                       |
-| VS Code     | [VS Code 设置指南](./docs/clients/vscode.md)                                                                                                                                      |
-| JSON 客户端 | [基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md)                                                                                                                 |
+```bash
+# Claude Code
+claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
+
+# Codex
+codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
+```
+
+其他客户端：[VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [JSON 客户端](./docs/clients/json-clients.md) · [Cursor 详情](./docs/clients/cursor.md)
+
+### 代理粘贴提示
+
+把下面内容粘贴给能改 MCP 配置的代理：
+
+```
+为此工作区安装 GitLab MCP 服务器（@zereight/mcp-gitlab）。
+二进制：zereight-mcp-gitlab（npm i -g @zereight/mcp-gitlab，或 npx -y @zereight/mcp-gitlab@latest）。
+认证：GITLAB_PERSONAL_ACCESS_TOKEN 和 GITLAB_API_URL=https://gitlab.com/api/v4（或 GITLAB_USE_OAUTH=true）。
+本地：claude mcp add gitlab --transport stdio --scope local --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
+或：codex mcp add gitlab --env GITLAB_PERSONAL_ACCESS_TOKEN="$GITLAB_PERSONAL_ACCESS_TOKEN" --env GITLAB_API_URL=https://gitlab.com/api/v4 -- zereight-mcp-gitlab
+Cursor：使用 README deeplink 或 docs/clients/cursor.md。
+远程 HTTP：将客户端指向 https://mcp.example.com/mcp（Streamable HTTP）。Claude.ai 需要该主机启用 GITLAB_MCP_OAUTH。
+默认列表：40 个工具（38 个 core + discover_tools + help）。用 discover_tools 扩展。除非接受绕过风险，否则不要启用 api toolset。
+同等非 MCP 路径：npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill 加上 zereight-mcp-gitlab CLI。
+```
+
+### 远程 HTTP
+
+托管或自建服务器的一等选项。把客户端指向 Streamable HTTP URL：
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+
+- 托管 / Claude.ai：服务器上设置 `GITLAB_MCP_OAUTH=true`（见 [MCP OAuth](#使用-mcp-oauth-代理gitlab_mcp_oauth)）
+- 每用户 PAT 头：`REMOTE_AUTHORIZATION=true`（见 [远程授权](#使用远程授权remote_authorization)）
+- 本地 Docker 示例见 [使用方法](#使用方法)
+
+### Skill + CLI（不需要 MCP）
+
+Skill + CLI 是同等路径，不是备选。同样的工作流，终端里拿完整载荷，无需注册 MCP。
+
+```bash
+npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
+zereight-mcp-gitlab user whoami
+zereight-mcp-gitlab mr list
+```
+
+见 [不使用 MCP 的 CLI](./docs/getting-started/cli-without-mcp.md) 和 [`skills/gitlab-mcp/`](./skills/gitlab-mcp/)。
+
+### MCP vs Human CLI
+
+| 使用 MCP 当 | 使用 CLI 当 |
+| ----------- | ----------- |
+| 代理需要聊天里的结构化工具 | 需要完整载荷（diff、日志、产物） |
+| `jmespath` 或 compact 结果已够用 | 已开 `GITLAB_MCP_COMPACT_RESULTS`，其余要在终端看 |
+| 已经注册了 MCP 服务器 | 已有 PAT 或跑过 `auth`，不想要 MCP |
+
+Human CLI 从不 compact。破坏性工具和 `GITLAB_TOOL_POLICY_APPROVE` 工具需要 `--yes`。
+
+### Tips
+
+`project_id` 是数字 ID 或 URL 编码路径。例如：组 `group`、项目 `project`、合并请求 `!123` → `project_id=group%2Fproject`，`merge_request_iid=123`。嵌套组的每一段之间用 `%2F`（`group%2Fsubgroup%2Fproject`）。
+
+### FAQ
+
+**如何认证？** 本地桌面最简单的是 `GITLAB_PERSONAL_ACCESS_TOKEN`（或 `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`）。本地 OAuth 用 `GITLAB_USE_OAUTH=true`。远程 Claude.ai 用 `GITLAB_MCP_OAUTH`。多用户 HTTP 用 `REMOTE_AUTHORIZATION` 和每请求令牌头。
+
+**为什么只看到大约 40 个工具？** 默认 `core` toolset 有 38 个工具，外加始终开启的 `discover_tools` 和 `help`。不带参数调用 `discover_tools` 可列出类别，再传入类别（`pipelines`、`wiki` 等）即可在本会话激活。`GITLAB_TOOLSETS=all` 仍然**不会**启用 `api`。
+
+**本地 OAuth、MCP OAuth 和远程授权有何区别？** 本地 OAuth 在服务器同一台机器上打开浏览器。MCP OAuth 用于公网 HTTPS 服务器和 Claude.ai 这类客户端。远程授权转发调用者的 PAT 或 job token，没有 OAuth 流程。
+
+**如何缩小巨大响应？** 在任意工具调用上传递 `jmespath`。或设置 `GITLAB_MCP_COMPACT_RESULTS=true`，把过大的 MCP 回复变成预览加 CLI 命令。需要完整载荷时用 CLI。
+
+**为什么 `api` toolset 危险？** `gitlab_api_request` 会绕过组/项目允许列表、其他工具过滤和单工具安全检查。提示注入可以驱动它。只有在 `GITLAB_TOOLSETS` 中列出 `api` 时才启用。`all`、`discover_tools` 和 `GITLAB_TOOLS` 都不会启用它。
+
+### Cursor rule / CLAUDE.md 片段
+
+```
+GitLab 合并请求、议题和流水线走此 MCP（@zereight/mcp-gitlab）。
+从默认 core 工具开始，用 discover_tools 扩展。
+优先 list_merge_request_changed_files，再批量 get_merge_request_file_diff。
+结果用 jmespath 或 compact；完整 diff 和 job 日志用 CLI。
+```
 
 [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
 
@@ -36,7 +138,7 @@ read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
 
 ### 为什么使用这个 GitLab MCP？
 
-- **277 个工具：toolset 中 275 个 + `execute_graphql` + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **默认 40 个工具（38 个 `core` + `discover_tools` + `help`）；共 278 个** — 先精简，再用 `discover_tools` 在本会话扩展
 - **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
 - **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
 - **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
@@ -50,7 +152,7 @@ read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
 |              | @zereight/mcp-gitlab                                                 | GitLab MCP A（社区 CQRS 型）               | GitLab 官方 MCP 服务器                                                                                                                  |
 | ------------ | -------------------------------------------------------------------- | ------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------- |
 | **更适合**   | AI 代理工作流                                                        | 企业多实例 / 分组工具                      | 内置于 GitLab，无需单独安装                                                                                                             |
-| **工具模型** | 277 个工具：toolset 中 275 个 + `execute_graphql` + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset                                                                                                                  |
+| **工具模型** | 278 个工具：toolset 中 275 个 + `execute_graphql` + `discover_tools` + `help` | ~50–60 个 `browse_*` / `manage_*` 分组工具 | 用 HTTP 头选择 toolset                                                                                                                  |
 | **MR 审查**  | 两步批量 diff                                                        | 因服务器而异                               | `get_merge_request` 带 diffs                                                                                                            |
 | **Node.js**  | >=18.17                                                              | 通常 >=24                                  | stdio 经 `mcp-remote`，需要 Node.js 20+                                                                                                 |
 | **许可证**   | MIT                                                                  | 因服务器而异                               | GitLab 的一部分                                                                                                                         |
@@ -602,7 +704,7 @@ node build/index.js
 
 ## Agent Skill Files
 
-对于支持 skill/instruction 加载的 AI 代理（Claude Code、GitHub Copilot、Cursor 等），[`skills/gitlab-mcp/`](./skills/gitlab-mcp/) 中提供了预构建 skill 文件。
+Skill + CLI 与 MCP 同等（见 [Skill + CLI](#skill--cli不需要-mcp)）。对于支持 skill/instruction 加载的 AI 代理（Claude Code、GitHub Copilot、Cursor 等），[`skills/gitlab-mcp/`](./skills/gitlab-mcp/) 中提供了预构建 skill 文件。
 
 - **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — 核心指南，包含工具集概览、关键工作流和参数提示
 - **[reference/](./skills/gitlab-mcp/reference/)** — 代码审查、合并请求、议题、流水线和漏洞分类的详细工作流文档

package/build/index.js

@@ -94,6 +94,8 @@ import { formatPrometheusMetrics } from "./server/metrics.js";
 import { SERVER_VERSION } from "./server/version.js";
 import { listMcpResources, listMcpResourceTemplates, readMcpResource, } from "./server/mcp-resources.js";
 import { getMcpPrompt, listMcpPrompts } from "./server/mcp-prompts.js";
+import { MCP_INSTRUCTIONS } from "./server/mcp-instructions.js";
+import { formatUnknownHelpTopic, getWorkflowGuide, readHelpTopic, } from "./server/mcp-help.js";
 import { isInitializationRequestBody, isUnauthenticatedDiscoveryRequestBody, readAcceptHeader, readMcpSessionIdHeader, redactSessionIdForLog, } from "./server/request-helpers.js";
 export { readMcpSessionIdHeader } from "./server/request-helpers.js";
 import { apiUrlUserinfoWarning, commaSplitHint, configuredApiUrlErrors, encodeGitLabPath, encodeGitLabPathSegment, invalidListEntryError, isCleartextRemoteUrl, normalizeGitLabApiUrl, parseConfiguredGitLabApiUrls, } from "./utils/url.js";
@@ -114,6 +116,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";
@@ -211,6 +215,7 @@ function createServer() {
             prompts: {},
             resources: {},
         },
+        instructions: MCP_INSTRUCTIONS,
     });
     mcpServer.server.setRequestHandler(ListPromptsRequestSchema, async () => listMcpPrompts());
     mcpServer.server.setRequestHandler(GetPromptRequestSchema, async (request) => getMcpPrompt(request.params.name, (request.params.arguments ?? {})));
@@ -229,14 +234,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)
@@ -331,6 +340,23 @@ function createServer() {
                 !filteredTools.some(t => t.name === toolName)) {
                 throw new Error(buildToolUnavailableMessage(toolName));
             }
+            if (toolName === "help") {
+                const topic = readHelpTopic(request.params.arguments?.topic);
+                if (topic === "invalid") {
+                    return logCompletion({
+                        content: [
+                            {
+                                type: "text",
+                                text: formatUnknownHelpTopic(request.params.arguments?.topic),
+                            },
+                        ],
+                        isError: true,
+                    });
+                }
+                return logCompletion({
+                    content: [{ type: "text", text: getWorkflowGuide(topic) }],
+                });
+            }
             // Handle discover_tools meta-tool directly (needs access to mcpServer and filteredTools)
             if (toolName === "discover_tools") {
                 const category = request.params.arguments?.category?.trim()?.toLowerCase();
@@ -477,8 +503,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
@@ -500,7 +531,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,
@@ -1418,12 +1449,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;
         }
     }
@@ -7646,7 +7677,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)}`);
@@ -7655,6 +7686,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.
@@ -10718,10 +10761,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");

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/server/mcp-help.js

@@ -0,0 +1,101 @@
+import { z } from "zod";
+export const HELP_TOPICS = [
+    "overview",
+    "code-review",
+    "merge-requests",
+    "issues",
+    "pipelines",
+    "search",
+    "token-saving",
+];
+export const HelpInputSchema = z.object({
+    topic: z
+        .enum(HELP_TOPICS)
+        .optional()
+        .describe("Guide to return. Omit for the overview and the list of topics. " +
+        "Values: overview, code-review, merge-requests, issues, pipelines, search, token-saving."),
+});
+export function isHelpTopic(value) {
+    for (const topic of HELP_TOPICS) {
+        if (topic === value) {
+            return true;
+        }
+    }
+    return false;
+}
+function assertNever(value) {
+    throw new Error(`Unhandled help topic: ${String(value)}`);
+}
+const GUIDES = {
+    overview: [
+        "GitLab MCP workflow guide. Default tools/list is 38 core tools plus discover_tools and help (40).",
+        "Call help with topic: code-review, merge-requests, issues, pipelines, search, token-saving.",
+        "Activate more categories with discover_tools. api is explicit-only (GITLAB_TOOLSETS=api).",
+        "project_id is a numeric ID or URL-encoded path (group%2Fproject). MR !123 → merge_request_iid=123.",
+    ].join("\n"),
+    "code-review": [
+        "Code review (2-step diffs):",
+        "1. list_merge_request_changed_files — paths only, no diff text.",
+        "2. get_merge_request_file_diff — 3-5 files per call.",
+        "3. create_merge_request_thread or create_draft_note, then bulk_publish_draft_notes.",
+        "Do not dump get_merge_request_diffs for a whole MR. Prefer jmespath on large results.",
+    ].join("\n"),
+    "merge-requests": [
+        "MR lifecycle: create_merge_request → review → approve_merge_request → merge_merge_request.",
+        "Lookup: project_id plus merge_request_iid (or source_branch).",
+        "Inspect: get_merge_request, get_merge_request_approval_state, get_merge_request_conflicts.",
+        "Discussions: mr_discussions, create_merge_request_thread, resolve_merge_request_thread.",
+        "merge_merge_request needs merge permission and often sha from get_merge_request.",
+    ].join("\n"),
+    issues: [
+        "Issues: list_issues (default scope is issues you created; use scope=all), my_issues, get_issue.",
+        "Write: create_issue, update_issue, create_issue_note, list_issue_discussions.",
+        "Small description edits: update_issue_description_patch instead of resending the full body.",
+        "project_id is a numeric ID or URL-encoded path.",
+    ].join("\n"),
+    pipelines: [
+        "Pipelines: discover_tools with category pipelines if those tools are hidden.",
+        "list_pipelines / get_pipeline, then list_pipeline_jobs / get_pipeline_job.",
+        "Logs: get_pipeline_job_output with pagination (limit / offset). Do not pull a whole trace.",
+        "Create/retry/cancel: create_pipeline, retry_pipeline, cancel_pipeline (destructive).",
+    ].join("\n"),
+    search: [
+        "search_repositories for projects. Code search: search_code, search_project_code, search_group_code",
+        "(needs GitLab advanced search or Zoekt; enable the search toolset via discover_tools).",
+        "If you already have an id or path, use get_project / get_issue / get_merge_request instead.",
+    ].join("\n"),
+    "token-saving": [
+        "Do not dump get_merge_request_diffs for a whole MR. Use list_merge_request_changed_files",
+        "then batched get_merge_request_file_diff.",
+        "Pass jmespath on any tool to shrink JSON. GITLAB_MCP_COMPACT_RESULTS replaces oversized",
+        "MCP replies with a preview plus a CLI command. Human CLI is never compacted.",
+        "Paginate logs (get_pipeline_job_output) and list endpoints. Prefer typed tools over",
+        "execute_graphql. Do not enable gitlab_api_request unless you accept its bypass risk.",
+    ].join("\n"),
+};
+export function getWorkflowGuide(topic = "overview") {
+    switch (topic) {
+        case "overview":
+        case "code-review":
+        case "merge-requests":
+        case "issues":
+        case "pipelines":
+        case "search":
+        case "token-saving":
+            return GUIDES[topic];
+        default:
+            return assertNever(topic);
+    }
+}
+export function readHelpTopic(value) {
+    if (value === undefined || value === null || value === "") {
+        return undefined;
+    }
+    if (typeof value === "string" && isHelpTopic(value)) {
+        return value;
+    }
+    return "invalid";
+}
+export function formatUnknownHelpTopic(value) {
+    return `Unknown help topic ${JSON.stringify(value)}. Available: ${HELP_TOPICS.join(", ")}`;
+}

package/build/server/mcp-instructions.js

@@ -0,0 +1,14 @@
+/**
+ * MCP initialize `instructions` — a short session briefing.
+ * Keep this under MCP_INSTRUCTIONS_MAX_BYTES so the handshake stays cheap.
+ */
+export const MCP_INSTRUCTIONS_MAX_BYTES = 2048;
+export const MCP_INSTRUCTIONS = [
+    "GitLab MCP. Default list: 38 core tools plus discover_tools and help (40). Call help for workflows.",
+    "MR review: list_merge_request_changed_files, then get_merge_request_file_diff for 3-5 files. Do not dump get_merge_request_diffs.",
+    "project_id: numeric ID or URL-encoded path (group%2Fproject). MR !123 uses merge_request_iid=123.",
+    "discover_tools: omit category to list; pass a category to activate for this session. api is explicit-only (GITLAB_TOOLSETS=api).",
+    "Shrink results: pass jmespath on any tool. Set GITLAB_MCP_COMPACT_RESULTS for oversized replies. Paginate get_pipeline_job_output.",
+    "Prefer typed tools over execute_graphql. Do not enable gitlab_api_request unless you accept allowlist and safety-check bypass. Prompt injection can drive it.",
+    "Destructive tools change GitLab state. Use the CLI (zereight-mcp-gitlab) for full diffs, logs, and artifacts.",
+].join("\n");

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/exposed-tools.js

@@ -1,4 +1,6 @@
 import { isExcludedBySlimProfile } from "./tool-profile.js";
+/** Meta tools re-added after every toolset filter so progressive disclosure stays available. */
+export const ALWAYS_LISTED_META_TOOLS = ["discover_tools", "help"];
 export function selectExposedTools(input) {
     const additiveAllowed = input.isAdditiveEnablementAllowed ?? (() => true);
     const toolsAfterToolsets = input.tools.filter(tool => input.isInEnabledToolset(tool.name));
@@ -22,12 +24,16 @@ export function selectExposedTools(input) {
         ? toolsAfterPermission.filter(tool => !deniedToolsRegex.test(tool.name))
         : [...toolsAfterPermission];
     const filteredToolNames = new Set(toolsAfterRegex.map(tool => tool.name));
-    const discoverTool = input.tools.find(tool => tool.name === "discover_tools");
-    if (discoverTool && !filteredToolNames.has("discover_tools")) {
-        const passesPermissionMode = input.isAllowedByPermissionMode("discover_tools");
-        const passesRegex = deniedToolsRegex ? !deniedToolsRegex.test("discover_tools") : true;
+    for (const metaName of ALWAYS_LISTED_META_TOOLS) {
+        const metaTool = input.tools.find(tool => tool.name === metaName);
+        if (!metaTool || filteredToolNames.has(metaName)) {
+            continue;
+        }
+        const passesPermissionMode = input.isAllowedByPermissionMode(metaName);
+        const passesRegex = deniedToolsRegex ? !deniedToolsRegex.test(metaName) : true;
         if (passesPermissionMode && passesRegex) {
-            toolsAfterRegex.push(discoverTool);
+            toolsAfterRegex.push(metaTool);
+            filteredToolNames.add(metaName);
         }
     }
     const withoutHidden = input.hiddenToolNames.size > 0

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/tools/registry.js

@@ -3,6 +3,7 @@ import { USE_GITLAB_WIKI, USE_MILESTONE, USE_PIPELINE, SSE, STREAMABLE_HTTP } fr
 import { getToolDescription } from "./tool-descriptions.js";
 import { ApproveMergeRequestSchema, BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobSchema, CancelPipelineSchema, ConvertWorkItemTypeSchema, CreateBranchSchema, CreateDraftNoteSchema, CreateGroupSchema, CreateGroupWikiPageSchema, CreateIssueLinkSchema, CreateIssueNoteSchema, CreateIssueSchema, CreateIssueEmojiReactionSchema, CreateIssueNoteEmojiReactionSchema, ListIssueEmojiReactionsSchema, ListIssueNoteEmojiReactionsSchema, CreateLabelSchema, MarkAllTodosDoneSchema, ListTodosSchema, MarkTodoDoneSchema, CreateMergeRequestDiscussionNoteSchema, CreateMergeRequestEmojiReactionSchema, ListMergeRequestEmojiReactionsSchema, ListMergeRequestNoteEmojiReactionsSchema, CreateMergeRequestNoteSchema, CreateMergeRequestNoteEmojiReactionSchema, CreateMergeRequestSchema, CreateMergeRequestThreadSchema, CreateNoteSchema, CreateCommitStatusSchema, CreateOrUpdateFileSchema, CreatePipelineSchema, CreateProjectMilestoneSchema, CreateGroupMilestoneSchema, CreateReleaseEvidenceSchema, CreateReleaseSchema, CreateRepositorySchema, CreateTagSchema, CreateTimelineEventSchema, CreateWebhookSchema, CreateWikiPageSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, CreateWorkItemSchema, DeleteBranchSchema, GetProtectedBranchSchema, ListProtectedBranchesSchema, ProtectBranchSchema, UpdateProtectedBranchSchema, ProtectTagSchema, UnprotectBranchSchema, UnprotectTagSchema, UpdateDefaultBranchSchema, DeleteDraftNoteSchema, DeleteGroupMilestoneSchema, DeleteGroupWikiPageSchema, DeleteIssueLinkSchema, DeleteIssueSchema, DeleteIssueEmojiReactionSchema, DeleteIssueNoteEmojiReactionSchema, DeleteLabelSchema, DeleteMergeRequestDiscussionNoteSchema, DeleteMergeRequestNoteSchema, DeleteMergeRequestEmojiReactionSchema, DeleteMergeRequestNoteEmojiReactionSchema, DeleteProjectMilestoneSchema, DeleteReleaseSchema, DeleteTagSchema, DeleteWebhookSchema, DeleteWikiPageSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, DownloadAttachmentSchema, DownloadAttachmentRemoteSchema, DownloadJobArtifactsSchema, DownloadJobArtifactsRemoteSchema, DownloadReleaseAssetSchema, EditProjectMilestoneSchema, EditGroupMilestoneSchema, ExecuteGraphQLSchema, ForkRepositorySchema, HealthCheckSchema, GetBranchSchema, GetBranchDiffsSchema, GetCommitDiffSchema, GetCommitSchema, GetFileBlameSchema, GetDeploymentSchema, CreateDeploymentSchema, UpdateDeploymentSchema, DeploymentApprovalSchema, ListDeploymentMergeRequestsSchema, GetDraftNoteSchema, GetEnvironmentSchema, UpdateEnvironmentSchema, StopEnvironmentSchema, StopStaleEnvironmentsSchema, DeleteReviewAppEnvironmentsSchema, PipelineTriggerIdSchema, ListPipelineTriggersSchema, CreatePipelineTriggerSchema, UpdatePipelineTriggerSchema, TriggerPipelineSchema, GetFileContentsSchema, GetGroupWikiPageSchema, GetIssueLinkSchema, GetIssueSchema, GetJobArtifactFileSchema, GetLabelSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GetMergeRequestDiffsSchema, GetMergeRequestFileDiffSchema, GetMergeRequestDiscussionSchema, GetMergeRequestNoteSchema, GetMergeRequestNotesSchema, GetMergeRequestSchema, GetMergeRequestVersionSchema, GetMilestoneBurndownEventsSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, GetGroupMilestoneSchema, GetGroupMilestoneIssuesSchema, GetGroupMilestoneMergeRequestsSchema, GetGroupMilestoneBurndownEventsSchema, GetNamespaceSchema, GetPipelineJobOutputSchema, PipelineJobControlSchema, GetPipelineSchema, GetRunnerSchema, GetPipelineVariablesSchema, UpdatePipelineMetadataSchema, DeletePipelineSchema, PipelineReportSchema, WaitForPipelineSchema, WaitForPipelineJobSchema, PlayPipelineJobsSchema, GetProjectEventsSchema, GetProjectMilestoneSchema, GetProjectSchema, GetReleaseSchema, GetRepositoryTreeSchema, GetTagSchema, GetTagSignatureSchema, GetProtectedTagSchema, GetTimelineEventsSchema, GetUsersSchema, GetUserSchema, WhoAmISchema, GetWebhookEventSchema, GetWikiPageSchema, GetWorkItemSchema, ListBranchesSchema, ListCommitsSchema, ListCommitStatusesSchema, ListCustomFieldDefinitionsSchema, ListDeploymentsSchema, ListDraftNotesSchema, ListEnvironmentsSchema, ListEventsSchema, ListGroupIterationsSchema, ListGroupMilestonesSchema, ListGroupProjectsSchema, ListGroupWikiPagesSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListJobArtifactsSchema, ListLabelsSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiffsSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestVersionsSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListPipelinesSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, ListGroupMembersSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListProjectRunnersSchema, ListReleasesSchema, ListTagsSchema, ListProtectedTagsSchema, ListWebhookEventsSchema, ListWebhooksSchema, ListWikiPagesSchema, ListWorkItemNotesSchema, ListWorkItemStatusesSchema, ListWorkItemsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, MergeMergeRequestSchema, MoveWorkItemSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, PlayPipelineJobSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PushFilesSchema, ResolveMergeRequestThreadSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, UnapproveMergeRequestSchema, RebaseMergeRequestSchema, UpdateDraftNoteSchema, UpdateGroupWikiPageSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, UpdateLabelSchema, UpdateProjectSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestSchema, UpdateReleaseSchema, UpdateWebhookSchema, UpdateWikiPageSchema, UpdateWorkItemSchema, VerifyNamespaceSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, } from "../schemas.js";
 import { GitLabApiRequestSchema } from "./gitlab-api-request.js";
+import { HelpInputSchema } from "../server/mcp-help.js";
 const IS_REMOTE = SSE || STREAMABLE_HTTP;
 // Define all available tools
 export const allTools = [
@@ -1427,10 +1428,16 @@ export const allTools = [
             },
         },
     },
+    {
+        name: "help",
+        description: "Return a short GitLab workflow guide. Omit topic for the overview and topic list.",
+        inputSchema: toJSONSchema(HelpInputSchema),
+    },
 ];
 // Define which tools are read-only
 export const readOnlyTools = new Set([
     "discover_tools",
+    "help",
     "health_check",
     "search_repositories",
     "search_code",

package/build/tools/tool-descriptions.js

@@ -39,6 +39,7 @@ const TOOL_GUIDANCE = {
     download_attachment: "Retrieve a project attachment. Remote HTTP returns inline base64 or a URL; local stdio saves under GITLAB_DOWNLOAD_DIR and never overwrites.",
     gitlab_api_request: "Send one GitLab REST call under /api/v4. Readonly allows GET only; modify rejects DELETE. Enable only by listing api in GITLAB_TOOLSETS; all, discover_tools, and GITLAB_TOOLS do not. Prompt injection can drive this tool, so operators who rely on group, project, or tool restrictions must not enable it. With GITLAB_ALLOWED_PROJECT_IDS or a session project scope, only /projects/:id paths for an allowed project are accepted; body and query parameters that name another project are not checked.",
     execute_graphql: "Use only when no typed REST tool covers the operation. The query is sent directly and may include mutations.",
+    help: "Use this for a short workflow guide (code-review, pipelines, issues, token-saving). Omit topic for the overview. Detailed GitLab operations stay on the typed tools.",
     whoami: "Requires classic read_user or fine-grained User:Read. Use `get_user` or `get_users` to look up another user.",
     list_project_members: "Search project members by name or username. Use `list_group_members` for a group.",
     get_commit_diff: "Return the file diffs for one commit. Use `get_commit` for metadata without the patch.",