feat(mcp/github-workflow): add list_issues tool, OpenAPI path/schemas and verification tests

MannXo · MannXo · commit 7f720ed92c26 · 2025-10-28T12:53:59.000+03:30
Closes: #7663 - Feat: Implement GitHub API-based 'list_issues' tool Includes: - IssueService.listIssues implementation - Registered list_issues in toolService - OpenAPI: GET /issues + IssueListResponse schema - lightweight file-based verification tests - HealthService robustness fix for gh stdout/stderr
diff --git a/ai/mcp/server/github-workflow/openapi.yaml b/ai/mcp/server/github-workflow/openapi.yaml
@@ -596,6 +596,63 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
 
   /issues:
+    get:
+      summary: List Issues
+      operationId: list_issues
+      x-pass-as-object: true
+      x-annotations:
+        readOnlyHint: true
+      description: |
+        Retrieves a list of issues from the repository. Supports basic filters such as `limit`, `state`, `labels`, and `assignee`.
+
+        **When to Use:**
+        - To find open work items or review recent closed issues.
+        - To look up issue numbers for use in other tools.
+      tags: [Issues]
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          description: Maximum number of issues to return.
+          schema:
+            type: integer
+            minimum: 1
+            maximum: 100
+            default: 30
+        - name: state
+          in: query
+          required: false
+          description: Filter issues by state.
+          schema:
+            type: string
+            enum: [open, closed, all]
+            default: open
+        - name: labels
+          in: query
+          required: false
+          description: Comma separated list of labels to filter by (all labels must be present on the issue).
+          schema:
+            type: string
+        - name: assignee
+          in: query
+          required: false
+          description: Filter issues by a single assignee login.
+          schema:
+            type: string
+      responses:
+        '200':
+          description: A list of issues.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/IssueListResponse'
+        '500':
+          description: Internal server error, e.g., GraphQL failure.
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/ErrorResponse'
+
     post:
       summary: Create a new GitHub issue
       operationId: create_issue
@@ -1016,3 +1073,52 @@ components:
           description: The permission level of the viewer.
           enum: [ADMIN, MAINTAIN, WRITE, TRIAGE, READ]
           example: WRITE
