@zereight/mcp-gitlab 2.1.69 → 2.2.0

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

@@ -1,143 +0,0 @@
-#!/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([
-    "after",
-    "allow_multiple",
-    "deleted_file",
-    "excluded_file_patterns",
-    "group_id",
-    "new_file",
-    "new_path",
-    "old_path",
-    "name",
-    "page",
-    "per_page",
-    "pipeline_id",
-    "job_inputs",
-    "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-server-card.js

@@ -1,39 +0,0 @@
-import fs from "node:fs";
-import path from "node:path";
-import { allTools } from "../tools/registry.js";
-async function main() {
-    const pkgPath = path.resolve(process.cwd(), "package.json");
-    const pkg = JSON.parse(fs.readFileSync(pkgPath, "utf8"));
-    const serverCard = {
-        serverInfo: {
-            name: pkg.mcpName || pkg.name,
-            version: pkg.version,
-        },
-        authentication: {
-            required: true,
-            schemes: ["bearer", "oauth2"],
-        },
-        tools: allTools.map(t => {
-            const tool = { ...t };
-            if (tool.inputSchema &&
-                typeof tool.inputSchema === "object" &&
-                "$schema" in tool.inputSchema) {
-                const schema = { ...tool.inputSchema };
-                delete schema["$schema"];
-                tool.inputSchema = schema;
-            }
-            return tool;
-        }),
-        resources: [],
-        prompts: [],
-    };
-    const outDir = path.resolve(process.cwd(), ".well-known", "mcp");
-    fs.mkdirSync(outDir, { recursive: true });
-    const outFile = path.join(outDir, "server-card.json");
-    fs.writeFileSync(outFile, JSON.stringify(serverCard, null, 2), "utf8");
-    console.log(`Successfully generated ${outFile} (${allTools.length} tools)`);
-}
-main().catch(err => {
-    console.error("Failed to generate server card:", err);
-    process.exit(1);
-});

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

@@ -1,58 +0,0 @@
-#!/usr/bin/env tsx
-/**
- * Generate docs/reference/tool-coverage.md from tools/registry.ts + test/ MCP calls.
- *
- * Detection rules live in ./tool-coverage/coverage.ts (AST-scoped): a tool is
- * invoked when test source sends that name as a `callTool*` argument, as the
- * `name` of a first-argument params object (`client.callTool({ name })`), or as
- * the `name` of a `params` object inside a `tools/call` payload literal.
- *
- * Name-only mentions (toolset tables, description-quality) do not count.
- * callTool(variable) loops are missed unless the name is also a literal in that call.
- *
- * Run with: npm run docs:tools
- */
-import { readFileSync, readdirSync, statSync, writeFileSync } from "node:fs";
-import { dirname, join, relative } from "node:path";
-import { fileURLToPath } from "node:url";
-import { allTools, TOOLSET_DEFINITIONS } from "../tools/registry.js";
-import { assertDetectorHealthy, buildCoverageMarkdown, collectInvocations, countInvoked, groupToolsByToolset, percent, SKIP_FILES, } from "./tool-coverage/coverage.js";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-const REPO_ROOT = join(__dirname, "..");
-const TEST_DIR = join(REPO_ROOT, "test");
-const OUT_PATH = join(REPO_ROOT, "docs", "reference", "tool-coverage.md");
-function walkTestFiles(dir) {
-    const out = [];
-    for (const name of readdirSync(dir)) {
-        const full = join(dir, name);
-        const stat = statSync(full);
-        if (stat.isDirectory()) {
-            out.push(...walkTestFiles(full));
-            continue;
-        }
-        if (/\.(ts|js)$/.test(name) && !SKIP_FILES.has(name)) {
-            out.push(full);
-        }
-    }
-    return out;
-}
-function repoPath(abs) {
-    return relative(REPO_ROOT, abs).split("\\").join("/");
-}
-function readScannedFiles() {
-    return walkTestFiles(TEST_DIR).map(abs => ({
-        path: repoPath(abs),
-        text: readFileSync(abs, "utf8"),
-    }));
-}
-function main() {
-    const toolNames = allTools.map(tool => tool.name);
-    const toolNameSet = new Set(toolNames);
-    const hits = collectInvocations(readScannedFiles(), toolNameSet);
-    const invokedCount = countInvoked(toolNames, hits);
-    assertDetectorHealthy(hits, invokedCount);
-    const grouped = groupToolsByToolset(toolNames, TOOLSET_DEFINITIONS);
-    writeFileSync(OUT_PATH, buildCoverageMarkdown(toolNames, hits, grouped));
-    console.log(`generated docs/reference/tool-coverage.md — ${invokedCount}/${toolNames.length} (${percent(invokedCount, toolNames.length)})`);
-}
-main();

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

