zephyr-scale-mcp-server 0.4.2 → 0.4.4

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: [{
@@ -98,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) {
@@ -202,13 +218,26 @@ 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+$/, '');
-                await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
-                    projectKey,
+                // UpdateTestCaseInput requires: id, key, name, priority, project, status
+                // 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: [{
@@ -289,8 +318,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');
@@ -442,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;
@@ -454,7 +483,12 @@ 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;
+        // 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)
@@ -469,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',
@@ -484,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}`,
                     }],
             };
         }
@@ -694,7 +758,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 +833,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

@@ -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',
@@ -91,13 +89,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 +189,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',
                 },
             },
@@ -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.2",
+  "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

@@ -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 {
@@ -115,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 }
@@ -224,13 +239,23 @@ 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+$/, '');
-        await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, {
-          projectKey,
+        // UpdateTestCaseInput requires: id, key, name, priority, project, status
+        // 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 {
@@ -318,8 +343,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) {
@@ -493,19 +517,23 @@ 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;
     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;
+    // 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'
@@ -524,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',
@@ -540,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) {
@@ -766,7 +827,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 +907,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

@@ -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',
@@ -91,13 +89,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 +189,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',
         },
       },
@@ -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

@@ -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 {
@@ -62,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>;