@zereight/mcp-gitlab 2.0.9 → 2.0.13

package/README.md

@@ -16,7 +16,58 @@ GitLab MCP(Model Context Protocol) Server. **Includes bug fixes and improvements
 
 When using with the Claude App, you need to set up your API key and URLs directly.
 
-#### npx
+#### Authentication Methods
+
+The server supports two authentication methods:
+
+1. **Personal Access Token** (traditional method)
+2. **OAuth2** (recommended for better security)
+
+#### Using OAuth2 Authentication
+
+OAuth2 provides a more secure authentication flow using browser-based authentication. When enabled, the server will:
+1. Open your browser to GitLab's authorization page
+2. Wait for you to approve the access
+3. Store the token securely for future use
+4. Automatically refresh the token when it expires
+
+For detailed OAuth2 setup instructions, see [OAuth Setup Guide](./docs/oauth-setup.md).
+
+Quick setup - first create a GitLab OAuth application:
+
+1. Go to your GitLab instance: `Settings` → `Applications`
+2. Create a new application with:
+   - **Name**: `GitLab MCP Server` (or any name you prefer)
+   - **Redirect URI**: `http://127.0.0.1:8888/callback`
+   - **Scopes**: Select `api` (provides complete read/write access to the API)
+3. Copy the **Application ID** (this is your Client ID)
+
+Then configure the MCP server with OAuth:
+
+```json
+{
+  "mcpServers": {
+    "gitlab": {
+      "command": "npx",
+      "args": ["-y", "@zereight/mcp-gitlab"],
+      "env": {
+        "GITLAB_USE_OAUTH": "true",
+        "GITLAB_OAUTH_CLIENT_ID": "your_oauth_client_id",
+        "GITLAB_OAUTH_REDIRECT_URI": "http://127.0.0.1:8888/callback",
+        "GITLAB_API_URL": "your_gitlab_api_url",
+        "GITLAB_PROJECT_ID": "your_project_id", // Optional: default project
+        "GITLAB_ALLOWED_PROJECT_IDS": "", // Optional: comma-separated list of allowed project IDs
+        "GITLAB_READ_ONLY_MODE": "false",
+        "USE_GITLAB_WIKI": "false", // use wiki api?
+        "USE_MILESTONE": "false", // use milestone api?
+        "USE_PIPELINE": "false" // use pipeline api?
+      }
+    }
+  }
+}
+```
+
+#### Using Personal Access Token (traditional)
 
 ```json
 {
@@ -185,7 +236,11 @@ docker run -i --rm \
 
 #### Authentication Configuration
 
-- `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token. **Required in standard mode**; not used when `REMOTE_AUTHORIZATION=true`.
+- `GITLAB_PERSONAL_ACCESS_TOKEN`: Your GitLab personal access token. **Required in standard mode**; not used when `REMOTE_AUTHORIZATION=true` or when using OAuth.
+- `GITLAB_USE_OAUTH`: Set to `true` to enable OAuth2 authentication instead of personal access token.
+- `GITLAB_OAUTH_CLIENT_ID`: The Client ID from your GitLab OAuth application. Required when using OAuth.
+- `GITLAB_OAUTH_REDIRECT_URI`: The OAuth callback URL. Default: `http://127.0.0.1:8888/callback`
+- `GITLAB_OAUTH_TOKEN_PATH`: Custom path to store the OAuth token. Default: `~/.gitlab-mcp-token.json`
 - `REMOTE_AUTHORIZATION`: When set to 'true', enables remote per-session authorization via HTTP headers. In this mode:
   - The server accepts GitLab PAT tokens from HTTP headers (`Authorization: Bearer <token>` or `Private-Token: <token>`) on a per-session basis
   - `GITLAB_PERSONAL_ACCESS_TOKEN` environment variable is **not required** and ignored
@@ -195,7 +250,7 @@ docker run -i --rm \
   - Tokens are stored per session and automatically cleaned up when sessions close or timeout
 - `SESSION_TIMEOUT_SECONDS`: Session auth token timeout in seconds. Default: `3600` (1 hour). Valid range: 1-86400 seconds (recommended: 60+). After this period of inactivity, the auth token is removed but the transport session remains active. The client must provide auth headers again on the next request. Only applies when `REMOTE_AUTHORIZATION=true`.
 
-#### Server Configuration
+#### General Configuration
 
 - `GITLAB_API_URL`: Your GitLab API URL. (Default: `https://gitlab.com/api/v4`)
 - `GITLAB_PROJECT_ID`: Default project ID. If set, Overwrite this value when making an API request.

package/build/index.js

@@ -17,6 +17,7 @@ import { CookieJar, parse as parseCookie } from "tough-cookie";
 import { fileURLToPath } from "url";
 import { z } from "zod";
 import { zodToJsonSchema } from "zod-to-json-schema";
+import { initializeOAuth } from "./oauth.js";
 // Add type imports for proxy agents
 import { Agent } from "http";
 import { Agent as HttpsAgent } from "https";
@@ -130,10 +131,11 @@ function validateConfiguration() {
     }
     // Validate auth configuration
     const remoteAuth = process.env.REMOTE_AUTHORIZATION === "true";
+    const useOAuth = process.env.GITLAB_USE_OAUTH === "true";
     const hasToken = !!process.env.GITLAB_PERSONAL_ACCESS_TOKEN;
     const hasCookie = !!process.env.GITLAB_AUTH_COOKIE_PATH;
