@zereight/mcp-gitlab 2.1.49 → 2.1.51

package/README.ko.md

@@ -62,6 +62,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 및 원격 인증 섹션을 참고하세요.
 
@@ -80,7 +81,7 @@ npm install -g @zereight/mcp-gitlab
 
 예시는 기존 `mcp-gitlab`보다 충돌 가능성이 낮은 `zereight-mcp-gitlab` 별칭을 사용합니다. MCP 클라이언트가 찾지 못하면 `which zereight-mcp-gitlab`의 절대 경로를 사용하세요.
 
-전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.48`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
+전역 설치를 쓰지 않으려면 `npx -y @zereight/mcp-gitlab@2.1.49`처럼 직전 안정 버전(문서가 권장하는 버전)으로 고정하세요. 항상 최신 버전을 원하면 `npx -y @zereight/mcp-gitlab@latest`를 사용하세요. 새 버전이 나오면 서버가 시작 시 stderr로 알려줍니다(`GITLAB_DISABLE_VERSION_CHECK=true`로 비활성화 가능).
 
 #### CLI 인자 사용하기(환경 변수 문제가 있는 클라이언트용)
 
@@ -111,8 +112,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,6 +1,6 @@
 # GitLab MCP Server
 
-[![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-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)
 
@@ -64,6 +64,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.
 
@@ -82,7 +83,7 @@ npm install -g @zereight/mcp-gitlab
 
 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.48`. 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.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`).
 
 #### Using CLI Arguments (for clients with env var issues)
 
@@ -113,8 +114,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

@@ -62,6 +62,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 和远程授权部分。
 
@@ -80,7 +81,7 @@ npm install -g @zereight/mcp-gitlab
 
 示例使用 `zereight-mcp-gitlab`，这是比旧的 `mcp-gitlab` 更不容易冲突的别名。如果 MCP 客户端找不到它，请使用 `which zereight-mcp-gitlab` 输出的绝对路径。
 
-如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.48`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
+如果不想全局安装，请将 `npx` 固定到上一个稳定版本（即文档推荐的版本），例如 `npx -y @zereight/mcp-gitlab@2.1.49`。如果始终想使用最新版本，请改用 `npx -y @zereight/mcp-gitlab@latest`。有新版本发布时，服务器会在启动时通过 stderr 提示（可用 `GITLAB_DISABLE_VERSION_CHECK=true` 关闭）。
 
 #### 使用 CLI 参数（适用于环境变量有问题的客户端）
 
@@ -111,7 +112,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);
 });

package/build/oauth-device-flow.js

