zephyr-scale-mcp-server 0.3.2 → 0.3.3

package/src/tool-handlers.ts

@@ -8,9 +8,10 @@ import {
   SearchTestCasesArgs,
   AddTestCasesToRunArgs,
   SearchTestRunsArgs,
+  GetTestExecutionArgs,
   JiraConfig
 } from './types.js';
-import { convertToGherkin, customPriorityMapping, priorityMapping } from './utils.js';
+import { convertToGherkin, resolveFolderIdByPath } from './utils.js';
 
 export class ZephyrToolHandlers {
   constructor(
@@ -26,36 +27,102 @@ export class ZephyrToolHandlers {
         content: [{ type: 'text', text: JSON.stringify(response.data, null, 2) }],
       };
     } 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: TestCaseArgs) {
+    if (this.jiraConfig.type === 'cloud') {
+      return this.createTestCaseCloud(args);
+    }
+    return this.createTestCaseDC(args);
+  }
+
+  private async createTestCaseCloud(args: TestCaseArgs) {
     const {
-      project_key,
-      name,
-      test_script,
-      folder,
-      status,
-      priority,
-      precondition,
-      objective,
-      component,
-      owner,
-      estimated_time,
-      labels,
-      issue_links,
-      custom_fields,
-      parameters
+      project_key, name, test_script, folder, priority, precondition,
+      objective, estimated_time, labels, custom_fields,
     } = args;
 
-    // Build the basic payload
-    const payload: any = {
-      projectKey: project_key,
-      name: name
-    };
+    const payload: any = { 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)}`);
+    }
+  }
+
+  private async upsertTestScriptCloud(testKey: string, test_script: TestCaseArgs['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: any) => ({
+        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 }
+      );
+    }
+  }
+
+  private async createTestCaseDC(args: TestCaseArgs) {
+    const {
+      project_key, name, test_script, folder, status, priority, precondition,
+      objective, component, owner, estimated_time, labels, issue_links,
+      custom_fields, parameters
+    } = args;
+
+    const payload: any = { projectKey: project_key, name };
 
-    // Add optional fields
     if (folder) payload.folder = folder;
     if (status) payload.status = status;
     if (priority) payload.priority = priority;
@@ -69,168 +136,230 @@ export class ZephyrToolHandlers {
     if (custom_fields) 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: any) => {
-          const stepObj: any = {};
-          if (step.description) stepObj.description = step.description;
-          if (step.testData) stepObj.testData = step.testData;
-          if (step.expectedResult) stepObj.expectedResult = step.expectedResult;
-          if (step.testCaseKey) stepObj.testCaseKey = step.testCaseKey;
-          return stepObj;
+          const s: any = {};
+          if (step.description) s.description = step.description;
+          if (step.testData) s.testData = step.testData;
+          if (step.expectedResult) s.expectedResult = step.expectedResult;
+          if (step.testCaseKey) 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) 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) {
+      throw new McpError(ErrorCode.InternalError, `Failed to create test case: ${this.formatError(error)}`);
+    }
+  }
 
-      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 {
-        throw new Error(`Unexpected status code: ${response.status}`);
+  async updateTestCaseBdd(args: UpdateBddArgs) {
+    if (this.jiraConfig.type === 'cloud') {
+      return this.updateTestCaseBddCloud(args);
+    }
+    return this.updateTestCaseBddDC(args);
+  }
+
+  private async updateTestCaseBddCloud(args: UpdateBddArgs) {
+    const { test_case_key, bdd_content, name } = args;
+
+    try {
+      // Step 1: GET existing test case to extract required fields for PUT
+      const getResponse = await this.axiosInstance.get(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`);
+      const tc = getResponse.data;
+
+      // Cloud v2 PUT requires: id, key, name, project, priority, status
+      const requiredFields = ['id', 'key', 'name', 'project', 'priority', 'status'];
+      for (const field of requiredFields) {
+        if (tc[field] === undefined || tc[field] === null) {
+          throw new McpError(ErrorCode.InternalError,
+            `Existing test case is missing required field '${field}' needed for Cloud v2 update.`);
+        }
       }