@@ -1,430 +0,0 @@
-#!/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;
-}
-/** Returns the availability note for a toolset group, or undefined when it is on by default. */
-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`. Tools excluded from the list (toolset / `GITLAB_TOOLS` / `GITLAB_DENIED_TOOLS_REGEX`) are also rejected on direct calls; `GITLAB_TOOL_POLICY_HIDDEN` tools stay callable unless they match `GITLAB_DENIED_TOOLS_REGEX`.";
-    }
-    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 and group 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: "Create, update, and delete project or group webhooks, 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.",
-    },
-    vulnerabilities: {
-        title: "Vulnerabilities",
-        blurb: "AI-assisted vulnerability triage — list findings, inspect details, dismiss with reason, or confirm for remediation. Backed by the GitLab GraphQL API; requires GitLab Ultimate.",
-    },
-    orbit: {
-        title: "GitLab Orbit",
-        blurb: "Query the Orbit SDLC knowledge graph (Beta; Premium/Ultimate). Graph queries consume GitLab credits; schema, status, and tool listing are free.",
-    },
-    snippets: {
-        title: "Snippets",
-        blurb: "Snippet CRUD — list, get (with optional file content), create, update, and delete personal or project snippets.",
-    },
-};
-const GROUP_ORDER = [
-    "projects",
-    "repositories",
-    "branches",
-    "groups",
-    "merge_requests",
-    "issues",
-    "labels",
-    "workitems",
-    "ci",
-    "pipelines",
-    "milestones",
-    "wiki",
-    "releases",
-    "tags",
-    "users",
-    "variables",
-    "webhooks",
-    "search",
-    "dependency_proxy",
-    "vulnerabilities",
-    "orbit",
-    "snippets",
-];
-// 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}) — ${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.",
-        "",
-        "Which of these have an MCP `tools/call` test is tracked in",
-        "[Tool invocation coverage](../reference/tool-coverage.md).",
-        "",
-        "> **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),
-        "",
-        "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 delete and teardown tools: every `delete_*` tool, `erase_pipeline_job`, `purge_dependency_proxy_cache`, the destructive teardown verbs `cancel_pipeline`, `cancel_pipeline_job`, `stop_environment`, `stop_stale_environments`, `unprotect_branch`, plus `push_files` `delete`/`move` actions.",
-        "- `GITLAB_READ_ONLY_MODE=true` (deprecated) — same as `readonly`; prefer `GITLAB_PERMISSION_MODE=readonly`.",
-        "",
-        "The `modify` guard applies to typed tools (`tools/list` and `tools/call`) and to destructive mutations sent through `execute_graphql`: any top-level mutation field whose name contains a deletion verb (`delete`, `destroy`, `remove`, `prune`, `purge`, `erase`) or a teardown verb (`revoke`, `cancel`, `stop`, `terminate`, `unprotect`, `disable`, `deactivate`, `drop`, `unschedule`). See [Environment Variables](../configuration/environment-variables.md#gitlab_permission_mode).",
-        "",
-        "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();