Enhance Tools List with OpenAPI Schema #7487

Author: tobiu

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

@@ -41,6 +41,7 @@ We will employ a rapid and agile development approach. The scope and API specifi
 - **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.
+    - `ticket-enhance-tools-list-with-schema.md`: Enhance the `/tools/list` endpoint to include OpenAPI schema definitions for each tool's parameters and responses.
 
 ### Future Scope
 - Implementation of the API endpoints.

.github/ISSUE/ticket-enhance-tools-list-with-schema.md

@@ -0,0 +1,30 @@
+---
+title: Enhance Tools List with OpenAPI Schema
+labels: enhancement, AI
+---
+
+GH ticket id: #7387
+
+**Epic:** #7477
+**Phase:** 3
+**Assignee:** tobiu
+**Status:** Done
+
+## Description
+
+See: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
+
+The current `/tools/list` endpoint provides only the name and description of available tools. To enable robust client-side integration and dynamic tool generation for the agent, the tool list needs to include the full OpenAPI schema for each tool's parameters and response, as dictated by the Model Context Protocol (MCP) specification.
+
+This enhancement will allow the agent to fully understand how to call each tool, including required arguments, their types, and the expected return format, directly from the `/tools/list` response.
+
+## Acceptance Criteria
+
+1.  The `toolService.mjs` is updated to extract relevant schema information (parameters, requestBody) for each operation from the `openapi.yaml` and convert it into a single `inputSchema` (JSON Schema) for each tool.
+2.  The `GET /tools/list` endpoint's response for each tool includes:
+    -   `name` (string): The unique identifier for the tool (from `operationId`).
+    -   `title` (string): A human-readable title for the tool (from `summary`).
+    -   `description` (string): A detailed description of the tool (from `description`).
+    -   `inputSchema` (JSON Schema object): A JSON Schema defining the tool's parameters, derived from the OpenAPI operation's `parameters` and `requestBody`.
+3.  The `callTool` function in `toolService.mjs` is updated to remove the manual `switch` statement for argument mapping. It should expect `args` to conform to the `inputSchema` and use a more generic method to pass them to the `tool.handler`.
+4.  The `outputSchema` (JSON Schema object) is optionally included in the tool definition if available in the OpenAPI response.

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

@@ -18,6 +18,51 @@ const serviceMapping = {
     ...pullRequestService
 };
 
+/**
+ * Converts OpenAPI parameters and requestBody into a JSON Schema inputSchema.
+ * @param {object} operation - The OpenAPI operation object.
+ * @returns {object} A JSON Schema object for the input.
+ */
+function buildInputSchema(operation) {
+    const schema = {
+        type: 'object',
+        properties: {},
+        required: []
+    };
+
+    // Handle parameters (path, query, header, cookie)
+    if (operation.parameters) {
+        for (const param of operation.parameters) {
+            schema.properties[param.name] = {
+                type: param.schema.type,
+                description: param.description
+            };
+            if (param.required) {
+                schema.required.push(param.name);
+            }
+        }
+    }
+
+    // Handle requestBody
+    if (operation.requestBody && operation.requestBody.content && operation.requestBody.content['application/json']) {
+        const requestBodySchema = operation.requestBody.content['application/json'].schema;
+        // Assuming requestBody is a simple object for now
+        if (requestBodySchema.properties) {
+            for (const [propName, propSchema] of Object.entries(requestBodySchema.properties)) {
+                schema.properties[propName] = {
+                    type: propSchema.type,
+                    description: propSchema.description
+                };
+                if (requestBodySchema.required && requestBodySchema.required.includes(propName)) {
+                    schema.required.push(propName);
+                }
+            }
+        }
+    }
+
+    return schema;
+}
+
 /**
  * Parses the openapi.yaml file to build a mapping of tool names to service functions.
  */
@@ -34,9 +79,11 @@ function initializeToolMapping() {
         for (const [method, operation] of Object.entries(pathItem)) {
             if (operation.operationId) {
                 toolMapping[operation.operationId] = {
-                    path,
-                    method,
-                    description: operation.description,
+                    name: operation.operationId,
+                    title: operation.summary || operation.operationId,
+                    description: operation.description || operation.summary,
+                    inputSchema: buildInputSchema(operation),
+                    // outputSchema: buildOutputSchema(operation), // To be implemented later
                     handler: serviceMapping[operation.operationId]
                 };
             }
@@ -50,9 +97,11 @@ function initializeToolMapping() {
  */
 function listTools() {
     initializeToolMapping();
-    return Object.entries(toolMapping).map(([name, tool]) => ({
-        name: name,
-        description: tool.description
+    return Object.values(toolMapping).map(tool => ({
+        name: tool.name,
+        title: tool.title,
+        description: tool.description,
+        inputSchema: tool.inputSchema
     }));
 }
 
@@ -70,27 +119,23 @@ async function callTool(toolName, args) {
         throw new Error(`Tool "${toolName}" not found or not implemented.`);
     }
 
-    // Explicitly map arguments based on toolName
-    switch (toolName) {
-        case 'listLabels':
-            return tool.handler();
-        case 'listPullRequests':
-            return tool.handler(args);
-        case 'checkoutPullRequest':
-        case 'getPullRequestDiff':
-        case 'getConversation':
-            return tool.handler(args.prNumber);
-        case 'createComment':
-            return tool.handler(args.prNumber, args.body);
-        case 'addLabels':
-        case 'removeLabels':
-            return tool.handler(args.issueNumber, args.labels);
-        default:
-            throw new Error(`Unknown tool: ${toolName}`);
+    // Dynamically extract arguments based on the inputSchema
+    const handlerArgs = [];
+    const inputSchema = tool.inputSchema;
+
+    if (inputSchema && inputSchema.properties) {
+        for (const propName of Object.keys(inputSchema.properties)) {
+            // For now, we assume the order of properties in inputSchema.properties
+            // matches the order of arguments expected by the handler function.
+            // This is a simplification and might need refinement for complex cases.
+            handlerArgs.push(args[propName]);
+        }
     }
+
+    return tool.handler(...handlerArgs);
 }
 
 export {
     listTools,
     callTool
-};
+};