#7486 tools list endpoint

Author: tobiu

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

@@ -37,6 +37,11 @@ We will employ a rapid and agile development approach. The scope and API specifi
     - `ticket-get-pr-conversation-history.md`: Implement an endpoint to retrieve the full conversation history for a PR.
     - `ticket-manage-repository-labels.md`: Implement endpoints for listing and managing repository labels.
 
+### Phase 3: MCP Refactoring
+- **Goal:** Evolve the server from a REST API to a true MCP tool-providing server.
+- **Sub-Tasks:**
+    - `ticket-refactor-to-mcp-tool-server.md`: Implement `tools/list` and `tools/call` endpoints to dynamically expose the server's capabilities.
+
 ### Future Scope
 - Implementation of the API endpoints.
 - Integration of ticket and issue synchronization.

.github/ISSUE/ticket-refactor-to-mcp-tool-server.md

@@ -0,0 +1,25 @@
+---
+title: Refactor to an MCP Tool-Providing Server
+labels: enhancement, AI, refactoring
+---
+
+GH ticket id: #7386
+
+**Epic:** #7477
+**Phase:** 3
+**Assignee:** tobiu
+**Status:** To Do
+
+## Description
+
+The server currently functions as a standard REST API, which forces the agent to use `curl`. This is inefficient and does not align with the Model Context Protocol (MCP) vision.
+
+This ticket covers the refactoring of the server to become a true MCP-compliant, tool-providing server. It will parse its own `openapi.yaml` to dynamically expose its capabilities as tools for the agent.
+
+## Acceptance Criteria
+
+1.  A new `toolService.mjs` is created that can parse the `openapi.yaml` and map API endpoints to their underlying service functions.
+2.  A new `tools.mjs` route is created.
+3.  A `GET /tools/list` endpoint is implemented. It returns a JSON array of available tools, derived from the OpenAPI spec.
+4.  A `POST /tools/call` endpoint is implemented. It receives a `toolName` and `arguments`, executes the correct service function, and returns the result.
+5.  The existing REST endpoints (e.g., `/pull-requests`, `/labels`) remain functional for now but are considered deprecated for agent use.

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

@@ -7,6 +7,7 @@ import healthRouter     from './routes/health.mjs';
 import issuesRouter     from './routes/issues.mjs';
 import labelsRouter     from './routes/labels.mjs';
 import pullRequestsRouter from './routes/pullRequests.mjs';
+import toolsRouter      from './routes/tools.mjs';
 import errorHandler     from './middleware/errorHandler.mjs';
 import notFoundHandler  from './middleware/notFoundHandler.mjs';
 import serverConfig     from './config.mjs';
@@ -26,6 +27,7 @@ app.use('/', healthRouter);
 app.use('/', issuesRouter);
 app.use('/', labelsRouter);
 app.use('/', pullRequestsRouter);
+app.use('/', toolsRouter);
 
 // 404 + Error handlers
 app.use(notFoundHandler);

ai/mcp/server/github-workflow/openapi.yaml

@@ -63,6 +63,7 @@ paths:
   /labels:
     get:
       summary: List Repository Labels
+      operationId: listLabels
       description: Retrieves a list of all available labels in the repository.
       tags: [Labels]
       responses:
@@ -82,6 +83,7 @@ paths:
   /pull-requests:
     get:
       summary: List Pull Requests
+      operationId: listPullRequests
       description: Retrieves a list of open pull requests from the GitHub repository.
       tags: [Pull Requests]
       parameters:
@@ -119,6 +121,7 @@ paths:
   /pull-requests/{pr_number}/checkout:
     post:
       summary: Checkout PR Branch
+      operationId: checkoutPullRequest
       description: Checks out the branch for a given pull request locally using `gh pr checkout`.
       tags: [Pull Requests]
       parameters:
@@ -152,6 +155,7 @@ paths:
   /pull-requests/{pr_number}/diff:
     get:
       summary: Get PR Diff
+      operationId: getPullRequestDiff
       description: Retrieves the diff for a specific pull request using `gh pr diff`.
       tags: [Pull Requests]
       parameters:
