@zereight/mcp-gitlab 2.3.25-next.222 → 2.3.25-next.224

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/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";
@@ -1370,6 +1370,12 @@ class ProjectAccessDeniedError extends Error {
1370
1370
  }
1371
1371
  }
1372
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.";
1373
1379
  /**
1374
1380
  * Utility function for handling GitLab API errors
1375
1381
  * API 에러 처리를 위한 유틸리티 함수 (Utility function for handling API errors)
@@ -1448,7 +1454,7 @@ function getEffectiveProjectId(projectId) {
1448
1454
  }
1449
1455
  // If no project ID provided but we have multiple allowed projects, require an explicit choice
1450
1456
  if (!projectId && allowedProjectIds.length > 1) {
1451
- 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."));
1452
1458
  }
1453
1459
  return projectId || allowedProjectIds[0];
1454
1460
  }
@@ -1459,7 +1465,7 @@ function getEffectiveProjectId(projectId) {
1459
1465
  if (GITLAB_PROJECT_ID) {
1460
1466
  return GITLAB_PROJECT_ID;
1461
1467
  }
1462
- 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."));
1463
1469
  }
1464
1470
  function rejectIfProjectScopedDeployment(toolName) {
1465
1471
  if (GITLAB_PROJECT_ID) {
@@ -1920,7 +1926,7 @@ async function resolveWorkItemGID(projectId, issueIid) {
1920
1926
  }
1921
1927
  }`, { path: projectPath, iid: String(issueIid) });
1922
1928
  if (!data.namespace?.workItem?.id) {
1923
- 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));
1924
1930
  }
1925
1931
  return { workItemGID: data.namespace.workItem.id, projectPath, namespaceKind };
1926
1932
  }
@@ -1947,18 +1953,22 @@ async function resolveNamesToIds(projectPath, namespaceKind, labelNames, usernam
1947
1953
  }`, { path: projectPath, usernames, ...labelVars });
1948
1954
  const labelNamespace = namespaceKind === "group" ? data.group : data.project;
1949
1955
  if (!labelNamespace) {
1950
- 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."));
1951
1957
  }
1952
1958
  const labelIds = labelNames.map((name, i) => {
1953
1959
  const nodes = labelNamespace[`l${i}`]?.nodes;
1954
- if (!nodes?.length)
1955
- 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
+ }
1956
1965
  return nodes[0].id;
1957
1966
  });
1958
1967
  const userIds = usernames.map(name => {
1959
1968
  const user = data.users.nodes.find(u => u.username === name);
1960
- if (!user)
1961
- 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
+ }
1962
1972
  return user.id;
1963
1973
  });
1964
1974
  return { labelIds, userIds };
@@ -1984,7 +1994,7 @@ const WORK_ITEM_TYPE_NAMES = {
1984
1994
  async function resolveWorkItemTypeGID(projectPath, typeName) {
1985
1995
  const targetName = WORK_ITEM_TYPE_NAMES[typeName];
1986
1996
  if (!targetName) {
1987
- 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(", ")}.`));
1988
1998
  }
1989
1999
  const data = await executeGraphQL(`query($path: ID!) {
1990
2000
  namespace(fullPath: $path) {
@@ -1998,7 +2008,7 @@ async function resolveWorkItemTypeGID(projectPath, typeName) {
1998
2008
  }`, { path: projectPath });
1999
2009
  const typeNode = data.namespace?.workItemTypes?.nodes?.find(n => n.name === targetName);
2000
2010
  if (!typeNode) {
2001
- 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));
2002
2012
  }
2003
2013
  return typeNode.id;
2004
2014
  }
@@ -2078,7 +2088,7 @@ async function listIssueStatuses(projectId, workItemType = "issue") {
2078
2088
  }`, { path: projectPath, typeName: typeName.replace(/ /g, "_").toUpperCase() });
2079
2089
  const typeNodes = data.namespace?.workItemTypes?.nodes;
2080
2090
  if (!typeNodes || typeNodes.length === 0) {
2081
- 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));
2082
2092
  }
2083
2093
  const typeNode = typeNodes[0];
2084
2094
  // Extract statuses from the status widget definition
@@ -2139,7 +2149,7 @@ async function listCustomFieldDefinitions(projectId, workItemType = "issue") {
2139
2149
  }`, { path: projectPath, typeName: typeName.replace(/ /g, "_").toUpperCase() });
2140
2150
  const typeNodes = data.namespace?.workItemTypes?.nodes;
2141
2151
  if (!typeNodes || typeNodes.length === 0) {
2142
- 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));
2143
2153
  }
2144
2154
  const typeNode = typeNodes[0];
2145
2155
  const customFieldsWidget = typeNode.widgetDefinitions?.find((w) => w.__typename === "WorkItemWidgetDefinitionCustomFields");
@@ -2224,7 +2234,7 @@ async function listWorkItemNotes(projectId, iid, options = {}) {
2224
2234
  });
2225
2235
  const workItem = data.namespace?.workItem;
2226
2236
  if (!workItem) {
2227
- 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));
2228
2238
  }
2229
2239
  const notesWidget = workItem.widgets?.find((w) => w.discussions);
2230
2240
  const discussions = notesWidget?.discussions;
@@ -2630,7 +2640,7 @@ async function getWorkItem(projectId, iid) {
2630
2640
  }
2631
2641
  }`, { path: projectPath, iid: String(iid) });
2632
2642
  if (!data.namespace?.workItem) {
2633
- 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));
2634
2644
  }
2635
2645
  const wi = data.namespace.workItem;
2636
2646
  const widgets = wi.widgets || [];
@@ -4586,10 +4596,10 @@ async function getMergeRequestConflicts(projectId, mergeRequestIid) {
4586
4596
  }`, variables);
4587
4597
  }
4588
4598
  if (!data.project) {
4589
- 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));
4590
4600
  }
4591
4601
  if (!data.project.mergeRequest) {
4592
- 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)."));
4593
4603
  }
4594
4604
  const { conflicts, conflictStatus, conflictFiles } = data.project.mergeRequest;
4595
4605
  const result = { has_conflicts: conflicts };
@@ -6427,7 +6437,7 @@ async function listCommitStatuses(projectId, sha, options = {}) {
6427
6437
  */