@@ -0,0 +1,158 @@
+import { z } from "zod";
+const DEFAULT_POLL_INTERVAL_SECONDS = 5;
+const SLOW_DOWN_INCREMENT_SECONDS = 5;
+const DEVICE_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:device_code";
+const DeviceAuthorizationSchema = z.object({
+    device_code: z.string().min(1),
+    user_code: z.string().min(1),
+    verification_uri: z.string().min(1),
+    verification_uri_complete: z.string().min(1).optional(),
+    expires_in: z.number().positive(),
+    interval: z.number().nonnegative().optional(),
+});
+const DeviceTokenErrorSchema = z.object({
+    error: z.string().min(1),
+    error_description: z.string().optional(),
+});
+const TokenResponseSchema = z.object({
+    access_token: z.string().min(1),
+    refresh_token: z.string().min(1).optional(),
+    expires_in: z.number().positive().optional(),
+    token_type: z.string().min(1).optional(),
+});
+function delayAsync(ms) {
+    return new Promise(resolve => {
+        setTimeout(resolve, ms);
+    });
+}
+async function readJsonBodyAsync(response) {
+    const text = await response.text();
+    if (!text) {
+        return undefined;
+    }
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+}
+function gitlabOrigin(gitlabUrl) {
+    return gitlabUrl.replace(/\/$/, "");
+}
+function formatOauthError(errorCode, description) {
+    if (description) {
+        return `${errorCode}: ${description}`;
+    }
+    return errorCode;
+}
+function unsupportedDeviceFlowMessage(status) {
+    return (`Device authorization is not available on this GitLab instance (HTTP ${status}). ` +
+        "GitLab 17.9+ is required for `zereight-mcp-gitlab auth` " +
+        "(17.2–17.8 need oauth2_device_grant_flow). " +
+        "Use a Personal Access Token (GITLAB_PERSONAL_ACCESS_TOKEN) instead.");
+}
+/**
+ * RFC 8628 Device Authorization Grant against GitLab (17.9+; 17.2–17.8 with
+ * oauth2_device_grant_flow).
+ * Does not open a browser. Never logs device_code or tokens.
+ */
+export async function runDeviceAuthorizationGrantAsync(input) {
+    const fetchImpl = input.fetchImpl ?? globalThis.fetch;
+    const sleepAsync = input.sleepAsync ?? delayAsync;
+    const now = input.now ?? Date.now;
+    const origin = gitlabOrigin(input.gitlabUrl);
+    const authorizeParams = new URLSearchParams({
+        client_id: input.clientId,
+        scope: input.scopes.join(" "),
+    });
+    const authorizeResponse = await fetchImpl(`${origin}/oauth/authorize_device`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/x-www-form-urlencoded",
+        },
+        body: authorizeParams.toString(),
+    });
+    if (authorizeResponse.status === 404) {
+        throw new Error(unsupportedDeviceFlowMessage(404));
+    }
+    const authorizeBody = await readJsonBodyAsync(authorizeResponse);
+    if (!authorizeResponse.ok) {
+        const parsedError = DeviceTokenErrorSchema.safeParse(authorizeBody);
+        if (parsedError.success) {
+            throw new Error(`Device authorization request failed: ${formatOauthError(parsedError.data.error, parsedError.data.error_description)}`);
+        }
+        if (authorizeResponse.status >= 400 && authorizeResponse.status < 500) {
+            throw new Error(unsupportedDeviceFlowMessage(authorizeResponse.status));
+        }
+        throw new Error(`Device authorization request failed (HTTP ${authorizeResponse.status}).`);
+    }
+    const authorization = DeviceAuthorizationSchema.safeParse(authorizeBody);
+    if (!authorization.success) {
+        throw new Error("Device authorization endpoint returned an invalid response.");
+    }
+    const { device_code: deviceCode, user_code: userCode, verification_uri: verificationUri, verification_uri_complete: verificationUriComplete, expires_in: expiresIn, interval: rawInterval, } = authorization.data;
+    input.onUserCode?.({
+        userCode,
+        verificationUri,
+        verificationUriComplete,
+    });
+    let intervalSeconds = rawInterval === undefined || rawInterval <= 0
+        ? DEFAULT_POLL_INTERVAL_SECONDS
+        : rawInterval;
+    const deadline = now() + expiresIn * 1000;
+    const tokenUrl = `${origin}/oauth/token`;
+    while (now() < deadline) {
+        const tokenParams = new URLSearchParams({
+            grant_type: DEVICE_GRANT_TYPE,
+            device_code: deviceCode,
+            client_id: input.clientId,
+        });
+        if (input.clientSecret) {
+            tokenParams.set("client_secret", input.clientSecret);
+        }
+        const tokenResponse = await fetchImpl(tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: tokenParams.toString(),
+        });
+        const tokenBody = await readJsonBodyAsync(tokenResponse);
+        if (tokenResponse.ok) {
+            const token = TokenResponseSchema.safeParse(tokenBody);
+            if (!token.success) {
+                throw new Error("Token endpoint returned an invalid response.");
+            }
+            return {
+                access_token: token.data.access_token,
+                refresh_token: token.data.refresh_token,
+                expires_in: token.data.expires_in,
+                created_at: now(),
+                token_type: token.data.token_type ?? "Bearer",
+            };
+        }
+        const tokenError = DeviceTokenErrorSchema.safeParse(tokenBody);
+        const errorCode = tokenError.success ? tokenError.data.error : undefined;
+        if (errorCode === "authorization_pending") {
+            await sleepAsync(intervalSeconds * 1000);
+            continue;
+        }
+        if (errorCode === "slow_down") {
+            intervalSeconds += SLOW_DOWN_INCREMENT_SECONDS;
+            await sleepAsync(intervalSeconds * 1000);
+            continue;
+        }
+        if (errorCode === "expired_token") {
+            throw new Error("Device code expired before authorization completed. Run `auth` again.");
+        }
+        if (errorCode === "access_denied") {
+            throw new Error("Authorization was denied in the browser.");
+        }
+        if (tokenError.success) {
+            throw new Error(`Device token request failed: ${formatOauthError(tokenError.data.error, tokenError.data.error_description)}`);
+        }
+        throw new Error(`Device token request failed (HTTP ${tokenResponse.status}).`);
+    }
+    throw new Error("Device code expired before authorization completed. Run `auth` again.");
+}

package/build/oauth.js

@@ -10,6 +10,7 @@ import { promisify } from "util";
 import open from "open";
 import pkceChallenge from "pkce-challenge";
 import { createLogger } from "./utils/logger.js";
+import { runDeviceAuthorizationGrantAsync } from "./oauth-device-flow.js";
 const logger = createLogger("gitlab-mcp-oauth");
 const execFileAsync = promisify(execFile);
 function escapeHtml(str) {
@@ -566,6 +567,25 @@ export class GitLabOAuth {
         }
         return !this.isTokenExpired(tokenData);
     }
