feat: add health check tool

Author: Killusions

index.ts

@@ -373,6 +373,7 @@ import {
   ListWebhooksSchema,
   ListWebhookEventsSchema,
   GetWebhookEventSchema,
+  HealthCheckSchema,
 } from "./schemas.js";
 
 import { randomUUID } from "node:crypto";
@@ -1254,6 +1255,15 @@ function buildAuthHeaders(): Record<string, string> {
   return {};
 }
 
+function usesJobTokenHeader(): boolean {
+  if (GITLAB_JOB_TOKEN) return true;
+  if (REMOTE_AUTHORIZATION || GITLAB_MCP_OAUTH) {
+    const ctx = sessionAuthStore.getStore();
+    return ctx?.header === "JOB-TOKEN";
+  }
+  return false;
+}
+
 /**
  * Get the effective GitLab API URL for the current request
  * In REMOTE_AUTHORIZATION mode with ENABLE_DYNAMIC_API_URL, reads from session context
@@ -7623,9 +7633,23 @@ async function createCommitStatus(
 async function getCurrentUser(): Promise<GitLabUser> {
   const response = await fetch(`${getEffectiveApiUrl()}/user`, getFetchConfig());
 
+  if (response.ok) {
+    const data = await response.json();
+    return GitLabUserSchema.parse(data);
+  }
+
+  if ((response.status === 401 || response.status === 403) && usesJobTokenHeader()) {
+    const jobResponse = await fetch(`${getEffectiveApiUrl()}/job`, getFetchConfig());
+    if (jobResponse.ok) {
+      const jobData = await jobResponse.json() as { user?: { username?: string; id?: number; name?: string } };
+      if (jobData.user) {
+        return GitLabUserSchema.parse(jobData.user);
+      }
+    }
+  }
+
   await handleGitLabError(response);
-  const data = await response.json();
-  return GitLabUserSchema.parse(data);
+  throw new Error(`GitLab API error: ${response.status} ${response.statusText}`);
 }
 
 /**
@@ -10341,6 +10365,21 @@ async function handleToolCall(params: any) {
         };
       }
 
+      case "health_check": {
+        HealthCheckSchema.parse(params.arguments);
+        const url = new URL(`${getEffectiveApiUrl()}/user`);
+        const response = await fetch(url.toString(), getFetchConfig());
+        let authenticated = response.ok;
+        if (!authenticated && (response.status === 401 || response.status === 403) && (GITLAB_JOB_TOKEN || usesJobTokenHeader())) {
+          const jobUrl = new URL(`${getEffectiveApiUrl()}/job`);
+          const jobResponse = await fetch(jobUrl.toString(), getFetchConfig());
+          authenticated = jobResponse.ok;
+        }
+        return {
+          content: [{ type: "text", text: JSON.stringify({ status: authenticated ? "ok" : "error", authenticated, gitlab_url: getEffectiveApiUrl() }) }],
+        };
+      }
+
       default:
         throw new Error(`Unknown tool: ${params.name}`);
     }

schemas.ts

@@ -3738,3 +3738,5 @@ export type GitLabSearchBlobResult = z.infer<typeof GitLabSearchBlobResultSchema
 export type SearchCodeOptions = z.infer<typeof SearchCodeSchema>;
 export type SearchProjectCodeOptions = z.infer<typeof SearchProjectCodeSchema>;
 export type SearchGroupCodeOptions = z.infer<typeof SearchGroupCodeSchema>;
+
+export const HealthCheckSchema = z.object({});

test/test-toolset-filtering.ts

@@ -34,7 +34,7 @@ const TOOLSET_TOOL_COUNTS: Record<string, number> = {
   issues: 23,
   repositories: 7,
   branches: 6,
-  projects: 8,
+  projects: 9,
   labels: 5,
   ci: 2,
   pipelines: 19,

test/utils/server-launcher.ts

@@ -110,11 +110,12 @@ export async function launchServer(config: ServerConfig): Promise<ServerInstance
         serverProcess.kill("SIGTERM");
 
         // Force kill if not terminated within 5 seconds
-        setTimeout(() => {
+        const forceKillTimer = setTimeout(() => {
           if (!serverProcess.killed) {
             serverProcess.kill("SIGKILL");
           }
         }, 5000);
+        forceKillTimer.unref();
       }
     },
   };

tools/registry.ts

@@ -74,6 +74,7 @@ import {
   EditProjectMilestoneSchema,
   ExecuteGraphQLSchema,
   ForkRepositorySchema,
+  HealthCheckSchema,
   GetBranchDiffsSchema,
   GetCommitDiffSchema,
   GetCommitSchema,
@@ -849,6 +850,11 @@ export const allTools = [
     description: "Download an uploaded file from a project (images returned as base64; use local_path to save to disk)",
     inputSchema: toJSONSchema(DownloadAttachmentSchema),
   },
+  {
+    name: "health_check",
+    description: "Verify server status and authentication",
+    inputSchema: toJSONSchema(HealthCheckSchema),
+  },
   {
     name: "list_events",
     description: "List events for the authenticated user (before/after: YYYY-MM-DD)",
@@ -1063,6 +1069,7 @@ export const allTools = [
 // Define which tools are read-only
 export const readOnlyTools = new Set([
   "discover_tools",
+  "health_check",
   "search_repositories",
   "search_code",
   "search_project_code",
@@ -1374,6 +1381,7 @@ export const TOOLSET_DEFINITIONS: readonly ToolsetDefinition[] = [
       "verify_namespace",
       "list_group_projects",
       "list_group_iterations",
+      "health_check",
     ]),
   },
   {