zephyr-scale-mcp-server 0.4.3 → 0.4.4

package/build/tool-handlers.js

@@ -108,13 +108,19 @@ export class ZephyrToolHandlers {
         if (!test_script)
             return;
         if (test_script.type === 'STEP_BY_STEP' && test_script.steps && test_script.steps.length > 0) {
-            const items = test_script.steps.map((step) => ({
-                inline: {
-                    description: step.description || '',
-                    testData: step.testData || null,
-                    expectedResult: step.expectedResult || null,
-                },
-            }));
+            const items = test_script.steps.map((step) => {
+                // If step is a call-to-test (testCaseKey), use the testCase variant
+                if (step.testCaseKey) {
+                    return { testCase: { testCaseKey: step.testCaseKey } };
+                }
+                return {
+                    inline: {
+                        description: step.description || '',
+                        testData: step.testData || null,
+                        expectedResult: step.expectedResult || null,
+                    },
+                };
+            });
             await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testcase}/${testKey}/teststeps`, { mode: 'OVERWRITE', items });
         }
         else if (test_script.type === 'BDD' && test_script.text) {
@@ -213,15 +219,25 @@ export class ZephyrToolHandlers {
                 const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
                 const tc = getResponse.data;
                 // UpdateTestCaseInput requires: id, key, name, priority, project, status
-                // tc.project is a ProjectLink { id, self } — pass it back as-is
-                await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
+                // All optional fields must also be re-sent or the API will clear them
+                const putPayload = {
                     id: tc.id,
                     key: test_case_key,
                     name,
                     status: tc.status,
                     priority: tc.priority,
                     project: tc.project,
-                });
+                };
+                // Preserve all optional fields to avoid the API clearing them
+                for (const field of ['objective', 'precondition', 'estimatedTime', 'component', 'owner', 'folder']) {
+                    if (tc[field] !== undefined && tc[field] !== null)
+                        putPayload[field] = tc[field];
+                }
+                if (Array.isArray(tc.labels) && tc.labels.length > 0)
+                    putPayload.labels = tc.labels;
+                if (tc.customFields && Object.keys(tc.customFields).length > 0)
+                    putPayload.customFields = tc.customFields;
+                await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, putPayload);
             }
             return {
                 content: [{
@@ -454,9 +470,10 @@ export class ZephyrToolHandlers {
         return this.createTestRunDC(args);
     }
     async createTestRunCloud(args) {
-        const { project_key, name, test_case_keys, folder, planned_start_date, planned_end_date, description, owner, environment, custom_fields, } = args;
+        const { project_key, name, test_case_keys, folder, planned_start_date, planned_end_date, description, owner, environment, custom_fields, issue_links, issue_key, jira_project_version, } = args;
         // Cloud v2 TestCycleInput: projectKey, name, description, plannedStartDate,
-        // plannedEndDate, statusName, folderId, ownerId, customFields
+        // plannedEndDate, statusName, folderId, ownerId, jiraProjectVersion, customFields
+        // Note: environment is NOT a TestCycleInput field on Cloud — it belongs on TestExecutionInput
         const payload = { projectKey: project_key, name };
         if (description)
             payload.description = description;
@@ -469,6 +486,9 @@ export class ZephyrToolHandlers {
         // Cloud v2 TestCycleInput supports ownerId (Jira Account ID)
         if (owner)
             payload.ownerId = owner;
+        // Link to a Jira project version/release (integer ID)
+        if (jira_project_version)
+            payload.jiraProjectVersion = jira_project_version;
         if (folder) {
             const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CYCLE');
             if (folderId !== null)
@@ -483,14 +503,43 @@ export class ZephyrToolHandlers {
             // Step 2: add test cases via test executions (Cloud v2 has no /testcycles/{key}/testcases)
             if (test_case_keys && test_case_keys.length > 0) {
                 for (const testCaseKey of test_case_keys) {
-                    await this.axiosInstance.post('/testexecutions', {
+                    const execPayload = {
                         projectKey: project_key,
                         testCaseKey,
                         testCycleKey: cycleKey,
                         statusName: 'Not Executed',
-                    });
+                    };
+                    // environment is set at execution level on Cloud, not cycle level
+                    if (environment)
+                        execPayload.environmentName = environment;
+                    await this.axiosInstance.post('/testexecutions', execPayload);
+                }
+            }
+            // Step 3: link Jira issues via POST /testcycles/{key}/links/issues
+            // Merge issue_key (single) and issue_links (array) into one list
+            const allIssueLinks = [
+                ...(issue_key ? [issue_key] : []),
+                ...(issue_links ?? []),
+            ];
+            const linkWarnings = [];
+            if (allIssueLinks.length > 0) {
+                for (const ik of allIssueLinks) {
+                    try {
+                        const issueId = await this.resolveJiraIssueId(ik);
+                        await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testrun}/${cycleKey}/links/issues`, { issueId });
+                    }
+                    catch (e) {
+                        linkWarnings.push(`${ik}: ${this.formatError(e)}`);
+                    }
                 }
             }
