npm - @zereight/mcp-gitlab - Versions diffs - 2.3.8-next.146 → 2.3.8-next.147 - Mend

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

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (11) hide show

package/README.ko.md +117 -15
package/README.md +120 -16
package/README.pt-BR.md +117 -15
package/README.zh-CN.md +117 -15
package/build/index.js +20 -0
package/build/server/mcp-help.js +101 -0
package/build/server/mcp-instructions.js +14 -0
package/build/tools/exposed-tools.js +11 -5
package/build/tools/registry.js +7 -0
package/build/tools/tool-descriptions.js +1 -0
package/package.json +1 -1

package/README.ko.md CHANGED Viewed

@@ -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개 도구** (`core` 38개 + `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 하세요. 셸 기록에는 변수 이름만 남습니다.
+### 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` |
+### 설치 3경로
+| 경로 | 언제 | 어떻게 |
+| ---- | ---- | ------ |
+| 로컬 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개 도구(core 38 + discover_tools + help). 확장은 discover_tools. api toolset은 우회 위험을 받아들일 때만.
+MCP 없는 동등 경로: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill 와 zereight-mcp-gitlab CLI.
+```
+### 원격 HTTP
+호스팅/셀프호스트 서버의 1순위 옵션입니다. 클라이언트를 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`, MR `!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 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 ### 왜 이 GitLab MCP를 사용하나요?
-- **277개 도구: toolset 275개 + `execute_graphql` + `discover_tools`** — 작은 toolset으로 시작하고, 런타임에 카테고리 활성화
+- **기본 40개 도구(`core` 38 + `discover_tools` + `help`); 전체 278개** — 작게 시작하고, `discover_tools`로 세션에서 확장
 - **MR 2단계 리뷰** — `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 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 |                 | @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 리뷰**     | 2단계 배치 diff                                                  | 서버마다 다름                              | `get_merge_request`에 diffs                                                                                                                     |
 | **Node.js**     | >=18.17                                                          | 보통 >=24                                  | stdio는 `mcp-remote`, Node.js 20+                                                                                                               |
 | **라이선스**    | MIT                                                              | 서버마다 다름                              | GitLab의 일부                                                                                                                                   |
@@ -603,7 +705,7 @@ node build/index.js
 ## Agent Skill Files
-AI 에이전트가 skill/instruction 로딩을 지원하는 경우(Claude Code, GitHub Copilot, Cursor 등), [`skills/gitlab-mcp/`](./skills/gitlab-mcp/)에 미리 작성된 skill 파일을 사용할 수 있습니다.
+Skill + CLI는 MCP와 동등한 경로입니다([Skill + CLI](#skill--cli-mcp-불필요) 참고). AI 에이전트가 skill/instruction 로딩을 지원하는 경우(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/README.md CHANGED Viewed

@@ -4,32 +4,135 @@
 [![npm downloads](https://badgen.net/npm/dm/@zereight/mcp-gitlab)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
 [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
 [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
-[![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)
 [![Ask DeepWiki](https://img.shields.io/badge/DeepWiki-Ask-blue)](https://deepwiki.com/zereight/gitlab-mcp)
-[![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp) [![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-zereight-gitlab-mcp)](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)
+[![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp)
+[![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-zereight-gitlab-mcp)](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)
 [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
-📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** Setup guides, environment variables, and the full tool reference live on the hosted docs site.
+📖 **[Documentation →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
-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.
+**Default: 40 tools** (38 `core` + `discover_tools` + `help`). 278 tools exist in total (275 in toolsets + `execute_graphql` + `discover_tools` + `help`). Start lean; call `discover_tools` to activate more for this session.
 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.
+### Without → With
+| Without this MCP | With this MCP |
+| ---------------- | ------------- |
+| Paste MR URLs and diffs into chat | `list_merge_request_changed_files` → batched `get_merge_request_file_diff` |
+| Hunt job logs in the GitLab UI | `get_pipeline_job_output` with pagination |
+| Re-explain the project path every turn | `project_id=group%2Fproject` and `merge_request_iid=123` |
+### Three install paths
+| Path | When | How |
+| ---- | ---- | --- |
+| Local IDE | Cursor, Claude Code, Codex on your machine | stdio + PAT or local OAuth |
+| Shared HTTP | Team or hosted MCP | Streamable HTTP URL + remote auth or MCP OAuth |
+| Claude.ai | Claude web connectors | Public HTTPS + `GITLAB_MCP_OAUTH` |
+### Install
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
+Install the binary first (`npm install -g @zereight/mcp-gitlab`, or Homebrew `brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp` then `brew install zereight/gitlab-mcp/zereight-mcp-gitlab`). Read the token without echo:
 ```bash
 read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
 ```
-| Client       | Install                                                                                                                                                                                          |
-| ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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 setup guide](./docs/clients/cursor.md)                                                                                                                                    |
-| VS Code      | [VS Code setup guide](./docs/clients/vscode.md)                                                                                                                                   |
-| JSON clients | [JSON-based MCP clients setup guide](./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
+```
+Other clients: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [JSON clients](./docs/clients/json-clients.md) · [Cursor details](./docs/clients/cursor.md)
+### Agent paste-prompt
+Copy this into an agent that can edit MCP config:
+```
+Install the GitLab MCP server (@zereight/mcp-gitlab) for this workspace.
+Binary: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, or npx -y @zereight/mcp-gitlab@latest).
+Auth: GITLAB_PERSONAL_ACCESS_TOKEN plus GITLAB_API_URL=https://gitlab.com/api/v4 (or GITLAB_USE_OAUTH=true).
+Local: 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
+Or: 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: use the README deeplink or docs/clients/cursor.md.
+Remote HTTP: point the client at https://mcp.example.com/mcp (Streamable HTTP). Claude.ai needs GITLAB_MCP_OAUTH on that host.
+Default list: 40 tools (38 core + discover_tools + help). Call discover_tools to expand. Do not enable the api toolset unless you accept its bypass risk.
+Equal non-MCP path: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill plus the zereight-mcp-gitlab CLI.
+```
+### Remote HTTP
+First-class option for a hosted or self-hosted server. Point the client at a Streamable HTTP URL:
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+- Hosted / Claude.ai: `GITLAB_MCP_OAUTH=true` on the server (see [MCP OAuth](#mcp-oauth-setup-claudeai-native-oauth))
+- Per-user PAT headers: `REMOTE_AUTHORIZATION=true` (see [Remote Authorization](#using-remote-authorization-remote_authorization))
+- Local Docker examples are in [Usage](#usage)
+### Skill + CLI (no MCP required)
+Skill + CLI is an equal path, not a fallback. Same workflows, full payloads in a terminal, no MCP registration.
+```bash
+npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
+zereight-mcp-gitlab user whoami
+zereight-mcp-gitlab mr list
+```
+See [CLI without MCP](./docs/getting-started/cli-without-mcp.md) and [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
+### MCP vs Human CLI
+| Use MCP when | Use the CLI when |
+| ------------ | ---------------- |
+| The agent needs structured tools in chat | You need the full payload (diffs, logs, artifacts) |
+| `jmespath` or compact results are enough | `GITLAB_MCP_COMPACT_RESULTS` is on and you want the rest in a terminal |
+| You already registered the server | You have a PAT or ran `auth` and do not want MCP |
+Human CLI is never compacted. Destructive tools and `GITLAB_TOOL_POLICY_APPROVE` tools need `--yes`.
+### Tips
+`project_id` is a numeric ID or a URL-encoded path. Example: group `group`, project `project`, merge request `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. Nested groups use `%2F` between every segment (`group%2Fsubgroup%2Fproject`).
+### FAQ
+**How do I authenticate?** Local desktop: `GITLAB_PERSONAL_ACCESS_TOKEN` (or `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) is the simplest. Local OAuth is `GITLAB_USE_OAUTH=true`. Remote Claude.ai uses `GITLAB_MCP_OAUTH`. Multi-user HTTP uses `REMOTE_AUTHORIZATION` and a per-request token header.
+**Why do I only see ~40 tools?** The default `core` toolset is 38 tools plus always-on `discover_tools` and `help`. Call `discover_tools` with no args to list categories, then pass a category (`pipelines`, `wiki`, …) to activate it for this session. `GITLAB_TOOLSETS=all` still does **not** enable `api`.
+**Local OAuth vs MCP OAuth vs remote auth?** Local OAuth opens a browser on the same machine as the server. MCP OAuth is for a public HTTPS server and clients such as Claude.ai. Remote authorization forwards the caller's PAT or job token; there is no OAuth dance.
+**How do I shrink huge replies?** Pass `jmespath` on any tool call. Or set `GITLAB_MCP_COMPACT_RESULTS=true` so oversized MCP replies become a preview plus a CLI command. Use the CLI when you need the full payload.
+**Why is the `api` toolset dangerous?** `gitlab_api_request` bypasses group/project allowlists, other tool filters, and per-tool safety checks. Prompt injection can drive it. Enable it only by listing `api` in `GITLAB_TOOLSETS`. `all`, `discover_tools`, and `GITLAB_TOOLS` do not.
+### Cursor rule / CLAUDE.md snippet
+```
+GitLab merge requests, issues, and pipelines go through this MCP (@zereight/mcp-gitlab).
+Start with the default core tools. Call discover_tools to expand.
+Prefer list_merge_request_changed_files, then batched get_merge_request_file_diff.
+Use jmespath or compact results; use the CLI for full diffs and job logs.
+```
 [![Star History Chart](./assets/star-history.png)](https://www.star-history.com/?repos=zereight%2Fgitlab-mcp&type=date&legend=top-left)
@@ -41,7 +144,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
 ### Why use this GitLab MCP?
-- **277 tools: 275 in toolsets + `execute_graphql` + `discover_tools`** — start with a small toolset; activate more at runtime without CQRS-style grouping
+- **Default 40 tools (38 `core` + `discover_tools` + `help`); 278 total** — start lean; call `discover_tools` to activate more without CQRS-style grouping
 - **MR 2-step review** — `list_merge_request_changed_files` → batched `get_merge_request_file_diff`
 - **Agent Skill built in** — workflow guidance in `skills/gitlab-mcp/`
 - **Flexible auth** — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
@@ -55,7 +158,7 @@ Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization
 |                | @zereight/mcp-gitlab                                              | GitLab MCP A (community CQRS-style)          | GitLab official MCP server                                                                                                                       |
 | -------------- | ----------------------------------------------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ |
 | **Best for**   | AI agent workflows                                                | Enterprise multi-instance / grouped tools    | Built into GitLab, no separate install                                                                                                           |
-| **Tool model** | 277 tools: 275 in toolsets + `execute_graphql` + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header                                                                                                              |
+| **Tool model** | 278 tools: 275 in toolsets + `execute_graphql` + `discover_tools` + `help` | ~50–60 grouped `browse_*` / `manage_*` tools | Toolsets chosen with an HTTP header                                                                                                              |
 | **MR review**  | 2-step batched diff                                               | Varies                                       | `get_merge_request` with diffs                                                                                                                   |
 | **Node.js**    | >=18.17                                                           | Often >=24                                   | Node.js 20+ for stdio via `mcp-remote`                                                                                                           |
 | **License**    | MIT                                                               | Varies                                       | Part of GitLab                                                                                                                                   |
@@ -653,7 +756,7 @@ No `headers` field is needed — Claude.ai obtains the token via OAuth automatic
 ## Agent Skill Files
-Pre-built skill files are available in [`skills/gitlab-mcp/`](./skills/gitlab-mcp/) for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).
+Skill + CLI is an equal path to MCP (see [Skill + CLI](#skill--cli-no-mcp-required)). Pre-built skill files are available in [`skills/gitlab-mcp/`](./skills/gitlab-mcp/) for AI agents that support skill/instruction loading (Claude Code, GitHub Copilot, Cursor, etc.).
 - **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — Core guide (~800 tokens) with toolset overview, key workflows, and parameter hints
 - **[reference/](./skills/gitlab-mcp/reference/)** — Detailed workflow docs for code review, merge requests, issues, pipelines, and vulnerability triage
@@ -950,6 +1053,7 @@ Register the skill directory in your AI client to get optimal tool usage guidanc
 275. `rebase_merge_request` - Rebase the source branch of a merge request onto its target branch
 276. `gitlab_api_request` - Send one GitLab REST call under /api/v4. Enabled only when GITLAB_TOOLSETS lists api. Readonly allows GET; modify rejects DELETE.
 277. `discover_tools` - Discover and activate additional tool categories for this session. Available categories: core, merge_requests, issues, repositories, branches, projects, labels, ci, groups, pipelines, milestones, wiki, releases, tags, snippets, users, workitems, webhooks, search, variables, dependency_proxy, vulnerabilities, orbit. Already-active categories are listed in the response.
+278. `help` - Return a short GitLab workflow guide. Omit topic for the overview and topic list.
 <!-- TOOLS-END -->

package/README.pt-BR.md CHANGED Viewed

@@ -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)
-📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)** Guias de configuração, variáveis de ambiente e a referência completa de ferramentas estão disponíveis no site de documentação.
+📖 **[Documentação →](https://zereight.github.io/gitlab-mcp/)** · [llms.txt](./llms.txt) · [llms-full.txt](./llms-full.txt)
-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).
+**Padrão: 40 ferramentas** (38 `core` + `discover_tools` + `help`). Existem 278 no total (275 em toolsets + `execute_graphql` + `discover_tools` + `help`). Comece enxuto; chame `discover_tools` para ativar mais nesta sessão.
 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.
+### Without → With
+| Sem este MCP | Com este MCP |
+| ------------ | ------------ |
+| Colar URLs e diffs de MR no chat | `list_merge_request_changed_files` → `get_merge_request_file_diff` em lote |
+| Caçar logs de job na UI do GitLab | `get_pipeline_job_output` com paginação |
+| Reexplicar o caminho do projeto a cada turno | `project_id=group%2Fproject` e `merge_request_iid=123` |
+### Três caminhos de instalação
+| Caminho | Quando | Como |
+| ------- | ------ | ---- |
+| IDE local | Cursor, Claude Code, Codex na sua máquina | stdio + PAT ou OAuth local |
+| HTTP compartilhado | MCP de time ou hospedado | URL Streamable HTTP + auth remota ou MCP OAuth |
+| Claude.ai | Conectores web do Claude | HTTPS público + `GITLAB_MCP_OAUTH` |
+### Instalação
+[![Install in Cursor](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en/install-mcp?name=zereight.gitlab-mcp&config=eyJ0eXBlIjoic3RkaW8iLCJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkB6ZXJlaWdodC9tY3AtZ2l0bGFiQGxhdGVzdCJdLCJlbnYiOnsiR0lUTEFCX1BFUlNPTkFMX0FDQ0VTU19UT0tFTiI6IiR7ZW52OkdJVExBQl9QRVJTT05BTF9BQ0NFU1NfVE9LRU59IiwiR0lUTEFCX0FQSV9VUkwiOiJodHRwczovL2dpdGxhYi5jb20vYXBpL3Y0In19)
+Instale o binário primeiro (`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`). Leia o token sem eco:
 ```bash
 read -rs GITLAB_PERSONAL_ACCESS_TOKEN && export GITLAB_PERSONAL_ACCESS_TOKEN
 ```
-| Cliente       | Instalação                                                                                                                                                                                       |
-| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| 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        | [Guia de configuração do Cursor](./docs/clients/cursor.md)                                                                                                                        |
-| VS Code       | [Guia de configuração do VS Code](./docs/clients/vscode.md)                                                                                                                       |
-| Clientes JSON | [Guia para clientes MCP baseados em JSON](./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
+```
+Outros clientes: [VS Code](./docs/clients/vscode.md) · [GitHub Copilot](./docs/clients/copilot.md) · [Clientes JSON](./docs/clients/json-clients.md) · [Detalhes do Cursor](./docs/clients/cursor.md)
+### Prompt para colar no agente
+Cole isto em um agente que possa editar a config MCP:
+```
+Instale o servidor GitLab MCP (@zereight/mcp-gitlab) neste workspace.
+Binário: zereight-mcp-gitlab (npm i -g @zereight/mcp-gitlab, ou npx -y @zereight/mcp-gitlab@latest).
+Auth: GITLAB_PERSONAL_ACCESS_TOKEN e GITLAB_API_URL=https://gitlab.com/api/v4 (ou GITLAB_USE_OAUTH=true).
+Local: 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
+Ou: 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: use o deeplink do README ou docs/clients/cursor.md.
+HTTP remoto: aponte o cliente para https://mcp.example.com/mcp (Streamable HTTP). Claude.ai precisa de GITLAB_MCP_OAUTH nesse host.
+Lista padrão: 40 ferramentas (38 core + discover_tools + help). Expanda com discover_tools. Não habilite o toolset api sem aceitar o risco de bypass.
+Caminho equivalente sem MCP: npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill mais a CLI zereight-mcp-gitlab.
+```
+### HTTP remoto
+Opção de primeira classe para servidor hospedado ou self-hosted. Aponte o cliente para uma URL Streamable HTTP:
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "type": "http",
+      "url": "https://mcp.example.com/mcp"
+    }
+  }
+}
+```
+- Hospedado / Claude.ai: `GITLAB_MCP_OAUTH=true` no servidor (veja [MCP OAuth](#usando-o-proxy-mcp-oauth-gitlab_mcp_oauth))
+- Cabeçalhos PAT por usuário: `REMOTE_AUTHORIZATION=true` (veja [autorização remota](#usando-autorização-remota-remote_authorization))
+- Exemplos Docker locais estão em [Uso](#uso)
+### Skill + CLI (MCP não é obrigatório)
+Skill + CLI é um caminho equivalente, não um fallback. Os mesmos fluxos, payload completo no terminal, sem registrar MCP.
+```bash
+npx skills add zereight/gitlab-mcp --skill gitlab-mcp-skill
+zereight-mcp-gitlab user whoami
+zereight-mcp-gitlab mr list
+```
+Veja [CLI sem MCP](./docs/getting-started/cli-without-mcp.md) e [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
+### MCP vs Human CLI
+| Use o MCP quando | Use a CLI quando |
+| ---------------- | ---------------- |
+| O agente precisa de ferramentas estruturadas no chat | Você precisa do payload completo (diffs, logs, artefatos) |
+| `jmespath` ou resultados compactos bastam | `GITLAB_MCP_COMPACT_RESULTS` está ligado e o resto vai para o terminal |
+| Você já registrou o servidor | Você tem um PAT ou rodou `auth` e não quer MCP |
+A CLI humana nunca é compactada. Ferramentas destrutivas e `GITLAB_TOOL_POLICY_APPROVE` precisam de `--yes`.
+### Tips
+`project_id` é um ID numérico ou um caminho com URL-encoding. Exemplo: grupo `group`, projeto `project`, merge request `!123` → `project_id=group%2Fproject`, `merge_request_iid=123`. Grupos aninhados usam `%2F` entre cada segmento (`group%2Fsubgroup%2Fproject`).
+### FAQ
+**Como autenticar?** No desktop local, `GITLAB_PERSONAL_ACCESS_TOKEN` (ou `GITLAB_PERSONAL_ACCESS_TOKEN_FILE`) é o mais simples. OAuth local é `GITLAB_USE_OAUTH=true`. Claude.ai remoto usa `GITLAB_MCP_OAUTH`. HTTP multi-usuário usa `REMOTE_AUTHORIZATION` e um cabeçalho de token por requisição.
+**Por que vejo só ~40 ferramentas?** O toolset `core` padrão tem 38 ferramentas mais o `discover_tools` e o `help` sempre ligados. Chame `discover_tools` sem args para listar categorias e passe uma (`pipelines`, `wiki`, …) para ativá-la nesta sessão. `GITLAB_TOOLSETS=all` ainda **não** habilita `api`.
+**OAuth local vs MCP OAuth vs auth remota?** OAuth local abre o navegador na mesma máquina do servidor. MCP OAuth é para um servidor HTTPS público e clientes como Claude.ai. Autorização remota encaminha o PAT ou job token do chamador; não há fluxo OAuth.
+**Como encolher respostas enormes?** Passe `jmespath` em qualquer chamada. Ou defina `GITLAB_MCP_COMPACT_RESULTS=true` para trocar respostas MCP grandes por um preview e um comando CLI. Use a CLI quando quiser o payload completo.
+**Por que o toolset `api` é perigoso?** `gitlab_api_request` ignora allowlists de grupo/projeto, outros filtros de ferramenta e checagens de segurança por ferramenta. Prompt injection pode acioná-lo. Habilite só listando `api` em `GITLAB_TOOLSETS`. `all`, `discover_tools` e `GITLAB_TOOLS` não fazem isso.
+### Snippet de Cursor rule / CLAUDE.md
+```
+Merge requests, issues e pipelines do GitLab passam por este MCP (@zereight/mcp-gitlab).
+Comece pelas ferramentas core padrão. Chame discover_tools para expandir.
+Prefira list_merge_request_changed_files e depois get_merge_request_file_diff em lote.
+Use jmespath ou resultados compactos; use a CLI para diffs e logs completos.
+```
 [![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 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 ### Por que usar este GitLab MCP?
-- **277 ferramentas: 275 em toolsets + `execute_graphql` + `discover_tools`** — comece com um toolset pequeno e ative mais categorias em tempo de execução
+- **40 ferramentas por padrão (38 `core` + `discover_tools` + `help`); 278 no total** — comece enxuto; chame `discover_tools` para expandir nesta sessã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
@@ -50,7 +152,7 @@ Suporta PAT, OAuth, modo somente leitura, URLs de API dinâmicas e autorização
 |                           | @zereight/mcp-gitlab                                                    | GitLab MCP A (comunidade, estilo CQRS)                    | Servidor MCP oficial do GitLab                                                                                                                                 |
 | ------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | **Mais indicado para**    | Workflows de agentes de IA                                              | Múltiplas instâncias corporativas / ferramentas agrupadas | Integrado ao GitLab, sem instalação separada                                                                                                                   |
-| **Modelo de ferramentas** | 277 ferramentas: 275 em toolsets + `execute_graphql` + `discover_tools` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      | Toolsets escolhidos por cabeçalho HTTP                                                                                                                         |
+| **Modelo de ferramentas** | 278 ferramentas: 275 em toolsets + `execute_graphql` + `discover_tools` + `help` | ~50–60 ferramentas agrupadas `browse_*` / `manage_*`      | Toolsets escolhidos por cabeçalho HTTP                                                                                                                         |
 | **Revisão de MR**         | Diff em lote em 2 etapas                                                | Varia                                                     | `get_merge_request` com diffs                                                                                                                                  |
 | **Node.js**               | >=18.17                                                                 | Frequentemente >=24                                       | Node.js 20+ para stdio via `mcp-remote`                                                                                                                        |
 | **Licença**               | MIT                                                                     | Varia                                                     | Parte do GitLab                                                                                                                                                |
@@ -603,7 +705,7 @@ Não é necessário definir `headers`. O Claude.ai obtém o token via OAuth.
 ## Arquivos de Agent Skill
-Para agentes de IA que suportam carregamento de skills/instructions (Claude Code, GitHub Copilot, Cursor etc.), arquivos de skill pré-configurados estão disponíveis em [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
+Skill + CLI é um caminho equivalente ao MCP (veja [Skill + CLI](#skill--cli-mcp-não-é-obrigatório)). Para agentes de IA que suportam carregamento de skills/instructions (Claude Code, GitHub Copilot, Cursor etc.), arquivos de skill pré-configurados estão disponíveis em [`skills/gitlab-mcp/`](./skills/gitlab-mcp/).
 - **[SKILL.md](./skills/gitlab-mcp/SKILL.md)** — guia principal com visão geral dos toolsets, workflows importantes e dicas de parâmetros
 - **[reference/](./skills/gitlab-mcp/reference/)** — documentação detalhada de workflows para code review, merge requests, issues, pipelines e triagem de vulnerabilidades

package/README.zh-CN.md CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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";
@@ -213,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 ?? {})));
@@ -337,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();

package/build/server/mcp-help.js ADDED Viewed

@@ -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 ADDED Viewed

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

@@ -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/registry.js CHANGED Viewed

@@ -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 CHANGED Viewed

@@ -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.",

package/package.json CHANGED Viewed

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