@zereight/mcp-gitlab 1.0.13 → 1.0.15

package/build/index.js

@@ -10,7 +10,9 @@ import { dirname } from "path";
 import fs from "fs";
 import path from "path";
 import { GitLabForkSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabIssueSchema, GitLabMergeRequestSchema, GitLabContentSchema, GitLabCreateUpdateFileResponseSchema, GitLabSearchResponseSchema, GitLabTreeSchema, GitLabCommitSchema, CreateOrUpdateFileSchema, SearchRepositoriesSchema, CreateRepositorySchema, GetFileContentsSchema, PushFilesSchema, CreateIssueSchema, CreateMergeRequestSchema, ForkRepositorySchema, CreateBranchSchema, GitLabMergeRequestDiffSchema, GetMergeRequestSchema, GetMergeRequestDiffsSchema, UpdateMergeRequestSchema, CreateNoteSchema, } from "./schemas.js";
-// Read version from package.json
+/**
+ * Read version from package.json
+ */
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = dirname(__filename);
 const packageJsonPath = path.resolve(__dirname, '../package.json');
@@ -33,7 +35,12 @@ const server = new Server({
     },
 });
 const GITLAB_PERSONAL_ACCESS_TOKEN = process.env.GITLAB_PERSONAL_ACCESS_TOKEN;
