@zereight/mcp-gitlab 2.1.3 → 2.1.5

package/README.md

@@ -173,12 +173,14 @@ exchanging credentials with GitLab on behalf of the client.
 | `GITLAB_OAUTH_APP_ID` | ✅       | GitLab OAuth Application ID                                |
 | `MCP_SERVER_URL`      | ✅       | Public HTTPS URL of this MCP server                        |
 | `STREAMABLE_HTTP`     | ✅       | Must be `true`                                             |
+| `GITLAB_OAUTH_CALLBACK_PROXY` | optional | Set to `true` to use the MCP server's fixed `/callback` URL |
 | `GITLAB_OAUTH_SCOPES` | optional | Comma-separated scopes (default: `api,read_api,read_user`) |
 
 ```shell
 docker run -i --rm \
   -e HOST=0.0.0.0 \
   -e GITLAB_MCP_OAUTH=true \
+  -e GITLAB_OAUTH_CALLBACK_PROXY=true \
   -e STREAMABLE_HTTP=true \
   -e MCP_SERVER_URL=https://your-server.example.com \
   -e GITLAB_API_URL="https://gitlab.com/api/v4" \
@@ -249,6 +251,7 @@ Commonly referenced variables:
 - `GITLAB_USE_OAUTH`
 - `REMOTE_AUTHORIZATION`
 - `GITLAB_MCP_OAUTH`
+- `GITLAB_OAUTH_CALLBACK_PROXY`
 
 The reference document also covers:
 
@@ -259,6 +262,8 @@ The reference document also covers:
 - transport and session variables
 - proxy and TLS variables
 
+For callback proxy mode details, see [GitLab MCP OAuth Callback Proxy](./docs/oauth-callback-proxy.md).
+
 ### Remote Authorization Setup (Multi-User Support)
 
 When using `REMOTE_AUTHORIZATION=true`, the MCP server can support multiple users, each with their own GitLab token passed via HTTP headers. This is useful for:

package/build/config.js

@@ -56,6 +56,7 @@ export const GITLAB_OAUTH_SCOPES_RAW = getConfig("oauth-scopes", "GITLAB_OAUTH_S
 export const GITLAB_OAUTH_SCOPES = GITLAB_OAUTH_SCOPES_RAW
     ? GITLAB_OAUTH_SCOPES_RAW.split(",").map((s) => s.trim()).filter(Boolean)
     : undefined;
+export const GITLAB_OAUTH_CALLBACK_PROXY = getConfig("oauth-callback-proxy", "GITLAB_OAUTH_CALLBACK_PROXY") === "true";
 export const ENABLE_DYNAMIC_API_URL = getConfig("enable-dynamic-api-url", "ENABLE_DYNAMIC_API_URL") === "true";
 // ---------------------------------------------------------------------------
 // Session / server settings

package/build/index.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { getConfig, ENABLE_DYNAMIC_API_URL, GITLAB_AUTH_COOKIE_PATH, GITLAB_CA_CERT_PATH, GITLAB_JOB_TOKEN, GITLAB_MCP_OAUTH, GITLAB_OAUTH_APP_ID, GITLAB_OAUTH_SCOPES, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_POOL_MAX_SIZE, GITLAB_READ_ONLY_MODE, GITLAB_TOOLSETS_RAW, GITLAB_TOOLS_RAW, HOST, HTTP_PROXY, HTTPS_PROXY, IS_OLD, MCP_SERVER_URL, NODE_TLS_REJECT_UNAUTHORIZED, NO_PROXY, PORT, REMOTE_AUTHORIZATION, SESSION_TIMEOUT_SECONDS, SSE, STREAMABLE_HTTP, USE_GITLAB_WIKI, USE_MILESTONE, USE_OAUTH, USE_PIPELINE, GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, } from "./config.js";
+import { getConfig, ENABLE_DYNAMIC_API_URL, GITLAB_AUTH_COOKIE_PATH, GITLAB_CA_CERT_PATH, GITLAB_JOB_TOKEN, GITLAB_MCP_OAUTH, GITLAB_OAUTH_APP_ID, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, GITLAB_PERSONAL_ACCESS_TOKEN, GITLAB_POOL_MAX_SIZE, GITLAB_READ_ONLY_MODE, GITLAB_TOOLSETS_RAW, GITLAB_TOOLS_RAW, HOST, HTTP_PROXY, HTTPS_PROXY, IS_OLD, MCP_SERVER_URL, NODE_TLS_REJECT_UNAUTHORIZED, NO_PROXY, PORT, REMOTE_AUTHORIZATION, SESSION_TIMEOUT_SECONDS, SSE, STREAMABLE_HTTP, USE_GITLAB_WIKI, USE_MILESTONE, USE_OAUTH, USE_PIPELINE, GITLAB_TOOL_POLICY_APPROVE_RAW, GITLAB_TOOL_POLICY_HIDDEN_RAW, } from "./config.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
@@ -4863,9 +4863,8 @@ async function cancelPipelineJob(projectId, jobId, force) {
 }
 /**
  * Get the repository tree for a project
- * @param {string} projectId - The ID or URL-encoded path of the project
  * @param {GetRepositoryTreeOptions} options - Options for the tree
- * @returns {Promise<GitLabTreeItem[]>}
+ * @returns Parsed tree items plus optional keyset pagination metadata.
  */
 async function getRepositoryTree(options) {
     options.project_id = decodeURIComponent(options.project_id); // Decode project_id within options
@@ -4890,7 +4889,11 @@ async function getRepositoryTree(options) {
         throw new Error(`Failed to get repository tree: ${response.statusText}`);
     }
     const data = await response.json();
-    return z.array(GitLabTreeItemSchema).parse(data);
+    const items = z.array(GitLabTreeItemSchema).parse(data);
+    const next_page_token = response.headers.get("x-next-page-token") ||
+        (options.pagination === "keyset" ? response.headers.get("x-next-page") : null) ||
+        undefined;
+    return { items, next_page_token };
 }
 /**
  * List project milestones in a GitLab project
@@ -6583,9 +6586,18 @@ async function handleToolCall(params) {
             }
             case "get_repository_tree": {
                 const args = GetRepositoryTreeSchema.parse(params.arguments);
-                const tree = await getRepositoryTree(args);
+                const { items, next_page_token } = await getRepositoryTree(args);
+                const result = args.pagination === "keyset" || next_page_token
+                    ? {
+                        items,
+                        ...(next_page_token ? { next_page_token } : {}),
+                        pagination_note: next_page_token
+                            ? "Pass next_page_token as page_token with pagination=keyset to retrieve the next page."
+                            : "No next_page_token was returned; this is the final keyset page.",
+                    }
+                    : items;
                 return {
-                    content: [{ type: "text", text: JSON.stringify(tree, null, 2) }],
+                    content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 };
             }
             case "list_pipelines": {
@@ -7359,7 +7371,10 @@ async function startStreamableHTTPServer() {
         app.set("trust proxy", 1);
         const gitlabBaseUrl = GITLAB_API_URL.replace(/\/api\/v4\/?$/, "").replace(/\/$/, "");
         const issuerUrl = new URL(MCP_SERVER_URL);
-        const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID, "GitLab MCP Server", GITLAB_READ_ONLY_MODE, GITLAB_OAUTH_SCOPES);
+        const callbackUrl = GITLAB_OAUTH_CALLBACK_PROXY
+            ? `${issuerUrl.origin}${issuerUrl.pathname.replace(/\/$/, "")}/callback`
+            : undefined;
+        const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID, "GitLab MCP Server", GITLAB_READ_ONLY_MODE, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, callbackUrl);
         const scopesSupported = GITLAB_OAUTH_SCOPES ?? ["api", "read_api", "read_user"];
         // When server URL has a path (e.g. behind Kong), the SDK's well-known metadata
         // advertises root-level endpoints. Override to use path-prefixed endpoints.
@@ -7412,6 +7427,14 @@ async function startStreamableHTTPServer() {
         }));
         // Expose provider so the /mcp route middleware can reference it
         app._mcpOAuthProvider = oauthProvider;
+        // Mount /callback route for callback proxy mode
+        if (GITLAB_OAUTH_CALLBACK_PROXY) {
+            const callbackPath = `${issuerUrl.pathname.replace(/\/$/, "")}/callback`;
+            app.get(callbackPath, (req, res, next) => {
+                oauthProvider.handleCallback(req, res).catch(next);
+            });
+            logger.info(`Callback proxy mode enabled — ${callbackPath} route mounted`);
+        }
     }
     // Build bearer-auth middleware — no-op unless GITLAB_MCP_OAUTH is enabled.
     // Unauthenticated requests receive 401 + WWW-Authenticate header, which is

package/build/oauth-proxy.js

@@ -13,7 +13,26 @@
  * and handles DCR locally — each MCP client gets a unique virtual client_id
  * mapped to the real GitLab app.
  *
- * ### Flow
+ * ### Flow (callback proxy mode — GITLAB_OAUTH_CALLBACK_PROXY=true)
+ *
+ * When callback proxy mode is enabled, the MCP server acts as a full OAuth
+ * intermediary, similar to the Atlassian MCP's OAuthProxy pattern. Only ONE
+ * fixed callback URL needs to be registered with GitLab, regardless of how
+ * many MCP clients connect.
+ *
+ * 1. MCP client calls POST /register (DCR) — proxy stores redirect_uris locally
+ *    and returns a virtual client_id.
+ * 2. MCP client redirects to /authorize — proxy stores the client's original
+ *    redirect_uri and state, generates its own PKCE pair, then redirects to
+ *    GitLab using the MCP server's fixed /callback URL as redirect_uri.
+ * 3. User authorizes on GitLab — GitLab redirects to the MCP server's /callback.
+ * 4. /callback handler exchanges the code with GitLab for tokens, stores them
+ *    server-side, generates a new proxy auth code, and redirects to the client's
+ *    original redirect_uri with the proxy code.
+ * 5. MCP client calls POST /token with the proxy code — proxy returns the
+ *    stored GitLab tokens.
+ *
+ * ### Flow (passthrough mode — default)
  *
  * 1. MCP client calls POST /register (DCR) — proxy stores redirect_uris locally
  *    and returns a virtual client_id.
@@ -27,62 +46,81 @@
  */
 import { InvalidTokenError, ServerError } from "@modelcontextprotocol/sdk/server/auth/errors.js";
 import { OAuthTokensSchema } from "@modelcontextprotocol/sdk/shared/auth.js";
-import { randomUUID } from "node:crypto";
+import { randomUUID, randomBytes, createHash } from "node:crypto";
 import { pino } from "pino";
 const logger = pino({ name: "gitlab-mcp-oauth-proxy" });
 // ---------------------------------------------------------------------------
-// Bounded LRU client cache
+// GitLab OAuth Server Provider
+// ---------------------------------------------------------------------------
+/**
+ * Minimum GitLab scopes required for the MCP server to function.
+ * Injected into the authorization request when the client does not request them.
+ */
+const REQUIRED_GITLAB_SCOPES_RW = ["api"];
+const REQUIRED_GITLAB_SCOPES_RO = ["read_api"];
+// ---------------------------------------------------------------------------
+// Callback proxy mode — pending auth transactions
 // ---------------------------------------------------------------------------
+const PENDING_AUTH_MAX_SIZE = 1000;
+const PENDING_AUTH_TTL_MS = 10 * 60 * 1000; // 10 minutes
 const CLIENT_CACHE_MAX_SIZE = 1000;
-class BoundedClientCache {
+class BoundedLRUMap {
     _map = new Map();
     _maxSize;
     constructor(maxSize) {
         this._maxSize = maxSize;
     }
-    get(clientId) {
-        const entry = this._map.get(clientId);
-        if (entry) {
-            this._map.delete(clientId);
-            this._map.set(clientId, entry);
+    get(key) {
+        const v = this._map.get(key);
+        if (v !== undefined) {
+            this._map.delete(key);
+            this._map.set(key, v);
         }
-        return entry;
+        return v;
     }
-    set(clientId, client) {
-        if (this._map.has(clientId)) {
-            this._map.delete(clientId);
-        }
+    /** Get and remove in one operation — for one-time-use entries. */
+    getAndDelete(key) {
+        const v = this._map.get(key);
+        if (v !== undefined)
+            this._map.delete(key);
+        return v;
+    }
+    set(key, value) {
+        if (this._map.has(key))
+            this._map.delete(key);
         else if (this._map.size >= this._maxSize) {
             const lruKey = this._map.keys().next().value;
             if (lruKey !== undefined)
                 this._map.delete(lruKey);
         }
-        this._map.set(clientId, client);
+        this._map.set(key, value);
+    }
+    delete(key) {
+        return this._map.delete(key);
     }
     get size() {
         return this._map.size;
     }
 }
-// ---------------------------------------------------------------------------
-// GitLab OAuth Server Provider
-// ---------------------------------------------------------------------------
-/**
- * Minimum GitLab scopes required for the MCP server to function.
- * Injected into the authorization request when the client does not request them.
- */
-const REQUIRED_GITLAB_SCOPES_RW = ["api"];
-const REQUIRED_GITLAB_SCOPES_RO = ["read_api"];
 class GitLabOAuthServerProvider {
     /**
-     * Tell the SDK not to validate PKCE locally — GitLab handles it.
+     * Tell the SDK not to validate PKCE locally.
+     * - Passthrough mode: GitLab handles PKCE validation.
+     * - Callback proxy mode: we verify the client's PKCE manually in
+     *   exchangeAuthorizationCode() after looking up stored tokens.
      */
     skipLocalPkceValidation = true;
     _gitlabBaseUrl;
     _gitlabAppId;
     _resourceName;
     _requiredScopes;
-    _clientCache = new BoundedClientCache(CLIENT_CACHE_MAX_SIZE);
-    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes) {
+    _clientCache = new BoundedLRUMap(CLIENT_CACHE_MAX_SIZE);
+    // Callback proxy mode fields
+    _callbackProxyEnabled;
+    _callbackUrl;
+    _pendingAuth = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
+    _storedTokens = new BoundedLRUMap(PENDING_AUTH_MAX_SIZE);
+    constructor(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled = false, callbackUrl = "") {
         this._gitlabBaseUrl = gitlabBaseUrl;
         this._gitlabAppId = gitlabAppId;
         this._resourceName = resourceName;
@@ -92,6 +130,14 @@ class GitLabOAuthServerProvider {
                 : readOnly
                     ? REQUIRED_GITLAB_SCOPES_RO
                     : REQUIRED_GITLAB_SCOPES_RW;
+        this._callbackProxyEnabled = callbackProxyEnabled;
+        this._callbackUrl = callbackUrl;
+        if (callbackProxyEnabled && !callbackUrl) {
+            throw new Error("callbackUrl is required when callbackProxyEnabled is true");
+        }
+        if (callbackProxyEnabled) {
+            logger.info(`Callback proxy mode enabled — fixed callback URL: ${callbackUrl}`);
+        }
     }
     // ---- Client store (local DCR) ------------------------------------------
     get clientsStore() {
@@ -130,7 +176,7 @@ class GitLabOAuthServerProvider {
         };
     }
     // ---- Authorize ---------------------------------------------------------
-    async authorize(_client, params, res) {
+    async authorize(client, params, res) {
         const scopes = params.scopes ?? [];
         const hasRequired = this._requiredScopes.some((s) => scopes.includes(s));
         const effectiveScopes = hasRequired
@@ -138,21 +184,57 @@ class GitLabOAuthServerProvider {
             : [...new Set([...scopes, ...this._requiredScopes])];
         // Build the GitLab authorize URL with the REAL app client_id
         const targetUrl = new URL(`${this._gitlabBaseUrl}/oauth/authorize`);
-        const searchParams = new URLSearchParams({
-            client_id: this._gitlabAppId,
-            response_type: "code",
-            redirect_uri: params.redirectUri,
-            code_challenge: params.codeChallenge,
-            code_challenge_method: "S256",
-        });
-        if (params.state)
-            searchParams.set("state", params.state);
-        if (effectiveScopes.length)
-            searchParams.set("scope", effectiveScopes.join(" "));
-        if (params.resource)
-            searchParams.set("resource", params.resource.href);
-        targetUrl.search = searchParams.toString();
-        logger.info(`authorize: redirecting to GitLab (app: ${this._gitlabAppId}, scopes: ${effectiveScopes.join(" ")})`);
+        if (this._callbackProxyEnabled) {
+            // --- Callback proxy mode ---
+            // Generate a proxy PKCE pair (MCP server ↔ GitLab)
+            const proxyCodeVerifier = randomBytes(32).toString("base64url");
+            const proxyCodeChallenge = createHash("sha256")
+                .update(proxyCodeVerifier)
+                .digest("base64url");
+            // Use a unique state to correlate the callback
+            const proxyState = randomUUID();
+            // Store the client's original params so /callback can redirect back
+            this._pendingAuth.set(proxyState, {
+                clientId: client.client_id,
+                clientRedirectUri: params.redirectUri,
+                clientState: params.state,
+                clientCodeChallenge: params.codeChallenge,
+                proxyCodeVerifier,
+                createdAt: Date.now(),
+            });
+            const searchParams = new URLSearchParams({
+                client_id: this._gitlabAppId,
+                response_type: "code",
+                redirect_uri: this._callbackUrl,
+                code_challenge: proxyCodeChallenge,
+                code_challenge_method: "S256",
+                state: proxyState,
+            });
+            if (effectiveScopes.length)
+                searchParams.set("scope", effectiveScopes.join(" "));
+            if (params.resource)
+                searchParams.set("resource", params.resource.href);
+            targetUrl.search = searchParams.toString();
+            logger.info(`authorize (callback proxy): redirecting to GitLab with fixed callback URL (app: ${this._gitlabAppId}, scopes: ${effectiveScopes.join(" ")})`);
+        }
+        else {
+            // --- Passthrough mode (original behavior) ---
+            const searchParams = new URLSearchParams({
+                client_id: this._gitlabAppId,
+                response_type: "code",
+                redirect_uri: params.redirectUri,
+                code_challenge: params.codeChallenge,
+                code_challenge_method: "S256",
+            });
+            if (params.state)
+                searchParams.set("state", params.state);
+            if (effectiveScopes.length)
+                searchParams.set("scope", effectiveScopes.join(" "));
+            if (params.resource)
+                searchParams.set("resource", params.resource.href);
+            targetUrl.search = searchParams.toString();
+            logger.info(`authorize: redirecting to GitLab (app: ${this._gitlabAppId}, scopes: ${effectiveScopes.join(" ")})`);
+        }
         res.redirect(targetUrl.toString());
     }
     // ---- PKCE challenge (delegated to GitLab) ------------------------------
@@ -160,7 +242,45 @@ class GitLabOAuthServerProvider {
         return "";
     }
     // ---- Token exchange ----------------------------------------------------
-    async exchangeAuthorizationCode(_client, authorizationCode, codeVerifier, redirectUri, resource) {
+    async exchangeAuthorizationCode(client, authorizationCode, codeVerifier, redirectUri, resource) {
+        if (this._callbackProxyEnabled) {
+            // --- Callback proxy mode ---
+            // The authorizationCode is a proxy code we generated in handleCallback().
+            // Look up the stored tokens by proxy code.
+            const entry = this._storedTokens.get(authorizationCode);
+            if (!entry) {
+                throw new ServerError("Invalid or expired authorization code");
+            }
+            // Check TTL before consuming — expired entries can't be retried anyway,
+            // but we give a specific error so the client knows to restart the flow.
+            if (Date.now() - entry.createdAt > PENDING_AUTH_TTL_MS) {
+                this._storedTokens.delete(authorizationCode);
+                throw new ServerError("Authorization code expired — please restart the OAuth flow");
+            }
+            // One-time use: delete after validation
+            this._storedTokens.delete(authorizationCode);
+            // Bind the proxy code to the client and redirect_uri that initiated
+            // /authorize, preserving the normal OAuth authorization-code invariant.
+            if (client.client_id !== entry.clientId) {
+                throw new ServerError("Invalid client for authorization code");
+            }
+            if (redirectUri !== entry.clientRedirectUri) {
+                throw new ServerError("Invalid redirect_uri for authorization code");
+            }
+            // Verify client PKCE: the client's code_verifier must match the
+            // code_challenge stored during /authorize.
+            if (entry.clientCodeChallenge) {
+                if (!codeVerifier) {
+                    throw new ServerError("PKCE code_verifier is required");
+                }
+                const computed = createHash("sha256").update(codeVerifier).digest("base64url");
+                if (computed !== entry.clientCodeChallenge) {
+                    throw new ServerError("PKCE verification failed");
+                }
+            }
+            return entry.tokens;
+        }
+        // --- Passthrough mode (original behavior) ---
         const params = new URLSearchParams({
             grant_type: "authorization_code",
             client_id: this._gitlabAppId,
@@ -227,6 +347,86 @@ class GitLabOAuthServerProvider {
                 : undefined,
         };
     }
+    // ---- Callback handler (callback proxy mode) ----------------------------
+    /**
+     * Handle the OAuth callback from GitLab.
+     * Exchanges the auth code for tokens, stores them, generates a proxy code,
+     * and redirects to the MCP client's original callback URL.
+     *
+     * Mount this as GET /callback in the Express app.
+     */
+    async handleCallback(req, res) {
+        if (!this._callbackProxyEnabled) {
+            res.status(404).send("Callback proxy mode is not enabled");
+            return;
+        }
+        const code = req.query.code;
+        const state = req.query.state;
+        const error = req.query.error;
+        if (error) {
+            logger.error(`GitLab OAuth error: ${error} — ${req.query.error_description ?? "(no description)"}`);
+            res.status(400).send("Authorization failed");
+            return;
+        }
+        if (!code || !state) {
+            res.status(400).send("Missing code or state parameter");
+            return;
+        }
+        // Look up the pending auth transaction
+        const pending = this._pendingAuth.getAndDelete(state);
+        if (!pending) {
+            res.status(400).send("Unknown or expired state parameter");
+            return;
+        }
+        // Check TTL
+        if (Date.now() - pending.createdAt > PENDING_AUTH_TTL_MS) {
+            res.status(400).send("Authorization request expired");
+            return;
+        }
+        // Exchange the GitLab auth code for tokens using the proxy's PKCE verifier
+        try {
+            const tokenParams = new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: this._gitlabAppId,
+                code,
+                redirect_uri: this._callbackUrl,
+                code_verifier: pending.proxyCodeVerifier,
+            });
+            const tokenResponse = await fetch(`${this._gitlabBaseUrl}/oauth/token`, {
+                method: "POST",
+                headers: { "Content-Type": "application/x-www-form-urlencoded" },
+                body: tokenParams.toString(),
+            });
+            if (!tokenResponse.ok) {
+                const body = await tokenResponse.text();
+                logger.error(`Callback token exchange failed (${tokenResponse.status}): ${body}`);
+                res.status(502).send("Token exchange with GitLab failed");
+                return;
+            }
+            const tokens = OAuthTokensSchema.parse(await tokenResponse.json());
+            // Generate a proxy auth code for the MCP client
+            const proxyCode = randomUUID();
+            this._storedTokens.set(proxyCode, {
+                tokens,
+                clientId: pending.clientId,
+                clientCodeChallenge: pending.clientCodeChallenge,
+                clientRedirectUri: pending.clientRedirectUri,
+                createdAt: Date.now(),
+            });
+            // Redirect to the MCP client's original callback URL
+            const clientCallback = new URL(pending.clientRedirectUri);
+            clientCallback.searchParams.set("code", proxyCode);
+            if (pending.clientState) {
+                clientCallback.searchParams.set("state", pending.clientState);
+            }
+            logger.info(`callback: exchanged code with GitLab, redirecting to client callback`);
+            res.redirect(clientCallback.toString());
+        }
+        catch (err) {
+            logger.error({ err }, "Callback handler error");
+            res.status(500).send("Internal error during token exchange");
+        }
+    }
     // ---- Revoke token ------------------------------------------------------
     async revokeToken(_client, request) {
         const params = new URLSearchParams({
@@ -258,7 +458,11 @@ class GitLabOAuthServerProvider {
  * @param resourceName   Human-readable name shown on the GitLab consent screen.
  * @param readOnly       When true and customScopes is not set, restricts to read_api scope.
  * @param customScopes   Explicit list of GitLab scopes to require. Overrides readOnly when set.
+ * @param callbackProxyEnabled  When true, the MCP server handles the OAuth callback internally.
+ *                              Only ONE fixed callback URL needs to be registered with GitLab.
+ * @param callbackUrl    The fixed callback URL (e.g. https://mcp.example.com/callback).
+ *                        Required when callbackProxyEnabled is true.
  */
-export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false, customScopes) {
-    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes);
+export function createGitLabOAuthProvider(gitlabBaseUrl, gitlabAppId, resourceName = "GitLab MCP Server", readOnly = false, customScopes, callbackProxyEnabled = false, callbackUrl = "") {
+    return new GitLabOAuthServerProvider(gitlabBaseUrl, gitlabAppId, resourceName, readOnly, customScopes, callbackProxyEnabled, callbackUrl);
 }

package/build/schemas.js

@@ -634,8 +634,14 @@ export const GetRepositoryTreeSchema = z.object({
         .describe("The name of a repository branch or tag. Defaults to the default branch."),
     recursive: z.coerce.boolean().optional().describe("Boolean value to get a recursive tree"),
     per_page: z.coerce.number().optional().describe("Number of results to show per page"),
-    page_token: z.string().optional().describe("The tree record ID for pagination"),
-    pagination: z.string().optional().describe("Pagination method (keyset)"),
+    page_token: z
+        .string()
+        .optional()
+        .describe("Token for keyset pagination. Use the next_page_token value returned in the previous response to retrieve the next page."),
+    pagination: z
+        .string()
+        .optional()
+        .describe("Pagination method. Use 'keyset' for keyset-based pagination (required for repositories with many files). Non-keyset calls keep the legacy array response for backward compatibility; that legacy response shape is deprecated and may be removed in a future major release. Keyset calls return a structured response with items and next_page_token when more pages are available."),
 });
 export const GitLabTreeSchema = z.object({
     id: z.string(), // Changed from sha to match GitLab API