@zereight/mcp-gitlab 1.0.55 → 1.0.57

package/README.md

@@ -36,8 +36,8 @@ When using with the Claude App, you need to set up your API key and URLs directl
 ```
 
 #### Docker
-
-```json
+- stdio
+```mcp.json
 {
   "mcpServers": {
     "GitLab communication server": {
@@ -73,6 +73,30 @@ When using with the Claude App, you need to set up your API key and URLs directl
 }
 ```
 
+- sse
+```shell
+docker run -i --rm \
+  -e GITLAB_PERSONAL_ACCESS_TOKEN=your_gitlab_token \
+  -e GITLAB_API_URL= "https://gitlab.com/api/v4"\
+  -e GITLAB_READ_ONLY_MODE=true \
+  -e USE_GITLAB_WIKI=true \
+  -e USE_MILESTONE=true \
+  -e USE_PIPELINE=true \
+  -e SSE=true \
+  -p 3333:3002 \
+  gitlab-mcp
+```
+
+```json
+{
+  "mcpServers": {
+    "GitLab communication server": {
+      "url": "http://localhost:3333/sse"
+    }
+  }
+}
+```
+
 #### Docker Image Push
 
 ```shell

package/build/index.js

@@ -1,6 +1,7 @@
 #!/usr/bin/env node
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { SSEServerTransport } from "@modelcontextprotocol/sdk/server/sse.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
 import fetch from "node-fetch";
 import { SocksProxyAgent } from "socks-proxy-agent";
@@ -12,6 +13,7 @@ import { fileURLToPath } from "url";
 import { dirname } from "path";
 import fs from "fs";
 import path from "path";
+import express from "express";
 // Add type imports for proxy agents
 import { Agent } from "http";
 import { Agent as HttpsAgent } from 'https';
@@ -21,7 +23,7 @@ import { GitLabForkSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLab
 GetPipelineJobOutputSchema, GitLabPipelineJobSchema, 
 // Discussion Schemas
 GitLabDiscussionNoteSchema, // Added
-GitLabDiscussionSchema, UpdateMergeRequestNoteSchema, // Added
+GitLabDiscussionSchema, PaginatedDiscussionsResponseSchema, UpdateMergeRequestNoteSchema, // Added
 CreateMergeRequestNoteSchema, // Added
 ListMergeRequestDiscussionsSchema, UpdateIssueNoteSchema, CreateIssueNoteSchema, ListMergeRequestsSchema, GitLabMilestonesSchema, ListProjectMilestonesSchema, GetProjectMilestoneSchema, CreateProjectMilestoneSchema, EditProjectMilestoneSchema, DeleteProjectMilestoneSchema, GetMilestoneIssuesSchema, GetMilestoneMergeRequestsSchema, PromoteProjectMilestoneSchema, GetMilestoneBurndownEventsSchema, GitLabCompareResultSchema, GetBranchDiffsSchema, } from "./schemas.js";
 /**
@@ -53,6 +55,7 @@ const GITLAB_READ_ONLY_MODE = process.env.GITLAB_READ_ONLY_MODE === "true";
 const USE_GITLAB_WIKI = process.env.USE_GITLAB_WIKI === "true";
 const USE_MILESTONE = process.env.USE_MILESTONE === "true";
 const USE_PIPELINE = process.env.USE_PIPELINE === "true";
+const SSE = process.env.SSE === "true";
 // Add proxy configuration
 const HTTP_PROXY = process.env.HTTP_PROXY;
 const HTTPS_PROXY = process.env.HTTPS_PROXY;
@@ -692,12 +695,14 @@ async function listIssues(projectId, options = {}) {
     // Add all query parameters
     Object.entries(options).forEach(([key, value]) => {
         if (value !== undefined) {
-            if (key === "label_name" && Array.isArray(value)) {
+            if (key === "labels" && Array.isArray(value)) {
                 // Handle array of labels
-                url.searchParams.append(key, value.join(","));
+                value.forEach(label => {
+                    url.searchParams.append("labels[]", label.toString());
+                });
             }
             else {
-                url.searchParams.append(key, value.toString());
+                url.searchParams.append("labels[]", value.toString());
             }
         }
     });
@@ -919,55 +924,66 @@ async function createMergeRequest(projectId, options) {
     return GitLabMergeRequestSchema.parse(data);
 }
 /**
- * List merge request discussion items
- * 병합 요청 토론 목록 조회
+ * Shared helper function for listing discussions
+ * 토론 목록 조회를 위한 공유 헬퍼 함수
  *
  * @param {string} projectId - The ID or URL-encoded path of the project
- * @param {number} mergeRequestIid - The IID of a merge request
- * @returns {Promise<GitLabDiscussion[]>} List of discussions
+ * @param {"issues" | "merge_requests"} resourceType - The type of resource (issues or merge_requests)
+ * @param {number} resourceIid - The IID of the issue or merge request
+ * @param {PaginationOptions} options - Pagination and sorting options
+ * @returns {Promise<PaginatedDiscussionsResponse>} Paginated list of discussions
  */
-async function listMergeRequestDiscussions(projectId, mergeRequestIid) {
+async function listDiscussions(projectId, resourceType, resourceIid, options = {}) {
     projectId = decodeURIComponent(projectId); // Decode project ID
-    const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/merge_requests/${mergeRequestIid}/discussions`);
+    const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/${resourceType}/${resourceIid}/discussions`);
+    // Add query parameters for pagination and sorting
+    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(), {
         ...DEFAULT_FETCH_CONFIG,
     });
     await handleGitLabError(response);
-    const data = await response.json();
-    // Ensure the response is parsed as an array of discussions
-    return z.array(GitLabDiscussionSchema).parse(data);
+    const discussions = await response.json();
+    // Extract pagination headers
+    const pagination = {
+        x_next_page: response.headers.get("x-next-page") ? parseInt(response.headers.get("x-next-page")) : null,
+        x_page: response.headers.get("x-page") ? parseInt(response.headers.get("x-page")) : undefined,
+        x_per_page: response.headers.get("x-per-page") ? parseInt(response.headers.get("x-per-page")) : undefined,
+        x_prev_page: response.headers.get("x-prev-page") ? parseInt(response.headers.get("x-prev-page")) : null,
+        x_total: response.headers.get("x-total") ? parseInt(response.headers.get("x-total")) : null,
+        x_total_pages: response.headers.get("x-total-pages") ? parseInt(response.headers.get("x-total-pages")) : null,
+    };
+    return PaginatedDiscussionsResponseSchema.parse({
+        items: discussions,
+        pagination: pagination,
+    });
+}
+/**
+ * List merge request discussion items
+ * 병합 요청 토론 목록 조회
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {number} mergeRequestIid - The IID of a merge request
+ * @param {DiscussionPaginationOptions} options - Pagination and sorting options
+ * @returns {Promise<GitLabDiscussion[]>} List of discussions
+ */
+async function listMergeRequestDiscussions(projectId, mergeRequestIid, options = {}) {
+    return listDiscussions(projectId, "merge_requests", mergeRequestIid, options);
 }
 /**
  * List discussions for an issue
  *
  * @param {string} projectId - The ID or URL-encoded path of the project
  * @param {number} issueIid - The internal ID of the project issue
- * @param {Object} options - Pagination and sorting options
+ * @param {DiscussionPaginationOptions} options - Pagination and sorting options
  * @returns {Promise<GitLabDiscussion[]>} List of issue discussions
  */
 async function listIssueDiscussions(projectId, issueIid, options = {}) {
-    projectId = decodeURIComponent(projectId); // Decode project ID
-    const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/issues/${issueIid}/discussions`);
-    // Add query parameters for pagination and sorting
-    if (options.page) {
-        url.searchParams.append("page", options.page.toString());
-    }
-    if (options.per_page) {
-        url.searchParams.append("per_page", options.per_page.toString());
-    }
-    if (options.sort) {
-        url.searchParams.append("sort", options.sort);
-    }
-    if (options.order_by) {
-        url.searchParams.append("order_by", options.order_by);
-    }
-    const response = await fetch(url.toString(), {
-        ...DEFAULT_FETCH_CONFIG,
-    });
-    await handleGitLabError(response);
-    const data = await response.json();
-    // Parse the response as an array of discussions
-    return z.array(GitLabDiscussionSchema).parse(data);
+    return listDiscussions(projectId, "issues", issueIid, options);
 }
 /**
  * Modify an existing merge request thread note
@@ -2457,7 +2473,8 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "mr_discussions": {
                 const args = ListMergeRequestDiscussionsSchema.parse(request.params.arguments);
-                const discussions = await listMergeRequestDiscussions(args.project_id, args.merge_request_iid);
+                const { project_id, merge_request_iid, ...options } = args;
+                const discussions = await listMergeRequestDiscussions(project_id, merge_request_iid, options);
                 return {
                     content: [{ type: "text", text: JSON.stringify(discussions, null, 2) }],
                 };
@@ -2966,8 +2983,36 @@ async function runServer() {
         console.error(`GitLab MCP Server v${SERVER_VERSION}`);
         console.error(`API URL: ${GITLAB_API_URL}`);
         console.error("========================");
-        const transport = new StdioServerTransport();
-        await server.connect(transport);
+        if (!SSE) {
+            const transport = new StdioServerTransport();
+            await server.connect(transport);
+        }
+        else {
+            const app = express();
+            const transports = {};
+            app.get("/sse", async (_, res) => {
+                const transport = new SSEServerTransport("/messages", res);
+                transports[transport.sessionId] = transport;
+                res.on("close", () => {
+                    delete transports[transport.sessionId];
+                });
+                await server.connect(transport);
+            });
+            app.post("/messages", async (req, res) => {
+                const sessionId = req.query.sessionId;
+                const transport = transports[sessionId];
+                if (transport) {
+                    await transport.handlePostMessage(req, res);
+                }
+                else {
+                    res.status(400).send("No transport found for sessionId");
+                }
+            });
+            const PORT = process.env.PORT || 3002;
+            app.listen(PORT, () => {
+                console.log(`Server is running on port ${PORT}`);
+            });
+        }
         console.error("GitLab MCP Server running on stdio");
     }
     catch (error) {

package/build/schemas.js

@@ -90,6 +90,12 @@ export const GitLabPipelineJobSchema = z.object({
         .optional(),
     web_url: z.string().optional(),
 });
+// Shared base schema for various pagination options
+// See https://docs.gitlab.com/api/rest/#pagination
+export const PaginationOptionsSchema = z.object({
+    page: z.number().optional().describe("Page number for pagination (default: 1)"),
+    per_page: z.number().optional().describe("Number of items per page (max: 100, default: 20)"),
+});
 // Schema for listing pipelines
 export const ListPipelinesSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
@@ -130,9 +136,7 @@ export const ListPipelinesSchema = z.object({
         .optional()
         .describe("Order pipelines by"),
     sort: z.enum(["asc", "desc"]).optional().describe("Sort pipelines"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page (max 100)"),
-});
+}).merge(PaginationOptionsSchema);
 // Schema for getting a specific pipeline
 export const GetPipelineSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
@@ -147,9 +151,7 @@ export const ListPipelineJobsSchema = z.object({
         .optional()
         .describe("The scope of jobs to show"),
     include_retried: z.boolean().optional().describe("Whether to include retried jobs"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page (max 100)"),
-});
+}).merge(PaginationOptionsSchema);
 // Schema for creating a new pipeline
 export const CreatePipelineSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
@@ -287,7 +289,7 @@ export const GitLabRepositorySchema = z.object({
     container_registry_access_level: z.string().optional(),
     issues_enabled: z.boolean().optional(),
     merge_requests_enabled: z.boolean().optional(),
-    merge_requests_template: z.string().optional(),
+    merge_requests_template: z.string().nullable().optional(),
     wiki_enabled: z.boolean().optional(),
     jobs_enabled: z.boolean().optional(),
     snippets_enabled: z.boolean().optional(),
@@ -643,15 +645,39 @@ export const GitLabDiscussionNoteSchema = z.object({
     })
         .optional(),
 });
+// Reusable pagination schema for GitLab API responses.
+// See https://docs.gitlab.com/api/rest/#pagination
+export const GitLabPaginationSchema = z.object({
+    x_next_page: z.number().nullable().optional(),
+    x_page: z.number().optional(),
+    x_per_page: z.number().optional(),
+    x_prev_page: z.number().nullable().optional(),
+    x_total: z.number().nullable().optional(),
+    x_total_pages: z.number().nullable().optional(),
+});
+// Base paginated response schema that can be extended.
+// See https://docs.gitlab.com/api/rest/#pagination
+export const PaginatedResponseSchema = z.object({
+    pagination: GitLabPaginationSchema.optional(),
+});
 export const GitLabDiscussionSchema = z.object({
     id: z.string(),
     individual_note: z.boolean(),
     notes: z.array(GitLabDiscussionNoteSchema),
 });
+// Create a schema for paginated discussions response
+export const PaginatedDiscussionsResponseSchema = z.object({
+    items: z.array(GitLabDiscussionSchema),
+    pagination: GitLabPaginationSchema,
+});
+export const ListIssueDiscussionsSchema = z.object({
+    project_id: z.string().describe("Project ID or URL-encoded path"),
+    issue_iid: z.number().describe("The internal ID of the project issue"),
+}).merge(PaginationOptionsSchema);
 // Input schema for listing merge request discussions
 export const ListMergeRequestDiscussionsSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.number().describe("The IID of a merge request"),
-});
+}).merge(PaginationOptionsSchema);
 // Input schema for updating a merge request discussion note
 export const UpdateMergeRequestNoteSchema = ProjectParamsSchema.extend({
     merge_request_iid: z.number().describe("The IID of a merge request"),
@@ -699,9 +725,7 @@ export const CreateOrUpdateFileSchema = ProjectParamsSchema.extend({
 });
 export const SearchRepositoriesSchema = z.object({
     search: z.string().describe("Search query"), // Changed from query to match GitLab API
-    page: z.number().optional().describe("Page number for pagination (default: 1)"),
-    per_page: z.number().optional().describe("Number of results per page (default: 20)"),
-});
+}).merge(PaginationOptionsSchema);
 export const CreateRepositorySchema = z.object({
     name: z.string().describe("Repository name"),
     description: z.string().optional().describe("Repository description"),
@@ -809,10 +833,10 @@ export const ListIssuesSchema = z.object({
     created_after: z.string().optional().describe("Return issues created after the given time"),
     created_before: z.string().optional().describe("Return issues created before the given time"),
     due_date: z.string().optional().describe("Return issues that have the due date"),
-    label_name: z.array(z.string()).optional().describe("Array of label names"),
+    labels: z.array(z.string()).optional().describe("Array of label names"),
     milestone: z.string().optional().describe("Milestone title"),
     scope: z
-        .enum(["created-by-me", "assigned-to-me", "all"])
+        .enum(["created_by_me", "assigned_to_me", "all"])
         .optional()
         .describe("Return issues from a specific scope"),
     search: z.string().optional().describe("Search for specific terms"),
@@ -823,9 +847,7 @@ export const ListIssuesSchema = z.object({
     updated_after: z.string().optional().describe("Return issues updated after the given time"),
     updated_before: z.string().optional().describe("Return issues updated before the given time"),
     with_labels_details: z.boolean().optional().describe("Return more details for each label"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
-});
+}).merge(PaginationOptionsSchema);
 // Merge Requests API operation schemas
 export const ListMergeRequestsSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
@@ -895,9 +917,7 @@ export const ListMergeRequestsSchema = z.object({
         .describe("Return merge requests from a specific source branch"),
     wip: z.enum(["yes", "no"]).optional().describe("Filter merge requests against their wip status"),
     with_labels_details: z.boolean().optional().describe("Return more details for each label"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
-});
+}).merge(PaginationOptionsSchema);
 export const GetIssueSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
     issue_iid: z.number().describe("The internal ID of the project issue"),
@@ -930,20 +950,6 @@ export const ListIssueLinksSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
     issue_iid: z.number().describe("The internal ID of a project's issue"),
 });
-export const ListIssueDiscussionsSchema = z.object({
-    project_id: z.string().describe("Project ID or URL-encoded path"),
-    issue_iid: z.number().describe("The internal ID of the project issue"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
-    sort: z
-        .enum(["asc", "desc"])
-        .optional()
-        .describe("Return issue discussions sorted in ascending or descending order"),
-    order_by: z
-        .enum(["created_at", "updated_at"])
-        .optional()
-        .describe("Return issue discussions ordered by created_at or updated_at fields"),
-});
 export const GetIssueLinkSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
     issue_iid: z.number().describe("The internal ID of a project's issue"),
@@ -967,10 +973,8 @@ export const DeleteIssueLinkSchema = z.object({
 // Namespace API operation schemas
 export const ListNamespacesSchema = z.object({
     search: z.string().optional().describe("Search term for namespaces"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
     owned: z.boolean().optional().describe("Filter for namespaces owned by current user"),
-});
+}).merge(PaginationOptionsSchema);
 export const GetNamespaceSchema = z.object({
     namespace_id: z.string().describe("Namespace ID or full path"),
 });
@@ -983,8 +987,6 @@ export const GetProjectSchema = z.object({
 });
 export const ListProjectsSchema = z.object({
     search: z.string().optional().describe("Search term for projects"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
     search_namespaces: z.boolean().optional().describe("Needs to be true if search is full path"),
     owned: z.boolean().optional().describe("Filter for projects owned by current user"),
     membership: z.boolean().optional().describe("Filter for projects where current user is a member"),
@@ -1011,7 +1013,7 @@ export const ListProjectsSchema = z.object({
         .optional()
         .describe("Filter projects with merge requests feature enabled"),
     min_access_level: z.number().optional().describe("Filter by minimum access level"),
-});
+}).merge(PaginationOptionsSchema);
 // Label operation schemas
 export const ListLabelsSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
@@ -1061,8 +1063,6 @@ export const ListGroupProjectsSchema = z.object({
         .optional()
         .describe("Field to sort by"),
     sort: z.enum(["asc", "desc"]).optional().describe("Sort direction"),
-    page: z.number().optional().describe("Page number"),
-    per_page: z.number().optional().describe("Number of results per page"),
     archived: z.boolean().optional().describe("Filter for archived projects"),
     visibility: z
         .enum(["public", "internal", "private"])
@@ -1082,13 +1082,11 @@ export const ListGroupProjectsSchema = z.object({
     statistics: z.boolean().optional().describe("Include project statistics"),
     with_custom_attributes: z.boolean().optional().describe("Include custom attributes"),
     with_security_reports: z.boolean().optional().describe("Include security reports"),
-});
+}).merge(PaginationOptionsSchema);
 // Add wiki operation schemas
 export const ListWikiPagesSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page"),
-});
+}).merge(PaginationOptionsSchema);
 export const GetWikiPageSchema = z.object({
     project_id: z.string().describe("Project ID or URL-encoded path"),
     slug: z.string().describe("URL-encoded slug of the wiki page"),
@@ -1166,9 +1164,7 @@ export const ListProjectMilestonesSchema = ProjectParamsSchema.extend({
         .string()
         .optional()
         .describe("Return milestones updated after the specified date (ISO 8601 format)"),
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page (max 100)"),
-});
+}).merge(PaginationOptionsSchema);
 // Schema for getting a single milestone
 export const GetProjectMilestoneSchema = ProjectParamsSchema.extend({
     milestone_id: z.number().describe("The ID of a project milestone"),
@@ -1196,14 +1192,8 @@ export const DeleteProjectMilestoneSchema = GetProjectMilestoneSchema;
 // Schema for getting issues assigned to a milestone
 export const GetMilestoneIssuesSchema = GetProjectMilestoneSchema;
 // Schema for getting merge requests assigned to a milestone
-export const GetMilestoneMergeRequestsSchema = GetProjectMilestoneSchema.extend({
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page (max 100)"),
-});
+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.extend({
-    page: z.number().optional().describe("Page number for pagination"),
-    per_page: z.number().optional().describe("Number of items per page (max 100)"),
-});
+export const GetMilestoneBurndownEventsSchema = GetProjectMilestoneSchema.merge(PaginationOptionsSchema);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zereight/mcp-gitlab",
-  "version": "1.0.55",
+  "version": "1.0.57",
   "description": "MCP server for using the GitLab API",
   "license": "MIT",
   "author": "zereight",
@@ -30,8 +30,9 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.8.0",
-    "form-data": "^4.0.0",
     "@types/node-fetch": "^2.6.12",
+    "express": "^5.1.0",
+    "form-data": "^4.0.0",
     "http-proxy-agent": "^7.0.2",
     "https-proxy-agent": "^7.0.6",
     "node-fetch": "^3.3.2",
@@ -39,13 +40,14 @@
     "zod-to-json-schema": "^3.23.5"
   },
   "devDependencies": {
+    "@types/express": "^5.0.2",
     "@types/node": "^22.13.10",
-    "typescript": "^5.8.2",
-    "zod": "^3.24.2",
     "@typescript-eslint/eslint-plugin": "^8.21.0",
     "@typescript-eslint/parser": "^8.21.0",
     "eslint": "^9.18.0",
     "prettier": "^3.4.2",
-    "ts-node": "^10.9.2"
+    "ts-node": "^10.9.2",
+    "typescript": "^5.8.2",
+    "zod": "^3.24.2"
   }
 }