zephyr-scale-mcp-server 0.2.8 → 0.3.0

package/build/index.js

@@ -14,7 +14,7 @@ class ZephyrServer {
         const jiraConfig = createJiraConfig();
         this.server = new Server({
             name: 'zephyr-server',
-            version: '0.2.0',
+            version: '0.3.0',
         }, {
             capabilities: {
                 tools: {},
@@ -63,6 +63,8 @@ class ZephyrServer {
                         return await this.toolHandlers.getTestExecution(args);
                     case 'search_test_cases_by_folder':
                         return await this.toolHandlers.searchTestCasesByFolder(args);
+                    case 'search_test_runs':
+                        return await this.toolHandlers.searchTestRuns(args);
                     case 'add_test_cases_to_run':
                         return await this.toolHandlers.addTestCasesToRun(args);
                     default:

package/build/tool-handlers.js

@@ -274,7 +274,7 @@ export class ZephyrToolHandlers {
         }
     }
     async createTestRun(args) {
-        const { project_key, name, test_case_keys, test_plan_key, folder, planned_start_date, planned_end_date, description, owner, environment, custom_fields } = args;
+        const { project_key, name, test_case_keys, test_plan_key, folder, planned_start_date, planned_end_date, description, owner, environment, issue_key, issue_links, custom_fields } = args;
         // Build the basic payload
         const payload = {
             projectKey: project_key,
@@ -298,6 +298,10 @@ export class ZephyrToolHandlers {
             payload.owner = owner;
         if (environment)
             payload.environment = environment;
+        if (issue_key)
+            payload.issueKey = issue_key;
+        if (issue_links && issue_links.length > 0)
+            payload.issueLinks = issue_links;
         if (custom_fields)
             payload.customFields = custom_fields;
         if (test_plan_key)
@@ -486,6 +490,71 @@ export class ZephyrToolHandlers {
             throw new McpError(ErrorCode.InternalError, `Failed to search test cases by folder: ${errorMessage}`);
         }
     }
+    async searchTestRuns(args) {
+        const { project_key, folder, max_results = 200, fields } = args;
+        // Build query string per Zephyr Scale API docs
+        const queryParts = [];
+        if (project_key)
+            queryParts.push(`projectKey = "${project_key}"`);
+        if (folder)
+            queryParts.push(`folder = "${folder}"`);
+        if (queryParts.length === 0) {
+            throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key or folder must be provided.');
+        }
+        const query = queryParts.join(' AND ');
+        const params = { query, maxResults: max_results };
+        if (fields)
+            params.fields = fields;
+        const searchEndpoint = this.jiraConfig.type === 'cloud'
+            ? '/testruns/search'
+            : '/rest/atm/1.0/testrun/search';
+        try {
+            const response = await this.axiosInstance.get(searchEndpoint, { params });
+            let testRuns = [];
+            if (Array.isArray(response.data)) {
+                testRuns = response.data;
+            }
+            else if (response.data.values && Array.isArray(response.data.values)) {
+                testRuns = response.data.values;
+            }
+            else if (response.data.results && Array.isArray(response.data.results)) {
+                testRuns = response.data.results;
+            }
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: `✅ Found ${testRuns.length} test run(s) matching query "${query}":\n${JSON.stringify({
+                            query,
+                            totalCount: testRuns.length,
+                            testRuns: testRuns.map((tr) => ({
+                                key: tr.key,
+                                name: tr.name,
+                                status: tr.status,
+                                folder: tr.folder,
+                                testCaseCount: tr.testCaseCount,
+                                issueKey: tr.issueKey,
+                            }))
+                        }, null, 2)}`,
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            let errorMessage = 'Unknown error';
+            if (error instanceof Error && 'response' in error) {
+                const axiosError = error;
+                errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
+            }
+            else if (error instanceof Error) {
+                errorMessage = error.message;
+            }
+            else {
+                errorMessage = String(error);
+            }
+            throw new McpError(ErrorCode.InternalError, `Failed to search test runs: ${errorMessage}`);
+        }
+    }
     async addTestCasesToRun(args) {
         const { test_run_key, test_case_keys } = args;
         try {

package/build/tool-schemas.js

@@ -273,6 +273,15 @@ export const toolSchemas = [
                     type: 'string',
                     description: 'Test environment (optional)',
                 },
+                issue_key: {
+                    type: 'string',
+                    description: 'Single issue key to link to the test run (optional) - will be mapped to issueKey in API',
+                },
+                issue_links: {
+                    type: 'array',
+                    description: 'Array of issue links (optional) - will be mapped to issueLinks in API',
+                    items: { type: 'string' },
+                },
                 custom_fields: {
                     type: 'object',
                     description: 'Custom fields object (optional)',
@@ -338,6 +347,32 @@ export const toolSchemas = [
             required: ['project_key', 'folder_path'],
         },
     },
+    {
+        name: 'search_test_runs',
+        description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_key: {
+                    type: 'string',
+                    description: 'Project key to filter by (e.g., "PROJ"). Can be a single key or omitted if using folder only.',
+                },
+                folder: {
+                    type: 'string',
+                    description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder")',
+                },
+                max_results: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (optional, default 200)',
+                    default: 200,
+                },
+                fields: {
+                    type: 'string',
+                    description: 'Comma-separated list of fields to include in the response (optional, e.g., "key,name,status,folder"). If not set, all fields are returned.',
+                },
+            },
+        },
+    },
     {
         name: 'add_test_cases_to_run',
         description: 'Add test cases to an existing test run',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.2.8",
+  "version": "0.3.0",
   "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

@@ -25,7 +25,7 @@ class ZephyrServer {
     this.server = new Server(
       {
         name: 'zephyr-server',
-        version: '0.2.0',
+        version: '0.3.0',
       },
       {
         capabilities: {
@@ -83,6 +83,8 @@ class ZephyrServer {
             return await this.toolHandlers.getTestExecution(args);
           case 'search_test_cases_by_folder':
             return await this.toolHandlers.searchTestCasesByFolder(args as any);
+          case 'search_test_runs':
+            return await this.toolHandlers.searchTestRuns(args as any);
           case 'add_test_cases_to_run':
             return await this.toolHandlers.addTestCasesToRun(args as any);
           default:

package/src/tool-handlers.ts

@@ -7,6 +7,7 @@ import {
   TestRunArgs,
   SearchTestCasesArgs,
   AddTestCasesToRunArgs,
+  SearchTestRunsArgs,
   JiraConfig
 } from './types.js';
 import { convertToGherkin, customPriorityMapping, priorityMapping } from './utils.js';
@@ -312,6 +313,8 @@ export class ZephyrToolHandlers {
       description,
       owner,
       environment,
+      issue_key,
+      issue_links,
       custom_fields
     } = args;
 
@@ -333,6 +336,8 @@ export class ZephyrToolHandlers {
     if (description) payload.description = description;
     if (owner) payload.owner = owner;
     if (environment) payload.environment = environment;
+    if (issue_key) payload.issueKey = issue_key;
+    if (issue_links && issue_links.length > 0) payload.issueLinks = issue_links;
     if (custom_fields) payload.customFields = custom_fields;
     if (test_plan_key) payload.testPlanKey = test_plan_key;
 
@@ -538,6 +543,71 @@ export class ZephyrToolHandlers {
     }
   }
 
+  async searchTestRuns(args: SearchTestRunsArgs) {
+    const { project_key, folder, max_results = 200, fields } = args;
+
+    // Build query string per Zephyr Scale API docs
+    const queryParts: string[] = [];
+    if (project_key) queryParts.push(`projectKey = "${project_key}"`);
+    if (folder) queryParts.push(`folder = "${folder}"`);
+
+    if (queryParts.length === 0) {
+      throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key or folder must be provided.');
+    }
+
+    const query = queryParts.join(' AND ');
+    const params: Record<string, any> = { query, maxResults: max_results };
+    if (fields) params.fields = fields;
+
+    const searchEndpoint = this.jiraConfig.type === 'cloud'
+      ? '/testruns/search'
+      : '/rest/atm/1.0/testrun/search';
+
+    try {
+      const response = await this.axiosInstance.get(searchEndpoint, { params });
+
+      let testRuns: any[] = [];
+      if (Array.isArray(response.data)) {
+        testRuns = response.data;
+      } else if (response.data.values && Array.isArray(response.data.values)) {
+        testRuns = response.data.values;
+      } else if (response.data.results && Array.isArray(response.data.results)) {
+        testRuns = response.data.results;
+      }
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `✅ Found ${testRuns.length} test run(s) matching query "${query}":\n${JSON.stringify({
+              query,
+              totalCount: testRuns.length,
+              testRuns: testRuns.map((tr: any) => ({
+                key: tr.key,
+                name: tr.name,
+                status: tr.status,
+                folder: tr.folder,
+                testCaseCount: tr.testCaseCount,
+                issueKey: tr.issueKey,
+              }))
+            }, null, 2)}`,
+          },
+        ],
+      };
+    } catch (error) {
+      let errorMessage = 'Unknown error';
+      if (error instanceof Error && 'response' in error) {
+        const axiosError = error as any;
+        errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
+      } else if (error instanceof Error) {
+        errorMessage = error.message;
+      } else {
+        errorMessage = String(error);
+      }
+      throw new McpError(ErrorCode.InternalError, `Failed to search test runs: ${errorMessage}`);
+    }
+  }
+
   async addTestCasesToRun(args: AddTestCasesToRunArgs) {
     const { test_run_key, test_case_keys } = args;
 

package/src/tool-schemas.ts

@@ -273,6 +273,15 @@ export const toolSchemas = [
           type: 'string',
           description: 'Test environment (optional)',
         },
+        issue_key: {
+          type: 'string',
+          description: 'Single issue key to link to the test run (optional) - will be mapped to issueKey in API',
+        },
+        issue_links: {
+          type: 'array',
+          description: 'Array of issue links (optional) - will be mapped to issueLinks in API',
+          items: { type: 'string' },
+        },
         custom_fields: {
           type: 'object',
           description: 'Custom fields object (optional)',
@@ -338,6 +347,32 @@ export const toolSchemas = [
       required: ['project_key', 'folder_path'],
     },
   },
+  {
+    name: 'search_test_runs',
+    description: 'Search for test runs using a query. Supports filtering by projectKey and/or folder path.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_key: {
+          type: 'string',
+          description: 'Project key to filter by (e.g., "PROJ"). Can be a single key or omitted if using folder only.',
+        },
+        folder: {
+          type: 'string',
+          description: 'Folder path to filter test runs by (e.g., "/MyFolder/SubFolder")',
+        },
+        max_results: {
+          type: 'number',
+          description: 'Maximum number of results to return (optional, default 200)',
+          default: 200,
+        },
+        fields: {
+          type: 'string',
+          description: 'Comma-separated list of fields to include in the response (optional, e.g., "key,name,status,folder"). If not set, all fields are returned.',
+        },
+      },
+    },
+  },
   {
     name: 'add_test_cases_to_run',
     description: 'Add test cases to an existing test run',

package/src/types.ts

@@ -63,6 +63,8 @@ export interface TestRunArgs {
   description?: string;
   owner?: string;
   environment?: string;
+  issue_key?: string;
+  issue_links?: string[];
   custom_fields?: Record<string, any>;
 }
 
@@ -77,6 +79,13 @@ export interface AddTestCasesToRunArgs {
   test_case_keys: string[];
 }
 
+export interface SearchTestRunsArgs {
+  project_key?: string;
+  folder?: string;
+  max_results?: number;
+  fields?: string;
+}
+
 export type JiraType = 'cloud' | 'datacenter';
 
 export interface ApiEndpoints {