6428
6438
  async function createCommitStatus(projectId, sha, options) {
6429
6439
  if (options.name && options.context) {
6430
- 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."));
6431
6441
  }
6432
6442
  projectId = decodeURIComponent(projectId);
6433
6443
  const url = new URL(`${getEffectiveApiUrl()}/projects/${encodeGitLabPathSegment(getEffectiveProjectId(projectId))}/statuses/${encodeGitLabPathSegment(sha)}`);
@@ -6833,7 +6843,7 @@ async function listGroupIterationCadences(groupId, options = {}) {
6833
6843
  after,
6834
6844
  });
6835
6845
  if (!data.group) {
6836
- throw new Error(`Group ${groupPath} was not found`);
6846
+ throw new ToolInputError(withRecoveryHint(`Group ${groupPath} was not found`, GROUP_NOT_FOUND_HINT));
6837
6847
  }
6838
6848
  const { nodes, pageInfo } = data.group.iterationCadences;
6839
6849
  cadences.push(...nodes.map(toGroupIterationCadence));
@@ -7075,8 +7085,9 @@ async function getDependencyProxySettings(groupPath) {
7075
7085
  }
7076
7086
  }`, { fullPath });
7077
7087
  const g = data.group;
7078
- if (!g)
7079
- throw new Error(`Group not found: ${fullPath}`);
7088
+ if (!g) {
7089
+ throw new ToolInputError(withRecoveryHint(`Group not found: ${fullPath}`, GROUP_NOT_FOUND_HINT));
7090
+ }
7080
7091
  return GitLabDependencyProxySchema.parse({
7081
7092
  enabled: g.dependencyProxySetting?.enabled ?? false,
7082
7093
  blob_count: g.dependencyProxyBlobCount,
@@ -7089,7 +7100,7 @@ async function updateDependencyProxySettings(groupPath, options) {
7089
7100
  if (options.enabled === undefined &&
7090
7101
  options.identity === undefined &&
7091
7102
  options.secret === undefined) {
7092
- 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."));
7093
7104
  }
7094
7105
  const fullPath = await resolveGroupFullPath(groupPath);
7095
7106
  const input = { groupPath: fullPath };
@@ -7119,8 +7130,9 @@ async function listDependencyProxyBlobs(groupPath, options = {}) {
7119
7130
  }
7120
7131
  }`, { fullPath, first: options.first ?? 20, after: options.after });
7121
7132
  const conn = data.group?.dependencyProxyBlobs;