+    /**
+     * Device Authorization Grant (GitLab 17.9+; 17.2–17.8 need oauth2_device_grant_flow).
+     * Does not open a browser.
+     * Stores the token with the same file format as the localhost callback flow.
+     */
+    async runDeviceFlowAsync(options) {
+        const tokenData = await runDeviceAuthorizationGrantAsync({
+            gitlabUrl: this.config.gitlabUrl,
+            clientId: this.config.clientId,
+            clientSecret: this.config.clientSecret,
+            scopes: this.config.scopes,
+            fetchImpl: options?.fetchImpl,
+            sleepAsync: options?.sleepAsync,
+            onUserCode: options?.onUserCode,
+            now: options?.now,
+        });
+        this.saveToken(tokenData);
+        return tokenData;
+    }
 }
 /**
  * Create and initialize a GitLabOAuth client.

package/build/schemas.js

@@ -830,11 +830,33 @@ export const GitLabContentSchema = z.union([
     GitLabFileContentSchema,
     z.array(GitLabDirectoryContentSchema),
 ]);
+function refineCommitFileAction(data, ctx) {
+    const action = data.action ?? "create";
+    if ((action === "create" || action === "update") && data.content === undefined) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: `content is required when action is '${action}'`,
+            path: ["content"],
+        });
+    }
+    if (action === "move" && (data.previous_path === undefined || data.previous_path.length === 0)) {
+        ctx.addIssue({
+            code: z.ZodIssueCode.custom,
+            message: "previous_path is required when action is 'move'",
+            path: ["previous_path"],
+        });
+    }
+}
 // Operation schemas
-export const FileOperationSchema = z.object({
+export const FileOperationSchema = z
+    .object({
     path: z.string(),
-    content: z.string(),
-});
+    content: z.string().optional(),
+    action: z.enum(["create", "update", "delete", "move"]).optional(),
+    encoding: z.enum(["text", "base64"]).optional(),
+    previous_path: z.string().optional(),
+})
+    .superRefine(refineCommitFileAction);
 // Tree and commit schemas
 export const GitLabTreeItemSchema = z.object({
     id: z.string(),
@@ -1160,6 +1182,7 @@ export const GitLabMergeRequestSchema = z.object({
     updated_at: z.string(),
     merged_at: z.string().nullable(),
     closed_at: z.string().nullable(),
+    sha: z.string().optional().describe("SHA of the head commit in the source branch"),
     merge_commit_sha: z.string().nullable(),
     merge_user: GitLabUserSchema.nullable()
         .optional()
@@ -1414,6 +1437,10 @@ export const CreateOrUpdateFileSchema = ProjectParamsSchema.extend({
     previous_path: z.string().optional().describe("Path of the file to move/rename"),
     last_commit_id: z.string().optional().describe("Last known file commit ID"),
     commit_id: z.string().optional().describe("Current file commit ID (for update operations)"),
+    encoding: z
+        .enum(["text", "base64"])
+        .optional()
+        .describe("Content encoding. Use 'base64' for binary files (content must already be base64-encoded). When omitted, GITLAB_REPO_FILE_ENCODING applies."),
 });
 export const SearchRepositoriesSchema = z
     .object({
@@ -1480,11 +1507,28 @@ export const GetFileContentsSchema = z
 export const PushFilesSchema = ProjectParamsSchema.extend({
     branch: z.string().describe("Branch to push to"),
     files: z
-        .array(z.object({
-        file_path: z.string().describe("Path where to create the file"),
-        content: z.string().describe("Content of the file"),
-    }))
-        .describe("Array of files to push"),
+        .array(z
+        .object({
+        file_path: z.string().describe("Path of the file in the repo"),
+        content: z
+            .string()
+            .optional()
+            .describe("File content. Required for create and update. Omit for delete, or for a move that should keep the original content. Base64-encoded when encoding is 'base64'."),
+        action: z
+            .enum(["create", "update", "delete", "move"])
+            .optional()
+            .describe("Commit action for this file. Defaults to 'create'."),
+        encoding: z
+            .enum(["text", "base64"])
+            .optional()
+            .describe("Use 'base64' for binary files (content must already be base64-encoded). When omitted, GITLAB_REPO_FILE_ENCODING applies."),
+        previous_path: z
+            .string()
+            .optional()
+            .describe("Previous path of the file. Required when action is 'move'."),
+    })
+        .superRefine(refineCommitFileAction))
+        .describe("Array of files to push. Each entry defaults to action 'create'. Per-file fields: action (create/update/delete/move), encoding (text/base64; omitted uses GITLAB_REPO_FILE_ENCODING), previous_path (required for move). Content is required for create and update; omit content for delete, or for a move that should keep the original file. GITLAB_PERMISSION_MODE=modify rejects delete and move."),
     commit_message: z.string().describe("Commit message"),
 });
 export const CreateIssueSchema = ProjectParamsSchema.extend({
@@ -1773,6 +1817,10 @@ export const UpdateMergeRequestSchema = MergeRequestParamsSchema.extend({
 });
 export const MergeMergeRequestSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.coerce.string().optional().describe("The IID of a merge request"),
+    sha: z
+        .string()
+        .optional()
+        .describe("SHA of the source-branch HEAD from get_merge_request (`sha` or `diff_refs.head_sha`). If provided, GitLab merges only when HEAD still matches. GitLab 19.2+ groups may require this (Require a commit SHA on the merge requests API)."),
     auto_merge: z.coerce
         .boolean()
         .optional()
@@ -3334,8 +3382,8 @@ export const GitLabArtifactEntrySchema = z.object({
     name: z.string(),
     path: z.string(),
     type: z.enum(["file", "directory"]),
-    size: z.coerce.number().optional(),
-    mode: z.string().optional(),
+    size: z.coerce.number().nullish(),
+    mode: z.string().nullish(),
 });
 export const DownloadJobArtifactsSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),