@zereight/mcp-gitlab 2.1.21 → 2.1.23

package/build/scripts/generate-tool-docs.js

@@ -0,0 +1,404 @@
+#!/usr/bin/env tsx
+/**
+ * Generate per-group tool reference pages under docs/tools/ from the
+ * authoritative tool registry (tools/registry.ts).
+ *
+ * Run with: npx tsx scripts/generate-tool-docs.ts
+ * Or via:   make tools-docs
+ */
+import { writeFileSync, mkdirSync, readdirSync, unlinkSync, statSync } from "node:fs";
+import { join, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { allTools, readOnlyTools, TOOLSET_DEFINITIONS } from "../tools/registry.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "..");
+const OUT_DIR = join(REPO_ROOT, "docs", "tools");
+// Legacy single-group env flags that pre-date GITLAB_TOOLSETS.
+// Only three groups have these for backward compatibility; everything else
+// opt-in is configured via GITLAB_TOOLSETS / GITLAB_TOOLS / discover_tools.
+const LEGACY_TOGGLE_ENV = {
+    pipelines: "USE_PIPELINE",
+    milestones: "USE_MILESTONE",
+    wiki: "USE_GITLAB_WIKI",
+};
+function isDefaultToolset(id) {
+    return TOOLSET_DEFINITIONS.find(d => d.id === id)?.isDefault ?? false;
+}
+function computeToggleNote(id) {
+    if (isDefaultToolset(id))
+        return undefined;
+    // Synthetic group for tools not in any TOOLSET_DEFINITIONS entry.
+    // discover_tools is always exposed; execute_graphql is opt-in via GITLAB_TOOLS.
+    if (id === "meta") {
+        return "Mixed availability. `discover_tools` is always exposed (the server re-adds it after every toolset filter). `execute_graphql` is not part of any toolset — enable it explicitly with `GITLAB_TOOLS=execute_graphql`.";
+    }
+    const legacy = LEGACY_TOGGLE_ENV[id];
+    if (legacy) {
+        return `Opt-in. Enable via \`GITLAB_TOOLSETS=${id}\` (or \`GITLAB_TOOLSETS=all\`), or use the legacy \`${legacy}=true\` flag for backward compatibility.`;
+    }
+    return `Opt-in. Enable via \`GITLAB_TOOLSETS=${id}\` (or \`GITLAB_TOOLSETS=all\`), list individual tools in \`GITLAB_TOOLS=\`, or activate at runtime with the \`discover_tools\` MCP tool.`;
+}
+const GROUP_META = {
+    merge_requests: {
+        title: "Merge Requests",
+        blurb: "MR lifecycle — create, update, merge, approve, plus diff/conflict inspection and the full discussion/note/draft API.",
+    },
+    issues: {
+        title: "Issues",
+        blurb: "Issue CRUD, links, discussions and notes, todos, and emoji reactions.",
+    },
+    repositories: {
+        title: "Projects & Files",
+        blurb: "Project search/creation/fork plus the Files API for reading and writing repository content without shelling out to git.",
+    },
+    branches: {
+        title: "Branches & Commits",
+        blurb: "Branch management, commit listing/inspection, file blame, and CI commit-status manipulation.",
+    },
+    projects: {
+        title: "Projects & Namespaces",
+        blurb: "Project/namespace listing, member queries, group iterations, and server health.",
+    },
+    labels: {
+        title: "Labels",
+        blurb: "Project label CRUD.",
+    },
+    ci: {
+        title: "CI Lint",
+        blurb: "Validate `.gitlab-ci.yml` snippets and project pipeline configs.",
+    },
+    groups: {
+        title: "Groups",
+        blurb: "Create new groups and subgroups.",
+    },
+    pipelines: {
+        title: "Pipelines, Jobs & Deployments",
+        blurb: "Pipeline + job control (trigger, retry, cancel, play manual jobs, fetch logs/artifacts), and the deployments/environments view.",
+    },
+    milestones: {
+        title: "Milestones",
+        blurb: "Project milestone CRUD plus associated issues/MRs and burndown events.",
+    },
+    wiki: {
+        title: "Wiki",
+        blurb: "Project and group wiki page CRUD. Attachment uploads where supported.",
+    },
+    releases: {
+        title: "Releases",
+        blurb: "Release lifecycle, release evidence, and asset download.",
+    },
+    tags: {
+        title: "Tags",
+        blurb: "Tag listing, creation, deletion, and signature inspection.",
+    },
+    users: {
+        title: "Users & Events",
+        blurb: "User lookup, the authenticated user (`whoami`), event streams, and markdown attachment upload/download.",
+    },
+    workitems: {
+        title: "Work Items",
+        blurb: "Modern unified API for issues, tasks, incidents, and other typed work items — including notes, emoji reactions, and incident timeline events.",
+    },
+    webhooks: {
+        title: "Webhooks",
+        blurb: "List webhooks configured on projects or groups, and inspect recent webhook events.",
+    },
+    search: {
+        title: "Search",
+        blurb: "Code search across all visible projects, a specific project, or a specific group.",
+    },
+    variables: {
+        title: "Variables",
+        blurb: "Project and group CI/CD variable CRUD.",
+    },
+    dependency_proxy: {
+        title: "Dependency Proxy",
+        blurb: "Inspect and manage the GitLab dependency proxy cache settings, blob storage, and purge operations.",
+    },
+};
+const GROUP_ORDER = [
+    "projects",
+    "repositories",
+    "branches",
+    "groups",
+    "merge_requests",
+    "issues",
+    "labels",
+    "workitems",
+    "ci",
+    "pipelines",
+    "milestones",
+    "wiki",
+    "releases",
+    "tags",
+    "users",
+    "variables",
+    "webhooks",
+    "search",
+    "dependency_proxy",
+];
+// Authoritative classification — uses the `readOnlyTools` set from
+// tools/registry.ts. That set is what the server itself consults to decide
+// which tools survive `GITLAB_READ_ONLY_MODE=true`, so the badges here
+// match real runtime behavior exactly (no prefix heuristics).
+function classify(name) {
+    return readOnlyTools.has(name) ? "read" : "write";
+}
+function rwBadge(name) {
+    return classify(name) === "read" ? "📖 Read-only" : "✏️ Writes";
+}
+function describeType(prop) {
+    if (prop.enum) {
+        return `enum (\`${prop.enum.map(String).join("` \\| `")}\`)`;
+    }
+    if (prop.anyOf || prop.oneOf) {
+        const variants = (prop.anyOf || prop.oneOf || []).map(describeType).filter(Boolean);
+        return variants.join(" \\| ") || "any";
+    }
+    if (Array.isArray(prop.type)) {
+        return prop.type.join(" \\| ");
+    }
+    if (prop.type === "array") {
+        return `array<${prop.items ? describeType(prop.items) : "any"}>`;
+    }
+    if (prop.format && prop.type) {
+        return `${prop.type} (${prop.format})`;
+    }
+    return prop.type || "any";
+}
+function escapePipe(text) {
+    return text.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function paramTable(schema) {
+    if (!schema || !schema.properties || Object.keys(schema.properties).length === 0) {
+        return "_No parameters._";
+    }
+    const required = new Set(schema.required || []);
+    const rows = ["| Parameter | Type | Required | Description |", "|---|---|:-:|---|"];
+    for (const [name, prop] of Object.entries(schema.properties)) {
+        const type = describeType(prop);
+        const req = required.has(name) ? "✓" : "";
+        const desc = escapePipe(prop.description || "");
+        rows.push(`| \`${name}\` | ${type} | ${req} | ${desc} |`);
+    }
+    return rows.join("\n");
+}
+function toolSection(name, description, schema) {
+    return [
+        `### \`${name}\``,
+        "",
+        `*${rwBadge(name)}*`,
+        "",
+        description,
+        "",
+        "**Parameters**",
+        "",
+        paramTable(schema),
+        "",
+    ].join("\n");
+}
+function buildGroupPage(id, toolNames) {
+    const meta = GROUP_META[id];
+    const lines = [`# ${meta.title}`, "", meta.blurb, ""];
+    const toggle = computeToggleNote(id);
+    if (toggle) {
+        lines.push(`!!! note "Feature toggle"`);
+        lines.push(`    ${toggle}`);
+        lines.push("");
+    }
+    // Quick index
+    lines.push("## Tools in this group");
+    lines.push("");
+    for (const name of toolNames) {
+        lines.push(`- [\`${name}\`](#${name.replace(/_/g, "_")}) — ${rwBadge(name)}`);
+    }
+    lines.push("");
+    lines.push("---");
+    lines.push("");
+    for (const name of toolNames) {
+        const tool = allTools.find(t => t.name === name);
+        if (!tool) {
+            throw new Error(`Tool '${name}' referenced in toolset '${id}' but missing from allTools registry`);
+        }
+        lines.push(toolSection(name, tool.description, tool.inputSchema));
+    }
+    return lines.join("\n");
+}
+function buildToggleSection(groupedToolsList) {
+    const grouped = groupedToolsList.filter(([id]) => GROUP_META[id]);
+    const defaults = grouped.filter(([id]) => isDefaultToolset(id));
+    const optins = grouped.filter(([id]) => !isDefaultToolset(id));
+    const formatList = (items) => items
+        .map(([id]) => {
+        const slug = id.replace(/_/g, "-");
+        const legacy = LEGACY_TOGGLE_ENV[id];
+        const suffix = legacy ? ` (also \`${legacy}=true\`)` : "";
+        return `[${GROUP_META[id].title}](${slug}.md)${suffix}`;
+    })
+        .join(", ");
+    return [
+        "| Status | Groups |",
+        "|---|---|",
+        `| **Default** — always exposed | ${formatList(defaults)} |`,
+        `| **Opt-in** — must be enabled | ${formatList(optins)} |`,
+        "",
+        "**How to enable opt-in groups** (any one is sufficient):",
+        "",
+        "- `GITLAB_TOOLSETS=<group,…>` — comma-separated toolset IDs.",
+        "- `GITLAB_TOOLSETS=all` — enables every group.",
+        "- `GITLAB_TOOLS=<tool,…>` — enables individual tools regardless of group.",
+        "- `USE_PIPELINE=true` / `USE_MILESTONE=true` / `USE_GITLAB_WIKI=true` —" +
+            " legacy single-group flags (Pipelines, Milestones, Wiki only).",
+        "- Call the `discover_tools` MCP tool at runtime to activate categories" +
+            " for the current session.",
+    ];
+}
+function buildIndexPage(groupedToolsList) {
+    const lines = [
+        "# Tools Reference",
+        "",
+        "Complete catalog of every tool the GitLab MCP server exposes.",
+        "",
+        "> **Setup first** — if you haven't connected your Personal Access Token or",
+        "> OAuth credentials yet, follow one of the [client setup guides](../clients/claude-code.md)",
+        "> or read [Getting Started](../getting-started/index.md). Tools listed below",
+        "> will be unavailable until the server is authenticated.",
+        "",
+        "## Feature toggles",
+        "",
+        "Toolsets are split into a **default** set (exposed automatically) and an",
+        "**opt-in** set (must be explicitly enabled). The lists below are derived",
+        "directly from `TOOLSET_DEFINITIONS` in",
+        "[`tools/registry.ts`](https://github.com/zereight/gitlab-mcp/blob/main/tools/registry.ts).",
+        "",
+        ...buildToggleSection(groupedToolsList),
+        "",
+        "Read-only mode (`GITLAB_READ_ONLY_MODE=true`) hides every write tool",
+        "regardless of toggles. See [Environment Variables](../configuration/environment-variables.md)",
+        "and [CLI Arguments](../getting-started/cli-arguments.md) for the full list.",
+        "",
+        "## Legend",
+        "",
+        "| Marker | Meaning |",
+        "|---|---|",
+        "| 📖 | **Read-only** — fetches data, does not modify GitLab state. Safe to invoke freely. |",
+        "| ✏️ | **Writes** — creates, updates, or deletes data on GitLab. Confirm intent before running. |",
+        "",
+        "## Browse by group",
+        "",
+        "Each group has its own page with full parameter tables — click any tool name to jump to its details, or click the group title for the per-group view.",
+        "",
+    ];
+    for (const [id, tools] of groupedToolsList) {
+        const meta = GROUP_META[id];
+        const slug = id.replace(/_/g, "-");
+        lines.push(`### [${meta.title}](${slug}.md)`);
+        lines.push("");
+        lines.push(`${meta.blurb} *(${tools.length} tools)*`);
+        lines.push("");
+        const toggle = computeToggleNote(id);
+        if (toggle) {
+            lines.push(`> ${toggle}`);
+            lines.push("");
+        }
+        lines.push("| Tool | What it does | R/W |");
+        lines.push("|---|---|:-:|");
+        for (const name of tools) {
+            const tool = allTools.find(t => t.name === name);
+            if (!tool)
+                continue;
+            const desc = escapePipe(tool.description);
+            const marker = classify(name) === "read" ? "📖" : "✏️";
+            lines.push(`| [\`${name}\`](${slug}.md#${name}) | ${desc} | ${marker} |`);
+        }
+        lines.push("");
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push("## Argument schemas");
+    lines.push("");
+    lines.push("Each group page includes a parameter table per tool, generated from");
+    lines.push("the authoritative Zod schemas in");
+    lines.push("[`schemas.ts`](https://github.com/zereight/gitlab-mcp/blob/main/schemas.ts).");
+    lines.push("For runtime schema inspection from a connected MCP client, call the");
+    lines.push("`discover_tools` tool.");
+    return lines.join("\n");
+}
+// --- Main -----------------------------------------------------------------
+function main() {
+    mkdirSync(OUT_DIR, { recursive: true });
+    // Clean previously generated per-group files (keep index.md until last)
+    for (const file of readdirSync(OUT_DIR)) {
+        const full = join(OUT_DIR, file);
+        if (statSync(full).isFile() && file.endsWith(".md")) {
+            unlinkSync(full);
+        }
+    }
+    const grouped = [];
+    const allCategorizedNames = new Set();
+    for (const id of GROUP_ORDER) {
+        const def = TOOLSET_DEFINITIONS.find(d => d.id === id);
+        if (!def) {
+            throw new Error(`Toolset '${id}' listed in GROUP_ORDER but missing from TOOLSET_DEFINITIONS — keep them in sync`);
+        }
+        // Preserve insertion order from TOOLSET_DEFINITIONS
+        const tools = [...def.tools];
+        for (const t of tools)
+            allCategorizedNames.add(t);
+        grouped.push([id, tools]);
+        const page = buildGroupPage(id, tools);
+        const slug = id.replace(/_/g, "-");
+        writeFileSync(join(OUT_DIR, `${slug}.md`), page);
+        console.log(`generated docs/tools/${slug}.md — ${tools.length} tools`);
+    }
+    // Tools NOT in any toolset (e.g., execute_graphql, discover_tools)
+    const uncategorized = allTools.map(t => t.name).filter(n => !allCategorizedNames.has(n));
+    if (uncategorized.length > 0) {
+        const metaToggle = computeToggleNote("meta");
+        const lines = [
+            `# Meta & GraphQL`,
+            "",
+            "Tools the MCP exposes that aren't tied to a specific GitLab feature group — server diagnostics and the GraphQL escape hatch.",
+            "",
+        ];
+        if (metaToggle) {
+            lines.push(`!!! note "Feature toggle"`);
+            lines.push(`    ${metaToggle}`);
+            lines.push("");
+        }
+        lines.push("## Tools in this group");
+        lines.push("");
+        for (const name of uncategorized) {
+            lines.push(`- [\`${name}\`](#${name}) — ${rwBadge(name)}`);
+        }
+        lines.push("");
+        lines.push("---");
+        lines.push("");
+        for (const name of uncategorized) {
+            const tool = allTools.find(t => t.name === name);
+            if (!tool) {
+                throw new Error(`Uncategorized tool '${name}' missing from allTools registry`);
+            }
+            lines.push(toolSection(name, tool.description, tool.inputSchema));
+        }
+        writeFileSync(join(OUT_DIR, "meta.md"), lines.join("\n"));
+        console.log(`generated docs/tools/meta.md — ${uncategorized.length} tools`);
+        grouped.push(["meta", uncategorized]);
+        GROUP_META["meta"] = {
+            title: "Meta & GraphQL",
+            blurb: "Server diagnostics, tool discovery, and the GraphQL escape hatch.",
+        };
+    }
+    writeFileSync(join(OUT_DIR, "index.md"), buildIndexPage(grouped));
+    console.log(`generated docs/tools/index.md`);
+    // Emit nav fragment so you can paste it into mkdocs.yml if needed
+    console.log("\n--- mkdocs.yml nav fragment ---");
+    console.log("  - Tools:");
+    console.log("      - Overview: tools/index.md");
+    for (const [id] of grouped) {
+        const meta = GROUP_META[id];
+        const slug = id.replace(/_/g, "-");
+        console.log(`      - ${meta.title}: tools/${slug}.md`);
+    }
+}
+main();

package/build/test/config-allowed-groups.test.js

@@ -0,0 +1,97 @@
+/**
+ * Tests for GITLAB_OAUTH_ALLOWED_GROUPS config resolution.
+ *
+ * Verifies that:
+ *   - The new GITLAB_OAUTH_ALLOWED_GROUPS env var is preferred when set.
+ *   - The deprecated GITLAB_ALLOWED_GROUPS is accepted as a fallback and
+ *     sets the deprecation flag so callers can emit a warning.
+ *   - When both are set, the new var wins and GITLAB_ALLOWED_GROUPS_RAW remains
+ *     set, so callers can emit a "set but ignored" warning.
+ *
+ * config.ts reads process.env at module load, so each scenario runs in a
+ * fresh child process — same pattern as test/stateless/config-ttl.test.ts.
+ */
+import assert from "node:assert/strict";
+import { execFileSync } from "node:child_process";
+import * as path from "node:path";
+import * as url from "node:url";
+import { describe, test } from "node:test";
+const __dirname = path.dirname(url.fileURLToPath(import.meta.url));
+const CONFIG_PATH = path.resolve(__dirname, "../config.ts");
+function loadConfig(env) {
+    const script = `
+    import(${JSON.stringify(url.pathToFileURL(CONFIG_PATH).href)}).then((m) => {
+      const out = {
+        GITLAB_OAUTH_ALLOWED_GROUPS: m.GITLAB_OAUTH_ALLOWED_GROUPS ?? null,
+        GITLAB_OAUTH_ALLOWED_GROUPS_RAW: m.GITLAB_OAUTH_ALLOWED_GROUPS_RAW ?? null,
+        GITLAB_ALLOWED_GROUPS_RAW: m.GITLAB_ALLOWED_GROUPS_RAW ?? null,
+      };
+      process.stdout.write(JSON.stringify(out));
+    }).catch((err) => {
+      process.stderr.write(String(err && err.stack || err));
+      process.exit(2);
+    });
+  `;
+    const childEnv = {
+        ...process.env,
+    };
+    delete childEnv.GITLAB_OAUTH_ALLOWED_GROUPS;
+    delete childEnv.GITLAB_ALLOWED_GROUPS;
+    for (const [k, v] of Object.entries(env)) {
+        if (v === undefined) {
+            delete childEnv[k];
+        }
+        else {
+            childEnv[k] = v;
+        }
+    }
+    const stdout = execFileSync(process.execPath, ["--import", "tsx/esm", "--input-type=module", "--eval", script], { env: childEnv, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+    return JSON.parse(stdout);
+}
+describe("config.ts — GITLAB_OAUTH_ALLOWED_GROUPS resolution", () => {
+    test("neither var set — resolved value and raws are null", () => {
+        const cfg = loadConfig({});
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, null);
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS_RAW, null);
+        assert.equal(cfg.GITLAB_ALLOWED_GROUPS_RAW, null);
+    });
+    test("only new var set — resolved correctly, deprecated raw is null", () => {
+        const cfg = loadConfig({ GITLAB_OAUTH_ALLOWED_GROUPS: "my-org" });
+        assert.deepEqual(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, ["my-org"]);
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS_RAW, "my-org");
+        assert.equal(cfg.GITLAB_ALLOWED_GROUPS_RAW, null);
+    });
+    test("only deprecated var set — resolved via fallback, deprecated raw is set", () => {
+        const cfg = loadConfig({ GITLAB_ALLOWED_GROUPS: "my-org" });
+        assert.deepEqual(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, ["my-org"]);
+        assert.equal(cfg.GITLAB_ALLOWED_GROUPS_RAW, "my-org");
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS_RAW, null);
+    });
+    test("both vars set — new var wins, both raws are set (triggers 'set but ignored' warning)", () => {
+        const cfg = loadConfig({
+            GITLAB_OAUTH_ALLOWED_GROUPS: "new-org",
+            GITLAB_ALLOWED_GROUPS: "old-org",
+        });
+        assert.deepEqual(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, ["new-org"]);
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS_RAW, "new-org");
+        assert.equal(cfg.GITLAB_ALLOWED_GROUPS_RAW, "old-org");
+    });
+    test("comma-separated values are split and trimmed", () => {
+        const cfg = loadConfig({
+            GITLAB_OAUTH_ALLOWED_GROUPS: "my-org/team-a , my-org/team-b , my-org",
+        });
+        assert.deepEqual(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, [
+            "my-org/team-a",
+            "my-org/team-b",
+            "my-org",
+        ]);
+    });
+    test("empty string resolves to null", () => {
+        const cfg = loadConfig({ GITLAB_OAUTH_ALLOWED_GROUPS: "" });
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, null);
+    });
+    test("whitespace-only entries are filtered out", () => {
+        const cfg = loadConfig({ GITLAB_OAUTH_ALLOWED_GROUPS: " , , " });
+        assert.equal(cfg.GITLAB_OAUTH_ALLOWED_GROUPS, null);
+    });
+});