-// Smart URL handling for GitLab API
+/**
+ * Smart URL handling for GitLab API
+ *
+ * @param {string | undefined} url - Input GitLab API URL
+ * @returns {string} Normalized GitLab API URL with /api/v4 path
+ */
 function normalizeGitLabApiUrl(url) {
     if (!url) {
         return "https://gitlab.com/api/v4";
@@ -59,20 +66,36 @@ if (!GITLAB_PERSONAL_ACCESS_TOKEN) {
     console.error("GITLAB_PERSONAL_ACCESS_TOKEN environment variable is not set");
     process.exit(1);
 }
-// GitLab API 공통 헤더
+/**
+ * Common headers for GitLab API requests
+ * GitLab API 공통 헤더 (Common headers for GitLab API)
+ */
 const DEFAULT_HEADERS = {
     Accept: "application/json",
     "Content-Type": "application/json",
     Authorization: `Bearer ${GITLAB_PERSONAL_ACCESS_TOKEN}`,
 };
-// API 에러 처리를 위한 유틸리티 함수
+/**
+ * Utility function for handling GitLab API errors
+ * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
+ *
+ * @param {import("node-fetch").Response} response - The response from GitLab API
+ * @throws {Error} Throws an error with response details if the request failed
+ */
 async function handleGitLabError(response) {
     if (!response.ok) {
         const errorBody = await response.text();
         throw new Error(`GitLab API error: ${response.status} ${response.statusText}\n${errorBody}`);
     }
 }
-// 프로젝트 포크 생성
+/**
+ * Create a fork of a GitLab project
+ * 프로젝트 포크 생성 (Create a project fork)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {string} [namespace] - The namespace to fork the project to
+ * @returns {Promise<GitLabFork>} The created fork
+ */
 async function forkProject(projectId, namespace) {
     // API 엔드포인트 URL 생성
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/fork`);
@@ -91,7 +114,14 @@ async function forkProject(projectId, namespace) {
     const data = await response.json();
     return GitLabForkSchema.parse(data);
 }
-// 새로운 브랜치 생성
+/**
+ * Create a new branch in a GitLab project
+ * 새로운 브랜치 생성 (Create a new branch)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {z.infer<typeof CreateBranchOptionsSchema>} options - Branch creation options
+ * @returns {Promise<GitLabReference>} The created branch reference
+ */
 async function createBranch(projectId, options) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/repository/branches`);
     const response = await fetch(url.toString(), {
@@ -105,7 +135,13 @@ async function createBranch(projectId, options) {
     await handleGitLabError(response);
     return GitLabReferenceSchema.parse(await response.json());
 }
-// 프로젝트의 기본 브랜치 조회
+/**
+ * Get the default branch for a GitLab project
+ * 프로젝트의 기본 브랜치 조회 (Get the default branch of a project)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @returns {Promise<string>} The name of the default branch
+ */
 async function getDefaultBranchRef(projectId) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}`);
     const response = await fetch(url.toString(), {
@@ -115,7 +151,15 @@ async function getDefaultBranchRef(projectId) {
     const project = GitLabRepositorySchema.parse(await response.json());
     return project.default_branch ?? "main";
 }
-// 파일 내용 조회
+/**
+ * Get the contents of a file from a GitLab project
+ * 파일 내용 조회 (Get file contents)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {string} filePath - The path of the file to get
+ * @param {string} [ref] - The name of the branch, tag or commit
+ * @returns {Promise<GitLabContent>} The file content
+ */
 async function getFileContents(projectId, filePath, ref) {
     const encodedPath = encodeURIComponent(filePath);
     // ref가 없는 경우 default branch를 가져옴
@@ -141,7 +185,14 @@ async function getFileContents(projectId, filePath, ref) {
     }
     return parsedData;
 }
-// 이슈 생성
+/**
+ * Create a new issue in a GitLab project
+ * 이슈 생성 (Create an issue)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {z.infer<typeof CreateIssueOptionsSchema>} options - Issue creation options
+ * @returns {Promise<GitLabIssue>} The created issue
+ */
 async function createIssue(projectId, options) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/issues`);
     const response = await fetch(url.toString(), {
@@ -164,6 +215,14 @@ async function createIssue(projectId, options) {
     const data = await response.json();
     return GitLabIssueSchema.parse(data);
 }
+/**
+ * Create a new merge request in a GitLab project
+ * 병합 요청 생성
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {z.infer<typeof CreateMergeRequestOptionsSchema>} options - Merge request creation options
+ * @returns {Promise<GitLabMergeRequest>} The created merge request
+ */
 async function createMergeRequest(projectId, options) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/merge_requests`);
     const response = await fetch(url.toString(), {
@@ -193,7 +252,19 @@ async function createMergeRequest(projectId, options) {
     const data = await response.json();
     return GitLabMergeRequestSchema.parse(data);
 }
-async function createOrUpdateFile(projectId, filePath, content, commitMessage, branch, previousPath) {
+/**
+ * Create or update a file in a GitLab project
+ * 파일 생성 또는 업데이트
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {string} filePath - The path of the file to create or update
+ * @param {string} content - The content of the file
+ * @param {string} commitMessage - The commit message
+ * @param {string} branch - The branch name
+ * @param {string} [previousPath] - The previous path of the file in case of rename
+ * @returns {Promise<GitLabCreateUpdateFileResponse>} The file update response
+ */
+async function createOrUpdateFile(projectId, filePath, content, commitMessage, branch, previousPath, last_commit_id, commit_id) {
     const encodedPath = encodeURIComponent(filePath);
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/repository/files/${encodedPath}`);
     const body = {
@@ -206,14 +277,38 @@ async function createOrUpdateFile(projectId, filePath, content, commitMessage, b
     // Check if file exists
     let method = "POST";
     try {
-        await getFileContents(projectId, filePath, branch);
+        // Get file contents to check existence and retrieve commit IDs
+        const fileData = await getFileContents(projectId, filePath, branch);
         method = "PUT";
+        // If fileData is not an array, it's a file content object with commit IDs
+        if (!Array.isArray(fileData)) {
+            // Use commit IDs from the file data if not provided in parameters
+            if (!commit_id && fileData.commit_id) {
+                body.commit_id = fileData.commit_id;
+            }
+            else if (commit_id) {
+                body.commit_id = commit_id;
+            }
+            if (!last_commit_id && fileData.last_commit_id) {
+                body.last_commit_id = fileData.last_commit_id;
+            }
+            else if (last_commit_id) {
+                body.last_commit_id = last_commit_id;
+            }
+        }
     }
     catch (error) {
         if (!(error instanceof Error && error.message.includes("File not found"))) {
             throw error;
         }
-        // File doesn't exist, use POST
+        // File doesn't exist, use POST - no need for commit IDs for new files
+        // But still use any provided as parameters if they exist
+        if (commit_id) {
+            body.commit_id = commit_id;
+        }
+        if (last_commit_id) {
+            body.last_commit_id = last_commit_id;
+        }
     }
     const response = await fetch(url.toString(), {
         method,
@@ -231,6 +326,15 @@ async function createOrUpdateFile(projectId, filePath, content, commitMessage, b
     const data = await response.json();
     return GitLabCreateUpdateFileResponseSchema.parse(data);
 }
+/**
+ * Create a tree structure in a GitLab project repository
+ * 저장소에 트리 구조 생성
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {FileOperation[]} files - Array of file operations
+ * @param {string} [ref] - The name of the branch, tag or commit
+ * @returns {Promise<GitLabTree>} The created tree
+ */
 async function createTree(projectId, files, ref) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/repository/tree`);
     if (ref) {
@@ -262,6 +366,16 @@ async function createTree(projectId, files, ref) {
     const data = await response.json();
     return GitLabTreeSchema.parse(data);
 }
+/**
+ * Create a commit in a GitLab project repository
+ * 저장소에 커밋 생성
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {string} message - The commit message
+ * @param {string} branch - The branch name
+ * @param {FileOperation[]} actions - Array of file operations for the commit
+ * @returns {Promise<GitLabCommit>} The created commit
+ */
 async function createCommit(projectId, message, branch, actions) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/repository/commits`);
     const response = await fetch(url.toString(), {
@@ -293,6 +407,15 @@ async function createCommit(projectId, message, branch, actions) {
     const data = await response.json();
     return GitLabCommitSchema.parse(data);
 }
+/**
+ * Search for GitLab projects
+ * 프로젝트 검색
+ *
+ * @param {string} query - The search query
+ * @param {number} [page=1] - The page number
+ * @param {number} [perPage=20] - Number of items per page
+ * @returns {Promise<GitLabSearchResponse>} The search results
+ */
 async function searchProjects(query, page = 1, perPage = 20) {
     const url = new URL(`${GITLAB_API_URL}/projects`);
     url.searchParams.append("search", query);
@@ -323,6 +446,13 @@ async function searchProjects(query, page = 1, perPage = 20) {
         items: projects,
     });
 }
+/**
+ * Create a new GitLab repository
+ * 새 저장소 생성
+ *
+ * @param {z.infer<typeof CreateRepositoryOptionsSchema>} options - Repository creation options
+ * @returns {Promise<GitLabRepository>} The created repository
+ */
 async function createRepository(options) {
     const response = await fetch(`${GITLAB_API_URL}/projects`, {
         method: "POST",
@@ -347,7 +477,14 @@ async function createRepository(options) {
     const data = await response.json();
     return GitLabRepositorySchema.parse(data);
 }
-// MR 조회 함수
+/**
+ * Get merge request details
+ * MR 조회 함수 (Function to retrieve merge request)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {number} mergeRequestIid - The internal ID of the merge request
+ * @returns {Promise<GitLabMergeRequest>} The merge request details
+ */
 async function getMergeRequest(projectId, mergeRequestIid) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/merge_requests/${mergeRequestIid}`);
     const response = await fetch(url.toString(), {
@@ -356,7 +493,15 @@ async function getMergeRequest(projectId, mergeRequestIid) {
     await handleGitLabError(response);
     return GitLabMergeRequestSchema.parse(await response.json());
 }
-// MR 변경사항 조회 함수
+/**
+ * Get merge request changes/diffs
+ * MR 변경사항 조회 함수 (Function to retrieve merge request changes)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {number} mergeRequestIid - The internal ID of the merge request
+ * @param {string} [view] - The view type for the diff (inline or parallel)
+ * @returns {Promise<GitLabMergeRequestDiff[]>} The merge request diffs
+ */
 async function getMergeRequestDiffs(projectId, mergeRequestIid, view) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/merge_requests/${mergeRequestIid}/changes`);
     if (view) {
@@ -369,7 +514,15 @@ async function getMergeRequestDiffs(projectId, mergeRequestIid, view) {
     const data = (await response.json());
     return z.array(GitLabMergeRequestDiffSchema).parse(data.changes);
 }
-// MR 업데이트 함수
+/**
+ * Update a merge request
+ * MR 업데이트 함수 (Function to update merge request)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {number} mergeRequestIid - The internal ID of the merge request
+ * @param {Object} options - The update options
+ * @returns {Promise<GitLabMergeRequest>} The updated merge request
+ */
 async function updateMergeRequest(projectId, mergeRequestIid, options) {
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/merge_requests/${mergeRequestIid}`);
     const response = await fetch(url.toString(), {
@@ -380,7 +533,17 @@ async function updateMergeRequest(projectId, mergeRequestIid, options) {
     await handleGitLabError(response);
     return GitLabMergeRequestSchema.parse(await response.json());
 }
-// 📦 새로운 함수: createNote - 이슈 또는 병합 요청에 노트(댓글)를 추가하는 함수
+/**
+ * Create a new note (comment) on an issue or merge request
+ * 📦 새로운 함수: createNote - 이슈 또는 병합 요청에 노트(댓글)를 추가하는 함수
+ * (New function: createNote - Function to add a note (comment) to an issue or merge request)
+ *
+ * @param {string} projectId - The ID or URL-encoded path of the project
+ * @param {"issue" | "merge_request"} noteableType - The type of the item to add a note to (issue or merge_request)
+ * @param {number} noteableIid - The internal ID of the issue or merge request
+ * @param {string} body - The content of the note
+ * @returns {Promise<any>} The created note
+ */
 async function createNote(projectId, noteableType, // 'issue' 또는 'merge_request' 타입 명시
 noteableIid, body) {
     // ⚙️ 응답 타입은 GitLab API 문서에 따라 조정 가능
@@ -520,7 +683,7 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
             }
             case "create_or_update_file": {
                 const args = CreateOrUpdateFileSchema.parse(request.params.arguments);
-                const result = await createOrUpdateFile(args.project_id, args.file_path, args.content, args.commit_message, args.branch, args.previous_path);
+                const result = await createOrUpdateFile(args.project_id, args.file_path, args.content, args.commit_message, args.branch, args.previous_path, args.last_commit_id, args.commit_id);
                 return {
                     content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
                 };
@@ -597,6 +760,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw error;
     }
 });
+/**
+ * Initialize and run the server
+ * 서버 초기화 및 실행
+ */
 async function runServer() {
     try {
         console.error("========================");

package/build/schemas.js

@@ -39,7 +39,9 @@ export const GitLabFileContentSchema = z.object({
     content_sha256: z.string(), // Changed from sha to match GitLab API
     ref: z.string(), // Added as GitLab requires branch reference
     blob_id: z.string(), // Added to match GitLab API
+    commit_id: z.string(), // ID of the current file version
     last_commit_id: z.string(), // Added to match GitLab API
+    execute_filemode: z.boolean().optional(), // Added to match GitLab API
 });
 export const GitLabDirectoryContentSchema = z.object({
     name: z.string(),
@@ -122,7 +124,7 @@ export const CreateBranchOptionsSchema = z.object({
 export const GitLabCreateUpdateFileResponseSchema = z.object({
     file_path: z.string(),
     branch: z.string(),
-    commit_id: z.string(), // Changed from sha to match GitLab API
+    commit_id: z.string().optional(), // Optional since it's not always returned by the API
     content: GitLabFileContentSchema.optional(),
 });
 export const GitLabSearchResponseSchema = z.object({
@@ -236,6 +238,14 @@ export const CreateOrUpdateFileSchema = ProjectParamsSchema.extend({
         .string()
         .optional()
         .describe("Path of the file to move/rename"),
+    last_commit_id: z
+        .string()
+        .optional()
+        .describe("Last known file commit ID"),
+    commit_id: z
+        .string()
+        .optional()
+        .describe("Current file commit ID (for update operations)"),
 });
 export const SearchRepositoriesSchema = z.object({
     search: z.string().describe("Search query"), // Changed from query to match GitLab API

package/package.json

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