Refine Health Check for GitHub Workflow Server #7480

Author: tobiu

.github/ISSUE/epic-architect-github-workflow-as-mcp.md

@@ -24,6 +24,8 @@ We will employ a rapid and agile development approach. The scope and API specifi
 - **Goal:** Establish the server's foundation and define the initial API for PR interactions.
 - **Sub-Tasks:**
     - `ticket-define-initial-openapi-spec.md`: Create and refine an `openapi.yaml` specification, focusing first on health checks and core PR operations (list, checkout, diff).
+    - `ticket-scaffold-github-workflow-server.md`: Scaffold the server structure, including directories, core files, and middleware, mirroring the memory server.
+    - `ticket-refine-healthcheck-for-github-workflow-server.md`: Implement a robust health check to verify `gh` installation, authentication, and version.
 
 ### Future Scope
 - Implementation of the API endpoints.

.github/ISSUE/ticket-refine-healthcheck-for-github-workflow-server.md

@@ -0,0 +1,29 @@
+---
+title: Refine Health Check for GitHub Workflow Server
+labels: enhancement, AI
+---
+
+GH ticket id: #7380
+
+**Epic:** #7477
+**Phase:** 1
+**Assignee:** tobiu
+**Status:** Done
+
+## Description
+
+The initial health check for the GitHub Workflow MCP server was a simple placeholder. This ticket covers the work to make it more robust and meaningful by incorporating the more detailed verification logic from the existing `buildScripts/ai/verifyGhSetup.mjs` script.
+
+The new health check now verifies three critical conditions:
+1.  That the `gh` CLI is installed.
+2.  That the CLI is authenticated.
+3.  That the CLI version meets a minimum requirement.
+
+This ensures that the server only reports as "healthy" if it is fully capable of performing its duties.
+
+## Acceptance Criteria
+
+1.  The `ai/mcp/server/github-workflow/services/healthService.mjs` file is updated.
+2.  The `buildHealthResponse` function now performs separate checks for `gh` installation, authentication, and version.
+3.  The JSON response from the `/healthcheck` endpoint now includes a more detailed `githubCli` object with separate booleans for `installed`, `authenticated`, and `versionOk`.
+4.  The overall health status is set to `unhealthy` if any of the checks fail, with a descriptive error message included in the response.

ai/mcp/server/github-workflow/app.mjs

@@ -4,7 +4,7 @@ import morgan           from 'morgan';
 import swaggerUi        from 'swagger-ui-express';
 import yaml             from 'js-yaml';
 import healthRouter     from './routes/health.mjs';
-// import pullRequestsRouter from './routes/pullRequests.mjs'; // To be enabled later
+import pullRequestsRouter from './routes/pullRequests.mjs';
 import errorHandler     from './middleware/errorHandler.mjs';
 import notFoundHandler  from './middleware/notFoundHandler.mjs';
 import serverConfig     from './config.mjs';
@@ -21,7 +21,7 @@ app.use('/docs', swaggerUi.serve, swaggerUi.setup(openApiDocument, {explorer: tr
 
 // Routes
 app.use('/', healthRouter);
-// app.use('/', pullRequestsRouter); // To be enabled later
+app.use('/', pullRequestsRouter);
 
 // 404 + Error handlers
 app.use(notFoundHandler);

ai/mcp/server/github-workflow/services/healthService.mjs

@@ -2,6 +2,43 @@ import {exec} from 'child_process';
 import {promisify} from 'util';
 
 const execAsync = promisify(exec);
+const MIN_GH_VERSION = '2.0.0';
+
+async function checkGhInstalled() {
+    try {
+        await execAsync('gh --version');
+        return {installed: true};
+    } catch (e) {
+        return {installed: false, error: 'GitHub CLI is not installed. Please install it.'};
+    }
+}
+
+async function checkGhAuth() {
+    try {
+        await execAsync('gh auth status');
+        return {authenticated: true};
+    } catch (e) {
+        return {authenticated: false, error: 'GitHub CLI is not authenticated. Please run "gh auth login".'};
+    }
+}
+
+async function checkGhVersion() {
+    try {
+        const {stdout} = await execAsync('gh --version');
+        const versionMatch = stdout.match(/gh version ([\d.]+)/);
+        if (versionMatch) {
+            const currentVersion = versionMatch[1];
+            if (currentVersion >= MIN_GH_VERSION) {
+                return {versionOk: true, version: currentVersion};
+            } else {
+                return {versionOk: false, version: currentVersion, error: `gh version (${currentVersion}) is outdated. Please upgrade to at least ${MIN_GH_VERSION}.`};
+            }
+        }
+        return {versionOk: false, error: 'Could not parse gh version.'};
+    } catch (e) {
+        return {versionOk: false, error: 'Could not get gh version.'};
+    }
+}
 
 /**
  * Checks the status of the GitHub CLI integration.
@@ -12,25 +49,44 @@ async function buildHealthResponse() {
         status   : 'healthy',
         timestamp: new Date().toISOString(),
         githubCli: {
-            installed    : true,
-            authenticated: true,
-            details      : ''
+            installed    : false,
+            authenticated: false,
+            versionOk    : false,
+            version      : null,
+            details      : []
         }
     };
 
-    try {
-        const {stdout} = await execAsync('gh auth status');
-        payload.githubCli.details = stdout.trim();
-    } catch (error).
+    const installedCheck = await checkGhInstalled();
+    payload.githubCli.installed = installedCheck.installed;
+    if (!installedCheck.installed) {
+        payload.status = 'unhealthy';
+        payload.githubCli.details.push(installedCheck.error);
+        return payload;
+    }
+
+    const authCheck = await checkGhAuth();
+    payload.githubCli.authenticated = authCheck.authenticated;
+    if (!authCheck.authenticated) {
         payload.status = 'unhealthy';
-        payload.githubCli.installed = !error.message.includes('command not found');
-        payload.githubCli.authenticated = false;
-        payload.githubCli.details = error.stderr.trim();
+        payload.githubCli.details.push(authCheck.error);
+    }
+
+    const versionCheck = await checkGhVersion();
+    payload.githubCli.versionOk = versionCheck.versionOk;
+    payload.githubCli.version = versionCheck.version;
+    if (!versionCheck.versionOk) {
+        payload.status = 'unhealthy';
+        payload.githubCli.details.push(versionCheck.error);
+    }
+
+    if (payload.status === 'healthy') {
+        payload.githubCli.details.push('GitHub CLI is installed, authenticated, and up to date.');
     }
 
     return payload;
 }
 
 export {
     buildHealthResponse
-};
+};

package.json

@@ -24,6 +24,7 @@
         "ai:query-memory"       : "node buildScripts/ai/queryMemory.mjs",
         "ai:verify-gh-setup"    : "node buildScripts/ai/verifyGhSetup.mjs",
         "ai:server"             : "chroma run --path ./chroma",
+        "ai:server-github-workflow-mcp": "node ai/mcp/server/github-workflow/index.mjs",
         "ai:server-memory"      : "chroma run --path ./chroma-memory --port 8001",
         "ai:server-memory-mcp"  : "node ai/mcp/server/memory/index.mjs",
         "ai:setup-memory-db"    : "node buildScripts/ai/setupMemoryDB.mjs",