7122
- if (!conn)
7123
- 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
+ }
7124
7136
  return {
7125
7137
  blobs: conn.nodes.map(n => GitLabDependencyProxyBlobSchema.parse({
7126
7138
  file_name: n.fileName,
@@ -7149,7 +7161,7 @@ function toVulnerabilityGid(vulnerabilityId) {
7149
7161
  if (/^gid:\/\/gitlab\/Vulnerability\/\d+$/.test(vulnerabilityId)) {
7150
7162
  return vulnerabilityId;
7151
7163
  }
7152
- 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."));
7153
7165
  }
7154
7166
  /**
7155
7167
  * Resolve a project ID or path to the full namespace path required by
@@ -7209,7 +7221,7 @@ async function ensureVulnerabilityProjectAllowed(vulnerabilityId) {
7209
7221
  }
7210
7222
  }`, { id: toVulnerabilityGid(vulnerabilityId) });
7211
7223
  if (!data.vulnerability) {
7212
- throw new Error(`Vulnerability not found: ${vulnerabilityId}`);
7224
+ throw new ToolInputError(withRecoveryHint(`Vulnerability not found: ${vulnerabilityId}`, VULNERABILITY_NOT_FOUND_HINT));
7213
7225
  }
7214
7226
  assertVulnerabilityProjectAllowed(vulnerabilityId, data.vulnerability.project);
7215
7227
  }
@@ -7319,7 +7331,7 @@ async function listProjectVulnerabilities(projectId, options = {}) {
7319
7331
  }
7320
7332
  }`, variables);
7321
7333
  if (!data.project) {
7322
- 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));
7323
7335
  }
7324
7336
  return {
7325
7337
  vulnerabilities: data.project.vulnerabilities.nodes,
@@ -7379,7 +7391,7 @@ async function getVulnerability(vulnerabilityId) {
7379
7391
  }
7380
7392
  }`, { id: toVulnerabilityGid(vulnerabilityId) });
7381
7393
  if (!data.vulnerability) {
7382
- throw new Error(`Vulnerability not found: ${vulnerabilityId}`);
7394
+ throw new ToolInputError(withRecoveryHint(`Vulnerability not found: ${vulnerabilityId}`, VULNERABILITY_NOT_FOUND_HINT));
7383
7395
  }
7384
7396
  assertVulnerabilityProjectAllowed(vulnerabilityId, data.vulnerability.project);
7385
7397
  return data.vulnerability;
@@ -7467,7 +7479,7 @@ async function markdownUpload(projectId, filePath, content, filename) {
7467
7479
  fileName = safeBasename;
7468
7480
  }
7469
7481
  else {
7470
- 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."));
7471
7483
  }
7472
7484
  // Create form data
7473
7485
  const form = new FormData();
@@ -7506,7 +7518,7 @@ function getSafeAttachmentFilename(filename) {
7506
7518
  filename === ".." ||
7507
7519
  filename.includes("/") ||
7508
7520
  filename.includes("\\")) {
7509
- 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 \\."));
7510
7522
  }
7511
7523
  return filename;
7512
7524
  }
@@ -7847,7 +7859,7 @@ function snippetCreateFilesPayload(options) {
7847
7859
  if (options.file_name !== undefined && options.content !== undefined) {
7848
7860
  return [{ file_path: options.file_name, content: options.content }];
7849
7861
  }
7850
- 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 }]."));
7851
7863
  }
7852
7864
  /**
7853
7865
  * Create a snippet — project-scoped if projectId is given, otherwise personal.
@@ -8860,7 +8872,7 @@ async function handleToolCall(params) {
8860
8872
  if (patch_type === "search_replace") {
8861
8873
  const blocks = parseSearchReplaceBlocks(patch);
8862
8874
  if (blocks.length === 0) {
8863
- 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".'));
8864
8876
  }
8865
8877
  result = applySearchReplace(currentDescription, blocks, allow_multiple);
8866
8878
  }
@@ -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.222",
3
+ "version": "2.3.25-next.224",
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": [
@@ -53,6 +53,8 @@
53
53
  "test": "npm run test:all",
54
54
  "test:all": "npm run build && npm run test:mock && npm run test:live",
55
55
  "test:mock": "bash scripts/run-mock-tests.sh",
56
+ "test:coverage": "bash scripts/run-coverage.sh",
57
+ "coverage:summary": "tsx scripts/code-coverage-summary.ts",
56
58
  "test:stateless": "npm run build && node --import tsx/esm --test --experimental-test-isolation=none test/stateless/codec.test.ts test/stateless/client-id.test.ts test/stateless/callback-proxy.test.ts test/stateless/session-id.test.ts test/stateless/session-id-integration.test.ts test/stateless/config-ttl.test.ts test/stateless/consumed-proxy-code-cache.test.ts",
57
59
  "test:mcp-oauth": "npm run build && node --import tsx/esm --test test/mcp-oauth-tests.ts",
58
60
  "test:live": "node test/validate-api.js",
@@ -100,6 +102,7 @@
100
102
  "@typescript-eslint/eslint-plugin": "^8.21.0",
101
103
  "@typescript-eslint/parser": "^8.21.0",
102
104
  "auto-changelog": "^2.4.0",
105
+ "c8": "^12.0.0",
103
106
  "dotenv": "^17.2.2",
104
107
  "eslint": "^9.18.0",
105
108
  "fast-check": "^4.10.2",
@@ -111,6 +114,10 @@
111
114
  "overrides": {
112
115
  "@typescript-eslint/typescript-estree": {
113
116
  "minimatch": "^11.0.1"
117
+ },
118
+ "test-exclude": {
119
+ "glob": "^14.0.4",
120
+ "minimatch": "^11.0.5"
114
121
  }
115
122
  }
116
123
  }