zephyr-scale-mcp-server 0.3.3 → 0.4.1

package/README.md

@@ -142,6 +142,20 @@ The server provides access to various resources through URI schemes:
 - `ZEPHYR_BASE_URL`: `https://your-company.atlassian.net`
 - `ZEPHYR_API_KEY`: Your Zephyr Scale API key (JWT). Generate it in Jira by clicking your profile picture (bottom left) → **Zephyr API keys**.
 
+### Jira Cloud – regional API endpoint (optional)
+Zephyr Scale Cloud has regional API hosts. By default the server uses the **US** endpoint (`https://api.zephyrscale.smartbear.com/v2`). If your instance uses the **EU** API (e.g. for EU data residency), set:
+- **`ZEPHYR_API_BASE_URL`**: Full base URL for the Zephyr Scale Cloud API (no trailing slash).
+
+**Example – EU:**
+```json
+"env": {
+  "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
+  "ZEPHYR_API_KEY": "your-zephyr-api-token",
+  "ZEPHYR_API_BASE_URL": "https://eu.api.zephyrscale.smartbear.com/v2"
+}
+```
+If `ZEPHYR_API_BASE_URL` is not set, the US URL is used. Omit this variable for US instances.
+
 ### Jira Data Center Configuration
 - `ZEPHYR_BASE_URL`: `https://your-jira-server.com`
 - `ZEPHYR_API_KEY`: Your Zephyr Scale API token from your Jira profile settings.

package/build/tool-handlers.js