+            const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+            const credHint = missingCreds && linkWarnings.length > 0
+                ? '\n💡 Tip: Set JIRA_USERNAME and JIRA_API_TOKEN env vars to enable issue linking on Cloud.'
+                : '';
+            const warningText = linkWarnings.length > 0
+                ? `\n⚠️ Some issue links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
+                : '';
             return {
                 content: [{
                         type: 'text',
@@ -498,7 +547,8 @@ export class ZephyrToolHandlers {
                             key: cycleKey,
                             name,
                             testCaseCount: test_case_keys?.length || 0,
-                        }, null, 2)}`,
+                            linkedIssues: allIssueLinks.length - linkWarnings.length,
+                        }, null, 2)}${warningText}`,
                     }],
             };
         }

package/build/tool-schemas.js

@@ -74,14 +74,12 @@ export const toolSchemas = [
                 },
                 status: {
                     type: 'string',
-                    description: 'Test case status (optional)',
-                    enum: ['Draft', 'Approved', 'Deprecated'],
+                    description: 'Test case status (optional, default: "Draft"). Value must match a status name configured in your Zephyr project (e.g. "Draft", "Approved", "Deprecated"). Note: always overridden to "Draft" on creation.',
                     default: 'Draft',
                 },
                 priority: {
                     type: 'string',
-                    description: 'Test case priority (optional)',
-                    enum: ['High', 'Normal', 'Low'],
+                    description: 'Test case priority (optional). Value must match a priority name configured in your Zephyr project (e.g. "High", "Normal", "Low", "Critical"). Use zephyr://testcase/EXISTING-KEY to check your project\'s valid values.',
                 },
                 precondition: {
                     type: 'string',
@@ -206,7 +204,7 @@ export const toolSchemas = [
             properties: {
                 test_run_key: {
                     type: 'string',
-                    description: 'Test run key (e.g., PROJ-C123)',
+                    description: 'Test run key (e.g., PROJ-R123)',
                 },
             },
             required: ['test_run_key'],
@@ -271,17 +269,21 @@ export const toolSchemas = [
                 },
                 environment: {
                     type: 'string',
-                    description: 'Test environment (optional)',
+                    description: 'Test environment name (optional). On Cloud, applied to each test execution (environmentName). On Data Center, set at cycle level.',
                 },
                 issue_key: {
                     type: 'string',
-                    description: 'Single issue key to link to the test run (optional) - will be mapped to issueKey in API',
+                    description: 'Single Jira issue key to link to the test cycle (e.g. "PROJ-123"). On Cloud, resolved to a numeric ID via Jira REST API — requires JIRA_USERNAME + JIRA_API_TOKEN env vars.',
                 },
                 issue_links: {
                     type: 'array',
-                    description: 'Array of issue links (optional) - will be mapped to issueLinks in API',
+                    description: 'Array of Jira issue keys to link to the test cycle (e.g. ["PROJ-123", "PROJ-456"]). On Cloud, each key is resolved to a numeric ID via Jira REST API — requires JIRA_USERNAME + JIRA_API_TOKEN env vars. Failures are reported as warnings and do not fail the tool call.',
                     items: { type: 'string' },
                 },
+                jira_project_version: {
+                    type: 'integer',
+                    description: 'Jira project version/release ID to link this test cycle to (optional, Cloud only — use the numeric version ID).',
+                },
                 custom_fields: {
                     type: 'object',
                     description: 'Custom fields object (optional)',
@@ -316,7 +318,7 @@ export const toolSchemas = [
                 },
                 test_run_keys: {
                     type: 'array',
-                    description: 'Array of test run keys to search in (required for Data Center, optional for Cloud — e.g., ["PROJ-C152", "PROJ-C161"])',
+                    description: 'Array of test run keys to search in (required for Data Center, optional for Cloud — e.g., ["PROJ-R152", "PROJ-R161"])',
                     items: { type: 'string' },
                     minItems: 1
                 },
@@ -395,7 +397,7 @@ export const toolSchemas = [
             properties: {
                 test_run_key: {
                     type: 'string',
-                    description: 'Test run key (e.g., PROJ-C161)',
+                    description: 'Test run key (e.g., PROJ-R161)',
                 },
                 test_case_keys: {
                     type: 'array',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.4.3",
+  "version": "0.4.4",
   "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/tool-handlers.ts

@@ -124,13 +124,19 @@ export class ZephyrToolHandlers {
     if (!test_script) return;
 
     if (test_script.type === 'STEP_BY_STEP' && test_script.steps && test_script.steps.length > 0) {
-      const items = test_script.steps.map((step: any) => ({
-        inline: {
-          description: step.description || '',
-          testData: step.testData || null,
-          expectedResult: step.expectedResult || null,
-        },
-      }));
+      const items = test_script.steps.map((step: any) => {
+        // If step is a call-to-test (testCaseKey), use the testCase variant
+        if (step.testCaseKey) {
+          return { testCase: { testCaseKey: step.testCaseKey } };
+        }
+        return {
+          inline: {
+            description: step.description || '',
+            testData: step.testData || null,
+            expectedResult: step.expectedResult || null,
+          },
+        };
+      });
       await this.axiosInstance.post(
         `${this.jiraConfig.apiEndpoints.testcase}/${testKey}/teststeps`,
         { mode: 'OVERWRITE', items }
@@ -234,15 +240,22 @@ export class ZephyrToolHandlers {
         const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
         const tc = getResponse.data;
         // UpdateTestCaseInput requires: id, key, name, priority, project, status
-        // tc.project is a ProjectLink { id, self } — pass it back as-is
-        await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
+        // All optional fields must also be re-sent or the API will clear them
+        const putPayload: any = {
           id: tc.id,
           key: test_case_key,
           name,
           status: tc.status,
           priority: tc.priority,
           project: tc.project,
-        });
+        };
+        // Preserve all optional fields to avoid the API clearing them
+        for (const field of ['objective', 'precondition', 'estimatedTime', 'component', 'owner', 'folder']) {
+          if (tc[field] !== undefined && tc[field] !== null) putPayload[field] = tc[field];
+        }
+        if (Array.isArray(tc.labels) && tc.labels.length > 0) putPayload.labels = tc.labels;
+        if (tc.customFields && Object.keys(tc.customFields).length > 0) putPayload.customFields = tc.customFields;
+        await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, putPayload);
       }
 
       return {
@@ -504,11 +517,13 @@ export class ZephyrToolHandlers {
     const {
       project_key, name, test_case_keys, folder,
       planned_start_date, planned_end_date, description,
-      owner, environment, custom_fields,
+      owner, environment, custom_fields, issue_links, issue_key,
+      jira_project_version,
     } = args;
 
     // Cloud v2 TestCycleInput: projectKey, name, description, plannedStartDate,
-    // plannedEndDate, statusName, folderId, ownerId, customFields
+    // plannedEndDate, statusName, folderId, ownerId, jiraProjectVersion, customFields
+    // Note: environment is NOT a TestCycleInput field on Cloud — it belongs on TestExecutionInput
     const payload: any = { projectKey: project_key, name };
 
     if (description) payload.description = description;
@@ -517,6 +532,8 @@ export class ZephyrToolHandlers {
     if (custom_fields) payload.customFields = custom_fields;
     // Cloud v2 TestCycleInput supports ownerId (Jira Account ID)
     if (owner) payload.ownerId = owner;
+    // Link to a Jira project version/release (integer ID)
+    if (jira_project_version) payload.jiraProjectVersion = jira_project_version;
     if (folder) {
       const folderId = await resolveFolderIdByPath(
         this.axiosInstance, project_key, folder, 'TEST_CYCLE'
@@ -535,15 +552,47 @@ export class ZephyrToolHandlers {
       // Step 2: add test cases via test executions (Cloud v2 has no /testcycles/{key}/testcases)
       if (test_case_keys && test_case_keys.length > 0) {
         for (const testCaseKey of test_case_keys) {
-          await this.axiosInstance.post('/testexecutions', {
+          const execPayload: any = {
             projectKey: project_key,
             testCaseKey,
             testCycleKey: cycleKey,
             statusName: 'Not Executed',
-          });
+          };
+          // environment is set at execution level on Cloud, not cycle level
+          if (environment) execPayload.environmentName = environment;
+          await this.axiosInstance.post('/testexecutions', execPayload);
+        }
+      }
+
+      // Step 3: link Jira issues via POST /testcycles/{key}/links/issues
+      // Merge issue_key (single) and issue_links (array) into one list
+      const allIssueLinks = [
+        ...(issue_key ? [issue_key] : []),
+        ...(issue_links ?? []),
+      ];
+      const linkWarnings: string[] = [];
+      if (allIssueLinks.length > 0) {
+        for (const ik of allIssueLinks) {
+          try {
+            const issueId = await this.resolveJiraIssueId(ik);
+            await this.axiosInstance.post(
+              `${this.jiraConfig.apiEndpoints.testrun}/${cycleKey}/links/issues`,
+              { issueId }
+            );
+          } catch (e) {
+            linkWarnings.push(`${ik}: ${this.formatError(e)}`);
+          }
         }
       }
 
+      const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+      const credHint = missingCreds && linkWarnings.length > 0
+        ? '\n💡 Tip: Set JIRA_USERNAME and JIRA_API_TOKEN env vars to enable issue linking on Cloud.'
+        : '';
+      const warningText = linkWarnings.length > 0
+        ? `\n⚠️ Some issue links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
+        : '';
+
       return {
         content: [{
           type: 'text',
@@ -551,7 +600,8 @@ export class ZephyrToolHandlers {
             key: cycleKey,
             name,
             testCaseCount: test_case_keys?.length || 0,
-          }, null, 2)}`,
+            linkedIssues: allIssueLinks.length - linkWarnings.length,
+          }, null, 2)}${warningText}`,
         }],
       };
     } catch (error) {

package/src/tool-schemas.ts

@@ -74,14 +74,12 @@ export const toolSchemas = [
         },
         status: {
           type: 'string',
-          description: 'Test case status (optional)',
-          enum: ['Draft', 'Approved', 'Deprecated'],
+          description: 'Test case status (optional, default: "Draft"). Value must match a status name configured in your Zephyr project (e.g. "Draft", "Approved", "Deprecated"). Note: always overridden to "Draft" on creation.',
           default: 'Draft',
         },
         priority: {
           type: 'string',
-          description: 'Test case priority (optional)',
-          enum: ['High', 'Normal', 'Low'],
+          description: 'Test case priority (optional). Value must match a priority name configured in your Zephyr project (e.g. "High", "Normal", "Low", "Critical"). Use zephyr://testcase/EXISTING-KEY to check your project\'s valid values.',
         },
         precondition: {
           type: 'string',
@@ -206,7 +204,7 @@ export const toolSchemas = [
       properties: {
         test_run_key: {
           type: 'string',
-          description: 'Test run key (e.g., PROJ-C123)',
+          description: 'Test run key (e.g., PROJ-R123)',
         },
       },
       required: ['test_run_key'],
@@ -271,17 +269,21 @@ export const toolSchemas = [
         },
         environment: {
           type: 'string',
-          description: 'Test environment (optional)',
+          description: 'Test environment name (optional). On Cloud, applied to each test execution (environmentName). On Data Center, set at cycle level.',
         },
         issue_key: {
           type: 'string',
-          description: 'Single issue key to link to the test run (optional) - will be mapped to issueKey in API',
+          description: 'Single Jira issue key to link to the test cycle (e.g. "PROJ-123"). On Cloud, resolved to a numeric ID via Jira REST API — requires JIRA_USERNAME + JIRA_API_TOKEN env vars.',
         },
         issue_links: {
           type: 'array',
-          description: 'Array of issue links (optional) - will be mapped to issueLinks in API',
+          description: 'Array of Jira issue keys to link to the test cycle (e.g. ["PROJ-123", "PROJ-456"]). On Cloud, each key is resolved to a numeric ID via Jira REST API — requires JIRA_USERNAME + JIRA_API_TOKEN env vars. Failures are reported as warnings and do not fail the tool call.',
           items: { type: 'string' },
         },
+        jira_project_version: {
+          type: 'integer',
+          description: 'Jira project version/release ID to link this test cycle to (optional, Cloud only — use the numeric version ID).',
+        },
         custom_fields: {
           type: 'object',
           description: 'Custom fields object (optional)',
@@ -316,7 +318,7 @@ export const toolSchemas = [
         },
         test_run_keys: {
           type: 'array',
-          description: 'Array of test run keys to search in (required for Data Center, optional for Cloud — e.g., ["PROJ-C152", "PROJ-C161"])',
+          description: 'Array of test run keys to search in (required for Data Center, optional for Cloud — e.g., ["PROJ-R152", "PROJ-R161"])',
           items: { type: 'string' },
           minItems: 1
         },
@@ -395,7 +397,7 @@ export const toolSchemas = [
       properties: {
         test_run_key: {
           type: 'string',
-          description: 'Test run key (e.g., PROJ-C161)',
+          description: 'Test run key (e.g., PROJ-R161)',
         },
         test_case_keys: {
           type: 'array',

package/src/types.ts

@@ -64,7 +64,8 @@ export interface TestRunArgs {
   planned_end_date?: string;
   description?: string;
   owner?: string;
-  environment?: string;
+  environment?: string;        // Cloud: mapped to environmentName on each TestExecutionInput; DC: cycle-level field
+  jira_project_version?: number; // Cloud only: Jira project version/release ID (integer)
   issue_key?: string;
   issue_links?: string[];
   custom_fields?: Record<string, any>;