-    } catch (error) {
-      let errorMessage = 'Unknown error';
-      if (error instanceof Error && 'response' in error) {
-        const axiosError = error as any;
-        errorMessage = `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
-      } else if (error instanceof Error) {
-        errorMessage = error.message;
-      } else {
-        errorMessage = String(error);
+
+      const putPayload: any = {
+        id: tc.id,
+        key: tc.key,
+        name: typeof name === 'string' && name.trim().length > 0 ? name : tc.name,
+        project: tc.project,
+        priority: tc.priority,
+        status: tc.status,
+      };
+
+      // Preserve optional fields
+      for (const field of ['objective', 'precondition', 'estimatedTime', 'folder', 'component', 'owner']) {
+        if (tc[field] !== undefined) putPayload[field] = tc[field];
       }
-      throw new McpError(
-        ErrorCode.InternalError,
-        `Failed to create test case: ${errorMessage}`
+      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 updateTestCaseBdd(args: UpdateBddArgs) {
+  private async updateTestCaseBddDC(args: UpdateBddArgs) {
     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: any = {};
-
-      // Required base fields (schema requires these on Server/Data Center). If missing, throw.
       const requiredFields: Array<[string, any]> = [
         ['projectKey', testCaseData.projectKey],
         ['name', testCaseData.name],
         ['status', testCaseData.status],
         ['priority', testCaseData.priority]
       ];
-
       for (const [field, value] of requiredFields) {
         if (value === undefined || value === null || value === '') {
-          throw new McpError(ErrorCode.InternalError, `Existing test case is missing required field '${field}' needed for update.`);
+          throw new McpError(ErrorCode.InternalError,
+            `Existing test case is missing required field '${field}' needed for update.`);
         }
         payload[field] = value;
       }
 
-      // Optional name update
-      if (typeof name === 'string' && name.trim().length > 0) {
-        payload.name = name;
-      }
+      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
+      payload.testScript = { type: 'BDD', text: finalText };
+
+      const updateResponse = await this.axiosInstance.put(
+        `${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, payload
+      );
+
+      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: FolderArgs) {
+    if (this.jiraConfig.type === 'cloud') {
+      return this.createFolderCloud(args);
+    }
+    return this.createFolderDC(args);
+  }
+
+  private async createFolderCloud(args: FolderArgs) {
+    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: number | null = 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.`);
+      }
+    }
 
-      // PUT update
-      const updateResponse = await this.axiosInstance.put(`${this.jiraConfig.apiEndpoints.testcase}/${test_case_key}`, payload);
+    const payload: any = {
+      projectKey: project_key,
+      name: leafName,
+      folderType: cloudFolderType,
+    };
+    if (parentId !== null) payload.parentId = parentId;
 
-      if (updateResponse.status === 200) {
+    try {
+      const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.folder, payload);
+      if (response.status === 201 || response.status === 200) {
         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)}`,
-            },
-          ],
+          content: [{
+            type: 'text',
+            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: FolderArgs) {
+  private async createFolderDC(args: FolderArgs) {
     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: any = {
       projectKey: project_key,
       name: name,
@@ -239,38 +368,55 @@ export class ZephyrToolHandlers {
 
     try {
       const response = await this.axiosInstance.post(this.jiraConfig.apiEndpoints.folder, payload);
-
       if (response.status === 201 || response.status === 200) {
         return {
-          content: [
-            {
-              type: 'text',
-              text: `✅ Folder created successfully: ${response.data.name || name} (ID: ${response.data.id || 'N/A'})\n${JSON.stringify(response.data, null, 2)}`,
-            },
-          ],
+          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 as any;
-        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: any) {
     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<string>();
+        const testCaseKeys: string[] = [];
+        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: any) => item.testCaseKey) || [];
@@ -278,76 +424,130 @@ export class ZephyrToolHandlers {
         content: [{ type: 'text', text: JSON.stringify(testCases, null, 2) }],
       };
     } 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: any) {
+    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: any) {
+    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: TestRunArgs) {
+    if (this.jiraConfig.type === 'cloud') {
+      return this.createTestRunCloud(args);
+    }
+    return this.createTestRunDC(args);
+  }
+
+  private async createTestRunCloud(args: TestRunArgs) {
     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
+      project_key, name, test_case_keys, folder,
+      planned_start_date, planned_end_date, description,
+      owner, environment, custom_fields,
     } = args;
 
-    // Build the basic payload
-    const payload: any = {
-      projectKey: project_key,
-      name: name,
-    };
+    // Cloud v2 TestCycleInput: projectKey, name, description, plannedStartDate,
+    // plannedEndDate, statusName, folderId, ownerId, customFields
+    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
+    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 to the cycle
+      if (test_case_keys && test_case_keys.length > 0) {
+        await this.axiosInstance.post(
+          `${this.jiraConfig.apiEndpoints.testrun}/${cycleKey}/testcases`,
+          { items: test_case_keys.map((k: string) => ({ testCaseKey: k })) }
+        );
+      }
+
+      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)}`);
+    }
+  }
+
+  private async createTestRunDC(args: TestRunArgs) {
+    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;
+
+    const payload: any = { projectKey: project_key, name };
 
-    // Add optional fields
     if (test_case_keys && test_case_keys.length > 0) {
-      payload.items = test_case_keys.map((testCaseKey: string) => ({
-        testCaseKey: testCaseKey
-      }));
+      payload.items = test_case_keys.map((testCaseKey: string) => ({ testCaseKey }));
     }
     if (folder) payload.folder = folder;
     if (planned_start_date) payload.plannedStartDate = planned_start_date;
@@ -362,163 +562,144 @@ export class ZephyrToolHandlers {
 
     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 {
-        throw new Error(`Unexpected status code: ${response.status}`);
-      }
+      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 as any;
-        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: any) {
     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 as any;
-        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: any) {
+  async getTestExecution(args: GetTestExecutionArgs) {
     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.'
+        '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: any[] = [];
 
-      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`);
+          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: any) =>
-              result.id && result.id.toString() === execution_id
-            );
-
-            if (matchingExecution) {
+            const match = results.find((r: any) => r.id && r.id.toString() === execution_id);
+            if (match) {
               return {
-                content: [
-                  {
-                    type: 'text',
-                    text: `✅ Test execution ${execution_id} found in ${testRunKey}:\n${JSON.stringify(matchingExecution, null, 2)}`,
-                  },
-                ],
+                content: [{
+                  type: 'text',
+                  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: any) => r.id).slice(0, 5) // Show first 5 IDs
-            });
+            searchResults.push({ testRunKey, executionCount: results.length, executionIds: results.map((r: any) => 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: SearchTestCasesArgs) {
     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: any) => 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;
@@ -527,62 +708,73 @@ export class ZephyrToolHandlers {
       } else if (response.data.results && Array.isArray(response.data.results)) {
         testCases = response.data.results;
       }
-      
+
       return {
-        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: any) => tc.key),
-              totalCount: testCases.length
-            }, null, 2)}`,
-          },
-        ],
+        content: [{
+          type: 'text',
+          text: `✅ Found ${testCases.length} test cases in folder "${folder_path}":\n${JSON.stringify({
+            folder: folder_path, query, testCaseKeys: testCases.map((tc: any) => tc.key), totalCount: testCases.length,
+          }, null, 2)}`,
+        }],
       };
     } catch (error) {
-      let errorMessage = 'Unknown error';
-      if (error instanceof Error && 'response' in error) {
-        const axiosError = error as any;
-        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: SearchTestRunsArgs) {
     const { project_key, folder, max_results = 200, fields } = args;
 
-    // Build query string per Zephyr Scale API docs
-    const queryParts: string[] = [];
-    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: Record<string, any> = { query, maxResults: max_results };
-    if (fields) params.fields = fields;
+    if (this.jiraConfig.type === 'cloud') {
+      try {
+        // Cloud v2: GET /testcycles?projectKey=X&folderId=Y
+        const params: Record<string, any> = { 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 searchEndpoint = this.jiraConfig.type === 'cloud'
-      ? '/testruns/search'
-      : '/rest/atm/1.0/testrun/search';
+        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: any) => ({
+                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: string[] = [];
+      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: Record<string, any> = { query, maxResults: max_results };
+      if (fields) params.fields = fields;
+
       const response = await this.axiosInstance.get(searchEndpoint, { params });
 
       let testRuns: any[] = [];
@@ -595,41 +787,23 @@ export class ZephyrToolHandlers {
       }
 
       return {
-        content: [
-          {
-            type: 'text',
-            text: `✅ Found ${testRuns.length} test run(s) matching query "${query}":\n${JSON.stringify({
-              query,
-              totalCount: testRuns.length,
-              testRuns: testRuns.map((tr: any) => ({
-                key: tr.key,
-                name: tr.name,
-                status: tr.status,
-                folder: tr.folder,
-                testCaseCount: tr.testCaseCount,
-                issueKey: tr.issueKey,
-              }))
-            }, null, 2)}`,
-          },
-        ],
+        content: [{
+          type: 'text',
+          text: `✅ Found ${testRuns.length} test run(s) matching query "${query}":\n${JSON.stringify({
+            query, totalCount: testRuns.length,
+            testRuns: testRuns.map((tr: any) => ({
+              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 as any;
-        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: AddTestCasesToRunArgs) {
-    const { test_run_key, test_case_keys } = args;
-
     if (this.jiraConfig.type === 'datacenter') {
       throw new McpError(
         ErrorCode.InvalidRequest,
@@ -637,11 +811,16 @@ export class ZephyrToolHandlers {
       );
     }
 
+    const { test_run_key, test_case_keys } = args;
+
     try {
       const payload = {
         items: test_case_keys.map(key => ({ testCaseKey: key }))
       };
-      const response = await this.axiosInstance.post(`/testcycles/${test_run_key}/testcases`, payload);
+      const response = await this.axiosInstance.post(
+        `${this.jiraConfig.apiEndpoints.testrun}/${test_run_key}/testcases`,
+        payload
+      );
 
       if (response.status === 200 || response.status === 201 || response.status === 204) {
         return {
@@ -649,7 +828,7 @@ export class ZephyrToolHandlers {
         };
       }
     } 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 {
@@ -657,4 +836,12 @@ export class ZephyrToolHandlers {
       isError: true,
     };
   }
-}
+
+  private formatError(error: unknown): string {
+    if (error instanceof Error && 'response' in error) {
+      const axiosError = error as any;
+      return `Status: ${axiosError.response?.status}, Data: ${JSON.stringify(axiosError.response?.data)}`;
+    }
+    return error instanceof Error ? error.message : String(error);
+  }
+}