@@ -20,6 +20,14 @@ export class ZephyrToolHandlers {
         }
     }
     async createTestCase(args) {
+        // Some MCP clients (e.g. Claude Code) pass nested object parameters as JSON strings.
+        // Parse test_script if it arrived as a string.
+        if (typeof args.test_script === 'string') {
+            try {
+                args.test_script = JSON.parse(args.test_script);
+            }
+            catch { }
+        }
         if (this.jiraConfig.type === 'cloud') {
             return this.createTestCaseCloud(args);
         }
@@ -169,40 +177,22 @@ export class ZephyrToolHandlers {
     }
     async updateTestCaseBddCloud(args) {
         const { test_case_key, bdd_content, name } = args;
+        const converted = convertToGherkin(bdd_content);
+        const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
         try {
-            // Step 1: GET existing test case to extract required fields for PUT
-            const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
-            const tc = getResponse.data;
-            // Cloud v2 PUT requires: id, key, name, project, priority, status
-            const requiredFields = ['id', 'key', 'name', 'project', 'priority', 'status'];
-            for (const field of requiredFields) {
-                if (tc[field] === undefined || tc[field] === null) {
-                    throw new McpError(ErrorCode.InternalError, `Existing test case is missing required field '${field}' needed for Cloud v2 update.`);
-                }
-            }
-            const putPayload = {
-                id: tc.id,
-                key: tc.key,
-                name: typeof name === 'string' && name.trim().length > 0 ? name : tc.name,
-                project: tc.project,
-                priority: tc.priority,
-                status: tc.status,
-            };
-            // Preserve optional fields
-            for (const field of ['objective', 'precondition', 'estimatedTime', 'folder', 'component', 'owner']) {
-                if (tc[field] !== undefined)
-                    putPayload[field] = tc[field];
-            }
-            if (Array.isArray(tc.labels))
-                putPayload.labels = tc.labels;
-            if (tc.customFields)
-                putPayload.customFields = tc.customFields;
-            // Step 2: PUT to update metadata
-            await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, putPayload);
-            // Step 3: POST testscript with BDD content
-            const converted = convertToGherkin(bdd_content);
-            const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
             await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}/testscript`, { type: 'bdd', text: finalText });
+            // Only fetch and PUT metadata when the caller also wants to rename the test case
+            if (typeof name === 'string' && name.trim().length > 0) {
+                const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
+                const tc = getResponse.data;
+                const projectKey = tc.projectKey ?? test_case_key.replace(/-T\d+$/, '');
+                await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
+                    projectKey,
+                    name,
+                    status: tc.status,
+                    priority: tc.priority,
+                });
+            }
             return {
                 content: [{
                         type: 'text',
@@ -224,8 +214,9 @@ export class ZephyrToolHandlers {
             const converted = convertToGherkin(bdd_content);
             const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
             const payload = {};
+            const projectKey = testCaseData.projectKey ?? test_case_key.replace(/-T\d+$/, '');
             const requiredFields = [
-                ['projectKey', testCaseData.projectKey],
+                ['projectKey', projectKey],
                 ['name', testCaseData.name],
                 ['status', testCaseData.status],
                 ['priority', testCaseData.priority]
@@ -458,9 +449,16 @@ export class ZephyrToolHandlers {
             if (response.status !== 201)
                 throw new Error(`Unexpected status code: ${response.status}`);
             const cycleKey = response.data.key || 'Unknown';
-            // Step 2: add test cases to the cycle
+            // Step 2: add test cases via test executions (Cloud v2 has no /testcycles/{key}/testcases)
             if (test_case_keys && test_case_keys.length > 0) {
-                await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testrun}/${cycleKey}/testcases`, { items: test_case_keys.map((k) => ({ testCaseKey: k })) });
+                for (const testCaseKey of test_case_keys) {
+                    await this.axiosInstance.post('/testexecutions', {
+                        projectKey: project_key,
+                        testCaseKey,
+                        testCycleKey: cycleKey,
+                        statusName: 'Not Executed',
+                    });
+                }
             }
             return {
                 content: [{
@@ -734,24 +732,24 @@ export class ZephyrToolHandlers {
             throw new McpError(ErrorCode.InvalidRequest, 'add_test_cases_to_run is only supported on Zephyr Scale Cloud. The Data Center API (v1) does not provide an endpoint to modify test runs after creation.');
         }
         const { test_run_key, test_case_keys } = args;
+        // Derive project key from the test run key (e.g. PROJ-R123 → PROJ)
+        const project_key = test_run_key.split('-')[0];
         try {
-            const payload = {
-                items: test_case_keys.map(key => ({ testCaseKey: key }))
-            };
-            const response = await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}/testcases`, payload);
-            if (response.status === 200 || response.status === 201 || response.status === 204) {
-                return {
-                    content: [{ type: 'text', text: `Added ${test_case_keys.length} test case(s) to test run ${test_run_key}.` }],
-                };
+            for (const testCaseKey of test_case_keys) {
+                await this.axiosInstance.post('/testexecutions', {
+                    projectKey: project_key,
+                    testCaseKey,
+                    testCycleKey: test_run_key,
+                    statusName: 'Not Executed',
+                });
             }
+            return {
+                content: [{ type: 'text', text: `Added ${test_case_keys.length} test case(s) to test run ${test_run_key}.` }],
+            };
         }
         catch (error) {
             throw new McpError(ErrorCode.InternalError, `Failed to add test cases: ${this.formatError(error)}`);
         }
-        return {
-            content: [{ type: 'text', text: 'An unexpected error occurred.' }],
-            isError: true,
-        };
     }
     formatError(error) {
         if (error instanceof Error && 'response' in error) {

package/build/utils.js

@@ -30,28 +30,48 @@ export async function resolveFolderIdByPath(axiosInstance, projectKey, folderPat
 export function convertToGherkin(bddContent) {
     const bddLines = [];
     const lines = bddContent.split('\n');
+    // Bold-markdown step keywords (e.g. **Given**, **When**, etc.)
+    const boldStepKeywords = ['Given', 'When', 'Then', 'And', 'But'];
+    // Plain step keyword prefixes
+    const stepKeywords = ['Given ', 'When ', 'Then ', 'And ', 'But '];
+    // Zephyr Scale Cloud only accepts steps and table rows — Feature:/Scenario: wrappers
+    // cause a 400 "Invalid Gherkin script" error and must be stripped.
+    const strippedPrefixes = [
+        'Feature:',
+        'Background:',
+        'Scenario Outline:',
+        'Scenario:',
+        'Examples:',
+    ];
     for (const line of lines) {
         const trimmedLine = line.trim();
         if (!trimmedLine || trimmedLine.startsWith('---'))
             continue;
-        if (trimmedLine.startsWith('**Given**')) {
-            bddLines.push(`Given ${trimmedLine.replace('**Given**', '').trim()}`);
-        }
-        else if (trimmedLine.startsWith('**When**')) {
-            bddLines.push(`When ${trimmedLine.replace('**When**', '').trim()}`);
-        }
-        else if (trimmedLine.startsWith('**Then**')) {
-            bddLines.push(`Then ${trimmedLine.replace('**Then**', '').trim()}`);
+        // Strip structural Gherkin keywords — not accepted by the Zephyr Scale Cloud testscript API
+        if (strippedPrefixes.some(p => trimmedLine.startsWith(p)))
+            continue;
+        // Convert **Keyword** markdown bold to plain Gherkin keyword
+        let matchedBold = false;
+        for (const kw of boldStepKeywords) {
+            if (trimmedLine.startsWith(`**${kw}**`)) {
+                bddLines.push(`${kw} ${trimmedLine.replace(`**${kw}**`, '').trim()}`);
+                matchedBold = true;
+                break;
+            }
         }
-        else if (trimmedLine.startsWith('**And**')) {
-            bddLines.push(`And ${trimmedLine.replace('**And**', '').trim()}`);
+        if (matchedBold)
+            continue;
+        // Plain step keywords — pass through unchanged
+        if (stepKeywords.some(k => trimmedLine.startsWith(k))) {
+            bddLines.push(trimmedLine);
+            continue;
         }
-        else if (trimmedLine.startsWith('Given ') || trimmedLine.startsWith('When ') ||
-            trimmedLine.startsWith('Then ') || trimmedLine.startsWith('And ')) {
+        // Table rows — pass through unchanged
+        if (trimmedLine.startsWith('|')) {
             bddLines.push(trimmedLine);
         }
     }
-    return bddLines.length > 0 ? '    ' + bddLines.join('\n    ') : '';
+    return bddLines.join('\n');
 }
 export const customPriorityMapping = {
     'High': 'P0',
@@ -111,8 +131,11 @@ export function createJiraConfig() {
     }
     const type = detectJiraType(jiraBaseUrl);
     const apiEndpoints = getApiEndpoints(type);
+    // Cloud: use ZEPHYR_API_BASE_URL if set (e.g. for EU: https://eu.api.zephyrscale.smartbear.com/v2), else default US
+    const defaultCloudBaseUrl = 'https://api.zephyrscale.smartbear.com/v2';
+    const cloudBaseUrl = process.env.ZEPHYR_API_BASE_URL?.trim();
     const baseUrl = type === 'cloud'
-        ? 'https://api.zephyrscale.smartbear.com/v2'
+        ? (cloudBaseUrl || defaultCloudBaseUrl)
         : jiraBaseUrl;
     const authHeaders = {
         'Authorization': `Bearer ${apiKey}`,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.3.3",
+  "version": "0.4.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",
@@ -57,7 +57,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "0.6.0",
-    "axios": "^1.10.0"
+    "axios": "^1.15.0"
   },
   "devDependencies": {
     "@types/node": "^20.11.24",

package/src/tool-handlers.ts

@@ -32,6 +32,11 @@ export class ZephyrToolHandlers {
   }
 
   async createTestCase(args: TestCaseArgs) {
+    // Some MCP clients (e.g. Claude Code) pass nested object parameters as JSON strings.
+    // Parse test_script if it arrived as a string.
+    if (typeof (args as any).test_script === 'string') {
+      try { (args as any).test_script = JSON.parse((args as any).test_script); } catch {}
+    }
     if (this.jiraConfig.type === 'cloud') {
       return this.createTestCaseCloud(args);
     }
@@ -185,47 +190,28 @@ export class ZephyrToolHandlers {
   private async updateTestCaseBddCloud(args: UpdateBddArgs) {
     const { test_case_key, bdd_content, name } = args;
 
-    try {
-      // Step 1: GET existing test case to extract required fields for PUT
-      const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
-      const tc = getResponse.data;
-
-      // Cloud v2 PUT requires: id, key, name, project, priority, status
-      const requiredFields = ['id', 'key', 'name', 'project', 'priority', 'status'];
-      for (const field of requiredFields) {
-        if (tc[field] === undefined || tc[field] === null) {
-          throw new McpError(ErrorCode.InternalError,
-            `Existing test case is missing required field '${field}' needed for Cloud v2 update.`);
-        }
-      }
-
-      const putPayload: any = {
-        id: tc.id,
-        key: tc.key,
-        name: typeof name === 'string' && name.trim().length > 0 ? name : tc.name,
-        project: tc.project,
-        priority: tc.priority,
-        status: tc.status,
-      };
-
-      // Preserve optional fields
-      for (const field of ['objective', 'precondition', 'estimatedTime', 'folder', 'component', 'owner']) {
-        if (tc[field] !== undefined) putPayload[field] = tc[field];
-      }
-      if (Array.isArray(tc.labels)) putPayload.labels = tc.labels;
-      if (tc.customFields) putPayload.customFields = tc.customFields;
-
-      // Step 2: PUT to update metadata
-      await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, putPayload);
+    const converted = convertToGherkin(bdd_content);
+    const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
 
-      // Step 3: POST testscript with BDD content
-      const converted = convertToGherkin(bdd_content);
-      const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
+    try {
       await this.axiosInstance.post(
         `${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}/testscript`,
         { type: 'bdd', text: finalText }
       );
 
+      // Only fetch and PUT metadata when the caller also wants to rename the test case
+      if (typeof name === 'string' && name.trim().length > 0) {
+        const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
+        const tc = getResponse.data;
+        const projectKey = tc.projectKey ?? test_case_key.replace(/-T\d+$/, '');
+        await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
+          projectKey,
+          name,
+          status: tc.status,
+          priority: tc.priority,
+        });
+      }
+
       return {
         content: [{
           type: 'text',
@@ -249,8 +235,9 @@ export class ZephyrToolHandlers {
       const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
 
       const payload: any = {};
+      const projectKey = testCaseData.projectKey ?? test_case_key.replace(/-T\d+$/, '');
       const requiredFields: Array<[string, any]> = [
-        ['projectKey', testCaseData.projectKey],
+        ['projectKey', projectKey],
         ['name', testCaseData.name],
         ['status', testCaseData.status],
         ['priority', testCaseData.priority]
@@ -513,12 +500,16 @@ export class ZephyrToolHandlers {
 
       const cycleKey = response.data.key || 'Unknown';
 
-      // Step 2: add test cases to the cycle
+      // Step 2: add test cases via test executions (Cloud v2 has no /testcycles/{key}/testcases)
       if (test_case_keys && test_case_keys.length > 0) {
-        await this.axiosInstance.post(
-          `${this.jiraConfig.apiEndpoints.testrun}/${cycleKey}/testcases`,
-          { items: test_case_keys.map((k: string) => ({ testCaseKey: k })) }
-        );
+        for (const testCaseKey of test_case_keys) {
+          await this.axiosInstance.post('/testexecutions', {
+            projectKey: project_key,
+            testCaseKey,
+            testCycleKey: cycleKey,
+            statusName: 'Not Executed',
+          });
+        }
       }
 
       return {
@@ -813,28 +804,24 @@ export class ZephyrToolHandlers {
 
     const { test_run_key, test_case_keys } = args;
 
-    try {
-      const payload = {
-        items: test_case_keys.map(key => ({ testCaseKey: key }))
-      };
-      const response = await this.axiosInstance.post(
-        `${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}/testcases`,
-        payload
-      );
+    // Derive project key from the test run key (e.g. PROJ-R123 → PROJ)
+    const project_key = test_run_key.split('-')[0];
 
-      if (response.status === 200 || response.status === 201 || response.status === 204) {
-        return {
-          content: [{ type: 'text', text: `Added ${test_case_keys.length} test case(s) to test run ${test_run_key}.` }],
-        };
+    try {
+      for (const testCaseKey of test_case_keys) {
+        await this.axiosInstance.post('/testexecutions', {
+          projectKey: project_key,
+          testCaseKey,
+          testCycleKey: test_run_key,
+          statusName: 'Not Executed',
+        });
       }
+      return {
+        content: [{ type: 'text', text: `Added ${test_case_keys.length} test case(s) to test run ${test_run_key}.` }],
+      };
     } catch (error) {
       throw new McpError(ErrorCode.InternalError, `Failed to add test cases: ${this.formatError(error)}`);
     }
-
-    return {
-      content: [{ type: 'text', text: 'An unexpected error occurred.' }],
-      isError: true,
-    };
   }
 
   private formatError(error: unknown): string {

package/src/utils.ts

@@ -43,28 +43,53 @@ export async function resolveFolderIdByPath(
 export function convertToGherkin(bddContent: string): string {
   const bddLines: string[] = [];
   const lines = bddContent.split('\n');
-  
+
+  // Bold-markdown step keywords (e.g. **Given**, **When**, etc.)
+  const boldStepKeywords = ['Given', 'When', 'Then', 'And', 'But'];
+  // Plain step keyword prefixes
+  const stepKeywords = ['Given ', 'When ', 'Then ', 'And ', 'But '];
+  // Zephyr Scale Cloud only accepts steps and table rows — Feature:/Scenario: wrappers
+  // cause a 400 "Invalid Gherkin script" error and must be stripped.
+  const strippedPrefixes = [
+    'Feature:',
+    'Background:',
+    'Scenario Outline:',
+    'Scenario:',
+    'Examples:',
+  ];
+
   for (const line of lines) {
     const trimmedLine = line.trim();
     if (!trimmedLine || trimmedLine.startsWith('---')) continue;
-    
-    if (trimmedLine.startsWith('**Given**')) {
-      bddLines.push(`Given ${trimmedLine.replace('**Given**', '').trim()}`);
-    } else if (trimmedLine.startsWith('**When**')) {
-      bddLines.push(`When ${trimmedLine.replace('**When**', '').trim()}`);
-    } else if (trimmedLine.startsWith('**Then**')) {
-      bddLines.push(`Then ${trimmedLine.replace('**Then**', '').trim()}`);
-    } else if (trimmedLine.startsWith('**And**')) {
-      bddLines.push(`And ${trimmedLine.replace('**And**', '').trim()}`);
-    } else if (trimmedLine.startsWith('Given ') || trimmedLine.startsWith('When ') || 
-               trimmedLine.startsWith('Then ') || trimmedLine.startsWith('And ')) {
+
+    // Strip structural Gherkin keywords — not accepted by the Zephyr Scale Cloud testscript API
+    if (strippedPrefixes.some(p => trimmedLine.startsWith(p))) continue;
+
+    // Convert **Keyword** markdown bold to plain Gherkin keyword
+    let matchedBold = false;
+    for (const kw of boldStepKeywords) {
+      if (trimmedLine.startsWith(`**${kw}**`)) {
+        bddLines.push(`${kw} ${trimmedLine.replace(`**${kw}**`, '').trim()}`);
+        matchedBold = true;
+        break;
+      }
+    }
+    if (matchedBold) continue;
+
+    // Plain step keywords — pass through unchanged
+    if (stepKeywords.some(k => trimmedLine.startsWith(k))) {
+      bddLines.push(trimmedLine);
+      continue;
+    }
+
+    // Table rows — pass through unchanged
+    if (trimmedLine.startsWith('|')) {
       bddLines.push(trimmedLine);
     }
   }
-  
-  return bddLines.length > 0 ? '    ' + bddLines.join('\n    ') : '';
-}
 
+  return bddLines.join('\n');
+}
 export const customPriorityMapping: { [key: string]: string } = {
   'High': 'P0',
   'Normal': 'P1',
@@ -128,9 +153,12 @@ export function createJiraConfig() {
 
   const type = detectJiraType(jiraBaseUrl);
   const apiEndpoints = getApiEndpoints(type);
-  
-  const baseUrl = type === 'cloud' 
-    ? 'https://api.zephyrscale.smartbear.com/v2' 
+
+  // Cloud: use ZEPHYR_API_BASE_URL if set (e.g. for EU: https://eu.api.zephyrscale.smartbear.com/v2), else default US
+  const defaultCloudBaseUrl = 'https://api.zephyrscale.smartbear.com/v2';
+  const cloudBaseUrl = process.env.ZEPHYR_API_BASE_URL?.trim();
+  const baseUrl = type === 'cloud'
+    ? (cloudBaseUrl || defaultCloudBaseUrl)
     : jiraBaseUrl;
 
   const authHeaders = {