@zereight/mcp-gitlab 2.1.3 → 2.1.4

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

package/build/test/callback-proxy-tests.js

@@ -0,0 +1,321 @@
+/**
+ * Callback Proxy Mode Tests
+ *
+ * Tests for GITLAB_OAUTH_CALLBACK_PROXY=true — the mode where the MCP server
+ * intercepts the OAuth callback from GitLab, exchanges the code for tokens
+ * server-side, and redirects to the MCP client with a proxy code.
+ */
+import { describe, test, after, before } from "node:test";
+import assert from "node:assert";
+import { createHash, randomBytes } from "node:crypto";
+import { launchServer, findAvailablePort, cleanupServers, TransportMode, HOST, } from "./utils/server-launcher.js";
+import { MockGitLabServer, findMockServerPort } from "./utils/mock-gitlab-server.js";
+const MOCK_GITLAB_PORT_BASE = 9400;
+const MCP_SERVER_PORT_BASE = 3400;
+const MOCK_ACCESS_TOKEN = "ya29.mock-callback-proxy-token-123456";
+const MOCK_REFRESH_TOKEN = "mock-refresh-token-abcdef";
+const MOCK_APP_ID = "test-callback-proxy-app-id";
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+function generatePKCE() {
+    const verifier = randomBytes(32).toString("base64url");
+    const challenge = createHash("sha256").update(verifier).digest("base64url");
+    return { verifier, challenge };
+}
+/** Register a client via DCR and return the virtual client_id. */
+async function registerClient(mcpBaseUrl, redirectUri) {
+    const res = await fetch(`${mcpBaseUrl}/register`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({
+            redirect_uris: [redirectUri],
+            client_name: "callback-proxy-test",
+        }),
+    });
+    assert.strictEqual(res.status, 201, `DCR failed: ${res.status}`);
+    const data = (await res.json());
+    return data.client_id;
+}
+/** Hit /authorize and return the redirect Location without following it. */
+async function authorize(mcpBaseUrl, clientId, redirectUri, codeChallenge, state) {
+    const params = new URLSearchParams({
+        response_type: "code",
+        client_id: clientId,
+        redirect_uri: redirectUri,
+        code_challenge: codeChallenge,
+        code_challenge_method: "S256",
+        state,
+        scope: "api",
+    });
+    const res = await fetch(`${mcpBaseUrl}/authorize?${params}`, {
+        redirect: "manual",
+    });
+    assert.strictEqual(res.status, 302, `Expected 302, got ${res.status}`);
+    const location = res.headers.get("location");
+    assert.ok(location, "Missing Location header");
+    return new URL(location);
+}
+/** Simulate GitLab redirecting to the MCP server's /callback. */
+async function simulateGitLabCallback(mcpBaseUrl, code, state) {
+    const res = await fetch(`${mcpBaseUrl}/callback?code=${encodeURIComponent(code)}&state=${encodeURIComponent(state)}`, { redirect: "manual" });
+    return {
+        status: res.status,
+        location: res.headers.get("location"),
+        body: await res.text(),
+    };
+}
+/** Exchange a proxy code for tokens via /token. */
+async function exchangeToken(mcpBaseUrl, clientId, code, codeVerifier, redirectUri) {
+    const res = await fetch(`${mcpBaseUrl}/token`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body: new URLSearchParams({
+            grant_type: "authorization_code",
+            client_id: clientId,
+            code,
+            code_verifier: codeVerifier,
+            redirect_uri: redirectUri,
+        }).toString(),
+    });
+    return {
+        status: res.status,
+        body: (await res.json()),
+    };
+}
+// ---------------------------------------------------------------------------
+// Test suite
+// ---------------------------------------------------------------------------
+describe("Callback Proxy Mode", () => {
+    let mcpBaseUrl;
+    let mockGitLab;
+    let mockGitLabUrl;
+    let servers = [];
+    const clientRedirectUri = "http://localhost:19999/oauth/callback";
+    // Track the last code+verifier GitLab received so we can verify the proxy PKCE
+    let lastTokenRequest = {};
+    before(async () => {
+        const mockPort = await findMockServerPort(MOCK_GITLAB_PORT_BASE);
+        mockGitLab = new MockGitLabServer({
+            port: mockPort,
+            validTokens: [MOCK_ACCESS_TOKEN],
+        });
+        await mockGitLab.start();
+        mockGitLabUrl = mockGitLab.getUrl();
+        // Mock GitLab token exchange — returns tokens and records the request
+        mockGitLab.addRootHandler("post", "/oauth/token", (req, res) => {
+            // Body may be URL-encoded (from handleCallback) — parse manually if needed
+            let body = req.body ?? {};
+            if (typeof body === "string") {
+                body = Object.fromEntries(new URLSearchParams(body));
+            }
+            else if (!body.grant_type && req.headers["content-type"]?.includes("urlencoded")) {
+                // express.json() didn't parse it — collect raw body
+                let raw = "";
+                req.on("data", (chunk) => { raw += chunk.toString(); });
+                req.on("end", () => {
+                    lastTokenRequest = Object.fromEntries(new URLSearchParams(raw));
+                    res.json({
+                        access_token: MOCK_ACCESS_TOKEN,
+                        token_type: "Bearer",
+                        expires_in: 7200,
+                        refresh_token: MOCK_REFRESH_TOKEN,
+                        scope: "api",
+                    });
+                });
+                return;
+            }
+            lastTokenRequest = body;
+            res.json({
+                access_token: MOCK_ACCESS_TOKEN,
+                token_type: "Bearer",
+                expires_in: 7200,
+                refresh_token: MOCK_REFRESH_TOKEN,
+                scope: "api",
+            });
+        });
+        // Mock token introspection
+        mockGitLab.addRootHandler("get", "/oauth/token/info", (req, res) => {
+            const auth = req.headers["authorization"];
+            const token = auth?.replace(/^Bearer\s+/i, "");
+            if (token !== MOCK_ACCESS_TOKEN) {
+                res.status(401).json({ error: "invalid_token" });
+                return;
+            }
+            res.json({
+                resource_owner_id: 42,
+                scopes: ["api"],
+                expires_in_seconds: 7200,
+                application: { uid: MOCK_APP_ID },
+                created_at: Math.floor(Date.now() / 1000),
+            });
+        });
+        const mcpPort = await findAvailablePort(MCP_SERVER_PORT_BASE);
+        mcpBaseUrl = `http://${HOST}:${mcpPort}`;
+        const server = await launchServer({
+            mode: TransportMode.STREAMABLE_HTTP,
+            port: mcpPort,
+            timeout: 5000,
+            env: {
+                STREAMABLE_HTTP: "true",
+                GITLAB_MCP_OAUTH: "true",
+                GITLAB_OAUTH_CALLBACK_PROXY: "true",
+                GITLAB_OAUTH_APP_ID: MOCK_APP_ID,
+                GITLAB_API_URL: `${mockGitLabUrl}/api/v4`,
+                MCP_SERVER_URL: mcpBaseUrl,
+                MCP_DANGEROUSLY_ALLOW_INSECURE_ISSUER_URL: "true",
+            },
+        });
+        servers.push(server);
+    });
+    after(async () => {
+        cleanupServers(servers);
+        if (mockGitLab)
+            await mockGitLab.stop();
+    });
+    // ---- Happy path --------------------------------------------------------
+    test("full flow: authorize → callback → token exchange", async () => {
+        const clientPKCE = generatePKCE();
+        const clientState = "test-state-123";
+        // 1. Register client
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        // 2. Authorize — should redirect to GitLab with fixed callback URL
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, clientState);
+        assert.strictEqual(gitlabUrl.hostname, new URL(mockGitLabUrl).hostname);
+        assert.strictEqual(gitlabUrl.pathname, "/oauth/authorize");
+        // redirect_uri should be the MCP server's /callback, NOT the client's
+        assert.strictEqual(gitlabUrl.searchParams.get("redirect_uri"), `${mcpBaseUrl}/callback`);
+        // State should be a proxy state, NOT the client's original state
+        const proxyState = gitlabUrl.searchParams.get("state");
+        assert.ok(proxyState);
+        assert.notStrictEqual(proxyState, clientState);
+        // 3. Simulate GitLab callback to MCP server
+        const callbackResult = await simulateGitLabCallback(mcpBaseUrl, "gitlab-auth-code-xyz", proxyState);
+        assert.strictEqual(callbackResult.status, 302);
+        assert.ok(callbackResult.location);
+        const clientCallbackUrl = new URL(callbackResult.location);
+        // Should redirect to the CLIENT's callback URL
+        assert.ok(clientCallbackUrl.href.startsWith(clientRedirectUri));
+        // Should include a proxy code (not the GitLab code)
+        const proxyCode = clientCallbackUrl.searchParams.get("code");
+        assert.ok(proxyCode);
+        assert.notStrictEqual(proxyCode, "gitlab-auth-code-xyz");
+        // Should restore the client's original state
+        assert.strictEqual(clientCallbackUrl.searchParams.get("state"), clientState);
+        // 4. Exchange proxy code for tokens
+        const tokenResult = await exchangeToken(mcpBaseUrl, clientId, proxyCode, clientPKCE.verifier, clientRedirectUri);
+        assert.strictEqual(tokenResult.status, 200);
+        assert.strictEqual(tokenResult.body.access_token, MOCK_ACCESS_TOKEN);
+        assert.strictEqual(tokenResult.body.refresh_token, MOCK_REFRESH_TOKEN);
+    });
+    // ---- One-time use proxy code -------------------------------------------
+    test("proxy code cannot be reused", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-reuse");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        const cb = await simulateGitLabCallback(mcpBaseUrl, "code-reuse", proxyState);
+        const proxyCode = new URL(cb.location).searchParams.get("code");
+        // First exchange succeeds
+        const first = await exchangeToken(mcpBaseUrl, clientId, proxyCode, clientPKCE.verifier, clientRedirectUri);
+        assert.strictEqual(first.status, 200);
+        // Second exchange with same code fails
+        const second = await exchangeToken(mcpBaseUrl, clientId, proxyCode, clientPKCE.verifier, clientRedirectUri);
+        assert.notStrictEqual(second.status, 200);
+    });
+    // ---- Client binding -----------------------------------------------------
+    test("proxy code cannot be redeemed by a different client_id", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const otherClientId = await registerClient(mcpBaseUrl, "http://localhost:19998/oauth/callback");
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-client-binding");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        const cb = await simulateGitLabCallback(mcpBaseUrl, "code-client-binding", proxyState);
+        const proxyCode = new URL(cb.location).searchParams.get("code");
+        const result = await exchangeToken(mcpBaseUrl, otherClientId, proxyCode, clientPKCE.verifier, clientRedirectUri);
+        assert.notStrictEqual(result.status, 200);
+    });
+    test("proxy code cannot be redeemed with a different redirect_uri", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-redirect-binding");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        const cb = await simulateGitLabCallback(mcpBaseUrl, "code-redirect-binding", proxyState);
+        const proxyCode = new URL(cb.location).searchParams.get("code");
+        const result = await exchangeToken(mcpBaseUrl, clientId, proxyCode, clientPKCE.verifier, "http://localhost:19998/oauth/callback");
+        assert.notStrictEqual(result.status, 200);
+    });
+    // ---- Unknown state parameter -------------------------------------------
+    test("callback with unknown state returns 400", async () => {
+        const result = await simulateGitLabCallback(mcpBaseUrl, "some-code", "unknown-state-value");
+        assert.strictEqual(result.status, 400);
+        assert.ok(result.body.includes("Unknown or expired"));
+    });
+    // ---- PKCE verification failure -----------------------------------------
+    test("token exchange with wrong code_verifier fails", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-pkce");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        const cb = await simulateGitLabCallback(mcpBaseUrl, "code-pkce", proxyState);
+        const proxyCode = new URL(cb.location).searchParams.get("code");
+        // Exchange with WRONG verifier
+        const result = await exchangeToken(mcpBaseUrl, clientId, proxyCode, "wrong-verifier-value", clientRedirectUri);
+        assert.notStrictEqual(result.status, 200);
+    });
+    // ---- PKCE verifier omitted ---------------------------------------------
+    test("token exchange without code_verifier fails when challenge was stored", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-no-verifier");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        const cb = await simulateGitLabCallback(mcpBaseUrl, "code-no-verifier", proxyState);
+        const proxyCode = new URL(cb.location).searchParams.get("code");
+        // Exchange WITHOUT verifier — should fail
+        const res = await fetch(`${mcpBaseUrl}/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/x-www-form-urlencoded" },
+            body: new URLSearchParams({
+                grant_type: "authorization_code",
+                client_id: clientId,
+                code: proxyCode,
+                redirect_uri: clientRedirectUri,
+            }).toString(),
+        });
+        assert.notStrictEqual(res.status, 200);
+    });
+    // ---- Replayed state parameter ------------------------------------------
+    test("state cannot be replayed after callback", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-replay");
+        const proxyState = gitlabUrl.searchParams.get("state");
+        // First callback succeeds
+        const first = await simulateGitLabCallback(mcpBaseUrl, "code-replay-1", proxyState);
+        assert.strictEqual(first.status, 302);
+        // Second callback with same state fails
+        const second = await simulateGitLabCallback(mcpBaseUrl, "code-replay-2", proxyState);
+        assert.strictEqual(second.status, 400);
+    });
+    // ---- Dual PKCE verification --------------------------------------------
+    test("proxy uses its own PKCE pair with GitLab", async () => {
+        const clientPKCE = generatePKCE();
+        const clientId = await registerClient(mcpBaseUrl, clientRedirectUri);
+        const gitlabUrl = await authorize(mcpBaseUrl, clientId, clientRedirectUri, clientPKCE.challenge, "state-dual-pkce");
+        // The code_challenge sent to GitLab should NOT be the client's challenge
+        const gitlabChallenge = gitlabUrl.searchParams.get("code_challenge");
+        assert.ok(gitlabChallenge);
+        assert.notStrictEqual(gitlabChallenge, clientPKCE.challenge);
+        // Complete the flow to verify the proxy verifier was sent to GitLab
+        const proxyState = gitlabUrl.searchParams.get("state");
+        await simulateGitLabCallback(mcpBaseUrl, "code-dual-pkce", proxyState);
+        // The token request to GitLab should have a code_verifier that matches
+        // the proxy challenge (not the client's verifier)
+        assert.ok(lastTokenRequest.code_verifier);
+        assert.notStrictEqual(lastTokenRequest.code_verifier, clientPKCE.verifier);
+        const computedChallenge = createHash("sha256")
+            .update(lastTokenRequest.code_verifier)
+            .digest("base64url");
+        assert.strictEqual(computedChallenge, gitlabChallenge);
+    });
+});

package/build/test/dynamic-routing-tests.js

@@ -230,6 +230,55 @@ describe('Dynamic Routing and Authentication Scenarios', () => {
             await validateToolCalls(client, headerMockServer, MOCK_TOKEN_HEADER);
             await client.disconnect();
         });
+        test('should preserve legacy tree array response and return keyset metadata when requested', async () => {
+            const client = new CustomHeaderClient({
+                headers: {
+                    'authorization': `Bearer ${MOCK_TOKEN_HEADER}`,
+                    'X-GitLab-API-URL': `${headerMockServer.getUrl()}/api/v4`,
+                }
+            });
+            await client.connect(mcpUrl);
+            headerMockServer.clearCustomHandlers();
+            headerMockServer.addMockHandler('get', '/projects/4/repository/tree', (req, res) => {
+                assert.strictEqual(req.headers['authorization'], `Bearer ${MOCK_TOKEN_HEADER}`);
+                assert.strictEqual(req.query.pagination, undefined);
+                res.json([createMockTreeItem('legacy-blob')]);
+            });
+            const legacyResult = await client.callTool('get_repository_tree', { project_id: '4' });
+            const legacyContent = JSON.parse(legacyResult.content[0].text);
+            assert.ok(Array.isArray(legacyContent));
+            assert.strictEqual(legacyContent[0].id, 'legacy-blob');
+            headerMockServer.clearCustomHandlers();
+            headerMockServer.addMockHandler('get', '/projects/4/repository/tree', (req, res) => {
+                assert.strictEqual(req.headers['authorization'], `Bearer ${MOCK_TOKEN_HEADER}`);
+                assert.strictEqual(req.query.pagination, 'keyset');
+                res.set('x-next-page-token', 'token-blob');
+                res.json([createMockTreeItem('keyset-blob')]);
+            });
+            const keysetResult = await client.callTool('get_repository_tree', {
+                project_id: '4',
+                pagination: 'keyset',
+            });
+            const keysetContent = JSON.parse(keysetResult.content[0].text);
+            assert.ok(!Array.isArray(keysetContent));
+            assert.strictEqual(keysetContent.items[0].id, 'keyset-blob');
+            assert.strictEqual(keysetContent.next_page_token, 'token-blob');
+            headerMockServer.clearCustomHandlers();
+            headerMockServer.addMockHandler('get', '/projects/4/repository/tree', (req, res) => {
+                assert.strictEqual(req.headers['authorization'], `Bearer ${MOCK_TOKEN_HEADER}`);
+                assert.strictEqual(req.query.pagination, 'keyset');
+                res.set('x-next-page', 'fallback-token');
+                res.json([createMockTreeItem('fallback-blob')]);
+            });
+            const fallbackResult = await client.callTool('get_repository_tree', {
+                project_id: '4',
+                pagination: 'keyset',
+            });
+            const fallbackContent = JSON.parse(fallbackResult.content[0].text);
+            assert.strictEqual(fallbackContent.items[0].id, 'fallback-blob');
+            assert.strictEqual(fallbackContent.next_page_token, 'fallback-token');
+            await client.disconnect();
+        });
     });
 });
 // Helper functions to create schema-compliant mock objects

package/build/test/schema-tests.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env ts-node
-import { GetFileContentsSchema, GitLabFileContentSchema, GitLabRepositorySchema, CreatePipelineSchema, CreateIssueNoteSchema, CreateMergeRequestEmojiReactionSchema, CreateIssueEmojiReactionSchema, DeleteMergeRequestEmojiReactionSchema, DeleteIssueEmojiReactionSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, CreateIssueSchema, ListIssuesSchema, ListMergeRequestsSchema, GitLabTreeItemSchema } from '../schemas.js';
+import { GetFileContentsSchema, GitLabFileContentSchema, GitLabRepositorySchema, CreatePipelineSchema, CreateIssueNoteSchema, CreateMergeRequestEmojiReactionSchema, CreateIssueEmojiReactionSchema, DeleteMergeRequestEmojiReactionSchema, DeleteIssueEmojiReactionSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, CreateIssueSchema, ListIssuesSchema, ListMergeRequestsSchema, GitLabTreeItemSchema, GetRepositoryTreeSchema } from '../schemas.js';
 function runGetFileContentsSchemaTests() {
     console.log('🧪 Testing GetFileContentsSchema...');
     const cases = [
@@ -625,6 +625,78 @@ function runGitLabTreeItemSchemaTests() {
     console.log(`\nResults: ${passed} passed, ${failed} failed`);
     return { passed, failed };
 }
+function runGetRepositoryTreeSchemaTests() {
+    console.log('\n=== GetRepositoryTree Schema Tests ===');
+    const cases = [
+        {
+            name: 'schema:get_repository_tree:minimal-project-id',
+            input: { project_id: 'my/project' },
+            expected: { project_id: 'my/project', path: undefined, ref: undefined, recursive: undefined, per_page: undefined, page_token: undefined, pagination: undefined },
+        },
+        {
+            name: 'schema:get_repository_tree:with-keyset-pagination',
+            input: { project_id: 'my/project', pagination: 'keyset', per_page: 100 },
+            expected: { project_id: 'my/project', pagination: 'keyset', per_page: 100 },
+        },
+        {
+            name: 'schema:get_repository_tree:page-token-for-next-page',
+            input: { project_id: 'my/project', pagination: 'keyset', per_page: 100, page_token: 'eyJpZCI6IjEyMyJ9' },
+            expected: { project_id: 'my/project', pagination: 'keyset', per_page: 100, page_token: 'eyJpZCI6IjEyMyJ9' },
+        },
+        {
+            name: 'schema:get_repository_tree:per-page-coerces-from-string',
+            input: { project_id: 'my/project', per_page: '50' },
+            expected: { project_id: 'my/project', per_page: 50 },
+        },
+        {
+            name: 'schema:get_repository_tree:recursive-coerces-from-string',
+            input: { project_id: 'my/project', recursive: 'true' },
+            expected: { project_id: 'my/project', recursive: true },
+        },
+        {
+            name: 'schema:get_repository_tree:with-path-and-ref',
+            input: { project_id: 'my/project', path: 'src/', ref: 'main' },
+            expected: { project_id: 'my/project', path: 'src/', ref: 'main' },
+        },
+    ];
+    let passed = 0;
+    let failed = 0;
+    cases.forEach(testCase => {
+        const result = { name: testCase.name, status: 'failed' };
+        const parsed = GetRepositoryTreeSchema.safeParse(testCase.input);
+        if (testCase.shouldFail) {
+            result.status = parsed.success ? 'failed' : 'passed';
+            if (parsed.success)
+                result.error = 'Expected schema validation to fail';
+        }
+        else if (parsed.success) {
+            const expected = testCase.expected || {};
+            const matches = Object.entries(expected).every(([key, value]) => {
+                const actual = parsed.data[key];
+                return JSON.stringify(actual) === JSON.stringify(value);
+            });
+            if (matches) {
+                result.status = 'passed';
+            }
+            else {
+                result.error = `Unexpected parsed result: ${JSON.stringify(parsed.data)}`;
+            }
+        }
+        else {
+            result.error = parsed.error?.message || 'Schema validation failed';
+        }
+        if (result.status === 'passed') {
+            passed++;
+            console.log(`✅ ${result.name}`);
+        }
+        else {
+            failed++;
+            console.log(`❌ ${result.name}: ${result.error}`);
+        }
+    });
+    console.log(`\nResults: ${passed} passed, ${failed} failed`);
+    return { passed, failed };
+}
 if (import.meta.url === `file://${process.argv[1]}`) {
     const getFileContentsResult = runGetFileContentsSchemaTests();
     const fileContentResult = runGitLabFileContentSchemaTests();
@@ -634,8 +706,9 @@ if (import.meta.url === `file://${process.argv[1]}`) {
     const repositorySchemaResult = runGitLabRepositorySchemaTests();
     const labelsCoercionResult = runLabelsCoercionSchemaTests();
     const treeItemResult = runGitLabTreeItemSchemaTests();
-    const totalPassed = getFileContentsResult.passed + fileContentResult.passed + createPipelineResult.passed + createIssueNoteResult.passed + emojiReactionResult.passed + repositorySchemaResult.passed + labelsCoercionResult.passed + treeItemResult.passed;
-    const totalFailed = getFileContentsResult.failed + fileContentResult.failed + createPipelineResult.failed + createIssueNoteResult.failed + emojiReactionResult.failed + repositorySchemaResult.failed + labelsCoercionResult.failed + treeItemResult.failed;
+    const repositoryTreeResult = runGetRepositoryTreeSchemaTests();
+    const totalPassed = getFileContentsResult.passed + fileContentResult.passed + createPipelineResult.passed + createIssueNoteResult.passed + emojiReactionResult.passed + repositorySchemaResult.passed + labelsCoercionResult.passed + treeItemResult.passed + repositoryTreeResult.passed;
+    const totalFailed = getFileContentsResult.failed + fileContentResult.failed + createPipelineResult.failed + createIssueNoteResult.failed + emojiReactionResult.failed + repositorySchemaResult.failed + labelsCoercionResult.failed + treeItemResult.failed + repositoryTreeResult.failed;
     console.log(`\nTotal Results: ${totalPassed} passed, ${totalFailed} failed`);
     if (totalFailed > 0) {
         process.exit(1);

package/package.json

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