zephyr-scale-mcp-server 0.4.0 → 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]

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.4.0",
+  "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]

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 = {