zephyr-scale-mcp-server 0.4.2 → 0.4.3

package/README.md

@@ -27,7 +27,29 @@ Configure your MCP client with the following structure.
       "args": ["zephyr-scale-mcp-server@latest"],
       "env": {
         "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
-        "ZEPHYR_API_KEY": "your-zephyr-api-key"
+        "ZEPHYR_API_KEY": "your-zephyr-api-key",
+        "JIRA_USERNAME": "your-email@company.com",
+        "JIRA_API_TOKEN": "your-jira-api-token"
+      }
+    }
+  }
+}
+```
+> **Note**: `JIRA_USERNAME` and `JIRA_API_TOKEN` are optional but required if you want to use the `issue_links` field when creating test cases. Without them, issue linking will fail with a 401 warning (the test case is still created). Generate a Jira API token at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens).
+
+**Jira Cloud (EU region):**
+```json
+{
+  "mcpServers": {
+    "zephyr-server": {
+      "command": "npx",
+      "args": ["zephyr-scale-mcp-server@latest"],
+      "env": {
+        "ZEPHYR_BASE_URL": "https://your-company.atlassian.net",
+        "ZEPHYR_API_KEY": "your-zephyr-api-key",
+        "JIRA_USERNAME": "your-email@company.com",
+        "JIRA_API_TOKEN": "your-jira-api-token",
+        "ZEPHYR_API_BASE_URL": "https://eu.api.zephyrscale.smartbear.com/v2"
       }
     }
   }
@@ -99,18 +121,19 @@ The server provides access to various resources through URI schemes:
 
 ## Usage Examples
 
-### Create a BDD Test Case
+### Create a BDD Test Case with Issue Links
 ```json
 {
   "project_key": "PROJ",
   "name": "User Authentication",
   "test_script": {
     "type": "BDD",
-    "text": "Feature: User Login\n\nScenario: Valid user login\n  Given a user with valid credentials\n  When the user attempts to log in\n  Then the user should be authenticated successfully"
-  }
+    "text": "Given a user with valid credentials\nWhen the user attempts to log in\nThen the user should be authenticated successfully"
+  },
+  "issue_links": ["PROJ-123", "PROJ-456"]
 }
 ```
-**Note**: The server will automatically convert markdown-style BDD to proper Gherkin format.
+**Note**: `issue_links` requires `JIRA_USERNAME` and `JIRA_API_TOKEN` to be set (Cloud only). Link failures are reported as warnings — the test case is still created.
 
 ### Use a Live Test Case as a Template
 1. Fetch an existing test case: `zephyr://testcase/PROJ-T123`
@@ -139,26 +162,25 @@ The server provides access to various resources through URI schemes:
 ## Authentication
 
 ### Jira Cloud Configuration
-- `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).
+| Variable | Required | Description |
+|---|---|---|
+| `ZEPHYR_BASE_URL` | ✅ | Your Jira Cloud URL, e.g. `https://your-company.atlassian.net` |
+| `ZEPHYR_API_KEY` | ✅ | Zephyr Scale API key (JWT). Generate in Jira: profile picture (bottom left) → **Zephyr API keys** |
+| `JIRA_USERNAME` | ⚠️ Optional* | Your Jira account email address |
+| `JIRA_API_TOKEN` | ⚠️ Optional* | Jira API token. Generate at [id.atlassian.com/manage-profile/security/api-tokens](https://id.atlassian.com/manage-profile/security/api-tokens) |
+| `ZEPHYR_API_BASE_URL` | Optional | Override the Zephyr API base URL (e.g. for EU: `https://eu.api.zephyrscale.smartbear.com/v2`). Defaults to US endpoint. |
+| `JIRA_TYPE` | Optional | Force `"cloud"` or `"datacenter"` — overrides auto-detection |
 
-**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_USERNAME` + `JIRA_API_TOKEN`**: Required only for the `issue_links` feature on Cloud. The Zephyr API key cannot authenticate against the Jira REST API, so a separate Jira credential is needed to resolve issue keys to numeric IDs. Without these, `issue_links` will fail with a 401 warning — the test case is still created successfully.
 
 ### 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.
+
+| Variable | Required | Description |
+|---|---|---|
+| `ZEPHYR_BASE_URL` | ✅ | Your Jira server URL, e.g. `https://your-jira-server.com` |
+| `ZEPHYR_API_KEY` | ✅ | Zephyr Scale API token from your Jira profile settings |
+| `JIRA_TYPE` | Optional | Set to `"datacenter"` to override auto-detection |
 
 ### Automatic Detection
 The server automatically detects your Jira type based on `ZEPHYR_BASE_URL` — URLs containing `.atlassian.net` are treated as Cloud, everything else as Data Center. Override with `JIRA_TYPE="cloud"` or `JIRA_TYPE="datacenter"`.

package/build/tool-handlers.js

@@ -1,3 +1,4 @@
+import axios from 'axios';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { convertToGherkin, resolveFolderIdByPath } from './utils.js';
 export class ZephyrToolHandlers {
@@ -34,7 +35,7 @@ export class ZephyrToolHandlers {
         return this.createTestCaseDC(args);
     }
     async createTestCaseCloud(args) {
-        const { project_key, name, test_script, folder, priority, precondition, objective, estimated_time, labels, custom_fields, issue_links, } = args;
+        const { project_key, name, test_script, folder, priority, precondition, objective, estimated_time, labels, custom_fields, issue_links, owner_id, component_id, } = args;
         const payload = { projectKey: project_key, name };
         // Cloud v2 uses statusName/priorityName (strings), folderId (integer)
         payload.statusName = 'Draft';
@@ -50,6 +51,11 @@ export class ZephyrToolHandlers {
             payload.labels = labels;
         if (custom_fields)
             payload.customFields = custom_fields;
+        // Cloud v2 uses ownerId (Jira Account ID) and componentId (integer)
+        if (owner_id)
+            payload.ownerId = owner_id;
+        if (component_id)
+            payload.componentId = component_id;
         // Resolve folder path → folderId
         if (folder) {
             const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CASE');
@@ -80,8 +86,12 @@ export class ZephyrToolHandlers {
                     }
                 }
             }
+            const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+            const credHint = missingCreds
+                ? '\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')}`
+                ? `\n⚠️ Some issue links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
                 : '';
             return {
                 content: [{
@@ -202,12 +212,15 @@ export class ZephyrToolHandlers {
             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+$/, '');
+                // 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}`, {
-                    projectKey,
+                    id: tc.id,
+                    key: test_case_key,
                     name,
                     status: tc.status,
                     priority: tc.priority,
+                    project: tc.project,
                 });
             }
             return {
@@ -289,8 +302,7 @@ export class ZephyrToolHandlers {
     async createFolderCloud(args) {
         const { project_key, name: folderPath, folder_type = 'TEST_CASE' } = args;
         // Cloud v2 uses folderType (not type) and parentId integer
-        // Map TEST_RUN → TEST_CYCLE for Cloud v2
-        const cloudFolderType = folder_type === 'TEST_RUN' ? 'TEST_CYCLE' : folder_type;
+        const cloudFolderType = folder_type;
         const segments = folderPath.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
         if (segments.length === 0) {
             throw new McpError(ErrorCode.InvalidParams, 'folder name/path cannot be empty');
@@ -454,7 +466,9 @@ export class ZephyrToolHandlers {
             payload.plannedEndDate = planned_end_date;
         if (custom_fields)
             payload.customFields = custom_fields;
-        // Resolve folder path → folderId
+        // Cloud v2 TestCycleInput supports ownerId (Jira Account ID)
+        if (owner)
+            payload.ownerId = owner;
         if (folder) {
             const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CYCLE');
             if (folderId !== null)
@@ -694,7 +708,7 @@ export class ZephyrToolHandlers {
                             text: `✅ Found ${testRuns.length} test run(s):\n${JSON.stringify({
                                 totalCount: testRuns.length,
                                 testRuns: testRuns.map((tr) => ({
-                                    key: tr.key, name: tr.name, status: tr.status?.name, folder: tr.folder?.name,
+                                    key: tr.key, name: tr.name, status: tr.status?.id, folder: tr.folder?.name,
                                 })),
                             }, null, 2)}`,
                         }],
@@ -769,11 +783,28 @@ export class ZephyrToolHandlers {
         }
     }
     async resolveJiraIssueId(issueKey) {
-        // The Zephyr API key is a Jira-issued token — it works against the Jira REST API too.
-        // We call GET {jiraBaseUrl}/rest/api/3/issue/{key}?fields=id to get the numeric issue ID
-        // required by POST /testcases/{key}/links/issues { issueId: <integer> }.
+        // 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.
+        const username = process.env.JIRA_USERNAME;
+        const apiToken = process.env.JIRA_API_TOKEN;
         const url = `${this.jiraConfig.jiraBaseUrl}/rest/api/3/issue/${issueKey}?fields=id`;
-        const response = await this.axiosInstance.get(url, { baseURL: '' });
+        let response;
+        if (username && apiToken) {
+            // Jira Cloud Basic Auth
+            response = await axios.get(url, {
+                headers: { 'Accept': 'application/json' },
+                auth: { username, password: apiToken },
+            });
+        }
+        else {
+            // Fallback: try Bearer token (works for Data Center with PAT)
+            response = await axios.get(url, {
+                headers: {
+                    'Accept': 'application/json',
+                    'Authorization': `Bearer ${process.env.ZEPHYR_API_KEY}`,
+                },
+            });
+        }
         const id = parseInt(response.data.id, 10);
         if (!id || isNaN(id)) {
             throw new Error(`Could not resolve numeric ID for Jira issue "${issueKey}"`);

package/build/tool-schemas.js

@@ -91,13 +91,13 @@ export const toolSchemas = [
                     type: 'string',
                     description: 'Test objective (optional)',
                 },
-                component: {
-                    type: 'string',
-                    description: 'Component name (optional)',
+                component_id: {
+                    type: 'integer',
+                    description: 'Jira component ID (optional, Cloud only — use the numeric component ID, not the name)',
                 },
-                owner: {
+                owner_id: {
                     type: 'string',
-                    description: 'Test case owner (optional)',
+                    description: 'Test case owner Jira Account ID (optional, Cloud only — e.g. "5b10a2844c20165700ede21g")',
                 },
                 estimated_time: {
                     type: 'number',
@@ -191,7 +191,7 @@ export const toolSchemas = [
                 folder_type: {
                     type: 'string',
                     description: 'Type of folder',
-                    enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_RUN'],
+                    enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_CYCLE'],
                     default: 'TEST_CASE',
                 },
             },

package/package.json

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

@@ -1,4 +1,5 @@
 import { AxiosInstance } from 'axios';
+import axios from 'axios';
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import {
   TestCaseArgs,
@@ -47,6 +48,7 @@ export class ZephyrToolHandlers {
     const {
       project_key, name, test_script, folder, priority, precondition,
       objective, estimated_time, labels, custom_fields, issue_links,
+      owner_id, component_id,
     } = args;
 
     const payload: any = { projectKey: project_key, name };
@@ -58,6 +60,9 @@ export class ZephyrToolHandlers {
     if (estimated_time) payload.estimatedTime = estimated_time;
     if (labels && labels.length > 0) payload.labels = labels;
     if (custom_fields) payload.customFields = custom_fields;
+    // Cloud v2 uses ownerId (Jira Account ID) and componentId (integer)
+    if (owner_id) payload.ownerId = owner_id;
+    if (component_id) payload.componentId = component_id;
 
     // Resolve folder path → folderId
     if (folder) {
@@ -96,8 +101,12 @@ export class ZephyrToolHandlers {
         }
       }
 
+      const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+      const credHint = missingCreds
+        ? '\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')}`
+        ? `\n⚠️ Some issue links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
         : '';
 
       return {
@@ -224,12 +233,15 @@ export class ZephyrToolHandlers {
       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+$/, '');
+        // 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}`, {
-          projectKey,
+          id: tc.id,
+          key: test_case_key,
           name,
           status: tc.status,
           priority: tc.priority,
+          project: tc.project,
         });
       }
 
@@ -318,8 +330,7 @@ export class ZephyrToolHandlers {
     const { project_key, name: folderPath, folder_type = 'TEST_CASE' } = args;
 
     // Cloud v2 uses folderType (not type) and parentId integer
-    // Map TEST_RUN → TEST_CYCLE for Cloud v2
-    const cloudFolderType = folder_type === 'TEST_RUN' ? 'TEST_CYCLE' : folder_type;
+    const cloudFolderType = folder_type;
 
     const segments = folderPath.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
     if (segments.length === 0) {
@@ -504,8 +515,8 @@ export class ZephyrToolHandlers {
     if (planned_start_date) payload.plannedStartDate = planned_start_date;
     if (planned_end_date) payload.plannedEndDate = planned_end_date;
     if (custom_fields) payload.customFields = custom_fields;
-
-    // Resolve folder path → folderId
+    // Cloud v2 TestCycleInput supports ownerId (Jira Account ID)
+    if (owner) payload.ownerId = owner;
     if (folder) {
       const folderId = await resolveFolderIdByPath(
         this.axiosInstance, project_key, folder, 'TEST_CYCLE'
@@ -766,7 +777,7 @@ export class ZephyrToolHandlers {
             text: `✅ Found ${testRuns.length} test run(s):\n${JSON.stringify({
               totalCount: testRuns.length,
               testRuns: testRuns.map((tr: any) => ({
-                key: tr.key, name: tr.name, status: tr.status?.name, folder: tr.folder?.name,
+                key: tr.key, name: tr.name, status: tr.status?.id, folder: tr.folder?.name,
               })),
             }, null, 2)}`,
           }],
@@ -846,11 +857,30 @@ export class ZephyrToolHandlers {
   }
 
   private async resolveJiraIssueId(issueKey: string): Promise<number> {
-    // The Zephyr API key is a Jira-issued token — it works against the Jira REST API too.
-    // We call GET {jiraBaseUrl}/rest/api/3/issue/{key}?fields=id to get the numeric issue ID
-    // required by POST /testcases/{key}/links/issues { issueId: <integer> }.
+    // 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.
+    const username = process.env.JIRA_USERNAME;
+    const apiToken = process.env.JIRA_API_TOKEN;
+
     const url = `${this.jiraConfig.jiraBaseUrl}/rest/api/3/issue/${issueKey}?fields=id`;
-    const response = await this.axiosInstance.get(url, { baseURL: '' });
+
+    let response;
+    if (username && apiToken) {
+      // Jira Cloud Basic Auth
+      response = await axios.get(url, {
+        headers: { 'Accept': 'application/json' },
+        auth: { username, password: apiToken },
+      });
+    } else {
+      // Fallback: try Bearer token (works for Data Center with PAT)
+      response = await axios.get(url, {
+        headers: {
+          'Accept': 'application/json',
+          'Authorization': `Bearer ${process.env.ZEPHYR_API_KEY}`,
+        },
+      });
+    }
+
     const id = parseInt(response.data.id, 10);
     if (!id || isNaN(id)) {
       throw new Error(`Could not resolve numeric ID for Jira issue "${issueKey}"`);

package/src/tool-schemas.ts

@@ -91,13 +91,13 @@ export const toolSchemas = [
           type: 'string',
           description: 'Test objective (optional)',
         },
-        component: {
-          type: 'string',
-          description: 'Component name (optional)',
+        component_id: {
+          type: 'integer',
+          description: 'Jira component ID (optional, Cloud only — use the numeric component ID, not the name)',
         },
-        owner: {
+        owner_id: {
           type: 'string',
-          description: 'Test case owner (optional)',
+          description: 'Test case owner Jira Account ID (optional, Cloud only — e.g. "5b10a2844c20165700ede21g")',
         },
         estimated_time: {
           type: 'number',
@@ -191,7 +191,7 @@ export const toolSchemas = [
         folder_type: {
           type: 'string',
           description: 'Type of folder',
-          enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_RUN'],
+          enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_CYCLE'],
           default: 'TEST_CASE',
         },
       },

package/src/types.ts

@@ -31,8 +31,10 @@ export interface TestCaseArgs {
   priority?: 'High' | 'Normal' | 'Low';
   precondition?: string;
   objective?: string;
-  component?: string;
-  owner?: string;
+  component?: string;       // Data Center: component name
+  owner?: string;           // Data Center: owner name
+  component_id?: number;    // Cloud: Jira component ID (integer)
+  owner_id?: string;        // Cloud: Jira Account ID
   estimated_time?: number;
   labels?: string[];
   issue_links?: string[];
@@ -49,7 +51,7 @@ export interface UpdateBddArgs {
 export interface FolderArgs {
   project_key: string;
   name: string; // Full folder path including parent folders (e.g., "/folder/subfolder")
-  folder_type?: 'TEST_CASE' | 'TEST_PLAN' | 'TEST_RUN';
+  folder_type?: 'TEST_CASE' | 'TEST_PLAN' | 'TEST_CYCLE';
 }
 
 export interface TestRunArgs {