opencode-gitlab-plugin 2.8.1 → 3.0.0

package/dist/mcp-server.cjs

@@ -28893,19 +28893,45 @@ var GitLabApiClient = class {
   }
 };
 
-// src/client/notes-types.ts
-function buildPaginationVariables(options) {
+// src/client/connection-pagination.ts
+var DEFAULT_PAGE_SIZE = 20;
+var MAX_PAGE_SIZE = 100;
+function normalizePageSize(value) {
+  if (value === void 0 || value === 0) return void 0;
+  if (!Number.isFinite(value)) return DEFAULT_PAGE_SIZE;
+  return Math.min(Math.max(Math.floor(value), 1), MAX_PAGE_SIZE);
+}
+function buildConnectionVariables(options) {
   const variables = {};
-  if (options?.first !== void 0) {
-    variables.first = options.first;
-  } else if (options?.last == null) {
-    variables.first = 20;
+  const first = normalizePageSize(options?.first);
+  const last = normalizePageSize(options?.last);
+  if (first !== void 0 && last !== void 0) {
+    throw new Error("Pagination accepts either 'first' or 'last', not both");
+  }
+  if (options?.after && last !== void 0) {
+    throw new Error("Pagination cursor 'after' cannot be combined with 'last'");
+  }
+  if (options?.before && first !== void 0) {
+    throw new Error("Pagination cursor 'before' cannot be combined with 'first'");
+  }
+  if (first !== void 0) {
+    variables.first = first;
+  } else if (last !== void 0) {
+    variables.last = last;
+  } else if (options?.before) {
+    variables.last = DEFAULT_PAGE_SIZE;
+  } else {
+    variables.first = DEFAULT_PAGE_SIZE;
   }
   if (options?.after) variables.after = options.after;
-  if (options?.last !== void 0) variables.last = options.last;
   if (options?.before) variables.before = options.before;
   return variables;
 }
+
+// src/client/notes-types.ts
+function buildPaginationVariables(options) {
+  return buildConnectionVariables(options);
+}
 var NOTES_FRAGMENT = `
   fragment NoteFields on Note {
     id
@@ -28944,16 +28970,7 @@ var NOTES_CONNECTION_FRAGMENT = `
 
 // src/client/discussions-types.ts
 function buildDiscussionsPaginationVariables(options) {
-  const variables = {};
-  if (options?.first !== void 0) {
-    variables.first = options.first;
-  } else if (options?.last == null) {
-    variables.first = 20;
-  }
-  if (options?.after) variables.after = options.after;
-  if (options?.last !== void 0) variables.last = options.last;
-  if (options?.before) variables.before = options.before;
-  return variables;
+  return buildConnectionVariables(options);
 }
 var DISCUSSION_NOTE_FRAGMENT = `
   fragment DiscussionNoteFields on Note {
@@ -30213,10 +30230,7 @@ var RepositoryClient = class extends GitLabApiClient {
   async getFile(projectId, filePath, ref) {
     const encodedProject = this.encodeProjectId(projectId);
     const encodedPath = encodeURIComponent(filePath);
-    let url2 = `/projects/${encodedProject}/repository/files/${encodedPath}`;
-    if (ref) {
-      url2 += `?ref=${encodeURIComponent(ref)}`;
-    }
+    const url2 = `/projects/${encodedProject}/repository/files/${encodedPath}?ref=${encodeURIComponent(ref)}`;
     const file2 = await this.fetch("GET", url2);
     if (file2.encoding === "base64") {
       return Buffer.from(file2.content, "base64").toString("utf-8");
@@ -32312,13 +32326,13 @@ var repositoryTools = {
   gitlab_get_file: tool({
     description: `Get the contents of a file from a repository.
 Supports fetching files from any branch, tag, or commit SHA.
-If ref is not specified, uses the project's default branch.
+An explicit ref is required by the GitLab repository files API.
 Note: Invalid refs will result in a 404 error from the GitLab API.`,
     args: {
       project_id: z5.string().describe("The project ID or URL-encoded path"),
       file_path: z5.string().describe("Path to the file in the repository"),
-      ref: z5.string().optional().describe(
-        `Branch name, tag, or commit SHA to fetch the file from. Supports full or short commit SHAs. If omitted, uses the project's default branch (e.g., "main" or "master").`
+      ref: z5.string().trim().min(1).describe(
+        "Branch name, tag, or commit SHA to fetch the file from. Supports full or short commit SHAs."
       )
     },
     execute: async (args, _ctx) => {
@@ -32495,6 +32509,8 @@ Scopes and their requirements:
 - wiki_blobs: Search wiki content (supports ref filter)
 - group_projects: Search projects within a group (requires group_id)
 
+For scopes other than milestones, state="all" is treated as omitted because it does not filter results.
+
 Examples:
 - Issues: scope="issues", search="bug", project_id="my-group/my-project"
 - Code: scope="blobs", search="function calculateTotal"
@@ -32529,6 +32545,9 @@ Examples:
       state: z6.enum(["active", "closed", "all"]).optional().describe("Filter by state (for milestones scope)")
     },
     execute: async (args, _ctx) => {
+      if (args.scope !== "milestones" && args.state === "all") {
+        args.state = void 0;
+      }
       validateSearchParams(args.scope, {
         project_id: args.project_id,
         group_id: args.group_id,
@@ -33230,10 +33249,10 @@ Examples:
         "Filter by resolved status: true for resolved, false for unresolved. Only returns resolvable discussions (excludes system notes). Client-side filtering."
       ),
       // Pagination
-      first: z13.number().optional().describe("Number of items to return (default: 20)"),
+      first: z13.number().int().min(0).max(100).optional().describe("Number of items to return (default: 20, max: 100; 0 uses the default)"),
       after: z13.string().optional().describe("Cursor for pagination - use endCursor from previous response"),
       before: z13.string().optional().describe("Cursor for backward pagination"),
-      last: z13.number().optional().describe("Number of items from the end")
+      last: z13.number().int().min(0).max(100).optional().describe("Number of items from the end (max: 100; 0 is omitted)")
     },
     execute: async (args, _ctx) => {
       validateResourceParams(args.resource_type, args);
@@ -33545,9 +33564,11 @@ Examples:
         "Filter by resolved status: true for resolved, false for unresolved. Only returns resolvable notes (excludes system notes). Client-side filtering."
       ),
       // Pagination
-      first: z14.number().optional().describe("Number of items to return from the beginning (default: 20, max: 100)"),
+      first: z14.number().int().min(0).max(100).optional().describe(
+        "Number of items to return from the beginning (default: 20, max: 100; 0 uses the default)"
+      ),
       after: z14.string().optional().describe("Cursor for forward pagination - use endCursor from previous response"),
-      last: z14.number().optional().describe("Number of items to return from the end (for backward pagination)"),
+      last: z14.number().int().min(0).max(100).optional().describe("Number of items to return from the end (max: 100; 0 is omitted)"),
       before: z14.string().optional().describe("Cursor for backward pagination - use startCursor from previous response")
     },
     execute: async (args, _ctx) => {
@@ -34178,6 +34199,372 @@ Examples:
   })
 };
 
