@zereight/mcp-gitlab 2.1.70 → 2.2.1

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();