zephyr-scale-mcp-server 0.3.2 → 0.4.0

package/build/tool-handlers.js

@@ -1,5 +1,5 @@
 import { McpError, ErrorCode } from '@modelcontextprotocol/sdk/types.js';
-import { convertToGherkin } from './utils.js';
+import { convertToGherkin, resolveFolderIdByPath } from './utils.js';
 export class ZephyrToolHandlers {
     axiosInstance;
     jiraConfig;
@@ -16,17 +16,83 @@ export class ZephyrToolHandlers {
             };
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to get test case: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to get test case: ${this.formatError(error)}`);
         }
     }
     async createTestCase(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            return this.createTestCaseCloud(args);
+        }
+        return this.createTestCaseDC(args);
+    }
+    async createTestCaseCloud(args) {
+        const { project_key, name, test_script, folder, priority, precondition, objective, estimated_time, labels, custom_fields, } = args;
+        const payload = { projectKey: project_key, name };
+        // Cloud v2 uses statusName/priorityName (strings), folderId (integer)
+        payload.statusName = 'Draft';
+        if (priority)
+            payload.priorityName = priority;
+        if (precondition)
+            payload.precondition = precondition;
+        if (objective)
+            payload.objective = objective;
+        if (estimated_time)
+            payload.estimatedTime = estimated_time;
+        if (labels && labels.length > 0)
+            payload.labels = labels;
+        if (custom_fields)
+            payload.customFields = custom_fields;
+        // Resolve folder path → folderId
+        if (folder) {
+            const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CASE');
+            if (folderId !== null)
+                payload.folderId = folderId;
+        }
+        try {
+            const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.testcase, payload);
+            if (response.status !== 201) {
+                throw new Error(`Unexpected status code: ${response.status}`);
+            }
+            const testKey = response.data.key || 'Unknown';
+            // Step 2: add test script via dedicated endpoint
+            if (test_script) {
+                await this.upsertTestScriptCloud(testKey, test_script);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Test case created successfully: ${testKey}\n${JSON.stringify({ key: testKey, type: test_script?.type || 'none' }, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to create test case: ${this.formatError(error)}`);
+        }
+    }
+    async upsertTestScriptCloud(testKey, test_script) {
+        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,
+                },
+            }));
+            await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testcase}/${testKey}/teststeps`, { mode: 'OVERWRITE', items });
+        }
+        else if (test_script.type === 'BDD' && test_script.text) {
+            const gherkin = convertToGherkin(test_script.text) || test_script.text;
+            await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testcase}/${testKey}/testscript`, { type: 'bdd', text: gherkin });
+        }
+        else if (test_script.type === 'PLAIN_TEXT' && test_script.text) {
+            await this.axiosInstance.post(`${this.jiraConfig.apiEndpoints.testcase}/${testKey}/testscript`, { type: 'plain', text: test_script.text });
+        }
+    }
+    async createTestCaseDC(args) {
         const { project_key, name, test_script, folder, status, priority, precondition, objective, component, owner, estimated_time, labels, issue_links, custom_fields, parameters } = args;
-        // Build the basic payload
-        const payload = {
-            projectKey: project_key,
-            name: name
-        };
-        // Add optional fields
+        const payload = { projectKey: project_key, name };
         if (folder)
             payload.folder = folder;
         if (status)
@@ -51,87 +117,113 @@ export class ZephyrToolHandlers {
             payload.customFields = custom_fields;
         if (parameters)
             payload.parameters = parameters;
-        // Handle test script
         if (test_script) {
-            payload.testScript = {
-                type: test_script.type
-            };
+            payload.testScript = { type: test_script.type };
             if (test_script.type === 'STEP_BY_STEP' && test_script.steps) {
                 payload.testScript.steps = test_script.steps.map((step) => {
-                    const stepObj = {};
+                    const s = {};
                     if (step.description)
-                        stepObj.description = step.description;
+                        s.description = step.description;
                     if (step.testData)
-                        stepObj.testData = step.testData;
+                        s.testData = step.testData;
                     if (step.expectedResult)
-                        stepObj.expectedResult = step.expectedResult;
+                        s.expectedResult = step.expectedResult;
                     if (step.testCaseKey)
-                        stepObj.testCaseKey = step.testCaseKey;
-                    return stepObj;
+                        s.testCaseKey = step.testCaseKey;
+                    return s;
                 });
             }
             else if ((test_script.type === 'PLAIN_TEXT' || test_script.type === 'BDD') && test_script.text) {
                 if (test_script.type === 'BDD') {
-                    const gherkinContent = convertToGherkin(test_script.text);
-                    payload.testScript.text = gherkinContent || test_script.text;
+                    const gherkin = convertToGherkin(test_script.text);
+                    payload.testScript.text = gherkin || test_script.text;
                 }
                 else {
                     payload.testScript.text = test_script.text;
                 }
             }
         }
-        // Always set status to Draft for new test cases
+        // Always Draft for new test cases
         payload.status = 'Draft';
         try {
             const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.testcase, payload);
-            if (response.status === 201) {
-                const testKey = response.data.key || 'Unknown';
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `✅ Test case created successfully: ${testKey}\n${JSON.stringify({
-                                key: testKey,
-                                type: test_script?.type || 'none',
-                                hasSteps: test_script?.type === 'STEP_BY_STEP' ? test_script.steps?.length || 0 : undefined,
-                                hasText: (test_script?.type === 'PLAIN_TEXT' || test_script?.type === 'BDD') ? !!test_script.text : undefined
-                            }, null, 2)}`,
-                        },
-                    ],
-                };
-            }
-            else {
+            if (response.status !== 201)
                 throw new Error(`Unexpected status code: ${response.status}`);
-            }
+            const testKey = response.data.key || 'Unknown';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Test case created successfully: ${testKey}\n${JSON.stringify({ key: testKey, type: test_script?.type || 'none' }, null, 2)}`,
+                    }],
+            };
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to create test case: ${errorMessage}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to create test case: ${this.formatError(error)}`);
         }
     }
     async updateTestCaseBdd(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            return this.updateTestCaseBddCloud(args);
+        }
+        return this.updateTestCaseBddDC(args);
+    }
+    async updateTestCaseBddCloud(args) {
+        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 = {
+                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 });
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Updated ${test_case_key} with BDD content successfully (Cloud v2)`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to update test case BDD: ${this.formatError(error)}`);
+        }
+    }
+    async updateTestCaseBddDC(args) {
         const { test_case_key, bdd_content, name } = args;
         try {
-            // First, get the existing test case data
             const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
             const testCaseData = getResponse.data;
-            // Convert incoming BDD markdown (fallback to raw content if conversion returns empty)
             const converted = convertToGherkin(bdd_content);
             const finalText = converted && converted.trim().length > 0 ? converted : bdd_content;
-            // Build a payload aligned with Zephyr Scale Server's update schema.
-            // Only include fields that exist to avoid accidental nulling; required fields must be present.
             const payload = {};
-            // Required base fields (schema requires these on Server/Data Center). If missing, throw.
             const requiredFields = [
                 ['projectKey', testCaseData.projectKey],
                 ['name', testCaseData.name],
@@ -144,66 +236,94 @@ export class ZephyrToolHandlers {
                 }
                 payload[field] = value;
             }
-            // Optional name update
-            if (typeof name === 'string' && name.trim().length > 0) {
+            if (typeof name === 'string' && name.trim().length > 0)
                 payload.name = name;
-            }
-            // Optional simple scalar/string fields
-            const optionalScalarFields = [
-                'objective',
-                'precondition',
-                'folder',
-                'component',
-                'owner',
-                'estimatedTime'
-            ];
-            for (const field of optionalScalarFields) {
+            for (const field of ['objective', 'precondition', 'folder', 'component', 'owner', 'estimatedTime']) {
                 if (testCaseData[field] !== undefined)
                     payload[field] = testCaseData[field];
             }
-            // Arrays / objects
             if (Array.isArray(testCaseData.labels))
                 payload.labels = testCaseData.labels;
             if (testCaseData.customFields)
                 payload.customFields = testCaseData.customFields;
             if (testCaseData.parameters)
                 payload.parameters = testCaseData.parameters;
-            // issueLinks preferred; map deprecated issueKey if present and issueLinks absent
             if (Array.isArray(testCaseData.issueLinks)) {
                 payload.issueLinks = testCaseData.issueLinks;
             }
             else if (testCaseData.issueKey) {
                 payload.issueLinks = [testCaseData.issueKey];
             }
-            // Build testScript. Force type to BDD when performing a BDD update.
-            payload.testScript = {
-                type: 'BDD',
-                text: finalText
-            };
-            // PUT update
+            payload.testScript = { type: 'BDD', text: finalText };
             const updateResponse = await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, payload);
-            if (updateResponse.status === 200) {
+            if (updateResponse.status !== 200) {
+                throw new Error(`Failed to update ${test_case_key}: ${updateResponse.status}`);
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Updated ${test_case_key} with BDD content successfully\nPayload summary: ${JSON.stringify({ textLength: finalText.length, projectKey: payload.projectKey, name: payload.name, preservedLabels: payload.labels?.length || 0 }, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to update test case BDD: ${this.formatError(error)}`);
+        }
+    }
+    async createFolder(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            return this.createFolderCloud(args);
+        }
+        return this.createFolderDC(args);
+    }
+    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 segments = folderPath.replace(/^\/+|\/+$/g, '').split('/').filter(Boolean);
+        if (segments.length === 0) {
+            throw new McpError(ErrorCode.InvalidParams, 'folder name/path cannot be empty');
+        }
+        const leafName = segments[segments.length - 1];
+        let parentId = null;
+        // Resolve parent if nested path
+        if (segments.length > 1) {
+            const parentPath = '/' + segments.slice(0, -1).join('/');
+            parentId = await resolveFolderIdByPath(this.axiosInstance, project_key, parentPath, cloudFolderType);
+            if (parentId === null) {
+                throw new McpError(ErrorCode.InternalError, `Parent folder not found for path: ${parentPath}. Create parent folders first.`);
+            }
+        }
+        const payload = {
+            projectKey: project_key,
+            name: leafName,
+            folderType: cloudFolderType,
+        };
+        if (parentId !== null)
+            payload.parentId = parentId;
+        try {
+            const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.folder, payload);
+            if (response.status === 201 || response.status === 200) {
                 return {
-                    content: [
-                        {
+                    content: [{
                             type: 'text',
-                            text: `✅ Updated ${test_case_key} with BDD content successfully\nPayload summary: ${JSON.stringify({ textLength: finalText.length, projectKey: payload.projectKey, name: payload.name, preservedLabels: payload.labels?.length || 0 }, null, 2)}`,
-                        },
-                    ],
+                            text: `✅ Folder created successfully: ${leafName} (ID: ${response.data.id || 'N/A'})\n${JSON.stringify(response.data, null, 2)}`,
+                        }],
                 };
             }
-            throw new Error(`Failed to update ${test_case_key}: ${updateResponse.status}`);
+            throw new Error(`Unexpected status code: ${response.status}`);
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to update test case BDD: ${error instanceof Error ? error.message : String(error)}`);
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to create folder: ${this.formatError(error)}`);
         }
     }
-    async createFolder(args) {
+    async createFolderDC(args) {
         const { project_key, name, folder_type = 'TEST_CASE' } = args;
-        // According to Zephyr Scale API documentation:
-        // - projectKey: Project key (required)
-        // - name: Full folder path including parent folders (e.g., "/folder/subfolder")
-        // - type: Folder type (TEST_CASE, TEST_PLAN, or TEST_RUN)
         const payload = {
             projectKey: project_key,
             name: name,
@@ -213,35 +333,51 @@ export class ZephyrToolHandlers {
             const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.folder, payload);
             if (response.status === 201 || response.status === 200) {
                 return {
-                    content: [
-                        {
+                    content: [{
                             type: 'text',
                             text: `✅ Folder created successfully: ${response.data.name || name} (ID: ${response.data.id || 'N/A'})\n${JSON.stringify(response.data, null, 2)}`,
-                        },
-                    ],
+                        }],
                 };
             }
-            else {
-                throw new Error(`Unexpected status code: ${response.status}`);
-            }
+            throw new Error(`Unexpected status code: ${response.status}`);
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}, Payload sent: ${JSON.stringify(payload)}`;
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to create folder: ${errorMessage}`);
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to create folder: ${this.formatError(error)}`);
         }
     }
     async getTestRunCases(args) {
         const { test_run_key } = args;
+        if (this.jiraConfig.type === 'cloud') {
+            try {
+                // Cloud: test cases are retrieved via executions associated with the cycle
+                const response = await this.axiosInstance.get('/testexecutions', {
+                    params: { testCycle: test_run_key, maxResults: 1000 },
+                });
+                const executions = Array.isArray(response.data)
+                    ? response.data
+                    : response.data?.values ?? [];
+                // Deduplicate by test case key
+                const seen = new Set();
+                const testCaseKeys = [];
+                for (const exec of executions) {
+                    const key = exec.testCase?.key
+                        ?? exec.testCase?.self?.match(/testcases\/([^/]+)/)?.[1];
+                    if (key && !seen.has(key)) {
+                        seen.add(key);
+                        testCaseKeys.push(key);
+                    }
+                }
+                return {
+                    content: [{ type: 'text', text: JSON.stringify(testCaseKeys, null, 2) }],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, `Failed to get test run cases: ${this.formatError(error)}`);
+            }
+        }
+        // Data Center: items[] in the run response
         try {
             const response = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}`);
             const testCases = response.data.items?.map((item) => item.testCaseKey) || [];
@@ -250,61 +386,111 @@ export class ZephyrToolHandlers {
             };
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to get test run cases: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to get test run cases: ${this.formatError(error)}`);
         }
     }
     async deleteTestCase(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            throw new McpError(ErrorCode.InvalidRequest, 'delete_test_case is not supported by the Zephyr Scale Cloud v2 API.');
+        }
         const { test_case_key } = args;
         try {
             const response = await this.axiosInstance.delete(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
             if (response.status === 204) {
-                return {
-                    content: [{ type: 'text', text: `Test case ${test_case_key} deleted successfully.` }],
-                };
-            }
-            else {
-                return {
-                    content: [{ type: 'text', text: `Failed to delete test case. Status: ${response.status}` }],
-                    isError: true,
-                };
+                return { content: [{ type: 'text', text: `Test case ${test_case_key} deleted successfully.` }] };
             }
+            return {
+                content: [{ type: 'text', text: `Failed to delete test case. Status: ${response.status}` }],
+                isError: true,
+            };
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to delete test case: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to delete test case: ${this.formatError(error)}`);
         }
     }
     async deleteTestRun(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            throw new McpError(ErrorCode.InvalidRequest, 'delete_test_run is not supported by the Zephyr Scale Cloud v2 API.');
+        }
         const { test_run_key } = args;
         try {
             const response = await this.axiosInstance.delete(`${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}`);
             if (response.status === 204) {
-                return {
-                    content: [{ type: 'text', text: `Test run ${test_run_key} deleted successfully.` }],
-                };
-            }
-            else {
-                return {
-                    content: [{ type: 'text', text: `Failed to delete test run. Status: ${response.status}` }],
-                    isError: true,
-                };
+                return { content: [{ type: 'text', text: `Test run ${test_run_key} deleted successfully.` }] };
             }
+            return {
+                content: [{ type: 'text', text: `Failed to delete test run. Status: ${response.status}` }],
+                isError: true,
+            };
         }
         catch (error) {
-            throw new McpError(ErrorCode.InternalError, `Failed to delete test run: ${error instanceof Error ? error.message : String(error)}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to delete test run: ${this.formatError(error)}`);
         }
     }
     async createTestRun(args) {
+        if (this.jiraConfig.type === 'cloud') {
+            return this.createTestRunCloud(args);
+        }
+        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;
+        // Cloud v2 TestCycleInput: projectKey, name, description, plannedStartDate,
+        // plannedEndDate, statusName, folderId, ownerId, customFields
+        const payload = { 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
+        if (folder) {
+            const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CYCLE');
+            if (folderId !== null)
+                payload.folderId = folderId;
+        }
+        // Note: environment and owner (by account ID) not mapped here — Cloud requires IDs
+        try {
+            const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.testrun, payload);
+            if (response.status !== 201)
+                throw new Error(`Unexpected status code: ${response.status}`);
+            const cycleKey = response.data.key || 'Unknown';
+            // 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', {
+                        projectKey: project_key,
+                        testCaseKey,
+                        testCycleKey: cycleKey,
+                        statusName: 'Not Executed',
+                    });
+                }
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Test run (cycle) created successfully: ${cycleKey}\n${JSON.stringify({
+                            key: cycleKey,
+                            name,
+                            testCaseCount: test_case_keys?.length || 0,
+                        }, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to create test run: ${this.formatError(error)}`);
+        }
+    }
+    async createTestRunDC(args) {
         const { project_key, name, test_case_keys, test_plan_key, folder, planned_start_date, planned_end_date, description, owner, environment, issue_key, issue_links, custom_fields } = args;
-        // Build the basic payload
-        const payload = {
-            projectKey: project_key,
-            name: name,
-        };
-        // Add optional fields
+        const payload = { projectKey: project_key, name };
         if (test_case_keys && test_case_keys.length > 0) {
-            payload.items = test_case_keys.map((testCaseKey) => ({
-                testCaseKey: testCaseKey
-            }));
+            payload.items = test_case_keys.map((testCaseKey) => ({ testCaseKey }));
         }
         if (folder)
             payload.folder = folder;
@@ -328,144 +514,129 @@ export class ZephyrToolHandlers {
             payload.testPlanKey = test_plan_key;
         try {
             const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.testrun, payload);
-            if (response.status === 201) {
-                const testRunKey = response.data.key || 'Unknown';
-                return {
-                    content: [
-                        {
-                            type: 'text',
-                            text: `✅ Test run created successfully: ${testRunKey}\n${JSON.stringify({
-                                key: testRunKey,
-                                name: name,
-                                testCaseCount: test_case_keys?.length || 0,
-                                environment: environment || 'Not specified'
-                            }, null, 2)}`,
-                        },
-                    ],
-                };
-            }
-            else {
+            if (response.status !== 201)
                 throw new Error(`Unexpected status code: ${response.status}`);
-            }
+            const testRunKey = response.data.key || 'Unknown';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Test run created successfully: ${testRunKey}\n${JSON.stringify({
+                            key: testRunKey, name, testCaseCount: test_case_keys?.length || 0,
+                            environment: environment || 'Not specified'
+                        }, null, 2)}`,
+                    }],
+            };
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to create test run: ${errorMessage}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to create test run: ${this.formatError(error)}`);
         }
     }
     async getTestRun(args) {
         const { test_run_key } = args;
+        // Both Cloud (/testcycles/{key}) and DC (/rest/atm/1.0/testrun/{key}) handled
+        // via apiEndpoints.testrun which now correctly maps to /testcycles for Cloud
         try {
             const response = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}`);
             return {
-                content: [
-                    {
-                        type: 'text',
-                        text: JSON.stringify(response.data, null, 2),
-                    },
-                ],
+                content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }],
             };
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                if (axiosError.response?.status === 404) {
-                    errorMessage = `Test run ${test_run_key} not found`;
-                }
-                else {
-                    errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-                }
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to get test run: ${errorMessage}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to get test run: ${this.formatError(error)}`);
         }
     }
     async getTestExecution(args) {
         const { execution_id, test_run_keys } = args;
-        // Require users to specify test runs to search - fail immediately if not provided
+        if (this.jiraConfig.type === 'cloud') {
+            // Cloud v2: direct fetch by ID or key (e.g. PROJ-E123)
+            try {
+                const response = await this.axiosInstance.get(`/testexecutions/${execution_id}`);
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `✅ Test execution ${execution_id} found:\n${JSON.stringify(response.data, null, 2)}`,
+                        }],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, `Failed to get test execution: ${this.formatError(error)}`);
+            }
+        }
+        // Data Center: iterate test runs searching testresults
         if (!test_run_keys || !Array.isArray(test_run_keys) || test_run_keys.length === 0) {
-            throw new McpError(ErrorCode.InvalidParams, 'test_run_keys is required. Please provide an array of test run keys to search in (e.g., ["PROJ-C152", "PROJ-C161"]). Use get_test_run_cases to find test runs if needed.');
+            throw new McpError(ErrorCode.InvalidParams, 'test_run_keys is required for Data Center. Provide an array of test run keys to search in.');
         }
         try {
-            const testRunsToTry = test_run_keys;
             const searchResults = [];
-            for (const testRunKey of testRunsToTry) {
+            for (const testRunKey of test_run_keys) {
                 try {
                     const response = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testrun}/${testRunKey}/testresults`);
                     if (response.status === 200 && response.data) {
-                        // Look for the specific execution_id in the results
                         const results = Array.isArray(response.data) ? response.data : [response.data];
-                        const matchingExecution = results.find((result) => result.id && result.id.toString() === execution_id);
-                        if (matchingExecution) {
+                        const match = results.find((r) => r.id && r.id.toString() === execution_id);
+                        if (match) {
                             return {
-                                content: [
-                                    {
+                                content: [{
                                         type: 'text',
-                                        text: `✅ Test execution ${execution_id} found in ${testRunKey}:\n${JSON.stringify(matchingExecution, null, 2)}`,
-                                    },
-                                ],
+                                        text: `✅ Test execution ${execution_id} found in ${testRunKey}:\n${JSON.stringify(match, null, 2)}`,
+                                    }],
                             };
                         }
-                        // Store search info for debugging
-                        searchResults.push({
-                            testRunKey,
-                            executionCount: results.length,
-                            executionIds: results.map((r) => r.id).slice(0, 5) // Show first 5 IDs
-                        });
+                        searchResults.push({ testRunKey, executionCount: results.length, executionIds: results.map((r) => r.id).slice(0, 5) });
                     }
                 }
                 catch (runError) {
-                    // Store error info for debugging
-                    searchResults.push({
-                        testRunKey,
-                        error: runError instanceof Error ? runError.message : String(runError)
-                    });
-                    continue;
+                    searchResults.push({ testRunKey, error: runError instanceof Error ? runError.message : String(runError) });
                 }
             }
-            // If not found, provide helpful debugging info
-            throw new Error(`Test execution ${execution_id} not found in any of the ${testRunsToTry.length} test runs searched. Search results: ${JSON.stringify(searchResults, null, 2)}`);
+            throw new Error(`Test execution ${execution_id} not found in any of the ${test_run_keys.length} test runs. Search results: ${JSON.stringify(searchResults, null, 2)}`);
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to get test execution: ${errorMessage}`);
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to get test execution: ${this.formatError(error)}`);
         }
     }
     async searchTestCasesByFolder(args) {
         const { project_key, folder_path, max_results = 100 } = args;
-        // Build JQL-style query for Zephyr Scale API
-        // Escape double quotes in folder path
-        const escapedFolderPath = folder_path.replace(/"/g, '\\"');
-        const query = `projectKey = "${project_key}" AND folder = "${escapedFolderPath}"`;
-        const params = {
-            query: query,
-            maxResults: max_results,
-        };
+        if (this.jiraConfig.type === 'cloud') {
+            try {
+                // Cloud v2: GET /testcases?projectKey=X&folderId=Y
+                const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder_path, 'TEST_CASE');
+                if (folderId === null) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `⚠️ Folder not found: "${folder_path}" in project ${project_key}. No test cases returned.`,
+                            }],
+                    };
+                }
+                const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.testcase, {
+                    params: { projectKey: project_key, folderId, maxResults: max_results },
+                });
+                const testCases = Array.isArray(response.data)
+                    ? response.data
+                    : response.data?.values ?? [];
+                return {
+                    content: [{
+                            type: 'text',
+                            text: `✅ Found ${testCases.length} test cases in folder "${folder_path}" (folderId: ${folderId}):\n${JSON.stringify({
+                                folder: folder_path, folderId, testCaseKeys: testCases.map((tc) => tc.key), totalCount: testCases.length,
+                            }, null, 2)}`,
+                        }],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, `Failed to search test cases by folder: ${this.formatError(error)}`);
+            }
+        }
+        // Data Center: query-based search
         try {
-            const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.search, { params });
-            // Handle different response structures
+            const escapedFolderPath = folder_path.replace(/"/g, '\\"');
+            const query = `projectKey = "${project_key}" AND folder = "${escapedFolderPath}"`;
+            const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.search, {
+                params: { query, maxResults: max_results },
+            });
             let testCases = [];
             if (Array.isArray(response.data)) {
                 testCases = response.data;
@@ -477,58 +648,66 @@ export class ZephyrToolHandlers {
                 testCases = response.data.results;
             }
             return {
-                content: [
-                    {
+                content: [{
                         type: 'text',
                         text: `✅ Found ${testCases.length} test cases in folder "${folder_path}":\n${JSON.stringify({
-                            folder: folder_path,
-                            query: query,
-                            testCaseKeys: testCases.map((tc) => tc.key),
-                            totalCount: testCases.length
+                            folder: folder_path, query, testCaseKeys: testCases.map((tc) => tc.key), totalCount: testCases.length,
                         }, null, 2)}`,
-                    },
-                ],
+                    }],
             };
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                if (axiosError.response?.status === 404) {
-                    errorMessage = `Folder "${folder_path}" not found or no test cases found`;
-                }
-                else {
-                    errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-                }
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to search test cases by folder: ${errorMessage}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to search test cases by folder: ${this.formatError(error)}`);
         }
     }
     async searchTestRuns(args) {
         const { project_key, folder, max_results = 200, fields } = args;
-        // Build query string per Zephyr Scale API docs
-        const queryParts = [];
-        if (project_key)
-            queryParts.push(`projectKey = "${project_key}"`);
-        if (folder)
-            queryParts.push(`folder = "${folder}"`);
-        if (queryParts.length === 0) {
+        if (!project_key && !folder) {
             throw new McpError(ErrorCode.InvalidParams, 'At least one of project_key or folder must be provided.');
         }
-        const query = queryParts.join(' AND ');
-        const params = { query, maxResults: max_results };
-        if (fields)
-            params.fields = fields;
-        const searchEndpoint = this.jiraConfig.type === 'cloud'
-            ? '/testruns/search'
-            : '/rest/atm/1.0/testrun/search';
+        if (this.jiraConfig.type === 'cloud') {
+            try {
+                // Cloud v2: GET /testcycles?projectKey=X&folderId=Y
+                const params = { maxResults: max_results };
+                if (project_key)
+                    params.projectKey = project_key;
+                if (folder && project_key) {
+                    const folderId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder, 'TEST_CYCLE');
+                    if (folderId !== null)
+                        params.folderId = folderId;
+                }
+                const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.testrun, { params });
+                const testRuns = Array.isArray(response.data)
+                    ? response.data
+                    : response.data?.values ?? [];
+                return {
+                    content: [{
+                            type: 'text',
+                            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,
+                                })),
+                            }, null, 2)}`,
+                        }],
+                };
+            }
+            catch (error) {
+                throw new McpError(ErrorCode.InternalError, `Failed to search test runs: ${this.formatError(error)}`);
+            }
+        }
+        // Data Center: query-based search
         try {
+            const queryParts = [];
+            if (project_key)
+                queryParts.push(`projectKey = "${project_key}"`);
+            if (folder)
+                queryParts.push(`folder = "${folder}"`);
+            const query = queryParts.join(' AND ');
+            const searchEndpoint = '/rest/atm/1.0/testrun/search';
+            const params = { query, maxResults: max_results };
+            if (fields)
+                params.fields = fields;
             const response = await this.axiosInstance.get(searchEndpoint, { params });
             let testRuns = [];
             if (Array.isArray(response.data)) {
@@ -541,62 +720,51 @@ export class ZephyrToolHandlers {
                 testRuns = response.data.results;
             }
             return {
-                content: [
-                    {
+                content: [{
                         type: 'text',
                         text: `✅ Found ${testRuns.length} test run(s) matching query "${query}":\n${JSON.stringify({
-                            query,
-                            totalCount: testRuns.length,
+                            query, totalCount: testRuns.length,
                             testRuns: testRuns.map((tr) => ({
-                                key: tr.key,
-                                name: tr.name,
-                                status: tr.status,
-                                folder: tr.folder,
-                                testCaseCount: tr.testCaseCount,
-                                issueKey: tr.issueKey,
-                            }))
+                                key: tr.key, name: tr.name, status: tr.status, folder: tr.folder,
+                                testCaseCount: tr.testCaseCount, issueKey: tr.issueKey,
+                            })),
                         }, null, 2)}`,
-                    },
-                ],
+                    }],
             };
         }
         catch (error) {
-            let errorMessage = 'Unknown error';
-            if (error instanceof Error && 'response' in error) {
-                const axiosError = error;
-                errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-            }
-            else if (error instanceof Error) {
-                errorMessage = error.message;
-            }
-            else {
-                errorMessage = String(error);
-            }
-            throw new McpError(ErrorCode.InternalError, `Failed to search test runs: ${errorMessage}`);
+            throw new McpError(ErrorCode.InternalError, `Failed to search test runs: ${this.formatError(error)}`);
         }
     }
     async addTestCasesToRun(args) {
-        const { test_run_key, test_case_keys } = args;
         if (this.jiraConfig.type === 'datacenter') {
             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(`/testcycles/${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: ${error instanceof Error ? error.message : String(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) {
+            const axiosError = error;
+            return `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
+        }
+        return error instanceof Error ? error.message : String(error);
     }
 }