@zereight/mcp-gitlab 2.1.29 → 2.1.38

package/build/schemas.js

@@ -527,7 +527,7 @@ export const GetPipelineJobOutputSchema = z.object({
     limit: z
         .number()
         .optional()
-        .describe("Maximum number of lines to return from the end of the log (default: 1000)"),
+        .describe("Maximum number of lines to return from the end of the log (default/max: 1000)"),
     offset: z
         .number()
         .optional()
@@ -939,6 +939,12 @@ export const GitLabMilestonesSchema = z.object({
     expired: z.coerce.boolean(),
     web_url: z.string().optional(),
 });
+// Group milestones return group_id (not project_id)
+export const GitLabGroupMilestonesSchema = GitLabMilestonesSchema.omit({
+    project_id: true,
+}).extend({
+    group_id: z.coerce.string(),
+});
 // Input schemas for operations
 export const CreateRepositoryOptionsSchema = z.object({
     name: z.string(),
@@ -1026,6 +1032,7 @@ export const CreateBranchOptionsSchema = z.object({
     ref: z.string(), // The source branch/commit for the new branch
 });
 export const GitLabCompareResultSchema = z.object({
+    // GitLab may return null commit for empty/no-op compare ranges
     commit: z
         .object({
         id: z.string().optional(),
@@ -1035,6 +1042,7 @@ export const GitLabCompareResultSchema = z.object({
         author_email: z.string().optional(),
         created_at: z.string().optional(),
     })
+        .nullable()
         .optional(),
     commits: z.array(GitLabCommitSchema),
     diffs: z.array(GitLabDiffSchema),
@@ -1658,8 +1666,9 @@ export const UpdateDefaultBranchSchema = ProjectParamsSchema.extend({
 export const GitLabProtectedBranchAccessLevelSchema = z.object({
     access_level: z.number().nullable().optional(),
     access_level_description: z.string().optional(),
-    user_id: z.number().optional(),
-    group_id: z.number().optional(),
+    // GitLab returns null for role-based access levels (not user-/group-specific)
+    user_id: z.number().nullable().optional(),
+    group_id: z.number().nullable().optional(),
 });
 export const GitLabProtectedBranchSchema = z.object({
     id: z.number().optional(),
@@ -1704,7 +1713,17 @@ export const GetBranchDiffsSchema = ProjectParamsSchema.extend({
         .optional()
         .describe('Array of regex patterns to exclude files from the diff results. Each pattern is a JavaScript-compatible regular expression that matches file paths to ignore. Examples: ["^vendor/", "^test/mocks/", "\\.spec\\.ts$", "package-lock\\.json"]'),
 });
-export const GetMergeRequestSchema = ProjectParamsSchema.extend({
+const flexibleBooleanOptional = z.preprocess(val => {
+    if (typeof val !== "string")
+        return val;
+    const normalized = val.trim().toLowerCase();
+    if (normalized === "true")
+        return true;
+    if (normalized === "false")
+        return false;
+    return val;
+}, z.boolean().optional());
+const MergeRequestParamsSchema = ProjectParamsSchema.extend({
     project_id: z
         .preprocess(value => (value === undefined || value === null ? value : String(value)), z
         .string({
@@ -1717,7 +1736,10 @@ export const GetMergeRequestSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.coerce.string().optional().describe("The IID of a merge request"),
     source_branch: z.string().optional().describe("Source branch name"),
 });
-export const UpdateMergeRequestSchema = GetMergeRequestSchema.extend({
+export const GetMergeRequestSchema = MergeRequestParamsSchema.extend({
+    include_summaries: flexibleBooleanOptional.describe("If true, include deployment_summary, commit_addition_summary and approval_summary (extra API calls, larger response). Default false to reduce token usage."),
+});
+export const UpdateMergeRequestSchema = MergeRequestParamsSchema.extend({
     title: z.string().optional().describe("The title of the merge request"),
     description: z.string().optional().describe("The description of the merge request"),
     target_branch: z.string().optional().describe("The target branch"),
@@ -1859,14 +1881,14 @@ export const ListMergeRequestPipelinesSchema = ProjectParamsSchema.extend({
         .transform(value => value.trim()))
         .describe("The internal ID of the merge request"),
 }).merge(PaginationOptionsSchema);
-export const GetMergeRequestDiffsSchema = GetMergeRequestSchema.extend({
+export const GetMergeRequestDiffsSchema = MergeRequestParamsSchema.extend({
     view: z.enum(["inline", "parallel"]).optional().describe("Diff view type"),
     excluded_file_patterns: z
         .array(z.string())
         .optional()
         .describe('Array of regex patterns to exclude files from the diff results. Each pattern is a JavaScript-compatible regular expression that matches file paths to ignore. Examples: ["^vendor/", "^test/mocks/", "\\.spec\\.ts$", "package-lock\\.json"]'),
 });
-export const ListMergeRequestDiffsSchema = GetMergeRequestSchema.extend({
+export const ListMergeRequestDiffsSchema = MergeRequestParamsSchema.extend({
     page: z.coerce.number().optional().describe("Page number for pagination (default: 1)"),
     per_page: z.coerce
         .number()
@@ -1877,13 +1899,13 @@ export const ListMergeRequestDiffsSchema = GetMergeRequestSchema.extend({
         .optional()
         .describe("Present diffs in the unified diff format. Default is false. Introduced in GitLab 16.5."),
 });
-export const ListMergeRequestChangedFilesSchema = GetMergeRequestSchema.extend({
+export const ListMergeRequestChangedFilesSchema = MergeRequestParamsSchema.extend({
     excluded_file_patterns: z
         .array(z.string())
         .optional()
         .describe('Array of regex patterns to exclude files. Examples: ["^vendor/", "\\.pb\\.go$"]'),
 });
-export const GetMergeRequestFileDiffSchema = GetMergeRequestSchema.extend({
+export const GetMergeRequestFileDiffSchema = MergeRequestParamsSchema.extend({
     file_paths: z
         .array(z.string())
         .describe("List of file paths to retrieve diffs for (e.g. ['src/api/users.ts', 'src/repo/user.go']). " +
@@ -2063,6 +2085,7 @@ export const ListMergeRequestsSchema = z
 export const GetIssueSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
     issue_iid: z.coerce.string().describe("The internal ID of the project issue"),
+    full_response: flexibleBooleanOptional.describe("If true, return the complete issue object including the full milestone description. Default returns a slim milestone (id, iid, title, state, web_url) to reduce token usage."),
 });
 export const UpdateIssueSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
@@ -2086,6 +2109,7 @@ export const UpdateIssueSchema = z.object({
     issue_type: z
         .preprocess(val => (typeof val === "string" ? val.toLowerCase() : val), z.enum(["issue", "incident", "test_case", "task"]).optional())
         .describe("The type of issue. One of issue, incident, test_case or task."),
+    full_response: flexibleBooleanOptional.describe("If true, return the complete updated issue object. Default returns a slim confirmation (iid, title, state, web_url, updated_at) to reduce token usage."),
 });
 export const DeleteIssueSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
@@ -2344,7 +2368,10 @@ export const CreateWikiPageSchema = z.object({
 export const UpdateWikiPageSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or URL-encoded path"),
     slug: z.string().describe("Slug of the wiki page (will be URL-encoded internally)"),
-    title: z.string().optional().describe("New title of the wiki page"),
+    title: z
+        .string()
+        .optional()
+        .describe("New title of the wiki page. WARNING: setting this renames the page and changes its slug/URL (for nested pages it can also move the page to a different path), which breaks existing links. To change only the displayed title while keeping the URL, omit this parameter and instead set a `title:` field in the content's YAML front matter."),
     content: z.string().optional().describe("New content of the wiki page"),
     format: z.string().optional().describe("Content format, e.g., markdown, rdoc"),
 });
@@ -2390,7 +2417,10 @@ export const CreateGroupWikiPageSchema = z.object({
 export const UpdateGroupWikiPageSchema = z.object({
     group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
     slug: z.string().describe("Slug of the wiki page (will be URL-encoded internally)"),
-    title: z.string().optional().describe("New title of the wiki page"),
+    title: z
+        .string()
+        .optional()
+        .describe("New title of the wiki page. WARNING: setting this renames the page and changes its slug/URL (for nested pages it can also move the page to a different path), which breaks existing links. To change only the displayed title while keeping the URL, omit this parameter and instead set a `title:` field in the content's YAML front matter."),
     content: z.string().optional().describe("New content of the wiki page"),
     format: z.string().optional().describe("Content format, e.g., markdown, rdoc"),
 });
@@ -2651,13 +2681,70 @@ export const EditProjectMilestoneSchema = GetProjectMilestoneSchema.extend({
 // Schema for deleting a milestone
 export const DeleteProjectMilestoneSchema = GetProjectMilestoneSchema;
 // Schema for getting issues assigned to a milestone
-export const GetMilestoneIssuesSchema = GetProjectMilestoneSchema;
+export const GetMilestoneIssuesSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
 // Schema for getting merge requests assigned to a milestone
 export const GetMilestoneMergeRequestsSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
 // Schema for promoting a project milestone to a group milestone
 export const PromoteProjectMilestoneSchema = GetProjectMilestoneSchema;
 // Schema for getting burndown chart events for a milestone
 export const GetMilestoneBurndownEventsSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);
+// Group milestone schemas (mirror project milestones against /groups/:id/milestones)
+export const ListGroupMilestonesSchema = z
+    .object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    iids: z
+        .array(z.coerce.number())
+        .optional()
+        .describe("Return only the milestones having the given iid"),
+    state: z
+        .enum(["active", "closed"])
+        .optional()
+        .describe("Return only active or closed milestones"),
+    title: z
+        .string()
+        .optional()
+        .describe("Return only milestones with a title matching the provided string"),
+    search: z
+        .string()
+        .optional()
+        .describe("Return only milestones with a title or description matching the provided string"),
+    include_ancestors: z.coerce.boolean().optional().describe("Include ancestor groups"),
+    include_descendants: z.coerce.boolean().optional().describe("Include descendant groups"),
+    updated_before: z
+        .string()
+        .optional()
+        .describe("Return milestones updated before the specified date (ISO 8601 format)"),
+    updated_after: z
+        .string()
+        .optional()
+        .describe("Return milestones updated after the specified date (ISO 8601 format)"),
+})
+    .merge(PaginationOptionsSchema);
+export const GetGroupMilestoneSchema = z.object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    milestone_id: z.coerce.string().describe("The ID of a group milestone"),
+});
+export const CreateGroupMilestoneSchema = z.object({
+    group_id: z.coerce.string().describe("Group ID or URL-encoded path"),
+    title: z.string().describe("The title of the milestone"),
+    description: z.string().optional().describe("The description of the milestone"),
+    due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
+    start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
+});
+export const EditGroupMilestoneSchema = GetGroupMilestoneSchema.extend({
+    title: z.string().optional().describe("The title of the milestone"),
+    description: z.string().optional().describe("The description of the milestone"),
+    due_date: z.string().optional().describe("The due date of the milestone (YYYY-MM-DD)"),
+    start_date: z.string().optional().describe("The start date of the milestone (YYYY-MM-DD)"),
+    state_event: z
+        .enum(["close", "activate"])
+        .optional()
+        .describe("The state event of the milestone"),
+});
+export const DeleteGroupMilestoneSchema = GetGroupMilestoneSchema;
+export const GetGroupMilestoneIssuesSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
+export const GetGroupMilestoneMergeRequestsSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
+export const GetGroupMilestoneBurndownEventsSchema = GetGroupMilestoneSchema.merge(PaginationOptionsSchema);
 // Add schemas for commit operations
 export const ListCommitsSchema = z.object({
     project_id: z.coerce.string().describe("Project ID or complete URL-encoded path to project"),
@@ -3330,17 +3417,17 @@ const workItemTypeEnum = z
     "requirement",
     "ticket",
 ]));
-const ProjectIdOrPathSchema = z.coerce
+const NamespaceIdOrPathSchema = z.coerce
     .string()
-    .describe("Project ID, URL-encoded project path, or group path (e.g. 'group/subgroup' for group-level work items)");
+    .describe("Project ID, URL-encoded project path, group path, or explicit namespace prefix for ambiguous numeric IDs (e.g. 'group/subgroup', 'group:123', or 'project:123')");
 // Common params for work item tools
 const WorkItemParamsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID (IID) of the work item"),
 });
 export const GetWorkItemSchema = WorkItemParamsSchema;
 export const ListWorkItemsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     types: z
         .array(workItemTypeEnum)
         .optional()
@@ -3360,7 +3447,7 @@ export const ListWorkItemsSchema = z.object({
         .describe("Cursor for pagination (from previous response's endCursor)"),
 });
 export const CreateWorkItemSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     title: z.string().describe("Title of the work item"),
     type: workItemTypeEnum
         .optional()
@@ -3501,19 +3588,19 @@ export const UpdateWorkItemSchema = WorkItemParamsSchema.extend({
         .describe("Incident only: set escalation status"),
 });
 export const ConvertWorkItemTypeSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     new_type: workItemTypeEnum.describe("The target work item type to convert to"),
 });
 export const ListWorkItemStatusesSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     work_item_type: workItemTypeEnum
         .optional()
         .default("issue")
         .describe("The work item type to list available statuses for. Defaults to 'issue'."),
 });
 export const ListWorkItemNotesSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     page_size: z.coerce
         .number()
@@ -3528,7 +3615,7 @@ export const ListWorkItemNotesSchema = z.object({
         .describe("Sort order for discussions"),
 });
 export const CreateWorkItemNoteSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     body: z.string().describe("Note body (Markdown supported)"),
     internal: z.coerce
@@ -3551,7 +3638,7 @@ export const MoveWorkItemSchema = z.object({
         .describe("Project ID, URL-encoded project path, or group path of the target namespace"),
 });
 export const ListCustomFieldDefinitionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     work_item_type: workItemTypeEnum
         .optional()
         .default("issue")
@@ -3608,17 +3695,17 @@ export const DeleteIssueNoteEmojiReactionSchema = ProjectParamsSchema.extend({
 });
 // --- Emoji Reaction schemas (GraphQL: Work Items) ---
 export const CreateWorkItemEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     name: emojiNameField,
 });
 export const DeleteWorkItemEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     name: emojiNameField,
 });
 export const CreateWorkItemNoteEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()
@@ -3626,7 +3713,7 @@ export const CreateWorkItemNoteEmojiReactionSchema = z.object({
     name: emojiNameField,
 });
 export const DeleteWorkItemNoteEmojiReactionSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()
@@ -3650,11 +3737,11 @@ export const ListIssueNoteEmojiReactionsSchema = ProjectParamsSchema.extend({
     discussion_id: noteEmojiDiscussionField,
 });
 export const ListWorkItemEmojiReactionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
 });
 export const ListWorkItemNoteEmojiReactionsSchema = z.object({
-    project_id: ProjectIdOrPathSchema,
+    project_id: NamespaceIdOrPathSchema,
     iid: z.coerce.number().describe("The internal ID of the work item"),
     note_id: z
         .string()

package/build/scripts/check-skill-sync.js

@@ -0,0 +1,137 @@
+#!/usr/bin/env tsx
+/**
+ * Verify skills/gitlab-mcp/ stays in sync with tools/registry.ts.
+ *
+ * Run with: npm run check:skill-sync
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { TOOLSET_DEFINITIONS, allTools, destructiveTools, DEFAULT_TOOLSET_IDS, } from "../tools/registry.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT = join(__dirname, "..");
+const SKILL_PATH = join(REPO_ROOT, "skills", "gitlab-mcp", "SKILL.md");
+const REF_DIR = join(REPO_ROOT, "skills", "gitlab-mcp", "reference");
+// Response field names in reference docs — not MCP tools.
+const REFERENCE_FIELD_ALLOWLIST = new Set([
+    "allow_multiple",
+    "deleted_file",
+    "excluded_file_patterns",
+    "group_id",
+    "new_file",
+    "new_path",
+    "old_path",
+    "project_id",
+    "renamed_file",
+]);
+function fail(message) {
+    console.error(`::error::${message}`);
+    process.exit(1);
+}
+function parseToolsetTable(skill) {
+    const rows = new Map();
+    const rowRe = /^\| ([a-z_]+) \((\d+) tools?\) \| (yes|no) \|/gm;
+    let match;
+    while ((match = rowRe.exec(skill)) !== null) {
+        rows.set(match[1], {
+            count: Number(match[2]),
+            isDefault: match[3] === "yes",
+        });
+    }
+    return rows;
+}
+function parseIntroCounts(skill) {
+    const match = skill.match(/providing (\d+) tools: (\d+) tools across (\d+) toolsets/);
+    if (!match) {
+        fail("skills/gitlab-mcp/SKILL.md intro line is missing or malformed");
+    }
+    return {
+        totalTools: Number(match[1]),
+        uniqueInToolsets: Number(match[2]),
+        toolsetCount: Number(match[3]),
+    };
+}
+function parseDestructiveTools(skill) {
+    const section = skill.match(/## Destructive Tools[^\n]*\n\n(`[^`]+`(?:, `[^`]+`)*)$/m);
+    if (!section) {
+        fail("skills/gitlab-mcp/SKILL.md destructive tools section is missing or malformed");
+    }
+    return new Set([...section[1].matchAll(/`([a-z_]+)`/g)].map((m) => m[1]));
+}
+function collectReferenceToolNames() {
+    const toolNames = new Set();
+    for (const file of readdirSync(REF_DIR).filter((name) => name.endsWith(".md"))) {
+        const text = readFileSync(join(REF_DIR, file), "utf8");
+        for (const match of text.matchAll(/`([a-z][a-z0-9_]*)`/g)) {
+            const name = match[1];
+            if (!REFERENCE_FIELD_ALLOWLIST.has(name)) {
+                toolNames.add(name);
+            }
+        }
+    }
+    return toolNames;
+}
+const skill = readFileSync(SKILL_PATH, "utf8");
+const errors = [];
+const registryCounts = Object.fromEntries(TOOLSET_DEFINITIONS.map((definition) => [definition.id, definition.tools.size]));
+const skillRows = parseToolsetTable(skill);
+if (skillRows.size !== TOOLSET_DEFINITIONS.length) {
+    errors.push(`toolset table has ${skillRows.size} rows; registry has ${TOOLSET_DEFINITIONS.length}`);
+}
+for (const definition of TOOLSET_DEFINITIONS) {
+    const row = skillRows.get(definition.id);
+    if (!row) {
+        errors.push(`missing toolset row for ${definition.id}`);
+        continue;
+    }
+    const actualCount = registryCounts[definition.id];
+    if (row.count !== actualCount) {
+        errors.push(`${definition.id}: skill says ${row.count}, registry has ${actualCount}`);
+    }
+    const expectedDefault = DEFAULT_TOOLSET_IDS.has(definition.id);
+    if (row.isDefault !== expectedDefault) {
+        errors.push(`${definition.id}: skill default=${row.isDefault}, registry default=${expectedDefault}`);
+    }
+}
+for (const id of skillRows.keys()) {
+    if (!registryCounts[id]) {
+        errors.push(`unknown toolset in skill table: ${id}`);
+    }
+}
+const uniqueInToolsets = new Set(TOOLSET_DEFINITIONS.flatMap((definition) => [...definition.tools]))
+    .size;
+const intro = parseIntroCounts(skill);
+if (intro.totalTools !== allTools.length) {
+    errors.push(`intro total tools: skill says ${intro.totalTools}, registry has ${allTools.length}`);
+}
+if (intro.uniqueInToolsets !== uniqueInToolsets) {
+    errors.push(`intro unique toolset tools: skill says ${intro.uniqueInToolsets}, registry has ${uniqueInToolsets}`);
+}
+if (intro.toolsetCount !== TOOLSET_DEFINITIONS.length) {
+    errors.push(`intro toolset count: skill says ${intro.toolsetCount}, registry has ${TOOLSET_DEFINITIONS.length}`);
+}
+const skillDestructive = parseDestructiveTools(skill);
+for (const tool of skillDestructive) {
+    if (!destructiveTools.has(tool)) {
+        errors.push(`destructive list includes non-destructive tool: ${tool}`);
+    }
+}
+for (const tool of destructiveTools) {
+    if (!skillDestructive.has(tool)) {
+        errors.push(`destructive list missing registry tool: ${tool}`);
+    }
+}
+const registryToolNames = new Set(allTools.map((tool) => tool.name));
+for (const tool of collectReferenceToolNames()) {
+    if (!registryToolNames.has(tool)) {
+        errors.push(`reference mentions unknown tool: ${tool}`);
+    }
+}
+if (errors.length > 0) {
+    console.error("skills/gitlab-mcp/ is out of sync with tools/registry.ts:");
+    for (const error of errors) {
+        console.error(`- ${error}`);
+    }
+    process.exit(1);
+}
+console.log("skills/gitlab-mcp/ is in sync with tools/registry.ts");

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

@@ -77,7 +77,7 @@ const GROUP_META = {
     },
     milestones: {
         title: "Milestones",
-        blurb: "Project milestone CRUD plus associated issues/MRs and burndown events.",
+        blurb: "Project and group milestone CRUD plus associated issues/MRs and burndown events.",
     },
     wiki: {
         title: "Wiki",
@@ -273,8 +273,13 @@ function buildIndexPage(groupedToolsList) {
         "",
         ...buildToggleSection(groupedToolsList),
         "",
-        "Read-only mode (`GITLAB_READ_ONLY_MODE=true`) hides every write tool",
-        "regardless of toggles. See [Environment Variables](../configuration/environment-variables.md)",
+        "Permission modes control which tools are exposed:",
+        "",
+        "- `GITLAB_PERMISSION_MODE=readonly` — hides every write tool regardless of toggles.",
+        "- `GITLAB_PERMISSION_MODE=modify` — allows create/update but blocks all `delete_*` tools.",
+        "- `GITLAB_READ_ONLY_MODE=true` (deprecated) — same as `readonly`; prefer `GITLAB_PERMISSION_MODE=readonly`.",
+        "",
+        "See [Environment Variables](../configuration/environment-variables.md)",
         "and [CLI Arguments](../getting-started/cli-arguments.md) for the full list.",
         "",
         "## Legend",

package/build/server/metrics.js

@@ -0,0 +1,84 @@
+export function escapePrometheusLabel(value) {
+    return String(value).replace(/\\/g, "\\\\").replace(/\n/g, "\\n").replace(/"/g, '\\"');
+}
+export function formatPrometheusMetrics(snapshot) {
+    const configLabels = Object.entries({
+        max_sessions: snapshot.config.maxSessions,
+        max_requests_per_minute: snapshot.config.maxRequestsPerMinute,
+        session_timeout_seconds: snapshot.config.sessionTimeoutSeconds,
+        remote_auth_enabled: snapshot.config.remoteAuthEnabled,
+        mcp_oauth_enabled: snapshot.config.mcpOAuthEnabled,
+        stateless_mode_enabled: snapshot.config.statelessModeEnabled,
+        stateless_rotation_key: snapshot.config.statelessRotationKey,
+    })
+        .map(([key, value]) => `${key}="${escapePrometheusLabel(value)}"`)
+        .join(",");
+    return [
+        "# HELP gitlab_mcp_requests_processed_total Total MCP requests processed",
+        "# TYPE gitlab_mcp_requests_processed_total counter",
+        `gitlab_mcp_requests_processed_total ${snapshot.requestsProcessed}`,
+        "",
+        "# HELP gitlab_mcp_requests_rejected_total Requests rejected, by reason",
+        "# TYPE gitlab_mcp_requests_rejected_total counter",
+        `gitlab_mcp_requests_rejected_total{reason="rate_limit"} ${snapshot.rejectedByRateLimit}`,
+        `gitlab_mcp_requests_rejected_total{reason="capacity"} ${snapshot.rejectedByCapacity}`,
+        "",
+        "# HELP gitlab_mcp_auth_failures_total Authentication failures",
+        "# TYPE gitlab_mcp_auth_failures_total counter",
+        `gitlab_mcp_auth_failures_total ${snapshot.authFailures}`,
+        "",
+        "# HELP gitlab_mcp_sessions_total Total sessions created",
+        "# TYPE gitlab_mcp_sessions_total counter",
+        `gitlab_mcp_sessions_total ${snapshot.totalSessions}`,
+        "",
+        "# HELP gitlab_mcp_sessions_expired_total Sessions expired due to inactivity",
+        "# TYPE gitlab_mcp_sessions_expired_total counter",
+        `gitlab_mcp_sessions_expired_total ${snapshot.expiredSessions}`,
+        "",
+        "# HELP gitlab_mcp_active_sessions Currently active sessions",
+        "# TYPE gitlab_mcp_active_sessions gauge",
+        `gitlab_mcp_active_sessions ${snapshot.activeSessions}`,
+        "",
+        "# HELP gitlab_mcp_authenticated_sessions Currently authenticated sessions",
+        "# TYPE gitlab_mcp_authenticated_sessions gauge",
+        `gitlab_mcp_authenticated_sessions ${snapshot.authenticatedSessions}`,
+        "",
+        "# HELP gitlab_mcp_client_pool_size Current GitLab client pool size",
+        "# TYPE gitlab_mcp_client_pool_size gauge",
+        `gitlab_mcp_client_pool_size ${snapshot.gitlabClientPool.size}`,
+        "",
+        "# HELP gitlab_mcp_client_pool_max_size Maximum GitLab client pool size",
+        "# TYPE gitlab_mcp_client_pool_max_size gauge",
+        `gitlab_mcp_client_pool_max_size ${snapshot.gitlabClientPool.maxSize}`,
+        "",
+        "# HELP gitlab_mcp_uptime_seconds Process uptime in seconds",
+        "# TYPE gitlab_mcp_uptime_seconds gauge",
+        `gitlab_mcp_uptime_seconds ${snapshot.uptime}`,
+        "",
+        "# HELP gitlab_mcp_memory_usage_bytes Node.js memory usage by type",
+        "# TYPE gitlab_mcp_memory_usage_bytes gauge",
+        ...Object.entries(snapshot.memoryUsage).map(([key, value]) => `gitlab_mcp_memory_usage_bytes{type="${escapePrometheusLabel(key)}"} ${value}`),
+        "",
+        "# HELP gitlab_mcp_stateless_requests_total Stateless MCP requests processed",
+        "# TYPE gitlab_mcp_stateless_requests_total counter",
+        `gitlab_mcp_stateless_requests_total ${snapshot.statelessRequests}`,
+        "",
+        "# HELP gitlab_mcp_stateless_auth_total Stateless auth successes, by source",
+        "# TYPE gitlab_mcp_stateless_auth_total counter",
+        `gitlab_mcp_stateless_auth_total{source="header"} ${snapshot.statelessAuthFromHeader}`,
+        `gitlab_mcp_stateless_auth_total{source="sealed_session_id"} ${snapshot.statelessAuthFromSealedSid}`,
+        "",
+        "# HELP gitlab_mcp_stateless_auth_failures_total Stateless auth failures",
+        "# TYPE gitlab_mcp_stateless_auth_failures_total counter",
+        `gitlab_mcp_stateless_auth_failures_total ${snapshot.statelessAuthFailures}`,
+        "",
+        "# HELP gitlab_mcp_stateless_session_id_rotations_total Stateless session id rotations",
+        "# TYPE gitlab_mcp_stateless_session_id_rotations_total counter",
+        `gitlab_mcp_stateless_session_id_rotations_total ${snapshot.statelessSidRotated}`,
+        "",
+        "# HELP gitlab_mcp_config_info Static configuration (value is always 1)",
+        "# TYPE gitlab_mcp_config_info gauge",
+        `gitlab_mcp_config_info{${configLabels}} 1`,
+        "",
+    ].join("\n");
+}

package/build/server/transport-mode.js

@@ -0,0 +1,25 @@
+import { SSE, STREAMABLE_HTTP } from "../config.js";
+/**
+ * Available transport modes for MCP server.
+ */
+export var TransportMode;
+(function (TransportMode) {
+    TransportMode["STDIO"] = "stdio";
+    TransportMode["SSE"] = "sse";
+    TransportMode["STREAMABLE_HTTP"] = "streamable-http";
+})(TransportMode || (TransportMode = {}));
+/**
+ * Determine the transport mode based on environment variables and availability.
+ *
+ * Transport mode priority (highest to lowest):
+ * 1. STREAMABLE_HTTP
+ * 2. SSE
+ * 3. STDIO
+ */
+export function determineTransportMode() {
+    if (STREAMABLE_HTTP)
+        return TransportMode.STREAMABLE_HTTP;
+    if (SSE)
+        return TransportMode.SSE;
+    return TransportMode.STDIO;
+}

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

@@ -95,7 +95,7 @@ describe("Callback Proxy Mode", () => {
     // 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);
+        const mockPort = await findMockServerPort();
         mockGitLab = new MockGitLabServer({
             port: mockPort,
             validTokens: [MOCK_ACCESS_TOKEN],

package/build/test/client-pool-test.js

@@ -22,7 +22,7 @@ describe('Client Pool Limits', () => {
     let mockGitLabUrl;
     before(async () => {
         // Start mock GitLab server
-        const mockPort = await findMockServerPort(MOCK_GITLAB_PORT_BASE);
+        const mockPort = await findMockServerPort();
         mockGitLab = new MockGitLabServer({
             port: mockPort,
             validTokens: [MOCK_TOKEN]

package/build/test/dynamic-api-url-allowlist.test.js

@@ -30,10 +30,10 @@ describe("Dynamic API URL allowlist", () => {
     let secondaryHit = false;
     let getAttackerHits = () => 0;
     before(async () => {
-        const primaryPort = await findMockServerPort(9100);
+        const primaryPort = await findMockServerPort();
         primaryGitLab = new MockGitLabServer({ port: primaryPort, validTokens: [MOCK_TOKEN] });
         await primaryGitLab.start();
-        const secondaryPort = await findMockServerPort(9200);
+        const secondaryPort = await findMockServerPort();
         secondaryGitLab = new MockGitLabServer({ port: secondaryPort, validTokens: [MOCK_TOKEN] });
         secondaryGitLab.addMockHandler("get", "/projects/1/issues", (_req, res) => {
             secondaryHit = true;