@@ -185,6 +189,7 @@ paths:
   /pull-requests/{pr_number}/comments:
     post:
       summary: Create a PR Comment
+      operationId: createComment
       description: Adds a comment to a specific pull request.
       tags: [Pull Requests]
       parameters:
@@ -231,6 +236,7 @@ paths:
   /pull-requests/{pr_number}/conversation:
     get:
       summary: Get PR Conversation
+      operationId: getConversation
       description: Retrieves the full conversation for a pull request, including the title, body, and all comments.
       tags: [Pull Requests]
       parameters:
@@ -252,6 +258,7 @@ paths:
   /issues/{issue_number}/labels:
     post:
       summary: Add labels to an issue or PR
+      operationId: addLabels
       description: Adds one or more labels to a specific issue or pull request.
       tags: [Issues]
       parameters:
@@ -296,6 +303,7 @@ paths:
                 $ref: '#/components/schemas/ErrorResponse'
     delete:
       summary: Remove labels from an issue or PR
+      operationId: removeLabels
       description: Removes one or more labels from a specific issue or pull request.
       tags: [Issues]
       parameters:

ai/mcp/server/github-workflow/routes/tools.mjs

@@ -0,0 +1,18 @@
+import {Router} from 'express';
+import asyncHandler from '../middleware/asyncHandler.mjs';
+import {listTools, callTool} from '../services/toolService.mjs';
+
+const router = Router();
+
+router.get('/tools/list', asyncHandler(async (req, res) => {
+    const tools = listTools();
+    res.status(200).json(tools);
+}));
+
+router.post('/tools/call', asyncHandler(async (req, res) => {
+    const {toolName, args} = req.body;
+    const result = await callTool(toolName, args);
+    res.status(200).json(result);
+}));
+
+export default router;

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

@@ -0,0 +1,81 @@
+import fs from 'fs';
+import yaml from 'js-yaml';
+import path from 'path';
+import {fileURLToPath} from 'url';
+import * as issueService from './issueService.mjs';
+import * as labelService from './labelService.mjs';
+import * as pullRequestService from './pullRequestService.mjs';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const openApiFilePath = path.join(__dirname, '../openapi.yaml');
+
+let toolMapping = null;
+
+const serviceMapping = {
+    ...issueService,
+    ...labelService,
+    ...pullRequestService
+};
+
+/**
+ * Parses the openapi.yaml file to build a mapping of tool names to service functions.
+ */
+function initializeToolMapping() {
+    if (toolMapping) {
+        return;
+    }
+
+    toolMapping = {};
+
+    const openApiDocument = yaml.load(fs.readFileSync(openApiFilePath, 'utf8'));
+
+    for (const [path, pathItem] of Object.entries(openApiDocument.paths)) {
+        for (const [method, operation] of Object.entries(pathItem)) {
+            if (operation.operationId) {
+                toolMapping[operation.operationId] = {
+                    path,
+                    method,
+                    description: operation.description,
+                    handler: serviceMapping[operation.operationId]
+                };
+            }
+        }
+    }
+}
+
+/**
+ * Lists all available tools.
+ * @returns {object[]} A list of tool definitions.
+ */
+function listTools() {
+    initializeToolMapping();
+    return Object.entries(toolMapping).map(([name, tool]) => ({
+        name: name,
+        description: tool.description
+    }));
+}
+
+/**
+ * Calls a tool by its name with the given arguments.
+ * @param {string} toolName - The name of the tool to call.
+ * @param {object} args - The arguments for the tool.
+ * @returns {Promise<any>} The result of the tool execution.
+ */
+async function callTool(toolName, args) {
+    initializeToolMapping();
+    const tool = toolMapping[toolName];
+
+    if (!tool || !tool.handler) {
+        throw new Error(`Tool "${toolName}" not found or not implemented.`);
+    }
+
+    // This is a simplified argument handling. A real implementation would be more robust.
+    const argValues = args ? Object.values(args) : [];
+    return tool.handler(...argValues);
+}
+
+export {
+    listTools,
+    callTool
+};