opencode-gitlab-plugin 2.8.2 → 3.0.1

package/dist/mcp-server.cjs

@@ -34199,6 +34199,450 @@ Examples:
   })
 };
 
+// src/tools/orbit.ts
+var z18 = tool.schema;
+function orbitRelTypes(entityType) {
+  switch (entityType) {
+    case "MergeRequest":
+      return [
+        "AUTHORED",
+        "REVIEWER",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "IN_PROJECT",
+        "HAS_HEAD_PIPELINE",
+        "TRIGGERED",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "WorkItem":
+      return [
+        "AUTHORED",
+        "ASSIGNED",
+        "CLOSES",
+        "MENTIONS",
+        "RELATED_TO",
+        "CONTAINS",
+        "IN_PROJECT",
+        "IN_GROUP",
+        "IN_MILESTONE",
+        "HAS_LABEL"
+      ];
+    case "User":
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "MEMBER_OF", "OWNER", "CREATOR"];
+    case "Project":
+      return ["CONTAINS", "IN_PROJECT", "MEMBER_OF", "CREATOR"];
+    case "Pipeline":
+      return ["HAS_HEAD_PIPELINE", "TRIGGERED", "IN_PROJECT", "HAS_JOB", "HAS_STAGE"];
+    case "File":
+      return ["CONTAINS", "IMPORTS", "DEFINES", "CALLS", "ON_BRANCH"];
+    case "Group":
+      return ["CONTAINS", "MEMBER_OF", "OWNER", "IN_GROUP"];
+    case "Commit":
+      return ["MERGED_AT_COMMIT"];
+    default:
+      return ["AUTHORED", "ASSIGNED", "REVIEWER", "CLOSES", "MENTIONS", "RELATED_TO", "IN_PROJECT"];
+  }
+}
+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: Fetch matching nodes or follow relationships between nodes
+- neighbors: Return nodes connected to one bounded node
+- aggregation: Count/sum/avg/group graph results
+- path_finding: Find a bounded path between two nodes
+
+QUERY SHAPE (current DSL, format_version 5.x):
+Every query has a "query_type" and a "nodes" array of node selectors (max 5).
+A node selector names an entity and is made SELECTIVE via "node_ids" (exact
+internal ids) or "filters" (natural properties). Relationships between selectors
+go in a "relationships" array referencing selector "id" aliases.
+
+IMPORTANT changes from older docs:
+- Use a top-level "nodes" ARRAY, not a single "node" object.
+- Pin ids with "node_ids": [123], NOT filters:{id:{op:"eq",value:123}}.
+- Filters use {op: value}, e.g. {"state": "merged"} or {"created_at": {"gte": "2026-01-01"}}.
+- A "neighbors" query uses a 1-element "nodes" array plus a top-level
+  "neighbors": {direction, rel_types:[...]} object. rel_types is REQUIRED to
+  bound the lookup and is capped at 10 entries.
+
+Example neighbors query (an MR's graph neighbours):
+{
+  "query_type": "neighbors",
+  "nodes": [{ "id": "mr", "entity": "MergeRequest", "node_ids": [507483917] }],
+  "neighbors": {
+    "direction": "both",
+    "rel_types": ["AUTHORED", "REVIEWER", "IN_PROJECT", "CLOSES", "HAS_HEAD_PIPELINE"]
+  },
+  "limit": 30
+}
+
+Example traversal (merged MRs in a project):
+{
+  "query_type": "traversal",
+  "nodes": [
+    { "id": "project", "entity": "Project", "filters": {"full_path": "gitlab-org/gitlab"} },
+    { "id": "mr", "entity": "MergeRequest", "filters": {"state": "merged"},
+      "columns": ["iid", "title", "merged_at"] }
+  ],
+  "relationships": [{ "type": "IN_PROJECT", "from": "mr", "to": "project" }],
+  "limit": 25
+}
+
+Notes:
+- node_ids are GitLab *internal* numeric ids (not IIDs). For an MR, get it via
+  gitlab_get_merge_request (the "id" field). For epics, use work_item_id.
+- Traversal/aggregation queries must include at least one selective node.
+- aggregation adds an "aggregations" array (e.g. [{"count":"mr"}]) with optional
+  "group_by"; path_finding adds a "path":{from,to,max_depth} object between two
+  node selectors. Both use the same envelope; see gitlab_orbit_schema and the
+  Orbit query-language docs for the full grammar.
+- Use gitlab_orbit_schema to discover entities and relationship types.
+Returns nodes and edges arrays.`,
+    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" and a top-level "nodes" array of selectors (each pinned by "node_ids" or "filters"); add "relationships"/"neighbors"/"aggregations"/"path" per the query_type. See the tool description for the current DSL and worked examples.'
+      ),
+      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
+        );
+      }
+      if (typeof queryObj !== "object" || queryObj === null || Array.isArray(queryObj)) {
+        return JSON.stringify(
+          {
+            error: "Invalid query parameter",
+            suggestion: 'The query must be a JSON object with a "query_type" and a "nodes" array.'
+          },
+          null,
+          2
+        );
+      }
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
+      const requestBody = {
+        query: queryObj,
+        response_format: "raw"
+      };
+      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 against the current DSL: top-level "nodes" array, pin ids with "node_ids", filters use {op: value}, and a "neighbors" query needs neighbors:{direction, rel_types} (max 10 rel_types).'
+            },
+            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). For epics, use the work_item_id.`,
+    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)"),
+      rel_types: z18.array(z18.string()).optional().describe(
+        'Relationship types to follow. Required by the API to bound the lookup; if omitted, a sensible default set for the entity type is used. The API caps this at 10 per selector, so more than 10 entries are truncated to the first 10 and the response includes a "warnings" field. See gitlab_orbit_schema for valid edge types.'
+      ),
+      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 requestedRelTypes = args.rel_types?.length ? args.rel_types : orbitRelTypes(args.entity_type);
+      const relTypes = requestedRelTypes.slice(0, 10);
+      const warnings = requestedRelTypes.length > relTypes.length ? [`rel_types truncated to 10 (got ${requestedRelTypes.length})`] : [];
+      const queryObj = {
+        query_type: "neighbors",
+        nodes: [
+          {
+            id: "n",
+            entity: args.entity_type,
+            node_ids: [args.entity_id]
+          }
+        ],
+        neighbors: {
+          direction,
+          rel_types: relTypes
+        }
+      };
+      if (args.limit !== void 0) {
+        queryObj.limit = args.limit;
+      }
+      const requestBody = {
+        query: queryObj,
+        response_format: "raw"
+      };
+      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,
+              ...warnings.length > 0 && { warnings }
+            },
+            null,
+            2
+          );
+        }
+        return JSON.stringify(warnings.length > 0 ? { ...result, warnings } : 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)) {
@@ -34224,31 +34668,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.2" : "0.0.0";
+  const version2 = true ? "3.0.1" : "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 () => {