@zereight/mcp-gitlab 2.3.25-next.221 → 2.3.25-next.223

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.ko.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # GitLab MCP Server
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
4
+ [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
5
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/zereight/gitlab-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/zereight/gitlab-mcp)
6
+ [![CodeQL](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml?query=branch%3Amain)
7
+ [![Live API Tests](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml?query=branch%3Amain)
4
8
 
5
9
  [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
6
10
 
package/README.md CHANGED
@@ -5,6 +5,8 @@
5
5
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
6
6
  [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
7
7
  [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/zereight/gitlab-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/zereight/gitlab-mcp)
8
+ [![CodeQL](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml?query=branch%3Amain)
9
+ [![Live API Tests](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml?query=branch%3Amain)
8
10
  [![Ask DeepWiki](https://img.shields.io/badge/DeepWiki-Ask-blue)](https://deepwiki.com/zereight/gitlab-mcp)
9
11
  [![MCP Toplist](https://mcptoplist.com/badge/io.github.zereight%2Fgitlab-mcp.svg)](https://mcptoplist.com/server/io.github.zereight%2Fgitlab-mcp)
10
12
  [![mcpindex](https://mcpindex.ai/api/v1/badge/io-github-zereight-gitlab-mcp)](https://mcpindex.ai/server/io-github-zereight-gitlab-mcp)
package/README.pt-BR.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # GitLab MCP Server
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
4
+ [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
5
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/zereight/gitlab-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/zereight/gitlab-mcp)
6
+ [![CodeQL](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml?query=branch%3Amain)
7
+ [![Live API Tests](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml?query=branch%3Amain)
4
8
 
5
9
  [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
6
10
 
package/README.zh-CN.md CHANGED
@@ -1,6 +1,10 @@
1
1
  # GitLab MCP Server
2
2
 
3
3
  [![npm](https://img.shields.io/npm/v/@zereight/mcp-gitlab.svg)](https://www.npmjs.com/package/@zereight/mcp-gitlab)
4
+ [![GitHub License](https://badgen.net/github/license/zereight/gitlab-mcp)](https://github.com/zereight/gitlab-mcp/blob/main/LICENSE)
5
+ [![OpenSSF Scorecard](https://api.securityscorecards.dev/projects/github.com/zereight/gitlab-mcp/badge)](https://scorecard.dev/viewer/?uri=github.com/zereight/gitlab-mcp)
6
+ [![CodeQL](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/codeql.yml?query=branch%3Amain)
7
+ [![Live API Tests](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml/badge.svg?branch=main)](https://github.com/zereight/gitlab-mcp/actions/workflows/live-tests.yml?query=branch%3Amain)
4
8
 
5
9
  [English](./README.md) | [한국어](./README.ko.md) | [简体中文](./README.zh-CN.md) | [Português (Brasil)](./README.pt-BR.md)
6
10
 
package/build/index.js CHANGED
@@ -125,7 +125,7 @@ import { parseGitLabVersionApiResponse, } from "./utils/gitlab-instance-version.
125
125
  import { buildBulkPublishDraftNotesBody, needsGitLab19_2BulkPublish, } from "./utils/bulk-publish-options.js";
126
126
  import { appendFilterParam, appendFilterParams, cleanMutuallyExclusiveIdUsernameOptions, dropBlankArrayEntries, isBlankFilterValue, LIST_MERGE_REQUESTS_ID_USERNAME_PAIRS, sanitizeToolArguments, } from "./utils/tool-args.js";
127
127
  import { applyJmespathToToolResult, getJmespathSyntaxError, JMESPATH_TOOL_ARGUMENT, JMESPATH_TOOL_ARGUMENT_DESCRIPTION, omitJmespathArgument, readJmespathExpression, } from "./utils/jmespath-tool-result.js";
128
- import { appendRecoveryHint } from "./utils/error-hints.js";
128
+ import { appendRecoveryHint, withRecoveryHint } from "./utils/error-hints.js";
129
129
  import { applyListSummaryToToolResult, omitListSummaryArgument, readListSummaryRequested, toolAcceptsDecoratedSummary, toolUsesListSummaryDefault, } from "./utils/list-summary.js";
130
130
  import { parseSearchReplaceBlocks, applySearchReplace, applyUnifiedDiff, } from "./utils/patch-helper.js";
131
131
  import { zodSchemaFor } from "./utils/schema.js";
@@ -135,6 +135,7 @@ import { executeGitLabApiRequestAsync, GitLabApiRequestHttpError, GitLabApiReque
135
135
  import { configureWikiTools, handleWikiToolCall } from "./tools/wiki.js";
136
136
  import { configureMilestoneTools, handleMilestoneToolCall } from "./tools/milestones.js";
137
137
  import { configureLabelTools, handleLabelToolCall } from "./tools/labels.js";
138
+ import { configureTagTools, handleTagToolCall } from "./tools/tags.js";
138
139
  import { buildUnavailableToolMessage, isSkippedByDiscoverActivation, } from "./tools/discover-activation.js";
139
140
  import { selectCallableHiddenToolNames, selectExposedTools } from "./tools/exposed-tools.js";
140
141
  import { createListedToolsCache, decorateToolsForList, } from "./tools/listed-tools.js";
@@ -145,8 +146,8 @@ import { BulkPublishDraftNotesSchema, CancelPipelineJobSchema, ErasePipelineJobS
145
146
  GitLabDiscussionNoteSchema, // Added
146
147
  GitLabDiscussionSchema,
147
148
  // Draft Notes Schemas
148
- GitLabDraftNoteSchema, GitLabForkSchema, GitLabBranchSchema, GitLabProtectedBranchSchema, GitLabProtectedTagSchema, GitLabGroupSchema, GitLabIssueLinkSchema, GitLabIssueSchema, GitLabIssueWithLinkDetailsSchema, GitLabMarkdownUploadSchema, GitLabMergeRequestPipelineSchema, GitLabMergeRequestSchema, GitLabNamespaceExistsResponseSchema, GitLabNamespaceSchema, GitLabPipelineJobSchema, GitLabDeploymentSchema, GitLabEnvironmentSchema, GitLabPipelineSchema, GitLabPipelineScheduleSchema, GitLabPipelineScheduleVariableSchema, GitLabPipelineSchedulePlayResultSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, GitLabPipelineTriggerJobSchema, GitLabProjectMemberSchema, GitLabProjectSchema, GitLabTodoSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabSearchBlobResultSchema, GitLabSearchResponseSchema, GitLabTreeItemSchema, GitLabUserSchema, GitLabUsersResponseSchema, GroupIteration, ListCommitStatusesSchema, ListBranchesSchema, ListCommitsSchema, ListDraftNotesSchema, ListGroupIterationsSchema, GetGroupIterationSchema, UpdateGroupIterationSchema, CreateGroupIterationSchema, GroupIterationCadence, ListGroupIterationCadencesSchema, DeleteGroupIterationSchema, ListProjectIterationsSchema, CreateGroupIterationCadenceSchema, UpdateGroupIterationCadenceSchema, DeleteGroupIterationCadenceSchema, ListGroupProjectsSchema, GitLabCiVariableSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GitLabDependencyProxySchema, GitLabDependencyProxyBlobSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListTodosSchema, ListMergeRequestDiffsSchema, // Added
149
- GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListProjectRunnersSchema, GetRunnerSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListProjectMembersSchema, ListGroupMembersSchema, ListProjectsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, RebaseMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, MarkAllTodosDoneSchema, MarkTodoDoneSchema, PaginatedDiscussionsResponseSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, ReorderIssueSchema, UpdateProjectSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, ListTagsSchema, GetTagSchema, CreateTagSchema, DeleteTagSchema, GetTagSignatureSchema, ListProtectedTagsSchema, GetProtectedTagSchema, ProtectTagSchema, UnprotectTagSchema, GitLabTagSchema, GitLabTagSignatureSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, GitLabSnippetSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, GetMergeRequestDiscussionSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, CreateWebhookSchema, UpdateWebhookSchema, DeleteWebhookSchema, ListWebhookEventsSchema, GetWebhookEventSchema, HealthCheckSchema, } from "./schemas.js";
149
+ GitLabDraftNoteSchema, GitLabForkSchema, GitLabBranchSchema, GitLabProtectedBranchSchema, GitLabGroupSchema, GitLabIssueLinkSchema, GitLabIssueSchema, GitLabIssueWithLinkDetailsSchema, GitLabMarkdownUploadSchema, GitLabMergeRequestPipelineSchema, GitLabMergeRequestSchema, GitLabNamespaceExistsResponseSchema, GitLabNamespaceSchema, GitLabPipelineJobSchema, GitLabDeploymentSchema, GitLabEnvironmentSchema, GitLabPipelineSchema, GitLabPipelineScheduleSchema, GitLabPipelineScheduleVariableSchema, GitLabPipelineSchedulePlayResultSchema, ListPipelineSchedulesSchema, GetPipelineScheduleSchema, ListPipelineSchedulePipelinesSchema, CreatePipelineScheduleSchema, UpdatePipelineScheduleSchema, DeletePipelineScheduleSchema, PlayPipelineScheduleSchema, TakeOwnershipPipelineScheduleSchema, GetPipelineScheduleVariableSchema, CreatePipelineScheduleVariableSchema, UpdatePipelineScheduleVariableSchema, DeletePipelineScheduleVariableSchema, GitLabPipelineTriggerJobSchema, GitLabProjectMemberSchema, GitLabProjectSchema, GitLabTodoSchema, GitLabReferenceSchema, GitLabRepositorySchema, GitLabSearchBlobResultSchema, GitLabSearchResponseSchema, GitLabTreeItemSchema, GitLabUserSchema, GitLabUsersResponseSchema, GroupIteration, ListCommitStatusesSchema, ListBranchesSchema, ListCommitsSchema, ListDraftNotesSchema, ListGroupIterationsSchema, GetGroupIterationSchema, UpdateGroupIterationSchema, CreateGroupIterationSchema, GroupIterationCadence, ListGroupIterationCadencesSchema, DeleteGroupIterationSchema, ListProjectIterationsSchema, CreateGroupIterationCadenceSchema, UpdateGroupIterationCadenceSchema, DeleteGroupIterationCadenceSchema, ListGroupProjectsSchema, GitLabCiVariableSchema, ListProjectVariablesSchema, GetProjectVariableSchema, CreateProjectVariableSchema, UpdateProjectVariableSchema, DeleteProjectVariableSchema, ListGroupVariablesSchema, GetGroupVariableSchema, CreateGroupVariableSchema, UpdateGroupVariableSchema, DeleteGroupVariableSchema, GitLabDependencyProxySchema, GitLabDependencyProxyBlobSchema, GetDependencyProxySettingsSchema, UpdateDependencyProxySettingsSchema, ListDependencyProxyBlobsSchema, PurgeDependencyProxyCacheSchema, ListProjectVulnerabilitiesSchema, GetVulnerabilitySchema, DismissVulnerabilitySchema, ConfirmVulnerabilitySchema, ListIssueDiscussionsSchema, ListIssueLinksSchema, ListIssuesSchema, ListTodosSchema, ListMergeRequestDiffsSchema, // Added
150
+ GetMergeRequestFileDiffSchema, ListMergeRequestChangedFilesSchema, ListMergeRequestDiscussionsSchema, ListMergeRequestPipelinesSchema, ListMergeRequestsSchema, ListGroupMergeRequestsSchema, ListMergeRequestVersionsSchema, GetMergeRequestVersionSchema, GitLabMergeRequestVersionSchema, GitLabMergeRequestVersionDetailSchema, ListNamespacesSchema, ListPipelineJobsSchema, ListPipelinesSchema, ListDeploymentsSchema, ListEnvironmentsSchema, ListProjectRunnersSchema, GetRunnerSchema, ListPipelineTriggerJobsSchema, ValidateCiLintSchema, ValidateProjectCiLintSchema, ListCiCatalogResourcesSchema, GetCiCatalogResourceSchema, ListProjectMembersSchema, ListGroupMembersSchema, ListProjectsSchema, MarkdownUploadSchema, MarkdownUploadRemoteSchema, DownloadAttachmentSchema, DownloadJobArtifactsSchema, GetJobArtifactFileSchema, GitLabArtifactEntrySchema, ListJobArtifactsSchema, MergeMergeRequestSchema, ApproveMergeRequestSchema, UnapproveMergeRequestSchema, RebaseMergeRequestSchema, GetMergeRequestApprovalStateSchema, GetMergeRequestConflictsSchema, GitLabMergeRequestApprovalStateSchema, MyIssuesSchema, OrbitQuerySchema, OrbitSchemaSchema, OrbitStatusSchema, OrbitToolsSchema, MarkAllTodosDoneSchema, MarkTodoDoneSchema, PaginatedDiscussionsResponseSchema, PublishDraftNoteSchema, PlayPipelineJobSchema, PushFilesSchema, RetryPipelineJobSchema, RetryPipelineSchema, SearchCodeSchema, SearchGroupCodeSchema, SearchProjectCodeSchema, SearchRepositoriesSchema, UpdateDraftNoteSchema, UpdateIssueNoteSchema, UpdateIssueSchema, UpdateIssueDescriptionPatchSchema, ReorderIssueSchema, UpdateProjectSchema, UpdateMergeRequestNoteSchema, UpdateMergeRequestDiscussionNoteSchema, UpdateMergeRequestSchema, VerifyNamespaceSchema, GitLabEventSchema, ListEventsSchema, GetProjectEventsSchema, ExecuteGraphQLSchema, GitLabReleaseSchema, ListReleasesSchema, GetReleaseSchema, CreateReleaseSchema, UpdateReleaseSchema, DeleteReleaseSchema, CreateReleaseEvidenceSchema, DownloadReleaseAssetSchema, ListSnippetsSchema, GetSnippetSchema, CreateSnippetSchema, UpdateSnippetSchema, DeleteSnippetSchema, GitLabSnippetSchema, GetMergeRequestNotesSchema, GetMergeRequestNoteSchema, GetMergeRequestDiscussionSchema, DeleteMergeRequestDiscussionNoteSchema, ResolveMergeRequestThreadSchema, GetWorkItemSchema, ListWorkItemsSchema, CreateWorkItemSchema, UpdateWorkItemSchema, ConvertWorkItemTypeSchema, ListWorkItemStatusesSchema, ListWorkItemNotesSchema, CreateWorkItemNoteSchema, CreateWorkItemEmojiReactionSchema, CreateWorkItemNoteEmojiReactionSchema, ListWorkItemEmojiReactionsSchema, ListWorkItemNoteEmojiReactionsSchema, DeleteWorkItemEmojiReactionSchema, DeleteWorkItemNoteEmojiReactionSchema, MoveWorkItemSchema, ListCustomFieldDefinitionsSchema, GetTimelineEventsSchema, CreateTimelineEventSchema, ListWebhooksSchema, CreateWebhookSchema, UpdateWebhookSchema, DeleteWebhookSchema, ListWebhookEventsSchema, GetWebhookEventSchema, HealthCheckSchema, } from "./schemas.js";
150
151
  import { createHash, randomUUID, timingSafeEqual } from "node:crypto";
151
152
  import { createLogger, flushBufferedLogs, flushStartupLogs } from "./utils/logger.js";
152
153
  const logger = createLogger();
@@ -989,8 +990,8 @@ configureGitLabRequestContext({
989
990
  getDispatcherForUrl: apiUrl => clientPool.getDispatcherForUrl(apiUrl),
990
991
  getOAuthAccessToken: () => OAUTH_ACCESS_TOKEN,
991
992
  });
992
- // The wiki, milestone, and label handlers call back into the fetch, error handling, and project
993
- // scope helpers below; fetch is read at call time because the cookie reload replaces it.
993
+ // The wiki, milestone, label, and tag handlers call back into the fetch, error handling, and
994
+ // project scope helpers below; fetch is read at call time because the cookie reload replaces it.
994
995
  configureWikiTools({
995
996
  getFetch: () => fetch,
996
997
  handleGitLabError,
@@ -1008,6 +1009,11 @@ configureLabelTools({
1008
1009
  handleGitLabError,
1009
1010
  getEffectiveProjectId,
1010
1011
  });
1012
+ configureTagTools({
1013
+ getFetch: () => fetch,
1014
+ handleGitLabError,
1015
+ getEffectiveProjectId,
1016
+ });
1011
1017
  // Create cookie jar with clean Netscape file parsing
1012
1018
  // Resolve cookie path once using os.homedir() for cross-platform support
1013
1019
  const resolvedCookiePath = GITLAB_AUTH_COOKIE_PATH
@@ -1364,6 +1370,12 @@ class ProjectAccessDeniedError extends Error {
1364
1370
  }
1365
1371
  }
1366
1372
  const MERGE_REQUEST_IDENTIFIER_REQUIRED = "Either merge_request_iid or source_branch must be provided";
1373
+ // Next-step hints for lookups that found nothing (see withRecoveryHint).
1374
+ const PROJECT_NOT_FOUND_HINT = "check project_id (numeric ID or group%2Fproject) and that the token can read the project.";
1375
+ const GROUP_NOT_FOUND_HINT = "check group_id (numeric ID or URL-encoded path such as parent%2Fchild) and that the token can read the group.";
1376
+ const WORK_ITEM_NOT_FOUND_HINT = "check project_id and the work item iid (the #number shown in GitLab, not the global ID).";
1377
+ const WORK_ITEM_TYPE_NOT_FOUND_HINT = "this project does not offer that work item type (some types need a higher GitLab tier or are turned off); use another type, such as issue or task.";
1378
+ const VULNERABILITY_NOT_FOUND_HINT = "check vulnerability_id; list_project_vulnerabilities lists the vulnerabilities the token can read.";
1367
1379
  /**
1368
1380
  * Utility function for handling GitLab API errors
1369
1381
  * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
@@ -1442,7 +1454,7 @@ function getEffectiveProjectId(projectId) {
1442
1454
  }
1443
1455
  // If no project ID provided but we have multiple allowed projects, require an explicit choice
1444
1456
  if (!projectId && allowedProjectIds.length > 1) {
1445
- throw new Error(`Multiple projects allowed (${allowedProjectIds.join(", ")}). Please specify a project ID.`);
1457
+ throw new ToolInputError(withRecoveryHint(`Multiple projects allowed (${allowedProjectIds.join(", ")}). Please specify a project ID.`, "pass project_id set to one of the allowed projects listed above."));
1446
1458
  }
1447
1459
  return projectId || allowedProjectIds[0];
1448
1460
  }
@@ -1453,7 +1465,7 @@ function getEffectiveProjectId(projectId) {
1453
1465
  if (GITLAB_PROJECT_ID) {
1454
1466
  return GITLAB_PROJECT_ID;
1455
1467
  }
1456
- throw new Error("No project ID provided and GITLAB_PROJECT_ID is not set");
1468
+ throw new ToolInputError(withRecoveryHint("No project ID provided and GITLAB_PROJECT_ID is not set", "pass project_id (numeric ID or group%2Fproject), or set GITLAB_PROJECT_ID to give the server a default project."));
1457
1469
  }
1458
1470
  function rejectIfProjectScopedDeployment(toolName) {
1459
1471
  if (GITLAB_PROJECT_ID) {
@@ -1914,7 +1926,7 @@ async function resolveWorkItemGID(projectId, issueIid) {
1914
1926
  }
1915
1927
  }`, { path: projectPath, iid: String(issueIid) });
1916
1928
  if (!data.namespace?.workItem?.id) {
1917
- throw new Error(`Work item #${issueIid} not found in namespace ${projectPath}`);
1929
+ throw new ToolInputError(withRecoveryHint(`Work item #${issueIid} not found in namespace ${projectPath}`, WORK_ITEM_NOT_FOUND_HINT));
1918
1930
  }
1919
1931
  return { workItemGID: data.namespace.workItem.id, projectPath, namespaceKind };
1920
1932
  }
@@ -1941,18 +1953,22 @@ async function resolveNamesToIds(projectPath, namespaceKind, labelNames, usernam
1941
1953
  }`, { path: projectPath, usernames, ...labelVars });
1942
1954
  const labelNamespace = namespaceKind === "group" ? data.group : data.project;
1943
1955
  if (!labelNamespace) {
1944
- throw new Error(`Namespace '${projectPath}' not found or inaccessible`);
1956
+ throw new ToolInputError(withRecoveryHint(`Namespace '${projectPath}' not found or inaccessible`, "check project_id (numeric ID, group%2Fproject, or group:<path> for a group) and that the token can read it."));
1945
1957
  }
1946
1958
  const labelIds = labelNames.map((name, i) => {
1947
1959
  const nodes = labelNamespace[`l${i}`]?.nodes;
1948
- if (!nodes?.length)
1949
- throw new Error(`Label '${name}' not found in namespace`);
1960
+ if (!nodes?.length) {
1961
+ throw new ToolInputError(withRecoveryHint(`Label '${name}' not found in namespace`, namespaceKind === "group"
1962
+ ? "use an existing group label title, or create a group label in GitLab first."
1963
+ : "use an existing label title (list_labels shows them), or create it first with create_label."));
1964
+ }
1950
1965
  return nodes[0].id;
1951
1966
  });
1952
1967
  const userIds = usernames.map(name => {
1953
1968
  const user = data.users.nodes.find(u => u.username === name);
1954
- if (!user)
1955
- throw new Error(`User '${name}' not found`);
1969
+ if (!user) {
1970
+ throw new ToolInputError(withRecoveryHint(`User '${name}' not found`, "pass the GitLab username without a leading @; get_users looks usernames up."));
1971
+ }
1956
1972
  return user.id;
1957
1973
  });
1958
1974
  return { labelIds, userIds };
@@ -1978,7 +1994,7 @@ const WORK_ITEM_TYPE_NAMES = {
1978
1994
  async function resolveWorkItemTypeGID(projectPath, typeName) {
1979
1995
  const targetName = WORK_ITEM_TYPE_NAMES[typeName];
1980
1996
  if (!targetName) {
1981
- throw new Error(`Unknown work item type: ${typeName}`);
1997
+ throw new ToolInputError(withRecoveryHint(`Unknown work item type: ${typeName}`, `use one of: ${Object.keys(WORK_ITEM_TYPE_NAMES).join(", ")}.`));
1982
1998
  }
1983
1999
  const data = await executeGraphQL(`query($path: ID!) {
1984
2000
  namespace(fullPath: $path) {
@@ -1992,7 +2008,7 @@ async function resolveWorkItemTypeGID(projectPath, typeName) {
1992
2008
  }`, { path: projectPath });
1993
2009
  const typeNode = data.namespace?.workItemTypes?.nodes?.find(n => n.name === targetName);
1994
2010
  if (!typeNode) {
1995
- throw new Error(`Work item type '${targetName}' not found in project ${projectPath}`);
2011
+ throw new ToolInputError(withRecoveryHint(`Work item type '${targetName}' not found in project ${projectPath}`, WORK_ITEM_TYPE_NOT_FOUND_HINT));
1996
2012
  }
1997
2013
  return typeNode.id;
1998
2014
  }
@@ -2072,7 +2088,7 @@ async function listIssueStatuses(projectId, workItemType = "issue") {
2072
2088
  }`, { path: projectPath, typeName: typeName.replace(/ /g, "_").toUpperCase() });
2073
2089
  const typeNodes = data.namespace?.workItemTypes?.nodes;
2074
2090
  if (!typeNodes || typeNodes.length === 0) {
2075
- throw new Error(`Work item type '${typeName}' not found in project`);
2091
+ throw new ToolInputError(withRecoveryHint(`Work item type '${typeName}' not found in project`, WORK_ITEM_TYPE_NOT_FOUND_HINT));
2076
2092
  }
2077
2093
  const typeNode = typeNodes[0];
2078
2094
  // Extract statuses from the status widget definition
@@ -2133,7 +2149,7 @@ async function listCustomFieldDefinitions(projectId, workItemType = "issue") {
2133
2149
  }`, { path: projectPath, typeName: typeName.replace(/ /g, "_").toUpperCase() });
2134
2150
  const typeNodes = data.namespace?.workItemTypes?.nodes;
2135
2151
  if (!typeNodes || typeNodes.length === 0) {
2136
- throw new Error(`Work item type '${typeName}' not found in project`);
2152
+ throw new ToolInputError(withRecoveryHint(`Work item type '${typeName}' not found in project`, WORK_ITEM_TYPE_NOT_FOUND_HINT));
2137
2153
  }
2138
2154
  const typeNode = typeNodes[0];
2139
2155
  const customFieldsWidget = typeNode.widgetDefinitions?.find((w) => w.__typename === "WorkItemWidgetDefinitionCustomFields");
@@ -2218,7 +2234,7 @@ async function listWorkItemNotes(projectId, iid, options = {}) {
2218
2234
  });
2219
2235
  const workItem = data.namespace?.workItem;
2220
2236
  if (!workItem) {
2221
- throw new Error(`Work item #${iid} not found in project ${projectPath}`);
2237
+ throw new ToolInputError(withRecoveryHint(`Work item #${iid} not found in project ${projectPath}`, WORK_ITEM_NOT_FOUND_HINT));
2222
2238
  }
2223
2239
  const notesWidget = workItem.widgets?.find((w) => w.discussions);
2224
2240
  const discussions = notesWidget?.discussions;
@@ -2624,7 +2640,7 @@ async function getWorkItem(projectId, iid) {
2624
2640
  }
2625
2641
  }`, { path: projectPath, iid: String(iid) });
2626
2642
  if (!data.namespace?.workItem) {
2627
- throw new Error(`Work item #${iid} not found in project ${projectPath}`);
2643
+ throw new ToolInputError(withRecoveryHint(`Work item #${iid} not found in project ${projectPath}`, WORK_ITEM_NOT_FOUND_HINT));
2628
2644
  }
2629
2645
  const wi = data.namespace.workItem;
2630
2646
  const widgets = wi.widgets || [];
@@ -4580,10 +4596,10 @@ async function getMergeRequestConflicts(projectId, mergeRequestIid) {
4580
4596
  }`, variables);
4581
4597
  }
4582
4598
  if (!data.project) {
4583
- throw new Error(`Project not found or not accessible: ${fullPath}`);
4599
+ throw new ToolInputError(withRecoveryHint(`Project not found or not accessible: ${fullPath}`, PROJECT_NOT_FOUND_HINT));
4584
4600
  }
4585
4601
  if (!data.project.mergeRequest) {
4586
- throw new Error(`Merge request !${mergeRequestIid} not found in project ${fullPath}`);
4602
+ throw new ToolInputError(withRecoveryHint(`Merge request !${mergeRequestIid} not found in project ${fullPath}`, "check merge_request_iid (the !number shown in GitLab, not the global ID)."));
4587
4603
  }
4588
4604
  const { conflicts, conflictStatus, conflictFiles } = data.project.mergeRequest;
4589
4605
  const result = { has_conflicts: conflicts };
@@ -6421,7 +6437,7 @@ async function listCommitStatuses(projectId, sha, options = {}) {
6421
6437
  */
6422
6438
  async function createCommitStatus(projectId, sha, options) {
6423
6439
  if (options.name && options.context) {
6424
- throw new Error("Use either name or context when creating a commit status, not both.");
6440
+ throw new ToolInputError(withRecoveryHint("Use either name or context when creating a commit status, not both.", "pass only name or only context; both set the same status label."));
6425
6441
  }
6426
6442
  projectId = decodeURIComponent(projectId);
6427
6443
  const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(getEffectiveProjectId(projectId))}/statuses/${encodeGitLabPathSegment(sha)}`);
@@ -6827,7 +6843,7 @@ async function listGroupIterationCadences(groupId, options = {}) {
6827
6843
  after,
6828
6844
  });
6829
6845
  if (!data.group) {
6830
- throw new Error(`Group ${groupPath} was not found`);
6846
+ throw new ToolInputError(withRecoveryHint(`Group ${groupPath} was not found`, GROUP_NOT_FOUND_HINT));
6831
6847
  }
6832
6848
  const { nodes, pageInfo } = data.group.iterationCadences;
6833
6849
  cadences.push(...nodes.map(toGroupIterationCadence));
@@ -7069,8 +7085,9 @@ async function getDependencyProxySettings(groupPath) {
7069
7085
  }
7070
7086
  }`, { fullPath });
7071
7087
  const g = data.group;
7072
- if (!g)
7073
- throw new Error(`Group not found: ${fullPath}`);
7088
+ if (!g) {
7089
+ throw new ToolInputError(withRecoveryHint(`Group not found: ${fullPath}`, GROUP_NOT_FOUND_HINT));
7090
+ }
7074
7091
  return GitLabDependencyProxySchema.parse({
7075
7092
  enabled: g.dependencyProxySetting?.enabled ?? false,
7076
7093
  blob_count: g.dependencyProxyBlobCount,
@@ -7083,7 +7100,7 @@ async function updateDependencyProxySettings(groupPath, options) {
7083
7100
  if (options.enabled === undefined &&
7084
7101
  options.identity === undefined &&
7085
7102
  options.secret === undefined) {
7086
- throw new Error("At least one of enabled, identity, or secret must be provided");
7103
+ throw new ToolInputError(withRecoveryHint("At least one of enabled, identity, or secret must be provided", "pass enabled (true or false), identity, or secret; get_dependency_proxy_settings shows the current settings."));
7087
7104
  }
7088
7105
  const fullPath = await resolveGroupFullPath(groupPath);
7089
7106
  const input = { groupPath: fullPath };
@@ -7113,8 +7130,9 @@ async function listDependencyProxyBlobs(groupPath, options = {}) {
7113
7130
  }
7114
7131
  }`, { fullPath, first: options.first ?? 20, after: options.after });
7115
7132
  const conn = data.group?.dependencyProxyBlobs;
7116
- if (!conn)
7117
- throw new Error(`Group not found or dependency proxy not enabled: ${fullPath}`);
7133
+ if (!conn) {
7134
+ throw new ToolInputError(withRecoveryHint(`Group not found or dependency proxy not enabled: ${fullPath}`, "check group_id, then run get_dependency_proxy_settings to see whether the dependency proxy is enabled."));
7135
+ }
7118
7136
  return {
7119
7137
  blobs: conn.nodes.map(n => GitLabDependencyProxyBlobSchema.parse({
7120
7138
  file_name: n.fileName,
@@ -7143,7 +7161,7 @@ function toVulnerabilityGid(vulnerabilityId) {
7143
7161
  if (/^gid:\/\/gitlab\/Vulnerability\/\d+$/.test(vulnerabilityId)) {
7144
7162
  return vulnerabilityId;
7145
7163
  }
7146
- throw new Error(`Invalid vulnerability ID "${vulnerabilityId}": expected a numeric ID or a gid://gitlab/Vulnerability/<id> global ID`);
7164
+ throw new ToolInputError(withRecoveryHint(`Invalid vulnerability ID "${vulnerabilityId}": expected a numeric ID or a gid://gitlab/Vulnerability/<id> global ID`, "copy the id from list_project_vulnerabilities, for example 123 or gid://gitlab/Vulnerability/123."));
7147
7165
  }
7148
7166
  /**
7149
7167
  * Resolve a project ID or path to the full namespace path required by
@@ -7203,7 +7221,7 @@ async function ensureVulnerabilityProjectAllowed(vulnerabilityId) {
7203
7221
  }
7204
7222
  }`, { id: toVulnerabilityGid(vulnerabilityId) });
7205
7223
  if (!data.vulnerability) {
7206
- throw new Error(`Vulnerability not found: ${vulnerabilityId}`);
7224
+ throw new ToolInputError(withRecoveryHint(`Vulnerability not found: ${vulnerabilityId}`, VULNERABILITY_NOT_FOUND_HINT));
7207
7225
  }
7208
7226
  assertVulnerabilityProjectAllowed(vulnerabilityId, data.vulnerability.project);
7209
7227
  }
@@ -7313,7 +7331,7 @@ async function listProjectVulnerabilities(projectId, options = {}) {
7313
7331
  }
7314
7332
  }`, variables);
7315
7333
  if (!data.project) {
7316
- throw new Error(`Project not found or not accessible: ${fullPath}`);
7334
+ throw new ToolInputError(withRecoveryHint(`Project not found or not accessible: ${fullPath}`, PROJECT_NOT_FOUND_HINT));
7317
7335
  }
7318
7336
  return {
7319
7337
  vulnerabilities: data.project.vulnerabilities.nodes,
@@ -7373,7 +7391,7 @@ async function getVulnerability(vulnerabilityId) {
7373
7391
  }
7374
7392
  }`, { id: toVulnerabilityGid(vulnerabilityId) });
7375
7393
  if (!data.vulnerability) {
7376
- throw new Error(`Vulnerability not found: ${vulnerabilityId}`);
7394
+ throw new ToolInputError(withRecoveryHint(`Vulnerability not found: ${vulnerabilityId}`, VULNERABILITY_NOT_FOUND_HINT));
7377
7395
  }
7378
7396
  assertVulnerabilityProjectAllowed(vulnerabilityId, data.vulnerability.project);
7379
7397
  return data.vulnerability;
@@ -7461,7 +7479,7 @@ async function markdownUpload(projectId, filePath, content, filename) {
7461
7479
  fileName = safeBasename;
7462
7480
  }
7463
7481
  else {
7464
- throw new Error("Either file_path or content must be provided");
7482
+ throw new ToolInputError(withRecoveryHint("Either file_path or content must be provided", "pass a non-empty file_path, or base64 content with filename."));
7465
7483
  }
7466
7484
  // Create form data
7467
7485
  const form = new FormData();
@@ -7500,7 +7518,7 @@ function getSafeAttachmentFilename(filename) {
7500
7518
  filename === ".." ||
7501
7519
  filename.includes("/") ||
7502
7520
  filename.includes("\\")) {
7503
- throw new Error("Invalid filename: directory separators are not allowed.");
7521
+ throw new ToolInputError(withRecoveryHint("Invalid filename: directory separators are not allowed.", "pass only the last segment of the upload URL (/uploads/<secret>/<filename>), without / or \\."));
7504
7522
  }
7505
7523
  return filename;
7506
7524
  }
@@ -7717,88 +7735,6 @@ async function downloadReleaseAsset(projectId, tagName, directAssetPath) {
7717
7735
  await handleGitLabError(response);
7718
7736
  return await response.text();
7719
7737
  }
7720
- /**
7721
- * List repository tags
7722
- *
7723
- * @param projectId The ID or URL-encoded path of the project
7724
- * @param options Optional parameters for filtering and pagination
7725
- * @returns Array of GitLab tags
7726
- */
7727
- async function listTags(projectId, options = {}) {
7728
- const effectiveProjectId = getEffectiveProjectId(projectId);
7729
- const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags`);
7730
- appendFilterParams(url.searchParams, options);
7731
- const response = await fetch(url.toString(), {
7732
- ...getFetchConfig(),
7733
- });
7734
- await handleGitLabError(response);
7735
- const data = await response.json();
7736
- return GitLabTagSchema.array().parse(data);
7737
- }
7738
- /**
7739
- * Get a repository tag by name
7740
- *
7741
- * @param projectId The ID or URL-encoded path of the project
7742
- * @param tagName The name of the tag
7743
- * @returns GitLab tag
7744
- */
7745
- async function getTag(projectId, tagName) {
7746
- const effectiveProjectId = getEffectiveProjectId(projectId);
7747
- const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}`, {
7748
- ...getFetchConfig(),
7749
- });
7750
- await handleGitLabError(response);
7751
- const data = await response.json();
7752
- return GitLabTagSchema.parse(data);
7753
- }
7754
- /**
7755
- * Create a new repository tag
7756
- *
7757
- * @param projectId The ID or URL-encoded path of the project
7758
- * @param options Options for creating the tag
7759
- * @returns Created GitLab tag
7760
- */
7761
- async function createTag(projectId, options) {
7762
- const effectiveProjectId = getEffectiveProjectId(projectId);
7763
- const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags`, {
7764
- ...getFetchConfig(),
7765
- method: "POST",
7766
- body: JSON.stringify(options),
7767
- });
7768
- await handleGitLabError(response);
7769
- const data = await response.json();
7770
- return GitLabTagSchema.parse(data);
7771
- }
7772
- /**
7773
- * Delete a repository tag
7774
- *
7775
- * @param projectId The ID or URL-encoded path of the project
7776
- * @param tagName The name of the tag
7777
- */
7778
- async function deleteTag(projectId, tagName) {
7779
- const effectiveProjectId = getEffectiveProjectId(projectId);
7780
- const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}`, {
7781
- ...getFetchConfig(),
7782
- method: "DELETE",
7783
- });
7784
- await handleGitLabError(response);
7785
- }
7786
- /**
7787
- * Get the signature of a repository tag
7788
- *
7789
- * @param projectId The ID or URL-encoded path of the project
7790
- * @param tagName The name of the tag
7791
- * @returns Tag signature
7792
- */
7793
- async function getTagSignature(projectId, tagName) {
7794
- const effectiveProjectId = getEffectiveProjectId(projectId);
7795
- const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}/signature`, {
7796
- ...getFetchConfig(),
7797
- });
7798
- await handleGitLabError(response);
7799
- const data = await response.json();
7800
- return GitLabTagSignatureSchema.parse(data);
7801
- }
7802
7738
  async function executeGitLabGraphQL(query, variables = {}) {
7803
7739
  const apiUrl = new URL(getEffectiveApiUrl());
7804
7740
  const restPath = apiUrl.pathname || "";
@@ -7923,7 +7859,7 @@ function snippetCreateFilesPayload(options) {
7923
7859
  if (options.file_name !== undefined && options.content !== undefined) {
7924
7860
  return [{ file_path: options.file_name, content: options.content }];
7925
7861
  }
7926
- throw new Error("Provide either files[] (multi-file) or both file_name and content (single-file)");
7862
+ throw new ToolInputError(withRecoveryHint("Provide either files[] (multi-file) or both file_name and content (single-file)", "for one file pass file_name and content; for several pass files: [{ file_path, content }]."));
7927
7863
  }
7928
7864
  /**
7929
7865
  * Create a snippet — project-scoped if projectId is given, otherwise personal.
@@ -8936,7 +8872,7 @@ async function handleToolCall(params) {
8936
8872
  if (patch_type === "search_replace") {
8937
8873
  const blocks = parseSearchReplaceBlocks(patch);
8938
8874
  if (blocks.length === 0) {
8939
- throw new Error("No valid search/replace blocks found. Expected format: <<<<<<< SEARCH\\ntext\\n=======\\nnew text\\n>>>>>>> REPLACE");
8875
+ throw new ToolInputError(withRecoveryHint("No valid search/replace blocks found. Expected format: <<<<<<< SEARCH\\ntext\\n=======\\nnew text\\n>>>>>>> REPLACE", 'put each <<<<<<< SEARCH, =======, and >>>>>>> REPLACE marker on its own line, or set patch_type to "unified_diff".'));
8940
8876
  }
8941
8877
  result = applySearchReplace(currentDescription, blocks, allow_multiple);
8942
8878
  }
@@ -10541,122 +10477,16 @@ async function handleToolCall(params) {
10541
10477
  content: [{ type: "text", text: assetContent }],
10542
10478
  };
10543
10479
  }
10544
- case "list_tags": {
10545
- const args = ListTagsSchema.parse(params.arguments);
10546
- const { project_id, ...options } = args;
10547
- const tags = await listTags(project_id, options);
10548
- return {
10549
- content: [{ type: "text", text: JSON.stringify(tags) }],
10550
- };
10551
- }
10552
- case "get_tag": {
10553
- const args = GetTagSchema.parse(params.arguments);
10554
- const tag = await getTag(args.project_id, args.tag_name);
10555
- return {
10556
- content: [{ type: "text", text: JSON.stringify(tag) }],
10557
- };
10558
- }
10559
- case "create_tag": {
10560
- const args = CreateTagSchema.parse(params.arguments);
10561
- const { project_id, ...options } = args;
10562
- const tag = await createTag(project_id, options);
10563
- return {
10564
- content: [{ type: "text", text: JSON.stringify(tag) }],
10565
- };
10566
- }
10567
- case "delete_tag": {
10568
- const args = DeleteTagSchema.parse(params.arguments);
10569
- await deleteTag(args.project_id, args.tag_name);
10570
- return {
10571
- content: [
10572
- {
10573
- type: "text",
10574
- text: JSON.stringify({
10575
- status: "success",
10576
- message: `Tag '${args.tag_name}' deleted successfully`,
10577
- }),
10578
- },
10579
- ],
10580
- };
10581
- }
10582
- case "get_tag_signature": {
10583
- const args = GetTagSignatureSchema.parse(params.arguments);
10584
- const signature = await getTagSignature(args.project_id, args.tag_name);
10585
- return {
10586
- content: [{ type: "text", text: JSON.stringify(signature) }],
10587
- };
10588
- }
10589
- case "list_protected_tags": {
10590
- const args = ListProtectedTagsSchema.parse(params.arguments);
10591
- const projectId = decodeURIComponent(args.project_id);
10592
- const effectiveProjectId = getEffectiveProjectId(projectId);
10593
- const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags`);
10594
- if (args.page)
10595
- url.searchParams.append("page", String(args.page));
10596
- if (args.per_page)
10597
- url.searchParams.append("per_page", String(args.per_page));
10598
- const response = await fetch(url.toString(), {
10599
- ...getFetchConfig(),
10600
- });
10601
- await handleGitLabError(response);
10602
- const data = z.array(GitLabProtectedTagSchema).parse(await response.json());
10603
- return {
10604
- content: [{ type: "text", text: JSON.stringify(data) }],
10605
- };
10606
- }
10607
- case "get_protected_tag": {
10608
- const args = GetProtectedTagSchema.parse(params.arguments);
10609
- const projectId = decodeURIComponent(args.project_id);
10610
- const effectiveProjectId = getEffectiveProjectId(projectId);
10611
- const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags/${encodeGitLabPathSegment(args.tag_name)}`);
10612
- const response = await fetch(url.toString(), {
10613
- ...getFetchConfig(),
10614
- });
10615
- await handleGitLabError(response);
10616
- const data = GitLabProtectedTagSchema.parse(await response.json());
10617
- return {
10618
- content: [{ type: "text", text: JSON.stringify(data) }],
10619
- };
10620
- }
10621
- case "protect_tag": {
10622
- const args = ProtectTagSchema.parse(params.arguments);
10623
- const projectId = decodeURIComponent(args.project_id);
10624
- const effectiveProjectId = getEffectiveProjectId(projectId);
10625
- const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags`);
10626
- const body = { name: args.tag_name };
10627
- if (args.create_access_level !== undefined) {
10628
- body.create_access_level = args.create_access_level;
10629
- }
10630
- const response = await fetch(url.toString(), {
10631
- ...getFetchConfig(),
10632
- method: "POST",
10633
- body: JSON.stringify(body),
10634
- });
10635
- await handleGitLabError(response);
10636
- const data = GitLabProtectedTagSchema.parse(await response.json());
10637
- return {
10638
- content: [{ type: "text", text: JSON.stringify(data) }],
10639
- };
10640
- }
10641
- case "unprotect_tag": {
10642
- const args = UnprotectTagSchema.parse(params.arguments);
10643
- const projectId = decodeURIComponent(args.project_id);
10644
- const effectiveProjectId = getEffectiveProjectId(projectId);
10645
- const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags/${encodeGitLabPathSegment(args.tag_name)}`);
10646
- const response = await fetch(url.toString(), {
10647
- ...getFetchConfig(),
10648
- method: "DELETE",
10649
- });
10650
- await handleGitLabError(response);
10651
- return {
10652
- content: [
10653
- {
10654
- type: "text",
10655
- text: JSON.stringify({ status: "unprotected", tag: args.tag_name }),
10656
- },
10657
- ],
10658
- };
10659
- }
10480
+ case "list_tags":
10481
+ case "get_tag":
10482
+ case "create_tag":
10483
+ case "delete_tag":
10484
+ case "get_tag_signature":
10485
+ case "list_protected_tags":
10486
+ case "get_protected_tag":
10487
+ case "protect_tag":
10488
+ case "unprotect_tag":
10489
+ return await handleTagToolCall(params);
10660
10490
  case "list_snippets": {
10661
10491
  const args = ListSnippetsSchema.parse(params.arguments);
10662
10492
  const { project_id, ...options } = args;
@@ -0,0 +1,226 @@
1
+ import { z } from "zod";
2
+ import { CreateTagSchema, DeleteTagSchema, GetProtectedTagSchema, GetTagSchema, GetTagSignatureSchema, GitLabProtectedTagSchema, GitLabTagSchema, GitLabTagSignatureSchema, ListProtectedTagsSchema, ListTagsSchema, ProtectTagSchema, UnprotectTagSchema, } from "../schemas.js";
3
+ import { getEffectiveApiUrl, getFetchConfig } from "../server/gitlab-request-context.js";
4
+ import { appendFilterParams } from "../utils/tool-args.js";
5
+ import { encodeGitLabPathSegment } from "../utils/url.js";
6
+ let deps;
7
+ export function configureTagTools(next) {
8
+ deps = next;
9
+ }
10
+ function requireDeps() {
11
+ if (!deps) {
12
+ throw new Error("Tag tools used before configureTagTools()");
13
+ }
14
+ return deps;
15
+ }
16
+ const fetch = (input, init) => requireDeps().getFetch()(input, init);
17
+ function handleGitLabError(response) {
18
+ return requireDeps().handleGitLabError(response);
19
+ }
20
+ function getEffectiveProjectId(projectId) {
21
+ return requireDeps().getEffectiveProjectId(projectId);
22
+ }
23
+ /**
24
+ * List repository tags
25
+ *
26
+ * @param projectId The ID or URL-encoded path of the project
27
+ * @param options Optional parameters for filtering and pagination
28
+ * @returns Array of GitLab tags
29
+ */
30
+ async function listTags(projectId, options = {}) {
31
+ const effectiveProjectId = getEffectiveProjectId(projectId);
32
+ const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags`);
33
+ appendFilterParams(url.searchParams, options);
34
+ const response = await fetch(url.toString(), {
35
+ ...getFetchConfig(),
36
+ });
37
+ await handleGitLabError(response);
38
+ const data = await response.json();
39
+ return GitLabTagSchema.array().parse(data);
40
+ }
41
+ /**
42
+ * Get a repository tag by name
43
+ *
44
+ * @param projectId The ID or URL-encoded path of the project
45
+ * @param tagName The name of the tag
46
+ * @returns GitLab tag
47
+ */
48
+ async function getTag(projectId, tagName) {
49
+ const effectiveProjectId = getEffectiveProjectId(projectId);
50
+ const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}`, {
51
+ ...getFetchConfig(),
52
+ });
53
+ await handleGitLabError(response);
54
+ const data = await response.json();
55
+ return GitLabTagSchema.parse(data);
56
+ }
57
+ /**
58
+ * Create a new repository tag
59
+ *
60
+ * @param projectId The ID or URL-encoded path of the project
61
+ * @param options Options for creating the tag
62
+ * @returns Created GitLab tag
63
+ */
64
+ async function createTag(projectId, options) {
65
+ const effectiveProjectId = getEffectiveProjectId(projectId);
66
+ const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags`, {
67
+ ...getFetchConfig(),
68
+ method: "POST",
69
+ body: JSON.stringify(options),
70
+ });
71
+ await handleGitLabError(response);
72
+ const data = await response.json();
73
+ return GitLabTagSchema.parse(data);
74
+ }
75
+ /**
76
+ * Delete a repository tag
77
+ *
78
+ * @param projectId The ID or URL-encoded path of the project
79
+ * @param tagName The name of the tag
80
+ */
81
+ async function deleteTag(projectId, tagName) {
82
+ const effectiveProjectId = getEffectiveProjectId(projectId);
83
+ const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}`, {
84
+ ...getFetchConfig(),
85
+ method: "DELETE",
86
+ });
87
+ await handleGitLabError(response);
88
+ }
89
+ /**
90
+ * Get the signature of a repository tag
91
+ *
92
+ * @param projectId The ID or URL-encoded path of the project
93
+ * @param tagName The name of the tag
94
+ * @returns Tag signature
95
+ */
96
+ async function getTagSignature(projectId, tagName) {
97
+ const effectiveProjectId = getEffectiveProjectId(projectId);
98
+ const response = await fetch(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/repository/tags/${encodeGitLabPathSegment(tagName)}/signature`, {
99
+ ...getFetchConfig(),
100
+ });
101
+ await handleGitLabError(response);
102
+ const data = await response.json();
103
+ return GitLabTagSignatureSchema.parse(data);
104
+ }
105
+ export async function handleTagToolCall(params) {
106
+ switch (params.name) {
107
+ case "list_tags": {
108
+ const args = ListTagsSchema.parse(params.arguments);
109
+ const { project_id, ...options } = args;
110
+ const tags = await listTags(project_id, options);
111
+ return {
112
+ content: [{ type: "text", text: JSON.stringify(tags) }],
113
+ };
114
+ }
115
+ case "get_tag": {
116
+ const args = GetTagSchema.parse(params.arguments);
117
+ const tag = await getTag(args.project_id, args.tag_name);
118
+ return {
119
+ content: [{ type: "text", text: JSON.stringify(tag) }],
120
+ };
121
+ }
122
+ case "create_tag": {
123
+ const args = CreateTagSchema.parse(params.arguments);
124
+ const { project_id, ...options } = args;
125
+ const tag = await createTag(project_id, options);
126
+ return {
127
+ content: [{ type: "text", text: JSON.stringify(tag) }],
128
+ };
129
+ }
130
+ case "delete_tag": {
131
+ const args = DeleteTagSchema.parse(params.arguments);
132
+ await deleteTag(args.project_id, args.tag_name);
133
+ return {
134
+ content: [
135
+ {
136
+ type: "text",
137
+ text: JSON.stringify({
138
+ status: "success",
139
+ message: `Tag '${args.tag_name}' deleted successfully`,
140
+ }),
141
+ },
142
+ ],
143
+ };
144
+ }
145
+ case "get_tag_signature": {
146
+ const args = GetTagSignatureSchema.parse(params.arguments);
147
+ const signature = await getTagSignature(args.project_id, args.tag_name);
148
+ return {
149
+ content: [{ type: "text", text: JSON.stringify(signature) }],
150
+ };
151
+ }
152
+ case "list_protected_tags": {
153
+ const args = ListProtectedTagsSchema.parse(params.arguments);
154
+ const projectId = decodeURIComponent(args.project_id);
155
+ const effectiveProjectId = getEffectiveProjectId(projectId);
156
+ const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags`);
157
+ if (args.page)
158
+ url.searchParams.append("page", String(args.page));
159
+ if (args.per_page)
160
+ url.searchParams.append("per_page", String(args.per_page));
161
+ const response = await fetch(url.toString(), {
162
+ ...getFetchConfig(),
163
+ });
164
+ await handleGitLabError(response);
165
+ const data = z.array(GitLabProtectedTagSchema).parse(await response.json());
166
+ return {
167
+ content: [{ type: "text", text: JSON.stringify(data) }],
168
+ };
169
+ }
170
+ case "get_protected_tag": {
171
+ const args = GetProtectedTagSchema.parse(params.arguments);
172
+ const projectId = decodeURIComponent(args.project_id);
173
+ const effectiveProjectId = getEffectiveProjectId(projectId);
174
+ const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags/${encodeGitLabPathSegment(args.tag_name)}`);
175
+ const response = await fetch(url.toString(), {
176
+ ...getFetchConfig(),
177
+ });
178
+ await handleGitLabError(response);
179
+ const data = GitLabProtectedTagSchema.parse(await response.json());
180
+ return {
181
+ content: [{ type: "text", text: JSON.stringify(data) }],
182
+ };
183
+ }
184
+ case "protect_tag": {
185
+ const args = ProtectTagSchema.parse(params.arguments);
186
+ const projectId = decodeURIComponent(args.project_id);
187
+ const effectiveProjectId = getEffectiveProjectId(projectId);
188
+ const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags`);
189
+ const body = { name: args.tag_name };
190
+ if (args.create_access_level !== undefined) {
191
+ body.create_access_level = args.create_access_level;
192
+ }
193
+ const response = await fetch(url.toString(), {
194
+ ...getFetchConfig(),
195
+ method: "POST",
196
+ body: JSON.stringify(body),
197
+ });
198
+ await handleGitLabError(response);
199
+ const data = GitLabProtectedTagSchema.parse(await response.json());
200
+ return {
201
+ content: [{ type: "text", text: JSON.stringify(data) }],
202
+ };
203
+ }
204
+ case "unprotect_tag": {
205
+ const args = UnprotectTagSchema.parse(params.arguments);
206
+ const projectId = decodeURIComponent(args.project_id);
207
+ const effectiveProjectId = getEffectiveProjectId(projectId);
208
+ const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(effectiveProjectId)}/protected_tags/${encodeGitLabPathSegment(args.tag_name)}`);
209
+ const response = await fetch(url.toString(), {
210
+ ...getFetchConfig(),
211
+ method: "DELETE",
212
+ });
213
+ await handleGitLabError(response);
214
+ return {
215
+ content: [
216
+ {
217
+ type: "text",
218
+ text: JSON.stringify({ status: "unprotected", tag: args.tag_name }),
219
+ },
220
+ ],
221
+ };
222
+ }
223
+ default:
224
+ throw new Error(`Unknown tool: ${params.name}`);
225
+ }
226
+ }
@@ -30,6 +30,17 @@ export function recoveryHintFor(message) {
30
30
  }
31
31
  return undefined;
32
32
  }
33
+ /**
34
+ * Adds a site-specific hint to a message on the same "\nNext: " line that
35
+ * appendRecoveryHint adds at the tool-call boundary. The message stays a prefix
36
+ * of the result, and a message that already has a hint comes back unchanged.
37
+ */
38
+ export function withRecoveryHint(message, hint) {
39
+ if (hasRecoveryHint(message)) {
40
+ return message;
41
+ }
42
+ return `${message}${NEXT_PREFIX}${hint}`;
43
+ }
33
44
  export function appendRecoveryHint(message) {
34
45
  if (hasRecoveryHint(message)) {
35
46
  return message;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@zereight/mcp-gitlab",
3
- "version": "2.3.25-next.221",
3
+ "version": "2.3.25-next.223",
4
4
  "mcpName": "io.github.zereight/gitlab-mcp",
5
5
  "description": "GitLab MCP server for projects, merge requests, issues, pipelines, wiki, releases, and more",
6
6
  "keywords": [