-    if (!remoteAuth && !hasToken && !hasCookie) {
-        errors.push('Either GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_AUTH_COOKIE_PATH, or REMOTE_AUTHORIZATION=true must be set');
+    if (!remoteAuth && !useOAuth && !hasToken && !hasCookie) {
+        errors.push('Either GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_AUTH_COOKIE_PATH, GITLAB_USE_OAUTH=true, or REMOTE_AUTHORIZATION=true must be set');
     }
     if (errors.length > 0) {
         logger.error('Configuration validation failed:');
@@ -143,7 +145,9 @@ function validateConfiguration() {
     logger.info('Configuration validation passed');
 }
 const GITLAB_PERSONAL_ACCESS_TOKEN = process.env.GITLAB_PERSONAL_ACCESS_TOKEN;
+let OAUTH_ACCESS_TOKEN = null;
 const GITLAB_AUTH_COOKIE_PATH = process.env.GITLAB_AUTH_COOKIE_PATH;
+const USE_OAUTH = process.env.GITLAB_USE_OAUTH === "true";
 const IS_OLD = process.env.GITLAB_IS_OLD === "true";
 const GITLAB_READ_ONLY_MODE = process.env.GITLAB_READ_ONLY_MODE === "true";
 const GITLAB_DENIED_TOOLS_REGEX = process.env.GITLAB_DENIED_TOOLS_REGEX ? new RegExp(process.env.GITLAB_DENIED_TOOLS_REGEX) : undefined;
@@ -281,12 +285,13 @@ function buildAuthHeaders() {
         }
         return {}; // No auth headers if no session context
     }
-    // Standard mode: use environment token
-    if (IS_OLD && GITLAB_PERSONAL_ACCESS_TOKEN) {
-        return { 'Private-Token': String(GITLAB_PERSONAL_ACCESS_TOKEN) };
+    // Standard mode: prioritize OAuth token, then fall back to environment token
+    const token = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN;
+    if (IS_OLD && token) {
+        return { 'Private-Token': String(token) };
     }
-    if (GITLAB_PERSONAL_ACCESS_TOKEN) {
-        return { Authorization: `Bearer ${GITLAB_PERSONAL_ACCESS_TOKEN}` };
+    if (token) {
+        return { Authorization: `Bearer ${token}` };
     }
     return {};
 }
@@ -948,12 +953,11 @@ if (REMOTE_AUTHORIZATION) {
     }
     logger.info("Remote authorization enabled: tokens will be read from HTTP headers");
 }
-else {
-    // Standard mode: token must be in environment
-    if (!GITLAB_PERSONAL_ACCESS_TOKEN) {
-        logger.error("GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not set");
-        process.exit(1);
-    }
+else if (!USE_OAUTH && !GITLAB_PERSONAL_ACCESS_TOKEN && !GITLAB_AUTH_COOKIE_PATH) {
+    // Standard mode: token must be in environment (unless using OAuth)
+    logger.error("GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not set");
+    logger.info("Either set GITLAB_PERSONAL_ACCESS_TOKEN or enable OAuth with GITLAB_USE_OAUTH=true");
+    process.exit(1);
 }
 /**
  * Utility function for handling GitLab API errors
@@ -5199,6 +5203,20 @@ async function runServer() {
     try {
         // Validate configuration before starting server
         validateConfiguration();
+        // Initialize OAuth token if OAuth is enabled
+        if (USE_OAUTH) {
+            logger.info("Using OAuth authentication...");
+            try {
+                const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4$/, "");
+                OAUTH_ACCESS_TOKEN = await initializeOAuth(gitlabBaseUrl);
+                logger.info("OAuth authentication successful");
+                // Note: Headers are automatically generated by buildAuthHeaders() using OAUTH_ACCESS_TOKEN
+            }
+            catch (error) {
+                logger.error("OAuth authentication failed:", error);
+                process.exit(1);
+            }
+        }
         const transportMode = determineTransportMode();
         await initializeServerByTransportMode(transportMode);
     }

package/build/oauth.js

@@ -0,0 +1,518 @@
+import * as fs from "fs";
+import * as path from "path";
+import * as http from "http";
+import * as net from "net";
+import * as url from "url";
+import open from "open";
+import pkceChallenge from "pkce-challenge";
+import { pino } from "pino";
+const logger = pino({
+    name: "gitlab-mcp-oauth",
+    level: process.env.LOG_LEVEL || "info",
+});
+// Track pending auth requests across multiple MCP instances
+const pendingAuthRequests = new Map();
+/**
+ * Check if a port is already in use
+ */
+async function isPortInUse(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once("error", (err) => {
+            if (err.code === "EADDRINUSE") {
+                resolve(true);
+            }
+            else {
+                resolve(false);
+            }
+        });
+        server.once("listening", () => {
+            server.close();
+            resolve(false);
+        });
+        server.listen(port, "127.0.0.1");
+    });
+}
+/**
+ * Request authentication from an existing OAuth server
+ */
+async function requestAuthFromExistingServer(port, requestId) {
+    return new Promise((resolve, reject) => {
+        const options = {
+            hostname: "127.0.0.1",
+            port: port,
+            path: `/auth-request?requestId=${requestId}`,
+            method: "GET",
+        };
+        const req = http.request(options, (res) => {
+            let data = "";
+            res.on("data", (chunk) => {
+                data += chunk;
+            });
+            res.on("end", () => {
+                if (res.statusCode === 200) {
+                    try {
+                        const tokenData = JSON.parse(data);
+                        resolve(tokenData);
+                    }
+                    catch (error) {
+                        reject(new Error(`Failed to parse token data: ${error}`));
+                    }
+                }
+                else {
+                    reject(new Error(`Auth request failed with status ${res.statusCode}: ${data}`));
+                }
+            });
+        });
+        req.on("error", (error) => {
+            reject(new Error(`Failed to connect to existing OAuth server: ${error.message}`));
+        });
+        req.setTimeout(5 * 60 * 1000, () => {
+            req.destroy();
+            reject(new Error("Auth request timed out"));
+        });
+        req.end();
+    });
+}
+export class GitLabOAuth {
+    config;
+    tokenStoragePath;
+    codeVerifier;
+    codeChallenge;
+    constructor(config) {
+        this.config = config;
+        this.tokenStoragePath =
+            config.tokenStoragePath ||
+                path.join(process.env.HOME || "", ".gitlab-mcp-token.json");
+    }
+    /**
+     * Get the authorization URL for OAuth flow
+     */
+    async getAuthorizationUrl(state) {
+        const challenge = await pkceChallenge();
+        this.codeVerifier = challenge.code_verifier;
+        this.codeChallenge = challenge.code_challenge;
+        const params = new URLSearchParams();
+        params.append("client_id", this.config.clientId);
+        params.append("redirect_uri", this.config.redirectUri);
+        params.append("response_type", "code");
+        params.append("state", state);
+        params.append("scope", this.config.scopes.join(" "));
+        if (this.codeChallenge) {
+            params.append("code_challenge", this.codeChallenge);
+            params.append("code_challenge_method", "S256");
+        }
+        return `${this.config.gitlabUrl}/oauth/authorize?${params.toString()}`;
+    }
+    /**
+     * Exchange authorization code for access token
+     */
+    async exchangeCodeForToken(code) {
+        if (!this.codeVerifier) {
+            throw new Error("Code verifier not found. Authorization flow not started.");
+        }
+        const tokenUrl = `${this.config.gitlabUrl}/oauth/token`;
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            code: code,
+            grant_type: "authorization_code",
+            redirect_uri: this.config.redirectUri,
+            code_verifier: this.codeVerifier,
+        });
+        const response = await fetch(tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token exchange failed: ${response.status} ${errorText}`);
+        }
+        const data = await response.json();
+        return {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token,
+            expires_in: data.expires_in,
+            created_at: Date.now(),
+            token_type: data.token_type,
+        };
+    }
+    /**
+     * Refresh the access token using the refresh token
+     */
+    async refreshAccessToken(refreshToken) {
+        const tokenUrl = `${this.config.gitlabUrl}/oauth/token`;
+        const params = new URLSearchParams({
+            client_id: this.config.clientId,
+            refresh_token: refreshToken,
+            grant_type: "refresh_token",
+            redirect_uri: this.config.redirectUri,
+        });
+        const response = await fetch(tokenUrl, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/x-www-form-urlencoded",
+            },
+            body: params.toString(),
+        });
+        if (!response.ok) {
+            const errorText = await response.text();
+            throw new Error(`Token refresh failed: ${response.status} ${errorText}`);
+        }
+        const data = await response.json();
+        return {
+            access_token: data.access_token,
+            refresh_token: data.refresh_token || refreshToken,
+            expires_in: data.expires_in,
+            created_at: Date.now(),
+            token_type: data.token_type,
+        };
+    }
+    /**
+     * Save token data to storage
+     */
+    saveToken(tokenData) {
+        try {
+            fs.writeFileSync(this.tokenStoragePath, JSON.stringify(tokenData, null, 2), { mode: 0o600 } // Restrict access to owner only
+            );
+            logger.info(`Token saved to ${this.tokenStoragePath}`);
+        }
+        catch (error) {
+            logger.error("Failed to save token:", error);
+            throw error;
+        }
+    }
+    /**
+     * Load token data from storage
+     */
+    loadToken() {
+        try {
+            if (!fs.existsSync(this.tokenStoragePath)) {
+                return null;
+            }
+            const data = fs.readFileSync(this.tokenStoragePath, "utf8");
+            return JSON.parse(data);
+        }
+        catch (error) {
+            logger.error("Failed to load token:", error);
+            return null;
+        }
+    }
+    /**
+     * Check if the token is expired
+     */
+    isTokenExpired(tokenData) {
+        if (!tokenData.expires_in) {
+            return false; // If no expiry, assume it's still valid
+        }
+        const expiryTime = tokenData.created_at + tokenData.expires_in * 1000;
+        // Add 5 minute buffer to refresh before actual expiry
+        return Date.now() >= expiryTime - 5 * 60 * 1000;
+    }
+    /**
+     * Start OAuth flow and wait for callback
+     * Uses a shared server if port is already in use
+     */
+    async startOAuthFlow() {
+        const callbackPort = parseInt(new URL(this.config.redirectUri).port || "8888");
+        const requestId = Math.random().toString(36).substring(7);
+        // Check if port is already in use
+        const portInUse = await isPortInUse(callbackPort);
+        if (portInUse) {
+            // Port is in use, try to connect to existing server
+            logger.info(`Port ${callbackPort} is already in use. Connecting to existing OAuth server...`);
+            try {
+                return await requestAuthFromExistingServer(callbackPort, requestId);
+            }
+            catch (error) {
+                logger.error("Failed to connect to existing OAuth server:", error);
+                throw new Error(`Port ${callbackPort} is in use but cannot connect to existing OAuth server. Please close other instances or use a different port.`);
+            }
+        }
+        // Port is free, start the shared OAuth server
+        return this.startSharedOAuthServer(callbackPort, requestId);
+    }
+    /**
+     * Start a shared OAuth server that can handle multiple authentication requests
+     */
+    async startSharedOAuthServer(callbackPort, initialRequestId) {
+        const stateToRequestId = new Map();
+        const requestIdToOAuthInstance = new Map();
+        return new Promise((resolve, reject) => {
+            // Create initial request
+            const state = Math.random().toString(36).substring(7);
+            stateToRequestId.set(state, initialRequestId);
+            requestIdToOAuthInstance.set(initialRequestId, this);
+            const timeout = setTimeout(() => {
+                pendingAuthRequests.get(initialRequestId)?.reject(new Error("OAuth flow timed out"));
+                pendingAuthRequests.delete(initialRequestId);
+            }, 5 * 60 * 1000);
+            pendingAuthRequests.set(initialRequestId, { resolve, reject, timeout });
+            const server = http.createServer(async (req, res) => {
+                try {
+                    const parsedUrl = url.parse(req.url || "", true);
+                    // Handle auth requests from other MCP instances
+                    if (parsedUrl.pathname === "/auth-request") {
+                        const newRequestId = parsedUrl.query.requestId;
+                        if (!newRequestId) {
+                            res.writeHead(400, { "Content-Type": "text/plain" });
+                            res.end("Missing requestId parameter");
+                            return;
+                        }
+                        logger.info(`Received auth request from another instance: ${newRequestId}`);
+                        // Create a new OAuth flow for this request
+                        const newState = Math.random().toString(36).substring(7);
+                        stateToRequestId.set(newState, newRequestId);
+                        // Store a reference to use the same OAuth config
+                        requestIdToOAuthInstance.set(newRequestId, this);
+                        // Open browser for this new request
+                        const authUrl = await this.getAuthorizationUrl(newState);
+                        logger.info("Opening browser for new authentication request...");
+                        logger.info(`If browser doesn't open, visit: ${authUrl}`);
+                        open(authUrl).catch((err) => {
+                            logger.error("Failed to open browser:", err);
+                            logger.info(`Please manually open: ${authUrl}`);
+                        });
+                        // Wait for the auth to complete
+                        const authPromise = new Promise((authResolve, authReject) => {
+                            const authTimeout = setTimeout(() => {
+                                authReject(new Error("OAuth flow timed out"));
+                                pendingAuthRequests.delete(newRequestId);
+                            }, 5 * 60 * 1000);
+                            pendingAuthRequests.set(newRequestId, {
+                                resolve: authResolve,
+                                reject: authReject,
+                                timeout: authTimeout,
+                            });
+                        });
+                        try {
+                            const tokenData = await authPromise;
+                            res.writeHead(200, { "Content-Type": "application/json" });
+                            res.end(JSON.stringify(tokenData));
+                        }
+                        catch (error) {
+                            res.writeHead(500, { "Content-Type": "text/plain" });
+                            res.end(`Authentication failed: ${error}`);
+                        }
+                        return;
+                    }
+                    // Handle OAuth callback
+                    if (parsedUrl.pathname === "/callback") {
+                        const { code, state: returnedState, error } = parsedUrl.query;
+                        if (error) {
+                            res.writeHead(400, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Failed</h1>
+                    <p>Error: ${error}</p>
+                    <p>You can close this window.</p>
+                  </body>
+                </html>
+              `);
+                            // Find and reject the corresponding request
+                            const reqId = stateToRequestId.get(returnedState);
+                            if (reqId) {
+                                const pending = pendingAuthRequests.get(reqId);
+                                if (pending) {
+                                    clearTimeout(pending.timeout);
+                                    pending.reject(new Error(`OAuth error: ${error}`));
+                                    pendingAuthRequests.delete(reqId);
+                                }
+                            }
+                            return;
+                        }
+                        if (!returnedState || typeof returnedState !== "string") {
+                            res.writeHead(400, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Failed</h1>
+                    <p>Invalid state parameter</p>
+                    <p>You can close this window.</p>
+                  </body>
+                </html>
+              `);
+                            return;
+                        }
+                        const reqId = stateToRequestId.get(returnedState);
+                        if (!reqId) {
+                            res.writeHead(400, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Failed</h1>
+                    <p>Unknown state parameter</p>
+                    <p>You can close this window.</p>
+                  </body>
+                </html>
+              `);
+                            return;
+                        }
+                        if (!code || typeof code !== "string") {
+                            res.writeHead(400, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Failed</h1>
+                    <p>No authorization code received</p>
+                    <p>You can close this window.</p>
+                  </body>
+                </html>
+              `);
+                            const pending = pendingAuthRequests.get(reqId);
+                            if (pending) {
+                                clearTimeout(pending.timeout);
+                                pending.reject(new Error("No authorization code received"));
+                                pendingAuthRequests.delete(reqId);
+                            }
+                            return;
+                        }
+                        try {
+                            const oauthInstance = requestIdToOAuthInstance.get(reqId) || this;
+                            const tokenData = await oauthInstance.exchangeCodeForToken(code);
+                            oauthInstance.saveToken(tokenData);
+                            res.writeHead(200, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Successful!</h1>
+                    <p>You can close this window and return to the terminal.</p>
+                  </body>
+                </html>
+              `);
+                            const pending = pendingAuthRequests.get(reqId);
+                            if (pending) {
+                                clearTimeout(pending.timeout);
+                                pending.resolve(tokenData);
+                                pendingAuthRequests.delete(reqId);
+                            }
+                            stateToRequestId.delete(returnedState);
+                            requestIdToOAuthInstance.delete(reqId);
+                        }
+                        catch (error) {
+                            res.writeHead(500, { "Content-Type": "text/html" });
+                            res.end(`
+                <html>
+                  <body>
+                    <h1>Authentication Failed</h1>
+                    <p>Failed to exchange code for token</p>
+                    <p>You can close this window.</p>
+                  </body>
+                </html>
+              `);
+                            const pending = pendingAuthRequests.get(reqId);
+                            if (pending) {
+                                clearTimeout(pending.timeout);
+                                pending.reject(error);
+                                pendingAuthRequests.delete(reqId);
+                            }
+                        }
+                    }
+                    else {
+                        res.writeHead(404, { "Content-Type": "text/plain" });
+                        res.end("Not Found");
+                    }
+                }
+                catch (error) {
+                    logger.error("Error handling request:", error);
+                    res.writeHead(500, { "Content-Type": "text/plain" });
+                    res.end("Internal Server Error");
+                }
+            });
+            server.listen(callbackPort, "127.0.0.1", async () => {
+                logger.info(`Shared OAuth callback server listening on port ${callbackPort}`);
+                const authUrl = await this.getAuthorizationUrl(state);
+                logger.info("Opening browser for authentication...");
+                logger.info(`If browser doesn't open, visit: ${authUrl}`);
+                open(authUrl).catch((err) => {
+                    logger.error("Failed to open browser:", err);
+                    logger.info(`Please manually open: ${authUrl}`);
+                });
+            });
+            server.on("error", (error) => {
+                logger.error("OAuth server error:", error);
+                const pending = pendingAuthRequests.get(initialRequestId);
+                if (pending) {
+                    clearTimeout(pending.timeout);
+                    pending.reject(error);
+                    pendingAuthRequests.delete(initialRequestId);
+                }
+            });
+        });
+    }
+    /**
+     * Get a valid access token, refreshing if necessary
+     */
+    async getAccessToken() {
+        let tokenData = this.loadToken();
+        // If no token or expired, start OAuth flow or refresh
+        if (!tokenData) {
+            logger.info("No stored token found. Starting OAuth flow...");
+            tokenData = await this.startOAuthFlow();
+        }
+        else if (this.isTokenExpired(tokenData)) {
+            logger.info("Token expired. Refreshing...");
+            if (tokenData.refresh_token) {
+                try {
+                    tokenData = await this.refreshAccessToken(tokenData.refresh_token);
+                    this.saveToken(tokenData);
+                }
+                catch (error) {
+                    logger.error("Token refresh failed. Starting new OAuth flow...", error);
+                    tokenData = await this.startOAuthFlow();
+                }
+            }
+            else {
+                logger.info("No refresh token available. Starting new OAuth flow...");
+                tokenData = await this.startOAuthFlow();
+            }
+        }
+        return tokenData.access_token;
+    }
+    /**
+     * Clear stored token
+     */
+    clearToken() {
+        try {
+            if (fs.existsSync(this.tokenStoragePath)) {
+                fs.unlinkSync(this.tokenStoragePath);
+                logger.info("Token cleared");
+            }
+        }
+        catch (error) {
+            logger.error("Failed to clear token:", error);
+        }
+    }
+    /**
+     * Check if a valid token exists
+     */
+    hasValidToken() {
+        const tokenData = this.loadToken();
+        if (!tokenData) {
+            return false;
+        }
+        return !this.isTokenExpired(tokenData);
+    }
+}
+/**
+ * Initialize OAuth authentication for GitLab MCP server
+ */
+export async function initializeOAuth(gitlabUrl = "https://gitlab.com") {
+    const clientId = process.env.GITLAB_OAUTH_CLIENT_ID;
+    const redirectUri = process.env.GITLAB_OAUTH_REDIRECT_URI || "http://127.0.0.1:8888/callback";
+    const tokenStoragePath = process.env.GITLAB_OAUTH_TOKEN_PATH;
+    if (!clientId) {
+        throw new Error("GITLAB_OAUTH_CLIENT_ID environment variable is required for OAuth authentication");
+    }
+    const oauth = new GitLabOAuth({
+        clientId,
+        redirectUri,
+        gitlabUrl,
+        scopes: ["api"],
+        tokenStoragePath,
+    });
+    return await oauth.getAccessToken();
+}