package/build/test/test-oauth-proxy-rate-limit.js

@@ -0,0 +1,133 @@
+/**
+ * Regression tests for OAuth endpoint rate limiting behind trusted proxies.
+ */
+import { describe, test, after, before } from "node:test";
+import assert from "node:assert";
+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 = 9210;
+const MCP_SERVER_PORT_BASE = 3210;
+const MOCK_CLIENT_ID = "mock-app-uid-from-dcr";
+function addOAuthEndpoints(mockGitLab, baseUrl) {
+    mockGitLab.addRootHandler("post", "/oauth/register", (req, res) => {
+        res.status(201).json({
+            client_id: MOCK_CLIENT_ID,
+            client_name: req.body?.client_name ?? "test",
+            redirect_uris: req.body?.redirect_uris ?? [],
+            token_endpoint_auth_method: "none",
+            require_pkce: true,
+        });
+    });
+    mockGitLab.addRootHandler("get", "/.well-known/oauth-authorization-server", (_req, res) => {
+        res.json({
+            issuer: baseUrl,
+            authorization_endpoint: `${baseUrl}/oauth/authorize`,
+            token_endpoint: `${baseUrl}/oauth/token`,
+            registration_endpoint: `${baseUrl}/oauth/register`,
+            revocation_endpoint: `${baseUrl}/oauth/revoke`,
+            scopes_supported: ["api", "read_api", "read_user"],
+            response_types_supported: ["code"],
+            grant_types_supported: ["authorization_code", "refresh_token"],
+            code_challenge_methods_supported: ["S256"],
+        });
+    });
+}
+describe("When MCP OAuth runs behind a trusted proxy", () => {
+    describe("with X-Forwarded-For containing client ports", () => {
+        let mcpBaseUrl;
+        let mockGitLab;
+        let servers = [];
+        before(async () => {
+            const mockPort = await findMockServerPort(MOCK_GITLAB_PORT_BASE);
+            mockGitLab = new MockGitLabServer({ port: mockPort, validTokens: [] });
+            await mockGitLab.start();
+            const mockGitLabUrl = mockGitLab.getUrl();
+            addOAuthEndpoints(mockGitLab, mockGitLabUrl);
+            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",
+                    MCP_TRUST_PROXY: "true",
+                    GITLAB_OAUTH_APP_ID: "test-oauth-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();
+            }
+        });
+        test("should not return 500 from /register", async () => {
+            const res = await fetch(`${mcpBaseUrl}/register`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    "X-Forwarded-For": "160.79.106.36:38914",
+                },
+                body: JSON.stringify({
+                    redirect_uris: ["https://client.example/callback"],
+                    client_name: "proxy-rate-limit-test",
+                }),
+            });
+            assert.notEqual(res.status, 500, "rate-limit key generation should not crash /register");
+            assert.strictEqual(res.status, 201, "DCR should succeed behind forwarded IPv4:port");
+        });
+        test("should not return 500 from /authorize", async () => {
+            const params = new URLSearchParams({
+                response_type: "code",
+                client_id: MOCK_CLIENT_ID,
+                redirect_uri: "https://client.example/callback",
+                code_challenge: "challenge",
+                code_challenge_method: "S256",
+                state: "proxy-rate-limit-state",
+                scope: "api",
+            });
+            const res = await fetch(`${mcpBaseUrl}/authorize?${params}`, {
+                redirect: "manual",
+                headers: {
+                    "X-Forwarded-For": "[2001:db8::1]:5678",
+                },
+            });
+            assert.notEqual(res.status, 500, "rate-limit key generation should not crash /authorize");
+        });
+        test("should not return 500 from /token", async () => {
+            const res = await fetch(`${mcpBaseUrl}/token`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "X-Forwarded-For": "160.79.106.36:38914",
+                },
+                body: new URLSearchParams({
+                    grant_type: "authorization_code",
+                    client_id: MOCK_CLIENT_ID,
+                    code: "invalid-code",
+                    redirect_uri: "https://client.example/callback",
+                }),
+            });
+            assert.notEqual(res.status, 500, "rate-limit key generation should not crash /token");
+        });
+        test("should not return 500 from /revoke", async () => {
+            const res = await fetch(`${mcpBaseUrl}/revoke`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/x-www-form-urlencoded",
+                    "X-Forwarded-For": "[2001:db8::1]",
+                },
+                body: new URLSearchParams({
+                    token: "invalid-token",
+                }),
+            });
+            assert.notEqual(res.status, 500, "rate-limit key generation should not crash /revoke");
+        });
+    });
+});