@zereight/mcp-gitlab 1.0.12 → 1.0.14

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,6 +252,18 @@ async function createMergeRequest(projectId, options) {
     const data = await response.json();
     return GitLabMergeRequestSchema.parse(data);
 }
+/**
+ * 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) {
     const encodedPath = encodeURIComponent(filePath);
     const url = new URL(`${GITLAB_API_URL}/projects/${encodeURIComponent(projectId)}/repository/files/${encodedPath}`);
@@ -231,6 +302,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 +342,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 +383,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 +422,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 +453,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 +469,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 +490,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 +509,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 문서에 따라 조정 가능
@@ -597,6 +736,10 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         throw error;
     }
 });
+/**
+ * Initialize and run the server
+ * 서버 초기화 및 실행
+ */
 async function runServer() {
     try {
         console.error("========================");

package/package.json

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