package/build/schemas.js

@@ -1412,7 +1412,7 @@ export const MergeRequestThreadPositionCreateSchema = z.object({
     old_path: z.string().nullable().optional().describe("File path before changes. REQUIRED for most diff comments. Use same as new_path if file wasn't renamed."),
     new_line: z.number().nullable().optional().describe("Line number in modified file (after changes). Use for added lines or context lines. NULL for deleted lines. For single-line comments on new lines."),
     old_line: z.number().nullable().optional().describe("Line number in original file (before changes). Use for deleted lines or context lines. NULL for added lines. For single-line comments on old lines."),
-    line_range: LineRangeSchema.optional().describe("MULTILINE COMMENTS: Specify start/end line positions for commenting on multiple lines. Alternative to single old_line/new_line."),
+    line_range: LineRangeSchema.nullable().optional().describe("MULTILINE COMMENTS: Specify start/end line positions for commenting on multiple lines. Alternative to single old_line/new_line."),
     width: z.number().optional().describe("IMAGE DIFFS ONLY: Width of the image (for position_type='image')."),
     height: z.number().optional().describe("IMAGE DIFFS ONLY: Height of the image (for position_type='image')."),
     x: z.number().optional().describe("IMAGE DIFFS ONLY: X coordinate on the image (for position_type='image')."),
@@ -1451,7 +1451,7 @@ export const MergeRequestThreadPositionSchema = z.object({
         .nullable()
         .optional()
         .describe("Line number in original file (before changes). Use for deleted lines or context lines. NULL for added lines. For single-line comments on old lines."),
-    line_range: LineRangeSchema.optional().describe("MULTILINE COMMENTS: Specify start/end line positions for commenting on multiple lines. Alternative to single old_line/new_line."),
+    line_range: LineRangeSchema.nullable().optional().describe("MULTILINE COMMENTS: Specify start/end line positions for commenting on multiple lines. Alternative to single old_line/new_line."),
     width: z
         .number()
         .optional()

package/build/test/oauth-tests.js

@@ -0,0 +1,389 @@
+#!/usr/bin/env tsx
+/**
+ * OAuth Authentication Tests
+ * Tests for GitLab OAuth2 authentication flow
+ */
+import * as fs from 'fs';
+import * as path from 'path';
+import * as http from 'http';
+import * as net from 'net';
+import { GitLabOAuth } from '../oauth.js';
+// Test configuration
+const TEST_CLIENT_ID = process.env.GITLAB_OAUTH_CLIENT_ID || 'test-client-id';
+const TEST_REDIRECT_URI = process.env.GITLAB_OAUTH_REDIRECT_URI || 'http://127.0.0.1:8888/callback';
+const TEST_GITLAB_URL = process.env.GITLAB_API_URL?.replace('/api/v4', '') || 'https://gitlab.com';
+const TEST_TOKEN_PATH = path.join(process.cwd(), '.test-gitlab-token.json');
+const testResults = [];
+// Helper function to run a single test
+async function runTest(name, testFn, skip = false) {
+    if (skip) {
+        console.log(`⏭️  SKIPPED: ${name}`);
+        testResults.push({ name, status: 'skipped', duration: 0 });
+        return;
+    }
+    const startTime = Date.now();
+    try {
+        console.log(`🧪 Testing: ${name}`);
+        await testFn();
+        const duration = Date.now() - startTime;
+        console.log(`✅ PASSED: ${name} (${duration}ms)`);
+        testResults.push({ name, status: 'passed', duration });
+    }
+    catch (error) {
+        const duration = Date.now() - startTime;
+        const errorMsg = error instanceof Error ? error.message : String(error);
+        console.log(`❌ FAILED: ${name} (${duration}ms)`);
+        console.log(`   Error: ${errorMsg}`);
+        testResults.push({ name, status: 'failed', duration, error: errorMsg });
+    }
+}
+// Helper function to assert conditions
+function assert(condition, message) {
+    if (!condition) {
+        throw new Error(`Assertion failed: ${message}`);
+    }
+}
+// Helper function to check if port is available
+async function isPortAvailable(port) {
+    return new Promise((resolve) => {
+        const server = net.createServer();
+        server.once('error', (err) => {
+            if (err.code === 'EADDRINUSE') {
+                resolve(false);
+            }
+            else {
+                resolve(true);
+            }
+        });
+        server.once('listening', () => {
+            server.close();
+            resolve(true);
+        });
+        server.listen(port, '127.0.0.1');
+    });
+}
+// Clean up test token file
+function cleanupTestToken() {
+    if (fs.existsSync(TEST_TOKEN_PATH)) {
+        fs.unlinkSync(TEST_TOKEN_PATH);
+    }
+}
+// Test 1: GitLabOAuth class instantiation
+async function testOAuthInstantiation() {
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    assert(oauth !== null, 'OAuth instance should be created');
+    assert(typeof oauth.getAccessToken === 'function', 'Should have getAccessToken method');
+    assert(typeof oauth.clearToken === 'function', 'Should have clearToken method');
+    assert(typeof oauth.hasValidToken === 'function', 'Should have hasValidToken method');
+}
+// Test 2: Token storage path configuration
+async function testTokenStoragePath() {
+    const customPath = path.join(process.cwd(), '.custom-test-token.json');
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: customPath,
+    });
+    assert(oauth !== null, 'OAuth instance with custom path should be created');
+    // Clean up
+    if (fs.existsSync(customPath)) {
+        fs.unlinkSync(customPath);
+    }
+}
+// Test 3: Scope configuration
+async function testScopeConfiguration() {
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    assert(oauth !== null, 'OAuth instance with api scope should be created');
+}
+// Test 4: Multiple scopes (should still work but is redundant)
+async function testMultipleScopesRedundant() {
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api', 'read_user', 'read_api', 'write_repository'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    assert(oauth !== null, 'OAuth instance with multiple scopes should be created');
+}
+// Test 5: hasValidToken returns false when no token exists
+async function testHasValidTokenNoToken() {
+    cleanupTestToken();
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    const hasToken = oauth.hasValidToken();
+    assert(hasToken === false, 'Should return false when no token exists');
+}
+// Test 6: hasValidToken returns true with valid token
+async function testHasValidTokenWithToken() {
+    const tokenData = {
+        access_token: 'test-token',
+        token_type: 'Bearer',
+        created_at: Date.now(),
+        expires_in: 7200, // 2 hours
+    };
+    fs.writeFileSync(TEST_TOKEN_PATH, JSON.stringify(tokenData), { mode: 0o600 });
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    const hasToken = oauth.hasValidToken();
+    assert(hasToken === true, 'Should return true with valid token');
+    cleanupTestToken();
+}
+// Test 7: hasValidToken returns false with expired token
+async function testHasValidTokenExpired() {
+    const tokenData = {
+        access_token: 'test-token',
+        token_type: 'Bearer',
+        created_at: Date.now() - 10000000, // 2.7+ hours ago
+        expires_in: 7200, // 2 hours
+    };
+    fs.writeFileSync(TEST_TOKEN_PATH, JSON.stringify(tokenData), { mode: 0o600 });
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    const hasToken = oauth.hasValidToken();
+    assert(hasToken === false, 'Should return false with expired token');
+    cleanupTestToken();
+}
+// Test 8: clearToken removes token file
+async function testClearToken() {
+    const tokenData = {
+        access_token: 'test-token',
+        token_type: 'Bearer',
+        created_at: Date.now(),
+    };
+    fs.writeFileSync(TEST_TOKEN_PATH, JSON.stringify(tokenData), { mode: 0o600 });
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    oauth.clearToken();
+    assert(!fs.existsSync(TEST_TOKEN_PATH), 'Token file should be deleted');
+}
+// Test 9: Token file has correct permissions (Unix only)
+async function testTokenFilePermissions() {
+    if (process.platform === 'win32') {
+        throw new Error('Skipping permission test on Windows');
+    }
+    const tokenData = {
+        access_token: 'test-token',
+        token_type: 'Bearer',
+        created_at: Date.now(),
+    };
+    fs.writeFileSync(TEST_TOKEN_PATH, JSON.stringify(tokenData), { mode: 0o600 });
+    const stats = fs.statSync(TEST_TOKEN_PATH);
+    const mode = stats.mode & 0o777;
+    assert(mode === 0o600, `Token file should have 0600 permissions, got ${mode.toString(8)}`);
+    cleanupTestToken();
+}
+// Test 10: Port availability check
+async function testPortAvailability() {
+    const port = 8888;
+    const available = await isPortAvailable(port);
+    // We just check that the function works, not the actual availability
+    assert(typeof available === 'boolean', 'Port availability check should return boolean');
+}
+// Test 11: OAuth redirect URI parsing
+async function testRedirectUriParsing() {
+    const redirectUri = 'http://127.0.0.1:8888/callback';
+    const url = new URL(redirectUri);
+    assert(url.port === '8888', 'Should correctly parse port from redirect URI');
+    assert(url.pathname === '/callback', 'Should correctly parse path from redirect URI');
+    assert(url.hostname === '127.0.0.1', 'Should correctly parse hostname from redirect URI');
+}
+// Test 12: Token expiration calculation
+async function testTokenExpirationCalculation() {
+    const now = Date.now();
+    const expiresIn = 7200; // 2 hours in seconds
+    const buffer = 5 * 60 * 1000; // 5 minutes in milliseconds
+    const expiryTime = now + (expiresIn * 1000);
+    const shouldRefreshAt = expiryTime - buffer;
+    assert(shouldRefreshAt < expiryTime, 'Refresh time should be before expiry');
+    assert(shouldRefreshAt > now, 'Refresh time should be in the future for new token');
+}
+// Test 13: Concurrent OAuth server handling (shared server concept)
+async function testSharedServerConcept() {
+    // Test that multiple instances can theoretically share a port
+    const port = 9999;
+    // First instance: start server
+    const server = http.createServer((req, res) => {
+        res.writeHead(200);
+        res.end('OK');
+    });
+    await new Promise((resolve) => {
+        server.listen(port, '127.0.0.1', () => resolve());
+    });
+    // Check port is now in use
+    const inUse = !(await isPortAvailable(port));
+    assert(inUse === true, 'Port should be in use after server starts');
+    // Clean up
+    await new Promise((resolve) => {
+        server.close(() => resolve());
+    });
+    // Check port is available again
+    const available = await isPortAvailable(port);
+    assert(available === true, 'Port should be available after server closes');
+}
+// Test 14: Environment variable configuration
+async function testEnvironmentVariableConfig() {
+    const clientId = process.env.GITLAB_OAUTH_CLIENT_ID;
+    const redirectUri = process.env.GITLAB_OAUTH_REDIRECT_URI || 'http://127.0.0.1:8888/callback';
+    assert(typeof clientId === 'string' || clientId === undefined, 'Client ID should be string or undefined');
+    assert(typeof redirectUri === 'string', 'Redirect URI should be string');
+    const url = new URL(redirectUri);
+    assert(url.protocol === 'http:', 'Redirect URI should use http protocol for localhost');
+}
+// Test 15: Token data structure validation
+async function testTokenDataStructure() {
+    const tokenData = {
+        access_token: 'glpat-test123456789',
+        refresh_token: 'refresh-test123456789',
+        token_type: 'Bearer',
+        expires_in: 7200,
+        created_at: Date.now(),
+    };
+    assert(typeof tokenData.access_token === 'string', 'access_token should be string');
+    assert(typeof tokenData.token_type === 'string', 'token_type should be string');
+    assert(typeof tokenData.created_at === 'number', 'created_at should be number');
+    assert(tokenData.expires_in === undefined || typeof tokenData.expires_in === 'number', 'expires_in should be number or undefined');
+}
+// Test 16: Invalid token storage path handling
+async function testInvalidTokenStoragePath() {
+    const invalidPath = '/root/nonexistent/directory/.token.json';
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: invalidPath,
+    });
+    // Should create instance even with invalid path (error occurs during save)
+    assert(oauth !== null, 'Should create instance with invalid path');
+}
+// Test 17: Self-hosted GitLab URL configuration
+async function testSelfHostedGitLabUrl() {
+    const selfHostedUrl = 'https://gitlab.example.com';
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: TEST_REDIRECT_URI,
+        gitlabUrl: selfHostedUrl,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    assert(oauth !== null, 'Should create instance with self-hosted URL');
+}
+// Test 18: Custom port in redirect URI
+async function testCustomPortInRedirectUri() {
+    const customRedirectUri = 'http://127.0.0.1:9999/callback';
+    const oauth = new GitLabOAuth({
+        clientId: TEST_CLIENT_ID,
+        redirectUri: customRedirectUri,
+        gitlabUrl: TEST_GITLAB_URL,
+        scopes: ['api'],
+        tokenStoragePath: TEST_TOKEN_PATH,
+    });
+    assert(oauth !== null, 'Should create instance with custom port');
+    const url = new URL(customRedirectUri);
+    assert(url.port === '9999', 'Should correctly parse custom port');
+}
+// Main test runner
+async function runOAuthTests() {
+    console.log('🚀 GitLab OAuth Authentication Tests\n');
+    console.log('='.repeat(50));
+    // Core functionality tests
+    await runTest('OAuth class instantiation', testOAuthInstantiation);
+    await runTest('Token storage path configuration', testTokenStoragePath);
+    await runTest('Scope configuration with api only', testScopeConfiguration);
+    await runTest('Multiple scopes configuration (redundant)', testMultipleScopesRedundant);
+    // Token management tests
+    await runTest('hasValidToken returns false without token', testHasValidTokenNoToken);
+    await runTest('hasValidToken returns true with valid token', testHasValidTokenWithToken);
+    await runTest('hasValidToken returns false with expired token', testHasValidTokenExpired);
+    await runTest('clearToken removes token file', testClearToken);
+    await runTest('Token file has correct permissions', testTokenFilePermissions, process.platform === 'win32');
+    // Network and configuration tests
+    await runTest('Port availability check', testPortAvailability);
+    await runTest('OAuth redirect URI parsing', testRedirectUriParsing);
+    await runTest('Token expiration calculation', testTokenExpirationCalculation);
+    await runTest('Shared server concept', testSharedServerConcept);
+    // Configuration tests
+    await runTest('Environment variable configuration', testEnvironmentVariableConfig);
+    await runTest('Token data structure validation', testTokenDataStructure);
+    await runTest('Invalid token storage path handling', testInvalidTokenStoragePath);
+    await runTest('Self-hosted GitLab URL configuration', testSelfHostedGitLabUrl);
+    await runTest('Custom port in redirect URI', testCustomPortInRedirectUri);
+    // Cleanup
+    cleanupTestToken();
+    // Print summary
+    console.log('\n' + '='.repeat(50));
+    console.log('📊 Test Results Summary\n');
+    const passed = testResults.filter(r => r.status === 'passed').length;
+    const failed = testResults.filter(r => r.status === 'failed').length;
+    const skipped = testResults.filter(r => r.status === 'skipped').length;
+    const total = testResults.length;
+    console.log(`Total tests: ${total}`);
+    console.log(`✅ Passed: ${passed}`);
+    console.log(`❌ Failed: ${failed}`);
+    console.log(`⏭️  Skipped: ${skipped}`);
+    if (total > 0) {
+        const successRate = ((passed / (total - skipped)) * 100).toFixed(1);
+        console.log(`Success rate: ${successRate}%`);
+    }
+    // Show failed tests
+    const failedTests = testResults.filter(r => r.status === 'failed');
+    if (failedTests.length > 0) {
+        console.log('\n❌ Failed Tests:');
+        failedTests.forEach(test => {
+            console.log(`  - ${test.name}`);
+            console.log(`    ${test.error}`);
+        });
+    }
+    // Save results to file
+    const reportPath = 'test-results-oauth.json';
+    fs.writeFileSync(reportPath, JSON.stringify(testResults, null, 2));
+    console.log(`\n📄 Detailed results saved to ${reportPath}`);
+    return failed === 0;
+}
+// Run tests if this is the main module
+if (import.meta.url === `file://${process.argv[1]}`) {
+    runOAuthTests()
+        .then(success => {
+        process.exit(success ? 0 : 1);
+    })
+        .catch(error => {
+        console.error('Error running tests:', error);
+        process.exit(1);
+    });
+}
+export { runOAuthTests, testResults };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.0.9",
+  "version": "2.0.13",
   "description": "MCP server for using the GitLab API",
   "license": "MIT",
   "author": "zereight",
