@zereight/mcp-gitlab 2.1.50 → 2.1.52

package/README.ko.md

@@ -1,5 +1,8 @@
 # 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)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%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%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
+
 [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md)
 
 📖 **[문서 →](https://zereight.github.io/gitlab-mcp/)** 설정 가이드, 환경 변수, 전체 도구 레퍼런스는 호스팅된 문서 사이트에서 확인할 수 있습니다.
@@ -8,19 +11,35 @@
 
 ## @zereight/mcp-gitlab
 
-AI 클라이언트를 위한 포괄적인 GitLab MCP 서버입니다. stdio, SSE, Streamable HTTP를 통해 프로젝트, 머지 리퀘스트, 이슈, 파이프라인, 위키, 릴리스, 마일스톤 등을 관리할 수 있습니다.
+**에이전트 워크플로우에 최적화된 GitLab MCP** — stdio, SSE, Streamable HTTP를 통해 프로젝트, 머지 리퀘스트, 이슈, 파이프라인, 위키, 릴리스, 마일스톤 등을 관리할 수 있습니다.
+
+동일한 서버가 [`@zereight/gitlab-mcp`](https://www.npmjs.com/package/@zereight/gitlab-mcp) 이름으로도 배포됩니다 (npm 검색용 별칭).
 
 PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며 VS Code, Claude, Cursor, Copilot 및 기타 MCP 클라이언트에서 사용할 수 있습니다.
 
 ### 왜 이 GitLab MCP를 사용하나요?
 
-- 넓은 GitLab 지원 범위: 프로젝트, 저장소 탐색, 머지 리퀘스트, 이슈, 파이프라인, 위키, 릴리스, 라벨, 마일스톤 등
-- 유연한 인증: Personal Access Token, 로컬 OAuth2 브라우저 플로우, MCP OAuth 프록시, 요청별 원격 인증
-- 여러 전송 방식: 로컬 클라이언트용 stdio, 레거시 클라이언트용 SSE, 최신 원격 배포용 Streamable HTTP
-- 클라이언트 친화적 설정: Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code 예시 제공
-- 셀프 호스팅 대응: 커스텀 GitLab 인스턴스, 프록시 설정, 동적 API URL 라우팅 지원
+- **217개 도구 + `discover_tools`** — 작은 toolset으로 시작하고, 런타임에 카테고리 활성화
+- **MR 2단계 리뷰** — `list_merge_request_changed_files` → 배치 `get_merge_request_file_diff`
+- **Agent Skill 내장** — `skills/gitlab-mcp/` 워크플로우 가이드
+- **유연한 인증** — Personal Access Token, 로컬 OAuth2 브라우저 플로우, MCP OAuth 프록시, 요청별 원격 인증
+- **여러 전송 방식** — 로컬 클라이언트용 stdio, 레거시 클라이언트용 SSE, 최신 원격 배포용 Streamable HTTP
+- **클라이언트 친화적 설정** — Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, Amp Code 예시 제공
+- **셀프 호스팅 대응** — 커스텀 GitLab 인스턴스, 프록시 설정, 동적 API URL 라우팅 지원
+
+### 비교 요약
 
-빠른 시작: 아래에서 Personal Access Token 또는 OAuth2 설정 중 하나를 선택하고 `@zereight/mcp-gitlab`을 설치한 뒤 MCP 클라이언트 설정에서 `zereight-mcp-gitlab`을 사용하세요.
+| | @zereight/mcp-gitlab | GitLab MCP A (커뮤니티 CQRS형) |
+|---|----------------------|--------------------------------|
+| **적합한 경우** | AI 에이전트 워크플로우 | 엔터프라이즈 멀티 인스턴스 / 그룹형 도구 |
+| **도구 모델** | ~217개 세분화 도구 + `discover_tools` | ~50–60개 `browse_*` / `manage_*` 그룹 도구 |
+| **MR 리뷰** | 2단계 배치 diff | 서버마다 다름 |
+| **Node.js** | >=18 | 보통 >=24 |
+| **라이선스** | MIT | 서버마다 다름 |
+
+[전체 비교 →](./docs/comparison/community-gitlab-mcp-a.md)
+
+빠른 시작: 아래에서 Personal Access Token 또는 OAuth2 설정 중 하나를 선택하고 `@zereight/mcp-gitlab`(또는 `@zereight/gitlab-mcp`)을 설치한 뒤 MCP 클라이언트 설정에서 `zereight-mcp-gitlab`을 사용하세요.
 
 ### 클라이언트 설정 가이드
 
@@ -62,6 +81,7 @@ PAT, OAuth, 읽기 전용 모드, 동적 API URL, 원격 인증을 지원하며
 - **Cursor**: [Cursor 설정 가이드](./docs/clients/cursor.md)
 - **Factory AI Droid / OpenClaw / OpenCode 스타일 클라이언트**: [JSON 기반 MCP 클라이언트 설정 가이드](./docs/clients/json-clients.md)
 - **OAuth 브라우저 플로우 상세**: [OAuth2 인증 설정 가이드](./docs/auth/oauth-setup.md)
+- **localhost callback 없이 OAuth** (SSO, 원격 셸, 백그라운드 클라이언트): `zereight-mcp-gitlab auth`를 먼저 실행하세요 (GitLab 17.9+ device flow; 17.2–17.8은 `oauth2_device_grant_flow` 필요). 그다음 서버는 `GITLAB_USE_OAUTH=true`로 시작합니다. [독립 device-flow 커맨드](./docs/auth/oauth-setup.md#standalone-device-flow-auth-command)를 참고하세요.
 
 가장 단순한 로컬 설정은 Personal Access Token으로 시작하세요. 브라우저 기반 로컬 인증은 OAuth2를 사용하세요. 원격 또는 멀티 유저 배포는 아래 MCP OAuth 및 원격 인증 섹션을 참고하세요.
 
@@ -72,15 +92,17 @@ brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
 brew install zereight/gitlab-mcp/zereight-mcp-gitlab
 ```
 
-npm으로 설치할 수도 있습니다:
+npm으로 설치할 수도 있습니다 (두 패키지명 모두 동일한 서버입니다):
 
 ```shell
 npm install -g @zereight/mcp-gitlab
+# 또는
+npm install -g @zereight/gitlab-mcp
 ```
 
 예시는 기존 `mcp-gitlab`보다 충돌 가능성이 낮은 `zereight-mcp-gitlab` 별칭을 사용합니다. MCP 클라이언트가 찾지 못하면 `which zereight-mcp-gitlab`의 절대 경로를 사용하세요.
 
-전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.49`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.51`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 
@@ -111,8 +133,10 @@ npm install -g @zereight/mcp-gitlab
 
 CLI 인자는 환경 변수보다 우선합니다.
 
+`zereight-mcp-gitlab auth`는 MCP 서버 플래그가 아니라 서브커맨드입니다. GitLab device flow를 실행한 뒤 종료합니다. [CLI 인자](./docs/getting-started/cli-arguments.md#auth)를 참고하세요.
+
 > **세밀한 도구 필터링:** `GITLAB_PERMISSION_MODE=modify`로 생성/수정은 허용하고 모든 삭제 도구를
-> 차단하거나, `GITLAB_PERMISSION_MODE=readonly`로 읽기 전용으로 운영할 수 있습니다. 또한
+> 차단하거나(`execute_graphql` 삭제 mutation과 `push_files`의 `delete`/`move` 포함), `GITLAB_PERMISSION_MODE=readonly`로 읽기 전용으로 운영할 수 있습니다. 또한
 > `GITLAB_TOOLSETS=<group,…>`로 도구 그룹을 활성화하고, `GITLAB_TOOLS=<tool,…>`로 개별 도구만
 > 허용하며(예: 읽기 도구 + 특정 쓰기 도구 몇 개), `GITLAB_DENIED_TOOLS_REGEX`로 패턴 차단할 수
 > 있습니다. 레거시 `USE_GITLAB_WIKI` / `USE_MILESTONE` / `USE_PIPELINE` 플래그는 하위 호환용으로만

package/README.md

@@ -1,5 +1,7 @@
 # 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)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%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%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
 [![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)
@@ -10,19 +12,35 @@
 
 ## @zereight/mcp-gitlab
 
-A comprehensive GitLab MCP server for AI clients. Manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.
+**Agent-workflow-optimized GitLab MCP** — manage projects, merge requests, issues, pipelines, wiki, releases, tags, milestones, and more through stdio, SSE, and Streamable HTTP.
+
+Also published as [`@zereight/gitlab-mcp`](https://www.npmjs.com/package/@zereight/gitlab-mcp) (search-friendly alias for the same server).
 
 Supports PAT, OAuth, read-only mode, dynamic API URLs, and remote authorization for VS Code, Claude, Cursor, Copilot, and other MCP clients.
 
 ### Why use this GitLab MCP?
 
-- Broad GitLab coverage — projects, repository browsing, merge requests, issues, pipelines, wiki, releases, tags, labels, milestones, and more
-- Flexible auth — Personal Access Token, local OAuth2 browser flow, MCP OAuth proxy, and per-request remote authorization
-- Multiple transports — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
-- Client-friendly setup — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
-- Self-hosted ready — works with custom GitLab instances, proxy settings, and dynamic API URL routing
+- **217 tools + `discover_tools`** — start with a small toolset; activate more at runtime 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
+- **Multiple transports** — stdio for local clients, SSE for legacy clients, and Streamable HTTP for modern remote deployments
+- **Client-friendly setup** — examples for Claude Code, Codex, Antigravity, OpenCode, Copilot, Cline, Roo Code, Cursor, Kilo Code, and Amp Code
+- **Self-hosted ready** — works with custom GitLab instances, proxy settings, and dynamic API URL routing
+
+### How we compare
+
+| | @zereight/mcp-gitlab | GitLab MCP A (community CQRS-style) |
+|---|----------------------|-------------------------------------|
+| **Best for** | AI agent workflows | Enterprise multi-instance / grouped tools |
+| **Tool model** | ~217 granular tools + `discover_tools` | ~50–60 grouped `browse_*` / `manage_*` tools |
+| **MR review** | 2-step batched diff | Varies |
+| **Node.js** | >=18 | Often >=24 |
+| **License** | MIT | Varies |
 
-Quick start: choose either Personal Access Token or OAuth2 setup below, install `@zereight/mcp-gitlab`, and use `zereight-mcp-gitlab` in your MCP client configuration.
+[Full comparison →](./docs/comparison/community-gitlab-mcp-a.md)
+
+Quick start: choose either Personal Access Token or OAuth2 setup below, install `@zereight/mcp-gitlab` (or `@zereight/gitlab-mcp`), and use `zereight-mcp-gitlab` in your MCP client configuration.
 
 ### Client Setup Guides
 
@@ -64,6 +82,7 @@ The server supports four authentication methods:
 - **Cursor**: see [Cursor Setup Guide](./docs/clients/cursor.md)
 - **Factory AI Droid / OpenClaw / OpenCode style clients**: see [JSON-Based MCP Clients Setup Guide](./docs/clients/json-clients.md)
 - **OAuth browser flow details**: see [OAuth2 Authentication Setup Guide](./docs/auth/oauth-setup.md)
+- **OAuth without a localhost callback** (SSO, remote shell, background clients): run `zereight-mcp-gitlab auth` (GitLab 17.9+ device flow; 17.2–17.8 need `oauth2_device_grant_flow`), then start the server with `GITLAB_USE_OAUTH=true`. See [standalone device-flow command](./docs/auth/oauth-setup.md#standalone-device-flow-auth-command).
 
 For the simplest local setup, start with a Personal Access Token. For browser-based local auth, use OAuth2. For remote or multi-user deployments, continue to the MCP OAuth and Remote Authorization sections later in this README.
 
@@ -74,15 +93,17 @@ brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
 brew install zereight/gitlab-mcp/zereight-mcp-gitlab
 ```
 
-Or with npm:
+Or with npm (either package name installs the same server):
 
 ```shell
 npm install -g @zereight/mcp-gitlab
+# or
+npm install -g @zereight/gitlab-mcp
 ```
 
 The examples use `zereight-mcp-gitlab`, a less collision-prone alias for the legacy `mcp-gitlab` binary. If your MCP client cannot find it, use the absolute path from `which zereight-mcp-gitlab`.
 
-No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.49`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
+No global install? Pin `npx` to the previous stable release (the version these docs recommend), for example `npx -y @zereight/mcp-gitlab@2.1.51`. If you always want the newest release, use `npx -y @zereight/mcp-gitlab@latest` instead. The server prints a notice to stderr on startup when a newer version is available (disable with `GITLAB_DISABLE_VERSION_CHECK=true`).
 
 #### Using CLI Arguments (for clients with env var issues)
 
@@ -113,8 +134,11 @@ Some MCP clients (like GitHub Copilot CLI) have issues with environment variable
 
 CLI arguments take precedence over environment variables.
 
+`zereight-mcp-gitlab auth` is a subcommand (not an MCP server flag). It runs GitLab device flow and exits. See [CLI Arguments](./docs/getting-started/cli-arguments.md#auth).
+
 > **Fine-grained tool filtering:** use `GITLAB_PERMISSION_MODE=modify` to allow create/update while
-> blocking every delete tool (including delete mutations through `execute_graphql`), or
+> blocking every delete tool (including delete mutations through `execute_graphql` and
+> `push_files` `delete`/`move` actions), or
 > `GITLAB_PERMISSION_MODE=readonly` for read-only access. You can also
 > enable toolset groups with `GITLAB_TOOLSETS=<group,…>`, allow-list individual tools with
 > `GITLAB_TOOLS=<tool,…>` (e.g. read-only groups plus a few specific write tools), and

package/README.zh-CN.md

@@ -1,5 +1,8 @@
 # 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)](vscode:mcp/install?%7B%22name%22%3A%22zereight.gitlab-mcp%22%2C%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%2C%22GITLAB_PERMISSION_MODE%22%3A%22full%22%7D%7D)
+
 [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md)
 
 📖 **[文档 →](https://zereight.github.io/gitlab-mcp/)** 设置指南、环境变量和完整工具参考请查看托管文档站点。
@@ -8,19 +11,35 @@
 
 ## @zereight/mcp-gitlab
 
-这是面向 AI 客户端的完整 GitLab MCP 服务器。可通过 stdio、SSE 和 Streamable HTTP 管理项目、合并请求、议题、流水线、Wiki、发布、里程碑等。
+**面向 AI 代理工作流优化的 GitLab MCP** — 可通过 stdio、SSE 和 Streamable HTTP 管理项目、合并请求、议题、流水线、Wiki、发布、里程碑等。
+
+同一服务器也以 [`@zereight/gitlab-mcp`](https://www.npmjs.com/package/@zereight/gitlab-mcp) 名称发布（便于 npm 搜索的别名）。
 
 支持 PAT、OAuth、只读模式、动态 API URL 和远程授权，可用于 VS Code、Claude、Cursor、Copilot 以及其他 MCP 客户端。
 
 ### 为什么使用这个 GitLab MCP？
 
-- 覆盖范围广：项目、仓库浏览、合并请求、议题、流水线、Wiki、发布、标签、里程碑等
-- 认证灵活：Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
-- 多种传输方式：本地客户端使用 stdio，旧客户端使用 SSE，现代远程部署使用 Streamable HTTP
-- 客户端设置友好：提供 Claude Code、Codex、Antigravity、OpenCode、Copilot、Cline、Roo Code、Cursor、Kilo Code 和 Amp Code 示例
-- 适合自托管：支持自定义 GitLab 实例、代理设置和动态 API URL 路由
+- **217 个工具 + `discover_tools`** — 从小型 toolset 开始，运行时按需激活类别
+- **MR 两步审查** — `list_merge_request_changed_files` → 批量 `get_merge_request_file_diff`
+- **内置 Agent Skill** — `skills/gitlab-mcp/` 工作流指南
+- **认证灵活** — Personal Access Token、本地 OAuth2 浏览器流程、MCP OAuth 代理、按请求远程授权
+- **多种传输方式** — 本地客户端使用 stdio，旧客户端使用 SSE，现代远程部署使用 Streamable HTTP
+- **客户端设置友好** — 提供 Claude Code、Codex、Antigravity、OpenCode、Copilot、Cline、Roo Code、Cursor、Kilo Code 和 Amp Code 示例
+- **适合自托管** — 支持自定义 GitLab 实例、代理设置和动态 API URL 路由
+
+### 对比摘要
 
-快速开始：在下面选择 Personal Access Token 或 OAuth2 设置，安装 `@zereight/mcp-gitlab`，并在 MCP 客户端配置中使用 `zereight-mcp-gitlab`。
+| | @zereight/mcp-gitlab | GitLab MCP A（社区 CQRS 型） |
+|---|----------------------|------------------------------|
+| **更适合** | AI 代理工作流 | 企业多实例 / 分组工具 |
+| **工具模型** | ~217 个细粒度工具 + `discover_tools` | ~50–60 个 `browse_*` / `manage_*` 分组工具 |
+| **MR 审查** | 两步批量 diff | 因服务器而异 |
+| **Node.js** | >=18 | 通常 >=24 |
+| **许可证** | MIT | 因服务器而异 |
+
+[完整对比 →](./docs/comparison/community-gitlab-mcp-a.md)
+
+快速开始：在下面选择 Personal Access Token 或 OAuth2 设置，安装 `@zereight/mcp-gitlab`（或 `@zereight/gitlab-mcp`），并在 MCP 客户端配置中使用 `zereight-mcp-gitlab`。
 
 ### 客户端设置指南
 
@@ -62,6 +81,7 @@
 - **Cursor**：[Cursor 设置指南](./docs/clients/cursor.md)
 - **Factory AI Droid / OpenClaw / OpenCode 风格客户端**：[基于 JSON 的 MCP 客户端设置指南](./docs/clients/json-clients.md)
 - **OAuth 浏览器流程详情**：[OAuth2 认证设置指南](./docs/auth/oauth-setup.md)
+- **无需 localhost callback 的 OAuth**（SSO、远程 shell、后台客户端）：先运行 `zereight-mcp-gitlab auth`（GitLab 17.9+ device flow；17.2–17.8 需 `oauth2_device_grant_flow`），再以 `GITLAB_USE_OAUTH=true` 启动服务器。参见[独立 device-flow 命令](./docs/auth/oauth-setup.md#standalone-device-flow-auth-command)。
 
 最简单的本地设置可以从 Personal Access Token 开始。基于浏览器的本地认证使用 OAuth2。远程或多用户部署请继续查看下面的 MCP OAuth 和远程授权部分。
 
@@ -72,15 +92,17 @@ brew tap zereight/gitlab-mcp https://github.com/zereight/gitlab-mcp
 brew install zereight/gitlab-mcp/zereight-mcp-gitlab
 ```
 
-也可以使用 npm 安装：
+也可以使用 npm 安装（两个包名安装的是同一服务器）：
 
 ```shell
 npm install -g @zereight/mcp-gitlab
+# 或
+npm install -g @zereight/gitlab-mcp
 ```
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.49`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.51`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -111,7 +133,10 @@ npm install -g @zereight/mcp-gitlab
 
 CLI 参数优先于环境变量。
 
-> **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新并阻止所有删除工具，
+`zereight-mcp-gitlab auth` 是子命令，不是 MCP 服务器参数。它运行 GitLab device flow 后退出。参见 [CLI 参数](./docs/getting-started/cli-arguments.md#auth)。
+
+> **细粒度工具过滤：**使用 `GITLAB_PERMISSION_MODE=modify` 允许创建/更新并阻止所有删除工具
+> （包括通过 `execute_graphql` 的删除 mutation 以及 `push_files` 的 `delete`/`move`），
 > 或使用 `GITLAB_PERMISSION_MODE=readonly` 只读运行。还可以用
 > `GITLAB_TOOLSETS=<group,…>` 启用工具分组，用 `GITLAB_TOOLS=<tool,…>` 白名单启用单个工具
 > （例如：只读分组 + 少数几个写工具），用 `GITLAB_DENIED_TOOLS_REGEX` 按正则屏蔽工具。

package/build/auth-cli.js

@@ -0,0 +1,95 @@
+import * as os from "os";
+import * as path from "path";
+import { GitLabOAuth } from "./oauth.js";
+import { createLogger } from "./utils/logger.js";
+const logger = createLogger("gitlab-mcp-auth");
+const DEFAULT_API_URL = "https://gitlab.com";
+const DEFAULT_REDIRECT_URI = "http://127.0.0.1:8888/callback";
+export const AUTH_CLI_HELP = `Usage: zereight-mcp-gitlab auth [options]
+
+Run GitLab OAuth Device Authorization Grant (GitLab 17.9+; 17.2–17.8 need
+oauth2_device_grant_flow) and store a token at the same path used by
+GITLAB_USE_OAUTH (default ~/.gitlab-mcp-token.json).
+
+This does not replace the local browser callback flow. After auth succeeds,
+start the MCP server with GITLAB_USE_OAUTH=true and GITLAB_OAUTH_CLIENT_ID.
+If you used --token-path, set GITLAB_OAUTH_TOKEN_PATH to the same path.
+
+Options:
+  --client-id <id>     OAuth application ID (or GITLAB_OAUTH_CLIENT_ID)
+  --api-url <url>      GitLab API URL (or GITLAB_API_URL). Default: https://gitlab.com
+  --token-path <path>  Token file path (or GITLAB_OAUTH_TOKEN_PATH)
+  -h, --help           Show this help
+`;
+function readFlag(argv, name) {
+    const equalsPrefix = `--${name}=`;
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith(equalsPrefix)) {
+            const value = arg.slice(equalsPrefix.length);
+            return value === "" ? undefined : value;
+        }
+        if (arg === `--${name}`) {
+            const next = argv[i + 1];
+            if (next && !next.startsWith("-")) {
+                return next;
+            }
+            return undefined;
+        }
+    }
+    return undefined;
+}
+function wantsHelp(argv) {
+    return argv.includes("--help") || argv.includes("-h");
+}
+function isReadOnlyMode(argv, env) {
+    const readOnly = readFlag(argv, "read-only") ?? env.GITLAB_READ_ONLY_MODE;
+    if (readOnly === "true") {
+        return true;
+    }
+    return (readFlag(argv, "permission-mode") ?? env.GITLAB_PERMISSION_MODE) === "readonly";
+}
+export function gitlabOriginFromApiUrl(apiUrl) {
+    return apiUrl.replace(/\/api\/v4\/?$/, "");
+}
+export async function runAuthCommandAsync(input = {}) {
+    const argv = input.argv ?? process.argv;
+    const env = input.env ?? process.env;
+    const stdout = input.stdout ?? process.stdout;
+    if (wantsHelp(argv)) {
+        stdout.write(AUTH_CLI_HELP);
+        return;
+    }
+    const clientId = readFlag(argv, "client-id") ?? env.GITLAB_OAUTH_CLIENT_ID;
+    if (!clientId) {
+        throw new Error("Missing OAuth client ID. Pass --client-id or set GITLAB_OAUTH_CLIENT_ID.");
+    }
+    const apiUrl = readFlag(argv, "api-url") ?? env.GITLAB_API_URL ?? DEFAULT_API_URL;
+    const tokenPath = readFlag(argv, "token-path") ??
+        env.GITLAB_OAUTH_TOKEN_PATH ??
+        path.join(os.homedir(), ".gitlab-mcp-token.json");
+    const gitlabUrl = gitlabOriginFromApiUrl(apiUrl);
+    const scopes = [isReadOnlyMode(argv, env) ? "read_api" : "api"];
+    const oauth = new GitLabOAuth({
+        clientId,
+        clientSecret: env.GITLAB_OAUTH_CLIENT_SECRET,
+        redirectUri: env.GITLAB_OAUTH_REDIRECT_URI || DEFAULT_REDIRECT_URI,
+        gitlabUrl,
+        scopes,
+        tokenStoragePath: tokenPath,
+    });
+    logger.info("Starting GitLab device authorization (no browser will be opened)");
+    await oauth.runDeviceFlowAsync({
+        fetchImpl: input.fetchImpl,
+        sleepAsync: input.sleepAsync,
+        onUserCode: info => {
+            const visitUrl = info.verificationUriComplete ?? info.verificationUri;
+            stdout.write(`Visit: ${visitUrl}\n`);
+            stdout.write(`Code:  ${info.userCode}\n`);
+            stdout.write("Waiting for authorization...\n");
+        },
+    });
+    stdout.write(`Token saved to ${tokenPath}\n`);
+    stdout.write("Start the MCP server with GITLAB_USE_OAUTH=true and the same GITLAB_OAUTH_CLIENT_ID.\n" +
+        "If you used --token-path, set GITLAB_OAUTH_TOKEN_PATH to that path as well.\n");
+}

package/build/cli-command.js

@@ -0,0 +1,33 @@
+const SCRIPT_PATH_PATTERN = /\.(cjs|mjs|js|cts|mts|ts)$/;
+const FLAGS_WITHOUT_VALUE = new Set(["--help", "-h"]);
+function isScriptPath(arg) {
+    return SCRIPT_PATH_PATTERN.test(arg);
+}
+/**
+ * Read the first positional CLI command (not a flag, not a script path).
+ * `tsx index.ts auth` and `node build/index.js auth` both resolve to `auth`.
+ * Space-separated option values such as `--api-url https://...` are skipped.
+ * Flags such as --token stay on the MCP server path.
+ */
+export function getPositionalCliCommand(argv) {
+    const args = argv.slice(2);
+    for (let i = 0; i < args.length; i++) {
+        const arg = args[i];
+        if (arg.startsWith("--") && arg.includes("=")) {
+            continue;
+        }
+        if (arg.startsWith("-")) {
+            if (!FLAGS_WITHOUT_VALUE.has(arg) &&
+                i + 1 < args.length &&
+                !args[i + 1].startsWith("-")) {
+                i += 1;
+            }
+            continue;
+        }
+        if (isScriptPath(arg)) {
+            continue;
+        }
+        return arg;
+    }
+    return undefined;
+}

package/build/index.js

@@ -75,6 +75,8 @@ import { CookieJar, parse as parseCookie } from "tough-cookie";
 import { URL } from "node:url";
 import { z } from "zod";
 import { initializeOAuthClient } from "./oauth.js";
+import { getPositionalCliCommand } from "./cli-command.js";
+import { runAuthCommandAsync } from "./auth-cli.js";
 import { createGitLabOAuthProvider } from "./oauth-proxy.js";
 import { mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
 import rateLimit, { ipKeyGenerator } from "express-rate-limit";
@@ -91,6 +93,7 @@ import { normalizeGitLabApiUrl } from "./utils/url.js";
 import { estimateMergeCommitCount, filterDiffsByPatterns, openSafeOutputWriteStream, readSafeExistingFile, summarizeWebhookEvents, } from "./utils/helpers.js";
 import { graphqlQueryContainsWriteOperation, graphqlQueryContainsDeleteOperation, } from "./utils/graphql-query.js";
 import { resolveNestedWikiUpdateTitle } from "./utils/wiki-title.js";
+import { encodeRepoFilePayloadContent, fileOperationsIncludeDeleteOrMove, toGitLabCommitActions, } from "./utils/gitlab-commit-actions.js";
 import { redactSensitiveGitLabFields } from "./utils/redact-sensitive.js";
 import { checkForNewVersion } from "./utils/version-check.js";
 import { assertGitLabVersionAtLeast } from "./utils/gitlab-version-gate.js";
@@ -1100,7 +1103,8 @@ if (GITLAB_MCP_OAUTH) {
     }
     logger.info("MCP OAuth enabled: GitLab OAuth proxy active (Private-Token/JOB-TOKEN headers bypass OAuth)");
 }
-if (!REMOTE_AUTHORIZATION &&
+if (getPositionalCliCommand(process.argv) !== "auth" &&
+    !REMOTE_AUTHORIZATION &&
     !GITLAB_MCP_OAUTH &&
     !USE_OAUTH &&
     !GITLAB_PERSONAL_ACCESS_TOKEN &&
@@ -3291,12 +3295,6 @@ async function updateMergeRequestNote(projectId, mergeRequestIid, noteId, body)
     const data = await response.json();
     return GitLabDiscussionNoteSchema.parse(data);
 }
-function encodeRepoFilePayloadContent(content) {
-    if (GITLAB_REPO_FILE_ENCODING === "base64") {
-        return Buffer.from(content).toString("base64");
-    }
-    return content;
-}
 /**
  * Create or update a file in a GitLab project
  * 파일 생성 또는 업데이트
@@ -3309,15 +3307,18 @@ function encodeRepoFilePayloadContent(content) {
  * @param {string} [previousPath] - The previous path of the file in case of rename
  * @returns {Promise<GitLabCreateUpdateFileResponse>} The file update response
  */
-async function createOrUpdateFile(projectId, filePath, content, commitMessage, branch, previousPath, last_commit_id, commit_id) {
+async function createOrUpdateFile(projectId, filePath, content, commitMessage, branch, previousPath, last_commit_id, commit_id, encoding) {
     projectId = decodeURIComponent(projectId); // Decode project ID
     const encodedPath = encodeURIComponent(filePath);
     const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/repository/files/${encodedPath}`);
+    const resolvedEncoding = encoding ?? GITLAB_REPO_FILE_ENCODING;
     const body = {
         branch,
-        content: encodeRepoFilePayloadContent(content),
+        content: encoding !== undefined
+            ? content
+            : encodeRepoFilePayloadContent(content, GITLAB_REPO_FILE_ENCODING),
         commit_message: commitMessage,
-        encoding: GITLAB_REPO_FILE_ENCODING,
+        encoding: resolvedEncoding,
         ...(previousPath ? { previous_path: previousPath } : {}),
     };
     // Check if file exists
@@ -3387,12 +3388,7 @@ async function createCommit(projectId, message, branch, actions) {
         body: JSON.stringify({
             branch,
             commit_message: message,
-            actions: actions.map(action => ({
-                action: "create",
-                file_path: action.path,
-                content: encodeRepoFilePayloadContent(action.content),
-                encoding: GITLAB_REPO_FILE_ENCODING,
-            })),
+            actions: toGitLabCommitActions(actions, GITLAB_REPO_FILE_ENCODING),
         }),
     });
     if (response.status === 400) {
@@ -7280,14 +7276,24 @@ async function handleToolCall(params) {
             }
             case "create_or_update_file": {
                 const args = CreateOrUpdateFileSchema.parse(params.arguments);
-                const result = await createOrUpdateFile(args.project_id, args.file_path, args.content, args.commit_message, args.branch, args.previous_path, args.last_commit_id, args.commit_id);
+                const result = await createOrUpdateFile(args.project_id, args.file_path, args.content, args.commit_message, args.branch, args.previous_path, args.last_commit_id, args.commit_id, args.encoding);
                 return {
                     content: [{ type: "text", text: JSON.stringify(result) }],
                 };
             }
             case "push_files": {
                 const args = PushFilesSchema.parse(params.arguments);
-                const result = await createCommit(args.project_id, args.commit_message, args.branch, args.files.map(f => ({ path: f.file_path, content: f.content })));
+                if (GITLAB_PERMISSION_MODE === "modify" &&
+                    fileOperationsIncludeDeleteOrMove(args.files)) {
+                    throw new Error("push_files does not allow delete or move actions in modify mode");
+                }
+                const result = await createCommit(args.project_id, args.commit_message, args.branch, args.files.map(f => ({
+                    path: f.file_path,
+                    content: f.content,
+                    action: f.action,
+                    encoding: f.encoding,
+                    previous_path: f.previous_path,
+                })));
                 return {
                     content: [{ type: "text", text: JSON.stringify(result) }],
                 };
@@ -10795,8 +10801,22 @@ async function runServer() {
         process.exit(1);
     }
 }
-// 下記の２行を追記
-runServer().catch(error => {
+async function main() {
+    if (getPositionalCliCommand(process.argv) === "auth") {
+        try {
+            await runAuthCommandAsync();
+            process.exit(0);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`${message}\n`);
+            logger.error({ err: error }, "auth command failed");
+            process.exit(1);
+        }
+    }
+    await runServer();
+}
+main().catch(error => {
     logger.fatal({ err: error }, "Fatal error in main()");
     process.exit(1);
 });