+
+    Issue:
+      type: object
+      properties:
+        number:
+          type: integer
+          example: 7608
+        title:
+          type: string
+        body:
+          type: string
+        state:
+          type: string
+          example: OPEN
+        author:
+          type: object
+          properties:
+            login:
+              type: string
+        url:
+          type: string
+          format: uri
+        labels:
+          type: array
+          items:
+            type: object
+            properties:
+              name:
+                type: string
+        assignees:
+          type: array
+          items:
+            type: object
+            properties:
+              login:
+                type: string
+        createdAt:
+          type: string
+          format: date-time
+
+    IssueListResponse:
+      type: object
+      properties:
+        count:
+          type: integer
+        issues:
+          type: array
+          items:
+            $ref: '#/components/schemas/Issue'
diff --git a/ai/mcp/server/github-workflow/services/HealthService.mjs b/ai/mcp/server/github-workflow/services/HealthService.mjs
@@ -85,12 +85,15 @@ class HealthService extends Base {
      */
     async #checkGhAuth() {
         try {
-            const { stdout } = await execAsync('gh auth status');
+            // Some platforms or gh versions may write status information to stderr
+            // instead of stdout. Capture both and check the combined output.
+            const { stdout, stderr } = await execAsync('gh auth status');
+            const out = `${stdout || ''}\n${stderr || ''}`;
 
             // The `gh auth status` command outputs information about the logged-in account.
             // We specifically check for "Logged in to github.com" to confirm the user
             // is authenticated to the correct GitHub instance (not enterprise).
-            if (stdout.includes('Logged in to github.com')) {
+            if (out.includes('Logged in to github.com')) {
                 return { authenticated: true };
             } else {
                 return {
@@ -99,12 +102,11 @@ class HealthService extends Base {
                 };
             }
         } catch (e) {
-            // The command failing typically means `gh` is not authenticated.
-            // This is a common scenario when the user first installs `gh` or their
-            // authentication token has expired.
+            // The command failing typically means `gh` is not installed or not
+            // available in PATH for child processes. Provide an actionable message.
             return {
                 authenticated: false,
-                error        : 'GitHub CLI is not authenticated. Please run `gh auth login`.'
+                error        : 'GitHub CLI is not authenticated or not available. Please run `gh auth login`.'
             };
         }
     }
@@ -125,8 +127,10 @@ class HealthService extends Base {
      */
     async #checkGhVersion() {
         try {
-            const { stdout }   = await execAsync('gh --version');
-            const versionMatch = stdout.match(/gh version ([\d.]+)/);
+            // Capture both stdout and stderr for robustness across environments
+            const { stdout, stderr } = await execAsync('gh --version');
+            const out = `${stdout || ''}\n${stderr || ''}`;
+            const versionMatch = out.match(/gh version ([\d.]+)/);
 
             if (versionMatch) {
                 const currentVersion = versionMatch[1];
diff --git a/ai/mcp/server/github-workflow/services/IssueService.mjs b/ai/mcp/server/github-workflow/services/IssueService.mjs
@@ -5,7 +5,7 @@ import logger                      from '../logger.mjs';
 import {exec}                      from 'child_process';
 import {promisify}                 from 'util';
 import {spawn}                     from 'child_process';
-import {GET_ISSUE_AND_LABEL_IDS}   from './queries/issueQueries.mjs';
+import {GET_ISSUE_AND_LABEL_IDS, FETCH_ISSUES_FOR_SYNC, DEFAULT_QUERY_LIMITS}   from './queries/issueQueries.mjs';
 import {ADD_LABELS, REMOVE_LABELS} from './queries/mutations.mjs';
 import RepositoryService           from './RepositoryService.mjs';
 
@@ -317,6 +317,77 @@ class IssueService extends Base {
             };
         }
     }
+
+    /**
+     * Lists issues from the repository using the GraphQL API.
+     * Supports basic pagination and state filtering. Label and assignee
+     * filters are applied client-side to keep the GraphQL query simple and
+     * compatible with the existing sync query.
+     *
+     * @param {object} options
+     * @param {number} [options.limit=30]
+     * @param {string} [options.state='open']
+     * @param {string[]|string} [options.labels]
+     * @param {string} [options.assignee]
+     * @param {string} [options.cursor]
+     * @returns {Promise<object>}
+     */
+    async listIssues(options = {}) {
+        const {
+            limit = 30,
+            state = 'open',
+            labels = null,
+            assignee = null,
+            cursor = null
+        } = options;
+
+        // normalize state to uppercase array (GraphQL expects IssueState enum values)
+        const states = state ? (Array.isArray(state) ? state.map(s => s.toUpperCase()) : [state.toUpperCase()]) : undefined;
+
+        const variables = {
+            owner     : aiConfig.owner,
+            repo      : aiConfig.repo,
+            limit,
+            cursor,
+            states,
+            since     : null,
+            ...DEFAULT_QUERY_LIMITS
+        };
+
+        try {
+            const data = await GraphqlService.query(FETCH_ISSUES_FOR_SYNC, variables);
+            let issues = data.repository.issues.nodes || [];
+
+            // client-side label filtering if requested
+            if (labels) {
+                const labelList = Array.isArray(labels) ? labels : String(labels).split(',').map(s => s.trim()).filter(Boolean);
+                issues = issues.filter(issue => {
+                    const issueLabels = (issue.labels && issue.labels.nodes || []).map(l => l.name);
+                    return labelList.every(l => issueLabels.includes(l));
+                });
+            }
+
+            // client-side assignee filtering if requested
+            if (assignee) {
+                issues = issues.filter(issue => {
+                    const assignees = (issue.assignees && issue.assignees.nodes || []).map(a => a.login);
+                    return assignees.includes(assignee);
+                });
+            }
+
+            return {
+                count: issues.length,
+                issues
+            };
+        } catch (error) {
+            logger.error('Error fetching issues via GraphQL:', error);
+            return {
+                error  : 'GraphQL API request failed',
+                message: error.message,
+                code   : 'GRAPHQL_API_ERROR'
+            };
+        }
+    }
 }
 
 export default Neo.setupClass(IssueService);
diff --git a/ai/mcp/server/github-workflow/services/toolService.mjs b/ai/mcp/server/github-workflow/services/toolService.mjs
@@ -26,6 +26,7 @@ const serviceMapping = {
     healthcheck          : HealthService     .healthcheck        .bind(HealthService),
     list_labels          : LabelService      .listLabels         .bind(LabelService),
     list_pull_requests   : PullRequestService.listPullRequests   .bind(PullRequestService),
+    list_issues          : IssueService      .listIssues         .bind(IssueService),
     remove_labels        : IssueService      .removeLabels       .bind(IssueService),
     sync_all             : SyncService       .runFullSync        .bind(SyncService),
     unassign_issue       : IssueService      .unassignIssue      .bind(IssueService)
diff --git a/ai/mcp/server/github-workflow/test/openapi-issues.test.mjs b/ai/mcp/server/github-workflow/test/openapi-issues.test.mjs
@@ -0,0 +1,22 @@
+import fs from 'fs';
+import path from 'path';
+
+const f = path.resolve('ai/mcp/server/github-workflow/openapi.yaml');
+if (!fs.existsSync(f)) {
+  console.error('openapi.yaml not found at', f);
+  process.exit(2);
+}
+const s = fs.readFileSync(f, 'utf8');
+
+const hasPath = /(^|\n)\s*\/issues\s*:/m.test(s) || /\/issues\b/.test(s);
+const hasSchema = /IssueListResponse\b/.test(s) || /components:[\s\S]*IssueListResponse/m.test(s);
+
+if (hasPath && hasSchema) {
+  console.log('OK: openapi.yaml contains /issues path and IssueListResponse schema');
+  process.exit(0);
+} else {
+  console.error('FAIL: openapi.yaml missing /issues path or IssueListResponse schema');
+  if (!hasPath) console.error('- /issues path not found');
+  if (!hasSchema) console.error('- IssueListResponse schema not found');
+  process.exit(1);
+}
diff --git a/ai/mcp/server/github-workflow/test/tool-registration.test.mjs b/ai/mcp/server/github-workflow/test/tool-registration.test.mjs
@@ -0,0 +1,25 @@
+import fs from 'fs';
+import path from 'path';
+
+const f = path.resolve('ai/mcp/server/github-workflow/services/toolService.mjs');
+if (!fs.existsSync(f)) {
+  console.error('toolService.mjs not found at', f);
+  process.exit(2);
+}
+const s = fs.readFileSync(f, 'utf8');
+
+// Try to extract the serviceMapping block roughly and detect keys
+const m = s.match(/serviceMapping\s*=\s*\{([\s\S]*?)\};?/m);
+if (!m) {
+  console.error('serviceMapping block not found in toolService.mjs');
+  process.exit(3);
+}
+const body = m[1];
+const keys = [...body.matchAll(/(?:['\"])?([a-zA-Z0-9_]+)(?:['\"])?\s*:/g)].map(x=>x[1]);
+if (keys.includes('list_issues')) {
+  console.log('OK: list_issues registered in toolService');
+  process.exit(0);
+} else {
+  console.error('FAIL: list_issues not found in toolService mapping. Keys found:', keys.join(', '));
+  process.exit(1);
+}