+// src/tools/orbit.ts
+var z18 = tool.schema;
+var orbitTools = {
+  gitlab_orbit_status: tool({
+    description: `Check GitLab Orbit Knowledge Graph API availability and health.
+
+Returns the status of the Orbit API for the connected GitLab instance.
+Orbit is GitLab's Knowledge Graph API that provides rich SDLC graph data.
+
+Note: Orbit is only available on Premium/Ultimate tiers and requires the feature flag to be enabled.
+If unavailable, returns an error with suggestions for REST API alternatives.`,
+    args: {},
+    execute: async (_args, _ctx) => {
+      const client = getGitLabClient();
+      try {
+        const status = await client.fetch("GET", "/orbit/status");
+        return JSON.stringify(
+          {
+            ...status,
+            available: true,
+            message: "Orbit Knowledge Graph API is available"
+          },
+          null,
+          2
+        );
+      } catch (error45) {
+        const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API not available",
+              reason: "The Orbit Knowledge Graph API is not enabled on this GitLab instance. Orbit requires GitLab Premium/Ultimate tier and the feature flag to be enabled.",
+              alternatives: [
+                "Use REST API endpoints for MRs, issues, pipelines",
+                "Use GraphQL API for complex queries",
+                "Use gitlab_search for finding related entities"
+              ]
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("403") || errorMessage.includes("forbidden")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API access forbidden",
+              reason: "Your access token does not have permission to use the Orbit API. This may require specific scopes or Premium/Ultimate tier.",
+              alternatives: [
+                "Check token scopes include api or read_api",
+                "Verify your GitLab tier supports Orbit",
+                "Use REST/GraphQL APIs as fallback"
+              ]
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              available: false,
+              error: "Orbit API temporarily unavailable",
+              reason: "The Orbit API returned a 502 error. This may be temporary.",
+              suggestion: "Try again later or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(
+          {
+            available: false,
+            error: "Orbit API error",
+            message: errorMessage,
+            alternatives: ["Use REST/GraphQL APIs as fallback"]
+          },
+          null,
+          2
+        );
+      }
+    }
+  }),
+  gitlab_orbit_schema: tool({
+    description: `Get the Orbit Knowledge Graph schema.
+
+Returns the available node types, relationship types, and their properties.
+Use this to understand what entities and relationships can be queried.
+
+Node type domains include:
+- Core: Project, Group, User
+- Source Code: File, Definition, Commit
+- Code Review: MergeRequest, Diff, Review
+- CI/CD: Pipeline, Job, Deployment
+- Planning: WorkItem (issues, epics, tasks)
+- Security: Vulnerability
+
+Note: Requires Orbit API to be available (Premium/Ultimate tier).`,
+    args: {},
+    execute: async (_args, _ctx) => {
+      const client = getGitLabClient();
+      try {
+        const schema = await client.fetch("GET", "/orbit/schema");
+        return JSON.stringify(schema, null, 2);
+      } catch (error45) {
+        const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API temporarily unavailable",
+              suggestion: "The Orbit API returned a 502 error. This may be temporary - try again later."
+            },
+            null,
+            2
+          );
+        }
+        throw error45;
+      }
+    }
+  }),
+  gitlab_orbit_query: tool({
+    description: `Execute a query against the Orbit Knowledge Graph.
+
+Query types:
+- traversal: Walk the graph from a starting node
+- neighbors: Get immediate neighbors of a node
+
+IMPORTANT: The query format uses variable names for node references.
+- "id" in node definition is a VARIABLE NAME (alias), not the actual entity ID
+- Actual IDs go in "filters" with {"field": {"op": "eq", "value": X}} format
+
+Example neighbors query to get a project's connections:
+{
+  "query_type": "neighbors",
+  "node": {
+    "entity": "Project",
+    "id": "p",
+    "filters": {"id": {"op": "eq", "value": 278964}}
+  },
+  "neighbors": {"node": "p", "direction": "incoming"},
+  "aggregations": [],
+  "path": {"type": "shortest", "from": "p", "to": "p", "max_depth": 1}
+}
+
+Example traversal query:
+{
+  "query_type": "traversal",
+  "node": {
+    "entity": "MergeRequest",
+    "id": "mr",
+    "filters": {"id": {"op": "eq", "value": 377844873}}
+  },
+  "neighbors": {"node": "mr", "direction": "both"},
+  "aggregations": [],
+  "path": {"type": "shortest", "from": "mr", "to": "mr", "max_depth": 1}
+}
+
+Note: Use gitlab_get_merge_request to get the internal ID from an IID.
+Returns nodes array and edges array with relationship types.`,
+    args: {
+      // Using a JSON string rather than a structured zod schema because the Orbit query
+      // format is still evolving. This allows flexibility as the API changes without
+      // requiring schema updates for each iteration.
+      query: z18.string().describe(
+        "JSON string containing the full query object. Must include query_type, node, neighbors, aggregations, and path fields. See description for format details."
+      ),
+      limit: z18.number().optional().describe("Maximum number of results (default: 30)")
+    },
+    execute: async (args, _ctx) => {
+      const client = getGitLabClient();
+      let queryObj;
+      try {
+        queryObj = JSON.parse(args.query);
+      } catch {
+        return JSON.stringify(
+          {
+            error: "Invalid JSON in query parameter",
+            suggestion: "Ensure the query parameter is valid JSON"
+          },
+          null,
+          2
+        );
+      }
+      const requestBody = {
+        query: queryObj
+      };
+      if (args.limit) {
+        requestBody.limit = args.limit;
+      }
+      try {
+        const result = await client.fetch("POST", "/orbit/query", requestBody);
+        if (result.code) {
+          return JSON.stringify(
+            {
+              error: "Query compilation error",
+              code: result.code,
+              message: result.message,
+              suggestion: 'Check query structure. Node "id" is a variable name, actual IDs go in filters.'
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(result, null, 2);
+      } catch (error45) {
+        const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit query failed",
+              message: "The Orbit API returned a 502 error. This is a known issue with some entity types (e.g., source_code domain).",
+              suggestion: "Try a different entity type or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        throw error45;
+      }
+    }
+  }),
+  gitlab_orbit_neighbors: tool({
+    description: `Get immediate neighbors of a node in the Orbit Knowledge Graph.
+
+This is a simplified wrapper that builds the query for you.
+Returns nodes directly connected to the specified node.
+
+Common use cases:
+- Get all connections to a project (users, groups, pipelines, MRs)
+- Get pipelines for an MR
+- Get files changed in a commit
+- Get deployments from a pipeline
+
+Note: Use GitLab internal numeric IDs (not IIDs).
+Example: For MR !123 in gitlab-org/gitlab, first get the internal ID via gitlab_get_merge_request,
+then use that ID (e.g., 377844873).`,
+    args: {
+      entity_type: z18.string().describe(
+        "Type of the entity (e.g., Project, MergeRequest, User, Pipeline, Commit, WorkItem, Group)"
+      ),
+      entity_id: z18.number().describe(
+        "GitLab internal numeric ID (not IID). Get this from REST/GraphQL API responses."
+      ),
+      direction: z18.enum(["incoming", "outgoing", "both"]).optional().describe("Direction of relationships to traverse (default: both)"),
+      limit: z18.number().optional().describe("Maximum number of neighbors to return (default: 30)")
+    },
+    execute: async (args, _ctx) => {
+      const client = getGitLabClient();
+      const direction = args.direction || "both";
+      const queryObj = {
+        query_type: "neighbors",
+        node: {
+          entity: args.entity_type,
+          id: "n",
+          filters: {
+            id: { op: "eq", value: args.entity_id }
+          }
+        },
+        neighbors: {
+          node: "n",
+          direction
+        },
+        aggregations: [],
+        path: { type: "shortest", from: "n", to: "n", max_depth: 1 }
+      };
+      const requestBody = {
+        query: queryObj
+      };
+      if (args.limit) {
+        requestBody.limit = args.limit;
+      }
+      try {
+        const result = await client.fetch("POST", "/orbit/query", requestBody);
+        if (result.code) {
+          return JSON.stringify(
+            {
+              error: "Query error",
+              code: result.code,
+              message: result.message,
+              entity_type: args.entity_type,
+              entity_id: args.entity_id
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(result, null, 2);
+      } catch (error45) {
+        const errorMessage = error45 instanceof Error ? error45.message : String(error45);
+        if (errorMessage.includes("404") || errorMessage.includes("not found")) {
+          return JSON.stringify(
+            {
+              error: "Orbit API not available",
+              entity_type: args.entity_type,
+              entity_id: args.entity_id,
+              suggestion: "Use gitlab_orbit_status to check API availability"
+            },
+            null,
+            2
+          );
+        }
+        if (errorMessage.includes("502")) {
+          return JSON.stringify(
+            {
+              error: "Orbit query failed",
+              entity_type: args.entity_type,
+              entity_id: args.entity_id,
+              message: "The Orbit API returned a 502 error. This is a known issue with some entity types.",
+              suggestion: "Try a different entity type or use REST/GraphQL APIs as fallback."
+            },
+            null,
+            2
+          );
+        }
+        throw error45;
+      }
+    }
+  })
+};
+
+// src/tools/index.ts
+var mcpTools = {
+  ...mergeRequestTools,
+  ...issueTools,
+  ...epicTools,
+  ...pipelineTools,
+  ...repositoryTools,
+  ...searchTools,
+  ...projectTools,
+  ...userTools,
+  ...securityTools,
+  ...todoTools,
+  ...wikiTools,
+  ...workItemTools,
+  ...discussionsUnifiedTools,
+  ...notesUnifiedTools,
+  ...gitTools,
+  ...auditTools,
+  ...awardEmojiTools
+};
+var allTools = {
+  ...mcpTools,
+  ...orbitTools
+};
+
 // src/mcp-adapter.ts
 function adaptToolsToMcp(server, tools) {
   for (const [name, def] of Object.entries(tools)) {
@@ -34203,31 +34590,12 @@ async function main() {
 `);
     process.exit(1);
   }
-  const allTools = {
-    ...mergeRequestTools,
-    ...issueTools,
-    ...epicTools,
-    ...pipelineTools,
-    ...repositoryTools,
-    ...searchTools,
-    ...projectTools,
-    ...userTools,
-    ...securityTools,
-    ...todoTools,
-    ...wikiTools,
-    ...workItemTools,
-    ...discussionsUnifiedTools,
-    ...notesUnifiedTools,
-    ...gitTools,
-    ...auditTools,
-    ...awardEmojiTools
-  };
-  const version2 = true ? "2.8.1" : "0.0.0";
+  const version2 = true ? "3.0.0" : "0.0.0";
   const server = new McpServer({ name: "gitlab", version: version2 });
-  adaptToolsToMcp(server, allTools);
+  adaptToolsToMcp(server, mcpTools);
   const transport = new StdioServerTransport();
   await server.connect(transport);
-  const toolCount = Object.keys(allTools).length;
+  const toolCount = Object.keys(mcpTools).length;
   process.stderr.write(`gitlab MCP: serving ${toolCount} tools via stdio
 `);
   process.on("SIGINT", async () => {