@zereight/mcp-gitlab 2.0.32 → 2.0.33

package/build/index.js

@@ -50,7 +50,7 @@ GitLabDiscussionNoteSchema, // Added
 GitLabDiscussionSchema, 
 // Draft Notes Schemas
 GitLabDraftNoteSchema, GitLabForkSchema, GitLabIssueLinkSchema, GitLabIssueSchema, GitLabIssueWithLinkDetailsSchema, GitLabMarkdownUploadSchema, GitLabMergeRequestSchema, GitLabMilestonesSchema, GitLabNamespaceExistsResponseSchema, GitLabNamespaceSchema, GitLabPipelineJobSchema, GitLabDeploymentSchema, GitLabEnvironmentSchema, GitLabPipelineSchema, GitLabPipelineTriggerJobSchema, GitLabProjectMemberSchema, GitLabProjectSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabSearchResponseSchema, GitLabTreeItemSchema, GitLabTreeSchema, GitLabUserSchema, GitLabUsersResponseSchema, GitLabWikiPageSchema, GroupIteration, ListCommitsSchema, ListDraftNotesSchema, ListGroupIterationsSchema, ListGroupProjectsSchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListLabelsSchema, ListMergeRequestDiffsSchema, // Added
-ListMergeRequestDiscussionsSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, MarkdownUploadSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, } from "./schemas.js";
+ListMergeRequestDiscussionsSchema, ListMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListPipelineTriggerJobsSchema, ListProjectMembersSchema, ListProjectMilestonesSchema, ListProjectsSchema, ListWikiPagesSchema, MarkdownUploadSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, GetMergeRequestApprovalStateSchema, GitLabMergeRequestApprovalsResponseSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, PaginatedDiscussionsResponseSchema, PromoteProjectMilestoneSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateLabelSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, UpdateWikiPageSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, ListWebhooksSchema, ListWebhookEventsSchema, GetWebhookEventSchema, } from "./schemas.js";
 import { randomUUID } from "node:crypto";
 import { pino } from "pino";
 const logger = pino({
@@ -226,9 +226,10 @@ function validateConfiguration() {
     const remoteAuth = getConfig("remote-auth", "REMOTE_AUTHORIZATION") === "true";
     const useOAuth = getConfig("use-oauth", "GITLAB_USE_OAUTH") === "true";
     const hasToken = !!getConfig("token", "GITLAB_PERSONAL_ACCESS_TOKEN");
+    const hasJobToken = !!getConfig("job-token", "GITLAB_JOB_TOKEN");
     const hasCookie = !!getConfig("cookie-path", "GITLAB_AUTH_COOKIE_PATH");
-    if (!remoteAuth && !useOAuth && !hasToken && !hasCookie) {
-        errors.push("Either --token, --cookie-path, --use-oauth=true, or --remote-auth=true must be set (or use environment variables)");
+    if (!remoteAuth && !useOAuth && !hasToken && !hasJobToken && !hasCookie) {
+        errors.push("Either --token, --job-token, --cookie-path, --use-oauth=true, or --remote-auth=true must be set (or use environment variables)");
     }
     const enableDynamicApiUrl = getConfig("enable-dynamic-api-url", "ENABLE_DYNAMIC_API_URL") === "true";
     if (enableDynamicApiUrl && !remoteAuth) {
@@ -242,6 +243,7 @@ function validateConfiguration() {
     logger.info("Configuration validation passed");
 }
 const GITLAB_PERSONAL_ACCESS_TOKEN = getConfig("token", "GITLAB_PERSONAL_ACCESS_TOKEN");
+const GITLAB_JOB_TOKEN = getConfig("job-token", "GITLAB_JOB_TOKEN");
 let OAUTH_ACCESS_TOKEN = null;
 let oauthClient = null;
 /**
@@ -492,6 +494,10 @@ function buildAuthHeaders() {
         }
         return {}; // No auth headers if no session context
     }
+    // CI job tokens use a dedicated header (not Bearer/Private-Token)
+    if (GITLAB_JOB_TOKEN) {
+        return { "JOB-TOKEN": String(GITLAB_JOB_TOKEN) };
+    }
     // Standard mode: prioritize OAuth token, then fall back to environment token
     const token = OAUTH_ACCESS_TOKEN || GITLAB_PERSONAL_ACCESS_TOKEN;
     if (IS_OLD && token) {
@@ -1152,6 +1158,21 @@ const allTools = [
         description: "Download a release asset file by direct asset path",
         inputSchema: toJSONSchema(DownloadReleaseAssetSchema),
     },
+    {
+        name: "list_webhooks",
+        description: "List all configured webhooks for a GitLab project or group. Provide either project_id or group_id.",
+        inputSchema: toJSONSchema(ListWebhooksSchema),
+    },
+    {
+        name: "list_webhook_events",
+        description: "List recent webhook events (past 7 days) for a project or group webhook. Use summary mode for overview, then get_webhook_event for full details.",
+        inputSchema: toJSONSchema(ListWebhookEventsSchema),
+    },
+    {
+        name: "get_webhook_event",
+        description: "Get full details of a specific webhook event by ID, including request/response payloads. Searches up to 500 most recent events.",
+        inputSchema: toJSONSchema(GetWebhookEventSchema),
+    },
 ];
 // Define which tools are read-only
 const readOnlyTools = new Set([
@@ -1214,6 +1235,9 @@ const readOnlyTools = new Set([
     "get_release",
     "download_release_asset",
     "get_merge_request_approval_state",
+    "list_webhooks",
+    "list_webhook_events",
+    "get_webhook_event",
 ]);
 // Define which tools are related to wiki and can be toggled by USE_GITLAB_WIKI
 const wikiToolNames = new Set([
@@ -1439,6 +1463,15 @@ const TOOLSET_DEFINITIONS = [
             "download_attachment",
         ]),
     },
+    {
+        id: "webhooks",
+        isDefault: false,
+        tools: new Set([
+            "list_webhooks",
+            "list_webhook_events",
+            "get_webhook_event",
+        ]),
+    },
 ];
 // Derived lookup: tool name → toolset ID
 const TOOLSET_BY_TOOL_NAME = new Map();
@@ -2926,7 +2959,7 @@ async function approveMergeRequest(projectId, mergeRequestIid, sha, approvalPass
         body: JSON.stringify(body),
     });
     await handleGitLabError(response);
-    return GitLabMergeRequestApprovalStateSchema.parse(await response.json());
+    return parseApprovalsResponse(await response.json());
 }
 /**
  * Unapprove a previously approved merge request
@@ -2944,7 +2977,7 @@ async function unapproveMergeRequest(projectId, mergeRequestIid) {
         body: JSON.stringify({}),
     });
     await handleGitLabError(response);
-    return GitLabMergeRequestApprovalStateSchema.parse(await response.json());
+    return parseApprovalsResponse(await response.json());
 }
 /**
  * Get the approval state of a merge request
@@ -2981,7 +3014,16 @@ async function getMergeRequestApprovalsFallback(projectId, mergeRequestIid) {
         method: "GET",
     });
     await handleGitLabError(approvalsResponse);
-    const parsedApprovals = GitLabMergeRequestApprovalsResponseSchema.parse(await approvalsResponse.json());
+    return parseApprovalsResponse(await approvalsResponse.json());
+}
+/**
+ * Parse the response from POST /approve and POST /unapprove endpoints.
+ * These endpoints return the approvals format (approved_by contains nested
+ * { user: {...} } objects), which must be converted to the flat format
+ * used by GitLabMergeRequestApprovalStateSchema.
+ */
+function parseApprovalsResponse(responseJson) {
+    const parsedApprovals = GitLabMergeRequestApprovalsResponseSchema.parse(responseJson);
     const approvedByUsers = getUniqueApprovalUsers((parsedApprovals.approved_by || []).map(approvedByEntry => approvedByEntry.user));
     const approvedByUsernames = approvedByUsers.map(user => user.username);
     return GitLabMergeRequestApprovalStateSchema.parse({
@@ -3624,6 +3666,89 @@ async function listGroupProjects(options) {
     const projects = await response.json();
     return GitLabProjectSchema.array().parse(projects);
 }
+// Webhook API helper functions
+/**
+ * Build the base URL for webhooks (project or group)
+ */
+function buildWebhookBaseUrl(projectId, groupId) {
+    if (projectId) {
+        projectId = decodeURIComponent(projectId);
+        return `${getEffectiveApiUrl()}/projects/${encodeURIComponent(getEffectiveProjectId(projectId))}/hooks`;
+    }
+    const decodedGroupId = decodeURIComponent(groupId);
+    return `${getEffectiveApiUrl()}/groups/${encodeURIComponent(decodedGroupId)}/hooks`;
+}
+/**
+ * List webhooks for a project or group
+ */
+async function listWebhooks(options) {
+    const url = new URL(buildWebhookBaseUrl(options.project_id, options.group_id));
+    if (options.page)
+        url.searchParams.append("page", options.page.toString());
+    if (options.per_page)
+        url.searchParams.append("per_page", options.per_page.toString());
+    const response = await fetch(url.toString(), { ...getFetchConfig() });
+    await handleGitLabError(response);
+    return (await response.json());
+}
+/**
+ * Summarize webhook events by stripping heavy payload fields
+ */
+function summarizeWebhookEvents(events) {
+    return events.map(event => ({
+        id: event.id,
+        url: event.url,
+        trigger: event.trigger,
+        response_status: event.response_status,
+        execution_duration: event.execution_duration,
+    }));
+}
+/**
+ * Fetch a single page of webhook events
+ */
+async function fetchWebhookEventsPage(baseUrl, page, perPage, status) {
+    const url = new URL(baseUrl);
+    url.searchParams.set("page", page.toString());
+    url.searchParams.set("per_page", perPage.toString());
+    if (status !== undefined)
+        url.searchParams.append("status", String(status));
+    const response = await fetch(url.toString(), { ...getFetchConfig() });
+    await handleGitLabError(response);
+    return (await response.json());
+}
+/**
+ * List webhook events for a project or group webhook
+ */
+async function listWebhookEvents(options) {
+    const eventsUrl = `${buildWebhookBaseUrl(options.project_id, options.group_id)}/${options.hook_id}/events`;
+    const events = await fetchWebhookEventsPage(eventsUrl, options.page ?? 1, options.per_page ?? 20, options.status);
+    return options.summary ? summarizeWebhookEvents(events) : events;
+}
+/**
+ * Get a specific webhook event by ID (searches up to 500 recent events)
+ */
+async function getWebhookEvent(options) {
+    const eventsUrl = `${buildWebhookBaseUrl(options.project_id, options.group_id)}/${options.hook_id}/events`;
+    // GitLab enforces max per_page=20 for webhook events
+    const perPage = 20;
+    if (options.page) {
+        // Direct page lookup — single API call
+        const events = await fetchWebhookEventsPage(eventsUrl, options.page, perPage);
+        const match = events.find(e => e.id === options.event_id);
+        return match ?? null;
+    }
+    // Auto-paginate up to 500 events
+    const maxPages = 25;
+    for (let page = 1; page <= maxPages; page++) {
+        const events = await fetchWebhookEventsPage(eventsUrl, page, perPage);
+        const match = events.find(e => e.id === options.event_id);
+        if (match)
+            return match;
+        if (events.length < perPage)
+            break;
+    }
+    return null;
+}
 // Wiki API helper functions
 /**
  * List wiki pages in a project
@@ -6102,6 +6227,40 @@ async function handleToolCall(params) {
                     content: [{ type: "text", text: assetContent }],
                 };
             }
+            case "list_webhooks": {
+                const args = ListWebhooksSchema.parse(params.arguments);
+                const webhooks = await listWebhooks(args);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(webhooks, null, 2) }],
+                };
+            }
+            case "list_webhook_events": {
+                const args = ListWebhookEventsSchema.parse(params.arguments);
+                const events = await listWebhookEvents(args);
+                return {
+                    content: [{ type: "text", text: JSON.stringify(events, null, 2) }],
+                };
+            }
+            case "get_webhook_event": {
+                const args = GetWebhookEventSchema.parse(params.arguments);
+                const event = await getWebhookEvent(args);
+                if (!event) {
+                    const searchScope = args.page
+                        ? `on page ${args.page}`
+                        : "in the 500 most recent events";
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: `Webhook event ${args.event_id} not found ${searchScope}` }, null, 2),
+                            },
+                        ],
+                    };
+                }
+                return {
+                    content: [{ type: "text", text: JSON.stringify(event, null, 2) }],
+                };
+            }
             default:
                 throw new Error(`Unknown tool: ${params.name}`);
         }

package/build/schemas.js

@@ -2449,3 +2449,69 @@ export const DownloadReleaseAssetSchema = z.object({
         .string()
         .describe("Path to the release asset file as specified when creating or updating its link"),
 });
+// --- Webhook schemas ---
+export const ListWebhooksSchema = z
+    .object({
+    project_id: z.coerce
+        .string()
+        .optional()
+        .describe("Project ID or URL-encoded path. Provide either project_id or group_id, not both."),
+    group_id: z.coerce
+        .string()
+        .optional()
+        .describe("Group ID or URL-encoded path. Provide either project_id or group_id, not both."),
+})
+    .merge(PaginationOptionsSchema)
+    .refine(data => (data.project_id || data.group_id) && !(data.project_id && data.group_id), {
+    message: "Provide exactly one of project_id or group_id",
+});
+export const ListWebhookEventsSchema = z
+    .object({
+    project_id: z.coerce
+        .string()
+        .optional()
+        .describe("Project ID or URL-encoded path. Provide either project_id or group_id, not both."),
+    group_id: z.coerce
+        .string()
+        .optional()
+        .describe("Group ID or URL-encoded path. Provide either project_id or group_id, not both."),
+    hook_id: z.coerce.number().describe("ID of the webhook"),
+    status: z
+        .union([z.number(), z.string()])
+        .optional()
+        .describe("Filter by response status code (e.g. 200, 500) or category: successful, client_failure, server_failure"),
+    summary: z
+        .boolean()
+        .optional()
+        .describe("If true, return only summary fields (id, url, trigger, response_status, execution_duration) without full request/response payloads. Recommended for overview queries to avoid huge responses."),
+    per_page: z
+        .number()
+        .max(20)
+        .optional()
+        .default(20)
+        .describe("Number of events per page"),
+    page: z.number().optional().describe("Page number for pagination"),
+})
+    .refine(data => (data.project_id || data.group_id) && !(data.project_id && data.group_id), {
+    message: "Provide exactly one of project_id or group_id",
+});
+export const GetWebhookEventSchema = z
+    .object({
+    project_id: z.coerce
+        .string()
+        .optional()
+        .describe("Project ID or URL-encoded path. Provide either project_id or group_id, not both."),
+    group_id: z.coerce
+        .string()
+        .optional()
+        .describe("Group ID or URL-encoded path. Provide either project_id or group_id, not both."),
+    hook_id: z.coerce.number().describe("ID of the webhook"),
+    event_id: z.coerce.number().describe("ID of the webhook event to retrieve"),
+    page: z
+        .number()
+        .optional()
+        .describe("If known, the page where the event is located (from list_webhook_events). Skips auto-pagination and fetches only this page."),
+})
+    .refine(data => (data.project_id || data.group_id) && !(data.project_id && data.group_id), {
+    message: "Provide exactly one of project_id or group_id",
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "2.0.32",
+  "version": "2.0.33",
   "description": "MCP server for using the GitLab API",
   "license": "MIT",
   "author": "zereight",