@zereight/mcp-gitlab 2.1.5 → 2.1.7

package/build/index.js

@@ -1,5 +1,6 @@
 #!/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_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 { 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, OAUTH_STATELESS_CLIENT_TTL_SECONDS, OAUTH_STATELESS_MODE, OAUTH_STATELESS_PENDING_TTL_SECONDS, OAUTH_STATELESS_SESSION_TTL_SECONDS, OAUTH_STATELESS_STORED_TTL_SECONDS, 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 { loadKeyMaterialFromEnv, looksLikeStatelessSessionId, mintSessionId, openSessionId, } from "./stateless/index.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";
@@ -32,11 +33,37 @@ GitLabDiscussionNoteSchema, // Added
 GitLabDiscussionSchema, 
 // Draft Notes Schemas
 GitLabDraftNoteSchema, GitLabForkSchema, GitLabIssueLinkSchema, GitLabIssueSchema, GitLabIssueWithLinkDetailsSchema, GitLabMarkdownUploadSchema, GitLabMergeRequestSchema, GitLabMilestonesSchema, GitLabNamespaceExistsResponseSchema, GitLabNamespaceSchema, GitLabPipelineJobSchema, GitLabDeploymentSchema, GitLabEnvironmentSchema, GitLabPipelineSchema, GitLabPipelineTriggerJobSchema, GitLabProjectMemberSchema, GitLabProjectSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabSearchBlobResultSchema, GitLabSearchResponseSchema, GitLabTreeItemSchema, GitLabUserSchema, GitLabUsersResponseSchema, GitLabWikiPageSchema, GroupIteration, ListCommitsSchema, ListDraftNotesSchema, ListGroupIterationsSchema, ListGroupProjectsSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListLabelsSchema, ListMergeRequestDiffsSchema, // Added
-GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, GetGroupWikiPageSchema, ListGroupWikiPagesSchema, UpdateGroupWikiPageSchema, MarkdownUploadSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, ListWebhookEventsSchema, GetWebhookEventSchema, } from "./schemas.js";
+GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, GetGroupWikiPageSchema, ListGroupWikiPagesSchema, UpdateGroupWikiPageSchema, MarkdownUploadSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, ListTagsSchema, GetTagSchema, CreateTagSchema, DeleteTagSchema, GetTagSignatureSchema, GitLabTagSchema, GitLabTagSignatureSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, ListWebhookEventsSchema, GetWebhookEventSchema, } from "./schemas.js";
 import { randomUUID } from "node:crypto";
 import { pino } from "pino";
 const logger = pino({
     level: process.env.LOG_LEVEL || "info",
+    // Redact sensitive values that must never appear in logs. Covers both
+    // typical auth-context property names and common HTTP header-bag shapes
+    // that tool/fetch wrappers may include when logging errors.
+    redact: {
+        paths: [
+            "token",
+            "*.token",
+            "ctx.token",
+            "context.token",
+            "authData.token",
+            "auth.token",
+            "headers.authorization",
+            "headers.Authorization",
+            'headers["private-token"]',
+            'headers["Private-Token"]',
+            'headers["job-token"]',
+            'headers["JOB-TOKEN"]',
+            'headers["mcp-session-id"]',
+            'headers["Mcp-Session-Id"]',
+            "sessionId",
+            "*.sessionId",
+            "ctx.sessionId",
+            "context.sessionId",
+        ],
+        censor: "[REDACTED]",
+    },
     transport: {
         target: "pino-pretty",
         options: {
@@ -412,6 +439,97 @@ function validateConfiguration() {
 }
 let OAUTH_ACCESS_TOKEN = null;
 let oauthClient = null;
+/**
+ * Produce a safe short form of a session id for logs. Legacy UUIDs pass
+ * through; stateless sealed sids are truncated to the "v1.sid." prefix
+ * plus a handful of bytes of the ciphertext so operators can correlate
+ * flows without the log line carrying the sealed bearer token.
+ */
+function redactSessionIdForLog(sid) {
+    if (!sid)
+        return "<none>";
+    if (sid.startsWith("v1.sid."))
+        return "v1.sid.<redacted>";
+    // UUIDs / other formats are low-sensitivity; show first 8 chars.
+    return sid.length > 8 ? `${sid.slice(0, 8)}…` : sid;
+}
+/**
+ * Detect whether an MCP JSON-RPC request body represents an "initialize"
+ * request. Accepts both single-message and batch forms. Returns false on any
+ * unexpected shape — callers treat an ambiguous body as non-init, which is
+ * the safer default (it means the SDK will fail loudly rather than silently
+ * spawning a new session).
+ */
+function isInitializationRequestBody(body) {
+    if (!body)
+        return false;
+    const isInitObj = (m) => typeof m === "object" &&
+        m !== null &&
+        m.method === "initialize";
+    if (Array.isArray(body))
+        return body.some(isInitObj);
+    return isInitObj(body);
+}
+/**
+ * Normalize an `Mcp-Session-Id` header value.
+ *
+ * Node's HTTP types allow any request header to surface as `string[]` when
+ * the client sends it more than once. Casting to `string` and calling
+ * `.startsWith()` on an array throws `TypeError: startsWith is not a
+ * function`, which Express converts to a 500 — silently turning malformed
+ * requests into server errors and breaking the 401/404 semantics we
+ * carefully distinguish in stateless mode. A duplicated `Mcp-Session-Id` is
+ * also ill-formed at the protocol level: there is no well-defined way to
+ * pick between two values, so we reject arrays rather than guess.
+ *
+ * Empty-string is normalized to `undefined` so call sites can use truthy
+ * checks and `?? undefined`-style fallbacks uniformly.
+ *
+ * Exported for unit tests; otherwise used only by the /mcp handlers below.
+ */
+export function readMcpSessionIdHeader(req) {
+    const raw = req.headers["mcp-session-id"];
+    if (typeof raw !== "string")
+        return undefined;
+    return raw.length > 0 ? raw : undefined;
+}
+/**
+ * Loaded once at startup. Null when OAUTH_STATELESS_MODE is disabled.
+ * When set, the OAuth provider and (later phases) the Mcp-Session-Id path
+ * switch to signed/sealed opaque values instead of per-pod in-memory caches.
+ */
+let STATELESS_MATERIAL = null;
+try {
+    // Drive enablement from the already-resolved config flag so the CLI flag
+    // (--oauth-stateless-mode) is honored. Re-reading env.OAUTH_STATELESS_MODE
+    // inside the loader would silently ignore the CLI flag and leave
+    // STATELESS_MATERIAL null, falling back to per-pod state.
+    STATELESS_MATERIAL = loadKeyMaterialFromEnv(OAUTH_STATELESS_MODE);
+    if (OAUTH_STATELESS_MODE && STATELESS_MATERIAL) {
+        // Avoid logging anything that could leak key length / entropy details.
+        // Keep the message aligned with similar startup banners.
+        // eslint-disable-next-line no-console -- startup banner parity
+        console.error("[gitlab-mcp] stateless OAuth mode enabled");
+    }
+}
+catch (err) {
+    // eslint-disable-next-line no-console -- startup failure must be visible
+    console.error(`[gitlab-mcp] failed to load stateless secret: ${err.message}`);
+    process.exit(1);
+}
+/**
+ * True when this request is a candidate for the stateless sid-auth path:
+ * stateless mode is enabled, key material loaded, and the client sent an
+ * Mcp-Session-Id header. We deliberately key off *presence* (not validity)
+ * so malformed / expired / legacy sids still reach handleStatelessMcpRequest
+ * and get the intended 404 Session not found — rather than being masked by
+ * a 401 from the OAuth bearer middleware.
+ */
+export function hasStatelessSessionId(req) {
+    return Boolean(OAUTH_STATELESS_MODE &&
+        STATELESS_MATERIAL &&
+        readMcpSessionIdHeader(req));
+}
 /**
  * Ensure the OAuth token is valid before making an API call.
  * Refreshes the token lazily (only when a tool is actually called).
@@ -5582,6 +5700,92 @@ async function downloadReleaseAsset(projectId, tagName, directAssetPath) {
     await handleGitLabError(response);
     return await response.text();
 }
+/**
+ * List repository tags
+ *
+ * @param projectId The ID or URL-encoded path of the project
+ * @param options Optional parameters for filtering and pagination
+ * @returns Array of GitLab tags
+ */
+async function listTags(projectId, options = {}) {
+    const effectiveProjectId = getEffectiveProjectId(projectId);
+    const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags`);
+    Object.entries(options).forEach(([key, value]) => {
+        if (value !== undefined) {
+            url.searchParams.append(key, value.toString());
+        }
+    });
+    const response = await fetch(url.toString(), {
+        ...getFetchConfig(),
+    });
+    await handleGitLabError(response);
+    const data = await response.json();
+    return GitLabTagSchema.array().parse(data);
+}
+/**
+ * Get a repository tag by name
+ *
+ * @param projectId The ID or URL-encoded path of the project
+ * @param tagName The name of the tag
+ * @returns GitLab tag
+ */
+async function getTag(projectId, tagName) {
+    const effectiveProjectId = getEffectiveProjectId(projectId);
+    const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags/${encodeURIComponent(tagName)}`, {
+        ...getFetchConfig(),
+    });
+    await handleGitLabError(response);
+    const data = await response.json();
+    return GitLabTagSchema.parse(data);
+}
+/**
+ * Create a new repository tag
+ *
+ * @param projectId The ID or URL-encoded path of the project
+ * @param options Options for creating the tag
+ * @returns Created GitLab tag
+ */
+async function createTag(projectId, options) {
+    const effectiveProjectId = getEffectiveProjectId(projectId);
+    const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags`, {
+        ...getFetchConfig(),
+        method: "POST",
+        body: JSON.stringify(options),
+    });
+    await handleGitLabError(response);
+    const data = await response.json();
+    return GitLabTagSchema.parse(data);
+}
+/**
+ * Delete a repository tag
+ *
+ * @param projectId The ID or URL-encoded path of the project
+ * @param tagName The name of the tag
+ */
+async function deleteTag(projectId, tagName) {
+    const effectiveProjectId = getEffectiveProjectId(projectId);
+    const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags/${encodeURIComponent(tagName)}`, {
+        ...getFetchConfig(),
+        method: "DELETE",
+    });
+    await handleGitLabError(response);
+}
+/**
+ * Get the signature of a repository tag
+ *
+ * @param projectId The ID or URL-encoded path of the project
+ * @param tagName The name of the tag
+ * @returns Tag signature
+ */
+async function getTagSignature(projectId, tagName) {
+    const effectiveProjectId = getEffectiveProjectId(projectId);
+    const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeURIComponent(effectiveProjectId)}/repository/tags/${encodeURIComponent(tagName)}/signature`, {
+        ...getFetchConfig(),
+    });
+    await handleGitLabError(response);
+    const data = await response.json();
+    return GitLabTagSignatureSchema.parse(data);
+}
 // Request handlers are now registered inside createServer() factory function
 // to ensure each transport connection gets its own Server instance (GHSA-345p-7cg4-v4c7).
 async function handleToolCall(params) {
@@ -7073,6 +7277,48 @@ async function handleToolCall(params) {
                     content: [{ type: "text", text: assetContent }],
                 };
             }
+            case "list_tags": {
+                const args = ListTagsSchema.parse(params.arguments);
+                const { project_id, ...options } = args;
+                const tags = await listTags(project_id, options);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(tags, null, 2) }],
+                };
+            }
+            case "get_tag": {
+                const args = GetTagSchema.parse(params.arguments);
+                const tag = await getTag(args.project_id, args.tag_name);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(tag, null, 2) }],
+                };
+            }
+            case "create_tag": {
+                const args = CreateTagSchema.parse(params.arguments);
+                const { project_id, ...options } = args;
+                const tag = await createTag(project_id, options);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(tag, null, 2) }],
+                };
+            }
+            case "delete_tag": {
+                const args = DeleteTagSchema.parse(params.arguments);
+                await deleteTag(args.project_id, args.tag_name);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({ status: "success", message: `Tag '${args.tag_name}' deleted successfully` }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case "get_tag_signature": {
+                const args = GetTagSignatureSchema.parse(params.arguments);
+                const signature = await getTagSignature(args.project_id, args.tag_name);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(signature, null, 2) }],
+                };
+            }
             case "list_webhooks": {
                 const args = ListWebhooksSchema.parse(params.arguments);
                 const webhooks = await listWebhooks(args);
@@ -7238,6 +7484,12 @@ async function startStreamableHTTPServer() {
         requestsProcessed: 0,
         rejectedByRateLimit: 0,
         rejectedByCapacity: 0,
+        // Stateless-mode counters. Only non-zero when OAUTH_STATELESS_MODE=true.
+        statelessRequests: 0,
+        statelessAuthFromHeader: 0, // fresh Authorization/Private-Token/JOB-TOKEN present
+        statelessAuthFromSealedSid: 0, // auth reconstructed from sealed Mcp-Session-Id
+        statelessAuthFailures: 0, // neither source yielded usable auth
+        statelessSidRotated: 0, // minted a new sid because fresh auth was present
     };
     // Rate limiting per session
     const sessionRequestCounts = {};
@@ -7362,6 +7614,189 @@ async function startStreamableHTTPServer() {
         delete authBySession[sessionId];
         clearAuthTimeout(sessionId);
     };
+    /**
+     * Stateless-mode handler for /mcp POSTs.
+     *
+     * The MCP Streamable HTTP SDK can run in "stateless mode" when
+     * `sessionIdGenerator` is undefined — it creates no session state and
+     * short-circuits session validation. We exploit that by driving the
+     * session identity ourselves via an AEAD-sealed `Mcp-Session-Id`:
+     *
+     *   1. Every request gets a freshly-instantiated transport (SDK-stateless).
+     *   2. The caller's auth is derived from:
+     *      - live request headers (preferred; handles OAuth token refresh),
+     *      - or the sealed Mcp-Session-Id (for requests that omit headers).
+     *   3. We assign `transport.sessionId = <sealed>` so the SDK emits the
+     *      Mcp-Session-Id response header for the client to echo back.
+     *   4. The AsyncLocalStorage auth context is populated from the derived
+     *      auth, bypassing authBySession / authTimeouts entirely.
+     *
+     * Rate limiting is explicitly disabled in stateless mode (per-pod counters
+     * would yield a loose global bound — operators can rate-limit upstream).
+     */
+    const handleStatelessMcpRequest = async (req, res, material, sessionTtlSeconds) => {
+        metrics.statelessRequests++;
+        // Step 1: derive the effective auth for this request.
+        // Priority: live headers > sealed sid. This lets clients refresh OAuth
+        // tokens without re-initializing their MCP session.
+        const headerAuth = parseAuthHeaders(req);
+        // In GITLAB_MCP_OAUTH mode, req.auth may be populated by requireBearerAuth.
+        // Use it when headerAuth is null (no Private-Token / JOB-TOKEN / Authorization).
+        let effective = null;
+        let freshAuthPresent = false;
+        if (headerAuth) {
+            effective = {
+                header: headerAuth.header,
+                token: headerAuth.token,
+                apiUrl: headerAuth.apiUrl,
+            };
+            freshAuthPresent = true;
+        }
+        else if (GITLAB_MCP_OAUTH) {
+            const authInfo = req.auth;
+            if (authInfo?.token) {
+                effective = {
+                    header: "Authorization",
+                    token: authInfo.token,
+                    apiUrl: GITLAB_API_URL,
+                };
+                freshAuthPresent = true;
+            }
+        }
+        if (freshAuthPresent)
+            metrics.statelessAuthFromHeader++;
+        // Fall back to the sealed sid when no live headers are present. Track
+        // whether a sid was presented but rejected (expired / tampered / wrong
+        // key / malformed) so we can return 404 below — the MCP Streamable HTTP
+        // contract is that session-bound requests get 404 on a terminated session,
+        // which tells the client to re-initialize. Returning 401 here would
+        // instead trigger the client's auth-failure path and break automatic
+        // recovery after inactivity TTL expiry.
+        const incomingSid = readMcpSessionIdHeader(req);
+        let sidPresentedButInvalid = false;
+        if (!effective && incomingSid) {
+            if (looksLikeStatelessSessionId(incomingSid)) {
+                const opened = openSessionId(material, incomingSid, sessionTtlSeconds);
+                if (opened) {
+                    effective = { header: opened.h, token: opened.t, apiUrl: opened.u };
+                    metrics.statelessAuthFromSealedSid++;
+                }
+                else {
+                    sidPresentedButInvalid = true;
+                }
+            }
+            else {
+                // Non-stateless-shaped sid (e.g. a UUID from a prior stateful run, or
+                // garbage). From the caller's perspective the session is unknown — we
+                // surface that as "session ended" rather than as an auth problem.
+                sidPresentedButInvalid = true;
+            }
+        }
+        if (!effective) {
+            metrics.authFailures++;
+            metrics.statelessAuthFailures++;
+            if (sidPresentedButInvalid) {
+                // Per MCP Streamable HTTP: a 404 on a session-bound request signals
+                // "session ended, re-initialize". The inactivity TTL expiring looks
+                // identical to a session the server no longer recognizes — in both
+                // cases the client should start a fresh initialize handshake.
+                res.status(404).json({
+                    error: "Session not found",
+                    message: "Stateless mode: Mcp-Session-Id is expired, invalid, or from a " +
+                        "different key. Re-initialize to obtain a new session id.",
+                });
+                return;
+            }
+            res.status(401).json({
+                error: "Authentication required",
+                message: "Stateless mode: provide Private-Token, JOB-TOKEN, or Authorization " +
+                    "header, or a valid Mcp-Session-Id from a previous response.",
+            });
+            return;
+        }
+        // Step 2: detect whether this is the initialization request. The MCP SDK
+        // only emits an Mcp-Session-Id response header when the transport is in
+        // SDK-stateful mode, which requires a sessionIdGenerator. We use
+        // SDK-stateful mode for init requests (so the client receives the sid)
+        // and SDK-stateless mode for subsequent requests (to avoid the SDK's
+        // per-instance _initialized / sessionId equality checks that would reject
+        // a freshly-constructed transport).
+        const isInit = isInitializationRequestBody(req.body);
+        // Always mint a fresh sid so the embedded iat advances on every request.
+        // This makes OAUTH_STATELESS_SESSION_TTL_SECONDS behave as an inactivity
+        // timeout rather than an absolute-age cap — matching the legacy
+        // setAuthTimeout semantics. Reusing the incoming sid would regress
+        // long-lived sessions that authenticate via sealed-sid replay (typical
+        // REMOTE_AUTHORIZATION flow after init).
+        const freshSid = mintSessionId(material, {
+            header: effective.header,
+            token: effective.token,
+            apiUrl: effective.apiUrl,
+        });
+        if (freshAuthPresent) {
+            metrics.statelessSidRotated++;
+        }
+        logger.debug({
+            sidPrefix: redactSessionIdForLog(freshSid),
+            freshAuthPresent,
+            header: effective.header,
+        }, "stateless /mcp request");
+        // Step 3: build the AsyncLocalStorage context so buildAuthHeaders and
+        // getEffectiveApiUrl read from the derived auth.
+        const ctx = {
+            sessionId: freshSid,
+            header: effective.header,
+            token: effective.token,
+            lastUsed: Date.now(),
+            apiUrl: effective.apiUrl,
+        };
+        // Step 4: create a fresh transport per request.
+        const transport = isInit
+            ? new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => freshSid,
+            })
+            : new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined, // SDK stateless mode for non-init
+            });
+        // For non-init requests the SDK runs in its internal stateless mode and
+        // does not emit an Mcp-Session-Id response header. We pre-set the
+        // freshly minted sid on the Express response so clients can adopt the
+        // latest sid (and its advanced iat) on every response. Headers passed
+        // to the SDK's writeHead() call are merged with pre-set headers per
+        // Node.js semantics, so this does not clobber SDK-managed values.
+        // Without this, the inactivity-timeout semantics of
+        // OAUTH_STATELESS_SESSION_TTL_SECONDS silently regress to an
+        // absolute-age cap for sid-only auth flows.
+        if (!isInit) {
+            res.setHeader("Mcp-Session-Id", freshSid);
+        }
+        const serverInstance = createServer();
+        await serverInstance.connect(transport);
+        await sessionAuthStore.run(ctx, async () => {
+            try {
+                await transport.handleRequest(req, res, req.body);
+            }
+            catch (err) {
+                logger.error({ err }, "stateless /mcp error");
+                if (!res.headersSent) {
+                    res.status(500).json({
+                        error: "Internal server error",
+                        message: err instanceof Error ? err.message : "Unknown error",
+                    });
+                }
+            }
+            finally {
+                // Fresh transport per request — always close to release any stream
+                // resources. The SDK treats close() as idempotent.
+                try {
+                    await transport.close();
+                }
+                catch {
+                    // ignore
+                }
+            }
+        });
+    };
     // Configure Express middleware
     app.use(express.json());
     // MCP OAuth — mount auth router and prepare bearer-auth middleware
@@ -7374,7 +7809,15 @@ async function startStreamableHTTPServer() {
         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 statelessOptions = OAUTH_STATELESS_MODE && STATELESS_MATERIAL
+            ? {
+                material: STATELESS_MATERIAL,
+                clientTtlSeconds: OAUTH_STATELESS_CLIENT_TTL_SECONDS,
+                pendingTtlSeconds: OAUTH_STATELESS_PENDING_TTL_SECONDS,
+                storedTtlSeconds: OAUTH_STATELESS_STORED_TTL_SECONDS,
+            }
+            : null;
+        const oauthProvider = createGitLabOAuthProvider(gitlabBaseUrl, GITLAB_OAUTH_APP_ID, "GitLab MCP Server", GITLAB_READ_ONLY_MODE, GITLAB_OAUTH_SCOPES, GITLAB_OAUTH_CALLBACK_PROXY, callbackUrl, statelessOptions);
         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.
@@ -7467,14 +7910,40 @@ async function startStreamableHTTPServer() {
                 });
                 return;
             }
+            // Stateless-mode sid bypass: when the client sends only an
+            // Mcp-Session-Id (no live Authorization), let handleStatelessMcpRequest
+            // open the sealed sid. Without this, requireBearerAuth would 401
+            // before the handler can reconstruct auth from the sid — breaking
+            // sid-only follow-up requests across pods under GITLAB_MCP_OAUTH.
+            //
+            // We still run oauthBearerAuth when an Authorization header IS
+            // present alongside the sid, so a client refreshing its OAuth token
+            // gets the new token validated normally. We also key this off
+            // header *presence* (not validity): malformed / expired / legacy
+            // sids still reach the handler and get the intended 404 Session
+            // not found response rather than being masked by a 401 here.
+            if (hasStatelessSessionId(req) && !req.headers.authorization) {
+                next();
+                return;
+            }
             oauthBearerAuth(req, res, next);
         }
         : (_req, _res, next) => next();
     // Streamable HTTP endpoint - handles both session creation and message handling
     app.post("/mcp", mcpBearerAuth, async (req, res) => {
-        const sessionId = req.headers["mcp-session-id"];
+        const sessionId = readMcpSessionIdHeader(req);
         // Track request
         metrics.requestsProcessed++;
+        // Stateless-mode branch: bypass authBySession / streamableTransports
+        // entirely and derive the session auth from either the current request
+        // headers (init) or a sealed Mcp-Session-Id (subsequent requests).
+        // Rate limiting is disabled here because there is no shared counter.
+        if (OAUTH_STATELESS_MODE &&
+            STATELESS_MATERIAL &&
+            (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH)) {
+            await handleStatelessMcpRequest(req, res, STATELESS_MATERIAL, OAUTH_STATELESS_SESSION_TTL_SECONDS);
+            return;
+        }
         // Rate limiting check for existing sessions
         if ((REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) && sessionId && !checkRateLimit(sessionId)) {
             metrics.rejectedByRateLimit++;
@@ -7697,6 +8166,8 @@ async function startStreamableHTTPServer() {
                 sessionTimeoutSeconds: SESSION_TIMEOUT_SECONDS,
                 remoteAuthEnabled: REMOTE_AUTHORIZATION,
                 mcpOAuthEnabled: GITLAB_MCP_OAUTH,
+                statelessModeEnabled: OAUTH_STATELESS_MODE && STATELESS_MATERIAL !== null,
+                statelessRotationKey: OAUTH_STATELESS_MODE && STATELESS_MATERIAL?.previous != null,
             },
         });
     });
@@ -7711,8 +8182,8 @@ async function startStreamableHTTPServer() {
         });
     });
     // to delete a mcp server session explicitly
-    app.delete("/mcp", async (req, res) => {
-        const sessionId = req.headers["mcp-session-id"];
+    app.delete("/mcp", mcpBearerAuth, async (req, res) => {
+        const sessionId = readMcpSessionIdHeader(req);
         if (!sessionId) {
             res.status(400).json({ error: "mcp-session-id header is required" });
             return;