@@ -27,7 +27,8 @@
     "test:remote-auth": "npm run build && npx tsx --test test/remote-auth-simple-test.ts",
     "test:server": "npm run build && node build/test/test-all-transport-server.js",
     "test:mcp:readonly": "tsx test/readonly-mcp-tests.ts",
-    "test:all": "npm run test && npm run test:mcp:readonly",
+    "test:oauth": "tsx test/oauth-tests.ts",
+    "test:all": "npm run test && npm run test:mcp:readonly && npm run test:oauth",
     "lint": "eslint . --ext .ts",
     "lint:fix": "eslint . --ext .ts --fix",
     "format": "prettier --write \"**/*.{js,ts,json,md}\"",
@@ -42,11 +43,13 @@
     "http-proxy-agent": "^7.0.2",
     "https-proxy-agent": "^7.0.6",
     "node-fetch": "^3.3.2",
+    "open": "^10.2.0",
     "pino": "^9.7.0",
     "pino-pretty": "^13.0.0",
+    "pkce-challenge": "^5.0.0",
     "socks-proxy-agent": "^8.0.5",
     "tough-cookie": "^5.1.2",
-    "zod-to-json-schema": "^3.23.5"
+    "zod-to-json-schema": "3.24.5"
   },
   "devDependencies": {
     "@types/express": "^5.0.2",