zephyr-scale-mcp-server 0.4.7 → 0.5.1

package/build/index.js

@@ -69,6 +69,8 @@ class ZephyrServer {
                         return await this.toolHandlers.searchTestRuns(args);
                     case 'add_test_cases_to_run':
                         return await this.toolHandlers.addTestCasesToRun(args);
+                    case 'list_executions_by_cycle':
+                        return await this.toolHandlers.listExecutionsByCycle(args);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/tool-handlers.js

@@ -808,9 +808,9 @@ export class ZephyrToolHandlers {
         }
     }
     async searchTestRuns(args) {
-        const { project_key, folder, max_results = 200, fields } = args;
-        if (!project_key && !folder) {
-            throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key or folder must be provided.');
+        const { project_key, folder, folder_id, max_results = 200, fields } = args;
+        if (!project_key && !folder && !folder_id) {
+            throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key, folder, or folder_id must be provided.');
         }
         if (this.jiraConfig.type === 'cloud') {
             try {
@@ -818,7 +818,11 @@ export class ZephyrToolHandlers {
                 const params = { maxResults: max_results };
                 if (project_key)
                     params.projectKey = project_key;
-                if (folder && project_key) {
+                // folder_id takes precedence over folder path
+                if (folder_id) {
+                    params.folderId = folder_id;
+                }
+                else if (folder && project_key) {
                     const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CYCLE');
                     if (folderId !== null)
                         params.folderId = folderId;
@@ -907,6 +911,79 @@ export class ZephyrToolHandlers {
             throw new McpError(ErrorCode.InternalError, `Failed to add test cases: ${this.formatError(error)}`);
         }
     }
+    async listExecutionsByCycle(args) {
+        const { test_cycle_key, project_key, max_results = 100 } = args;
+        if (this.jiraConfig.type === 'cloud') {
+            try {
+                // Cloud v2: GET /testexecutions?projectKey=X&testCycle=Y
+                const params = {
+                    projectKey: project_key,
+                    testCycle: test_cycle_key,
+                    maxResults: max_results,
+                };
+                const response = await this.axiosInstance.get('/testexecutions', { params });
+                const executions = Array.isArray(response.data)
+                    ? response.data
+                    : response.data?.values ?? [];
+                const summary = executions.map((ex) => ({
+                    key: ex.key,
+                    testCaseKey: ex.testCase?.self?.match(/testcases\/(.+?)\/versions/)?.[1] || ex.testCase?.id,
+                    status: ex.testExecutionStatus?.id,
+                    statusName: ex.testExecutionStatus?.name,
+                    executedById: ex.executedById,
+                    assignedToId: ex.assignedToId,
+                    actualEndDate: ex.actualEndDate,
+                    automated: ex.automated,
+                    comment: ex.comment,
+                }));
+                // Count statuses
+                const statusCounts = {};
+                for (const ex of executions) {
+                    const statusId = ex.testExecutionStatus?.id?.toString() || 'unknown';
+                    statusCounts[statusId] = (statusCounts[statusId] || 0) + 1;
+                }
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `✅ Found ${executions.length} execution(s) for cycle ${test_cycle_key}:\n${JSON.stringify({
+                                cycleKey: test_cycle_key,
+                                totalExecutions: executions.length,
+                                statusCounts,
+                                executions: summary,
+                            }, null, 2)}`,
+                        }],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, `Failed to list executions: ${this.formatError(error)}`);
+            }
+        }
+        // Data Center: GET /rest/atm/1.0/testrun/{key}/testresults
+        try {
+            const response = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testrun}/${test_cycle_key}/testresults`);
+            const results = Array.isArray(response.data) ? response.data : [];
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Found ${results.length} execution(s) for cycle ${test_cycle_key}:\n${JSON.stringify({
+                            cycleKey: test_cycle_key,
+                            totalExecutions: results.length,
+                            executions: results.map((r) => ({
+                                id: r.id,
+                                testCaseKey: r.testCaseKey,
+                                status: r.status,
+                                executedBy: r.executedBy,
+                                executionDate: r.executionDate,
+                                automated: r.automated,
+                            })),
+                        }, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to list executions: ${this.formatError(error)}`);
+        }
+    }
     async resolveJiraIssueId(issueKey) {
         // The Zephyr API key is NOT valid for the Jira REST API — Jira Cloud requires
         // Basic Auth: base64(email:api_token) via JIRA_USERNAME + JIRA_API_TOKEN env vars.

package/build/tool-schemas.js

@@ -351,7 +351,7 @@ export const toolSchemas = [
     },
     {
         name: 'search_test_runs',
-        description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path.',
+        description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path. On Cloud, only returns cycles in the exact folder (not sub-folders). Use folder_id for direct numeric ID lookup (skips path resolution).',
         inputSchema: {
             type: 'object',
             properties: {
@@ -361,7 +361,11 @@ export const toolSchemas = [
                 },
                 folder: {
                     type: 'string',
-                    description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder")',
+                    description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder"). Resolved to a numeric folderId on Cloud.',
+                },
+                folder_id: {
+                    type: 'number',
+                    description: 'Numeric folder ID to filter test runs by (optional). If provided, takes precedence over folder path and skips path resolution. Use this when you already know the folder ID.',
                 },
                 max_results: {
                     type: 'number',
@@ -375,6 +379,29 @@ export const toolSchemas = [
             },
         },
     },
+    {
+        name: 'list_executions_by_cycle',
+        description: 'List all test executions for a specific test cycle. Returns execution status, executedBy, actualEndDate for each test case in the cycle. Cloud only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                test_cycle_key: {
+                    type: 'string',
+                    description: 'Test cycle key (e.g., DDCN-R371)',
+                },
+                project_key: {
+                    type: 'string',
+                    description: 'Project key (required for Cloud)',
+                },
+                max_results: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (optional, default 100)',
+                    default: 100,
+                },
+            },
+            required: ['test_cycle_key', 'project_key'],
+        },
+    },
     {
         name: 'delete_test_run',
         description: 'Delete a specific test run (Data Center only — not supported on Cloud v2)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.4.7",
+  "version": "0.5.1",
   "description": "Model Context Protocol (MCP) server for Zephyr Scale test case management with comprehensive STEP_BY_STEP, PLAIN_TEXT, and BDD support",
   "type": "module",
   "main": "./build/index.js",

package/src/index.ts

@@ -89,6 +89,8 @@ class ZephyrServer {
             return await this.toolHandlers.searchTestRuns(args as any);
           case 'add_test_cases_to_run':
             return await this.toolHandlers.addTestCasesToRun(args as any);
+          case 'list_executions_by_cycle':
+            return await this.toolHandlers.listExecutionsByCycle(args as any);
           default:
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
         }

package/src/tool-handlers.ts

@@ -10,6 +10,7 @@ import {
   AddTestCasesToRunArgs,
   SearchTestRunsArgs,
   GetTestExecutionArgs,
+  ListExecutionsByCycleArgs,
   JiraConfig
 } from './types.js';
 import { convertToGherkin, resolveFolderIdByPath } from './utils.js';
@@ -879,10 +880,10 @@ export class ZephyrToolHandlers {
   }
 
   async searchTestRuns(args: SearchTestRunsArgs) {
-    const { project_key, folder, max_results = 200, fields } = args;
+    const { project_key, folder, folder_id, max_results = 200, fields } = args;
 
-    if (!project_key && !folder) {
-      throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key or folder must be provided.');
+    if (!project_key && !folder && !folder_id) {
+      throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key, folder, or folder_id must be provided.');
     }
 
     if (this.jiraConfig.type === 'cloud') {
@@ -891,7 +892,10 @@ export class ZephyrToolHandlers {
         const params: Record<string, any> = { maxResults: max_results };
         if (project_key) params.projectKey = project_key;
 
-        if (folder && project_key) {
+        // folder_id takes precedence over folder path
+        if (folder_id) {
+          params.folderId = folder_id;
+        } else if (folder && project_key) {
           const folderId = await resolveFolderIdByPath(
             this.axiosInstance, project_key, folder, 'TEST_CYCLE'
           );
@@ -989,6 +993,89 @@ export class ZephyrToolHandlers {
     }
   }
 
+  async listExecutionsByCycle(args: ListExecutionsByCycleArgs) {
+    const { test_cycle_key, project_key, max_results = 100 } = args;
+
+    if (this.jiraConfig.type === 'cloud') {
+      try {
+        // Cloud v2: GET /testexecutions?projectKey=X&testCycle=Y
+        const params: Record<string, any> = {
+          projectKey: project_key,
+          testCycle: test_cycle_key,
+          maxResults: max_results,
+        };
+
+        const response = await this.axiosInstance.get('/testexecutions', { params });
+
+        const executions = Array.isArray(response.data)
+          ? response.data
+          : response.data?.values ?? [];
+
+        const summary = executions.map((ex: any) => ({
+          key: ex.key,
+          testCaseKey: ex.testCase?.self?.match(/testcases\/(.+?)\/versions/)?.[1] || ex.testCase?.id,
+          status: ex.testExecutionStatus?.id,
+          statusName: ex.testExecutionStatus?.name,
+          executedById: ex.executedById,
+          assignedToId: ex.assignedToId,
+          actualEndDate: ex.actualEndDate,
+          automated: ex.automated,
+          comment: ex.comment,
+        }));
+
+        // Count statuses
+        const statusCounts: Record<string, number> = {};
+        for (const ex of executions) {
+          const statusId = ex.testExecutionStatus?.id?.toString() || 'unknown';
+          statusCounts[statusId] = (statusCounts[statusId] || 0) + 1;
+        }
+
+        return {
+          content: [{
+            type: 'text',
+            text: `✅ Found ${executions.length} execution(s) for cycle ${test_cycle_key}:\n${JSON.stringify({
+              cycleKey: test_cycle_key,
+              totalExecutions: executions.length,
+              statusCounts,
+              executions: summary,
+            }, null, 2)}`,
+          }],
+        };
+      } catch (error) {
+        throw new McpError(ErrorCode.InternalError, `Failed to list executions: ${this.formatError(error)}`);
+      }
+    }
+
+    // Data Center: GET /rest/atm/1.0/testrun/{key}/testresults
+    try {
+      const response = await this.axiosInstance.get(
+        `${this.jiraConfig.apiEndpoints.testrun}/${test_cycle_key}/testresults`
+      );
+
+      const results = Array.isArray(response.data) ? response.data : [];
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Found ${results.length} execution(s) for cycle ${test_cycle_key}:\n${JSON.stringify({
+            cycleKey: test_cycle_key,
+            totalExecutions: results.length,
+            executions: results.map((r: any) => ({
+              id: r.id,
+              testCaseKey: r.testCaseKey,
+              status: r.status,
+              executedBy: r.executedBy,
+              executionDate: r.executionDate,
+              automated: r.automated,
+            })),
+          }, null, 2)}`,
+        }],
+      };
+    } catch (error) {
+      throw new McpError(ErrorCode.InternalError, `Failed to list executions: ${this.formatError(error)}`);
+    }
+  }
+
   private async resolveJiraIssueId(issueKey: string): Promise<number> {
     // The Zephyr API key is NOT valid for the Jira REST API — Jira Cloud requires
     // Basic Auth: base64(email:api_token) via JIRA_USERNAME + JIRA_API_TOKEN env vars.

package/src/tool-schemas.ts

@@ -351,7 +351,7 @@ export const toolSchemas = [
   },
   {
     name: 'search_test_runs',
-    description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path.',
+    description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path. On Cloud, only returns cycles in the exact folder (not sub-folders). Use folder_id for direct numeric ID lookup (skips path resolution).',
     inputSchema: {
       type: 'object',
       properties: {
@@ -361,7 +361,11 @@ export const toolSchemas = [
         },
         folder: {
           type: 'string',
-          description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder")',
+          description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder"). Resolved to a numeric folderId on Cloud.',
+        },
+        folder_id: {
+          type: 'number',
+          description: 'Numeric folder ID to filter test runs by (optional). If provided, takes precedence over folder path and skips path resolution. Use this when you already know the folder ID.',
         },
         max_results: {
           type: 'number',
@@ -375,6 +379,29 @@ export const toolSchemas = [
       },
     },
   },
+  {
+    name: 'list_executions_by_cycle',
+    description: 'List all test executions for a specific test cycle. Returns execution status, executedBy, actualEndDate for each test case in the cycle. Cloud only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        test_cycle_key: {
+          type: 'string',
+          description: 'Test cycle key (e.g., DDCN-R371)',
+        },
+        project_key: {
+          type: 'string',
+          description: 'Project key (required for Cloud)',
+        },
+        max_results: {
+          type: 'number',
+          description: 'Maximum number of results to return (optional, default 100)',
+          default: 100,
+        },
+      },
+      required: ['test_cycle_key', 'project_key'],
+    },
+  },
   {
     name: 'delete_test_run',
     description: 'Delete a specific test run (Data Center only — not supported on Cloud v2)',

package/src/types.ts

@@ -91,10 +91,17 @@ export interface GetTestExecutionArgs {
 export interface SearchTestRunsArgs {
   project_key?: string;
   folder?: string;
+  folder_id?: number;
   max_results?: number;
   fields?: string;
 }
 
+export interface ListExecutionsByCycleArgs {
+  test_cycle_key: string;
+  project_key: string;
+  max_results?: number;
+}
+
 export type JiraType = 'cloud' | 'datacenter';
 
 export interface ApiEndpoints {