zephyr-scale-mcp-server 0.7.0 → 0.8.0

package/README.md

@@ -115,11 +115,14 @@ The server provides access to various resources through URI schemes:
 ### Test Execution & Search
 - `get_test_execution`: Get detailed individual test execution results.
 - `list_executions_by_cycle`: List all test executions for a specific test cycle with status, executor, and date. *(Cloud only)*
-- `search_test_cases_by_folder`: Search for test cases in a specific folder.
+- `update_test_execution`: Update a test case execution's status within a cycle (Pass/Fail/etc.), add a comment, and attach bug(s) as Jira issue links. Identify the execution by `execution_id`, or by `test_cycle_key` + `test_case_key`. *(Cloud only)*
+- `search_test_cases_by_folder`: Search for test cases in a specific folder. Automatically paginates through all results.
 - `search_test_runs`: Search for test runs by project key and/or folder path.
+- `get_test_cycles_for_issue`: Get the Zephyr test cycles linked to a Jira issue (story/epic). Resolves each cycle ID to its key (e.g. `PROJ-R123`) and name so you can feed it straight into `list_executions_by_cycle` / `update_test_execution`. *(Cloud only)*
 
 ### Organization
 - `create_folder`: Create a new folder in Zephyr Scale.
+- `get_folders`: List folders, optionally filtered by project, type, and path. When `folder_path` is given, returns the matching folder and its full subtree at every depth.
 
 ## Usage Examples
 
@@ -161,6 +164,33 @@ The server provides access to various resources through URI schemes:
 ```
 **Note**: The server will convert markdown-style BDD into Gherkin when possible and will preserve all other existing test case fields.
 
+### Mark an Execution as Failed and Attach a Bug
+```json
+{
+  "test_cycle_key": "PROJ-R123",
+  "test_case_key": "PROJ-T456",
+  "status": "Fail",
+  "comment": "Login button unresponsive on submit.",
+  "bug_keys": ["PROJ-789"]
+}
+```
+Or target an execution directly by key:
+```json
+{
+  "execution_id": "PROJ-E123",
+  "status": "Pass"
+}
+```
+**Note**: `update_test_execution` is Cloud only. `bug_keys` requires `JIRA_USERNAME` and `JIRA_API_TOKEN`; link failures are reported as warnings while the status update still succeeds.
+
+### Find the Test Cycle Linked to a Jira Ticket
+```json
+{
+  "issue_key": "PROJ-6752"
+}
+```
+Returns the linked cycles with resolved keys, e.g. `[{ "id": "110702963", "key": "PROJ-R467", "name": "..." }]`. This is the bridge from a Jira ticket to its Zephyr cycle — the association is stored on the Zephyr side, not in Jira's issue fields. Chain it: `get_test_cycles_for_issue` → `list_executions_by_cycle` → `update_test_execution`. Pass `"resolve_keys": false` to skip the per-cycle key/name lookup and return raw IDs only. **Cloud only.**
+
 ## Authentication
 
 ### Jira Cloud Configuration

package/build/index.js

@@ -75,6 +75,10 @@ class ZephyrServer {
                         return await this.toolHandlers.addTestCasesToRun(args);
                     case 'list_executions_by_cycle':
                         return await this.toolHandlers.listExecutionsByCycle(args);
+                    case 'update_test_execution':
+                        return await this.toolHandlers.updateTestExecution(args);
+                    case 'get_test_cycles_for_issue':
+                        return await this.toolHandlers.getTestCyclesForIssue(args);
                     default:
                         throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
                 }

package/build/tool-handlers.js

@@ -1151,6 +1151,171 @@ export class ZephyrToolHandlers {
             throw new McpError(ErrorCode.InternalError, `Failed to list executions: ${this.formatError(error)}`);
         }
     }
+    async updateTestExecution(args) {
+        if (this.jiraConfig.type !== 'cloud') {
+            throw new McpError(ErrorCode.InvalidRequest, 'update_test_execution is only supported on Zephyr Scale Cloud. The Data Center API (v1) uses a different test-result model.');
+        }
+        const { execution_id, test_cycle_key, test_case_key, project_key, status, comment, environment, execution_time, actual_end_date, executed_by_id, assigned_to_id, bug_keys, } = args;
+        // Resolve which execution to update: explicit execution_id wins, otherwise cycle + test case.
+        let execKey = execution_id;
+        if (!execKey) {
+            if (!test_cycle_key || !test_case_key) {
+                throw new McpError(ErrorCode.InvalidParams, 'Provide either execution_id, or both test_cycle_key and test_case_key to identify the execution.');
+            }
+            execKey = await this.resolveExecutionByCycleAndCase(test_cycle_key, test_case_key, project_key);
+        }
+        // Build the update payload — the PUT ignores null/undefined and only touches provided fields.
+        const payload = {};
+        if (status !== undefined)
+            payload.statusName = status;
+        if (comment !== undefined)
+            payload.comment = comment;
+        if (environment !== undefined)
+            payload.environmentName = environment;
+        if (execution_time !== undefined)
+            payload.executionTime = execution_time;
+        if (actual_end_date !== undefined)
+            payload.actualEndDate = actual_end_date;
+        if (executed_by_id !== undefined)
+            payload.executedById = executed_by_id;
+        if (assigned_to_id !== undefined)
+            payload.assignedToId = assigned_to_id;
+        const hasBugs = Array.isArray(bug_keys) && bug_keys.length > 0;
+        if (Object.keys(payload).length === 0 && !hasBugs) {
+            throw new McpError(ErrorCode.InvalidParams, 'Nothing to update — provide at least one of: status, comment, environment, execution_time, actual_end_date, executed_by_id, assigned_to_id, or bug_keys.');
+        }
+        try {
+            if (Object.keys(payload).length > 0) {
+                await this.axiosInstance.put(`/testexecutions/${execKey}`, payload);
+            }
+            // Attach bugs / Jira issues. IssueLinkInput requires a numeric issueId, so resolve each
+            // key via the Jira REST API (needs JIRA_USERNAME + JIRA_API_TOKEN on Cloud), mirroring create_test_case.
+            const linkWarnings = [];
+            let linkedCount = 0;
+            if (hasBugs) {
+                for (const bugKey of bug_keys) {
+                    try {
+                        const issueId = await this.resolveJiraIssueId(bugKey);
+                        await this.axiosInstance.post(`/testexecutions/${execKey}/links/issues`, { issueId });
+                        linkedCount++;
+                    }
+                    catch (e) {
+                        linkWarnings.push(`${bugKey}: ${this.formatError(e)}`);
+                    }
+                }
+            }
+            const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+            const credHint = missingCreds && linkWarnings.length > 0
+                ? '\n💡 Tip: Set JIRA_USERNAME and JIRA_API_TOKEN env vars to enable bug/issue linking on Cloud.'
+                : '';
+            const warningText = linkWarnings.length > 0
+                ? `\n⚠️ Some bug links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
+                : '';
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Updated test execution ${execKey} successfully.\n${JSON.stringify({
+                            executionKey: execKey,
+                            status: status ?? '(unchanged)',
+                            updatedFields: Object.keys(payload),
+                            linkedBugs: linkedCount,
+                        }, null, 2)}${warningText}`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to update test execution: ${this.formatError(error)}`);
+        }
+    }
+    async getTestCyclesForIssue(args) {
+        if (this.jiraConfig.type !== 'cloud') {
+            throw new McpError(ErrorCode.InvalidRequest, 'get_test_cycles_for_issue is only supported on Zephyr Scale Cloud. The Data Center API (v1) does not expose issue-link lookups.');
+        }
+        const { issue_key, resolve_keys = true } = args;
+        if (!issue_key) {
+            throw new McpError(ErrorCode.InvalidParams, 'issue_key is required (e.g. "PROJ-123").');
+        }
+        try {
+            // GET /issuelinks/{issueKey}/testcycles → TestCycleIdList: [{ id, self }, ...]
+            const response = await this.axiosInstance.get(`/issuelinks/${issue_key}/testcycles`);
+            const raw = Array.isArray(response.data)
+                ? response.data
+                : response.data?.values ?? [];
+            const cycleIds = raw
+                .map((c) => c.id ?? c.self?.match(/testcycles\/(\d+)/)?.[1])
+                .filter((id) => id !== undefined && id !== null)
+                .map((id) => String(id));
+            // Optionally resolve each numeric cycle ID to its human-readable key + name.
+            let cycles;
+            if (resolve_keys) {
+                cycles = [];
+                for (const id of cycleIds) {
+                    try {
+                        const cyc = await this.axiosInstance.get(`/testcycles/${id}`);
+                        cycles.push({ id, key: cyc.data?.key ?? null, name: cyc.data?.name ?? null });
+                    }
+                    catch (e) {
+                        cycles.push({ id, key: null, name: null, error: this.formatError(e) });
+                    }
+                }
+            }
+            else {
+                cycles = cycleIds.map((id) => ({ id }));
+            }
+            return {
+                content: [{
+                        type: 'text',
+                        text: `✅ Found ${cycles.length} test cycle(s) linked to ${issue_key}:\n${JSON.stringify({
+                            issueKey: issue_key,
+                            totalCount: cycles.length,
+                            testCycles: cycles,
+                        }, null, 2)}`,
+                    }],
+            };
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to get test cycles for issue: ${this.formatError(error)}`);
+        }
+    }
+    /** Find the latest execution key for a test case within a cycle (Cloud). */
+    async resolveExecutionByCycleAndCase(cycleKey, caseKey, projectKey) {
+        const derivedProject = projectKey || cycleKey.split('-')[0];
+        try {
+            const response = await this.axiosInstance.get('/testexecutions', {
+                params: {
+                    projectKey: derivedProject,
+                    testCycle: cycleKey,
+                    onlyLastExecutions: true,
+                    maxResults: 1000,
+                },
+            });
+            const executions = Array.isArray(response.data)
+                ? response.data
+                : response.data?.values ?? [];
+            const match = executions.find((ex) => {
+                const key = ex.testCase?.self?.match(/testcases\/(.+?)\/versions/)?.[1]
+                    ?? ex.testCase?.key;
+                return key === caseKey;
+            });
+            if (!match) {
+                throw new McpError(ErrorCode.InvalidParams, `No execution found for test case ${caseKey} in cycle ${cycleKey}. Ensure the test case is part of the cycle.`);
+            }
+            const execKey = match.key ?? (match.id !== undefined ? String(match.id) : undefined);
+            if (!execKey) {
+                throw new McpError(ErrorCode.InternalError, `Found a matching execution for ${caseKey} in ${cycleKey} but it has no key or id.`);
+            }
+            return execKey;
+        }
+        catch (error) {
+            if (error instanceof McpError)
+                throw error;
+            throw new McpError(ErrorCode.InternalError, `Failed to resolve execution for ${caseKey} in ${cycleKey}: ${this.formatError(error)}`);
+        }
+    }
     async resolveJiraIssueId(issueKey) {
         // The Zephyr API key is NOT valid for the Jira REST API — Jira Cloud requires
         // Basic Auth: base64(email:api_token) via JIRA_USERNAME + JIRA_API_TOKEN env vars.

package/build/tool-schemas.js

@@ -466,6 +466,83 @@ export const toolSchemas = [
             required: ['test_run_key'],
         },
     },
+    {
+        name: 'update_test_execution',
+        description: 'Update a test case execution\'s status within a test cycle, and optionally attach bug(s) as Jira issue links. Identify the execution either by execution_id directly, or by test_cycle_key + test_case_key (the latest execution is used). Cloud only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                execution_id: {
+                    type: 'string',
+                    description: 'Test execution key or ID (e.g. "PROJ-E123" or 5805255). Takes precedence over test_cycle_key/test_case_key.',
+                },
+                test_cycle_key: {
+                    type: 'string',
+                    description: 'Test cycle key (e.g. "PROJ-R123"). Used together with test_case_key to locate the execution when execution_id is not given.',
+                },
+                test_case_key: {
+                    type: 'string',
+                    description: 'Test case key (e.g. "PROJ-T456"). Used together with test_cycle_key to locate the execution.',
+                },
+                project_key: {
+                    type: 'string',
+                    description: 'Project key for the cycle lookup (optional — derived from test_cycle_key when omitted).',
+                },
+                status: {
+                    type: 'string',
+                    description: 'New execution status name. Common values: "Pass", "Fail", "In Progress", "Blocked", "Not Executed". Must match a status configured in your Zephyr project.',
+                },
+                comment: {
+                    type: 'string',
+                    description: 'Comment against the overall execution (e.g. failure details).',
+                },
+                environment: {
+                    type: 'string',
+                    description: 'Environment name assigned to the execution (e.g. "Chrome Latest Version").',
+                },
+                execution_time: {
+                    type: 'number',
+                    description: 'Actual execution time in milliseconds (optional).',
+                },
+                actual_end_date: {
+                    type: 'string',
+                    description: 'Actual end date in ISO format, e.g. "2024-05-20T13:15:13Z" (optional).',
+                },
+                executed_by_id: {
+                    type: 'string',
+                    description: 'Jira Account ID of the user who executed the test (optional).',
+                },
+                assigned_to_id: {
+                    type: 'string',
+                    description: 'Jira Account ID of the user the execution is assigned to (optional).',
+                },
+                bug_keys: {
+                    type: 'array',
+                    description: 'Jira issue keys to attach to the execution as bugs (e.g. ["PROJ-789"]). Each key is resolved to a numeric ID via the Jira REST API (requires JIRA_USERNAME + JIRA_API_TOKEN) and linked via POST /testexecutions/{key}/links/issues. Failures are reported as warnings and do not fail the call.',
+                    items: { type: 'string' },
+                },
+            },
+        },
+    },
+    {
+        name: 'get_test_cycles_for_issue',
+        description: 'Get the Zephyr test cycles linked to a Jira issue (e.g. a story or epic). Calls GET /issuelinks/{issueKey}/testcycles and, by default, resolves each numeric cycle ID to its key (e.g. "PROJ-R123") and name. Use this to discover the test cycle referenced by a Jira ticket, then feed the key into list_executions_by_cycle / update_test_execution. Cloud only.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                issue_key: {
+                    type: 'string',
+                    description: 'Jira issue key whose linked test cycles to fetch (e.g. "PROJ-123").',
+                },
+                resolve_keys: {
+                    type: 'boolean',
+                    description: 'When true (default), resolve each cycle ID to its key + name via GET /testcycles/{id}. Set false to return raw numeric IDs only (faster, no extra calls).',
+                    default: true,
+                },
+            },
+            required: ['issue_key'],
+        },
+    },
     {
         name: 'delete_test_run',
         description: 'Delete a specific test run (Data Center only — not supported on Cloud v2)',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zephyr-scale-mcp-server",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "Model Context Protocol (MCP) server for Zephyr Scale test case management with comprehensive STEP_BY_STEP, PLAIN_TEXT, and BDD support",
   "type": "module",
   "main": "./build/index.js",

package/src/index.ts

@@ -95,6 +95,10 @@ class ZephyrServer {
             return await this.toolHandlers.addTestCasesToRun(args as any);
           case 'list_executions_by_cycle':
             return await this.toolHandlers.listExecutionsByCycle(args as any);
+          case 'update_test_execution':
+            return await this.toolHandlers.updateTestExecution(args as any);
+          case 'get_test_cycles_for_issue':
+            return await this.toolHandlers.getTestCyclesForIssue(args as any);
           default:
             throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${request.params.name}`);
         }

package/src/tool-handlers.ts

@@ -11,6 +11,8 @@ import {
   SearchTestRunsArgs,
   GetTestExecutionArgs,
   ListExecutionsByCycleArgs,
+  UpdateTestExecutionArgs,
+  GetTestCyclesForIssueArgs,
   JiraConfig
 } from './types.js';
 import { convertToGherkin, resolveFolderIdByPath, getAccountIdFromApiKey } from './utils.js';
@@ -1259,6 +1261,199 @@ export class ZephyrToolHandlers {
     }
   }
 
+  async updateTestExecution(args: UpdateTestExecutionArgs) {
+    if (this.jiraConfig.type !== 'cloud') {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        'update_test_execution is only supported on Zephyr Scale Cloud. The Data Center API (v1) uses a different test-result model.'
+      );
+    }
+
+    const {
+      execution_id, test_cycle_key, test_case_key, project_key,
+      status, comment, environment, execution_time, actual_end_date,
+      executed_by_id, assigned_to_id, bug_keys,
+    } = args;
+
+    // Resolve which execution to update: explicit execution_id wins, otherwise cycle + test case.
+    let execKey = execution_id;
+    if (!execKey) {
+      if (!test_cycle_key || !test_case_key) {
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          'Provide either execution_id, or both test_cycle_key and test_case_key to identify the execution.'
+        );
+      }
+      execKey = await this.resolveExecutionByCycleAndCase(test_cycle_key, test_case_key, project_key);
+    }
+
+    // Build the update payload — the PUT ignores null/undefined and only touches provided fields.
+    const payload: any = {};
+    if (status !== undefined) payload.statusName = status;
+    if (comment !== undefined) payload.comment = comment;
+    if (environment !== undefined) payload.environmentName = environment;
+    if (execution_time !== undefined) payload.executionTime = execution_time;
+    if (actual_end_date !== undefined) payload.actualEndDate = actual_end_date;
+    if (executed_by_id !== undefined) payload.executedById = executed_by_id;
+    if (assigned_to_id !== undefined) payload.assignedToId = assigned_to_id;
+
+    const hasBugs = Array.isArray(bug_keys) && bug_keys.length > 0;
+    if (Object.keys(payload).length === 0 && !hasBugs) {
+      throw new McpError(
+        ErrorCode.InvalidParams,
+        'Nothing to update — provide at least one of: status, comment, environment, execution_time, actual_end_date, executed_by_id, assigned_to_id, or bug_keys.'
+      );
+    }
+
+    try {
+      if (Object.keys(payload).length > 0) {
+        await this.axiosInstance.put(`/testexecutions/${execKey}`, payload);
+      }
+
+      // Attach bugs / Jira issues. IssueLinkInput requires a numeric issueId, so resolve each
+      // key via the Jira REST API (needs JIRA_USERNAME + JIRA_API_TOKEN on Cloud), mirroring create_test_case.
+      const linkWarnings: string[] = [];
+      let linkedCount = 0;
+      if (hasBugs) {
+        for (const bugKey of bug_keys!) {
+          try {
+            const issueId = await this.resolveJiraIssueId(bugKey);
+            await this.axiosInstance.post(`/testexecutions/${execKey}/links/issues`, { issueId });
+            linkedCount++;
+          } catch (e) {
+            linkWarnings.push(`${bugKey}: ${this.formatError(e)}`);
+          }
+        }
+      }
+
+      const missingCreds = !process.env.JIRA_USERNAME || !process.env.JIRA_API_TOKEN;
+      const credHint = missingCreds && linkWarnings.length > 0
+        ? '\n💡 Tip: Set JIRA_USERNAME and JIRA_API_TOKEN env vars to enable bug/issue linking on Cloud.'
+        : '';
+      const warningText = linkWarnings.length > 0
+        ? `\n⚠️ Some bug links failed:\n${linkWarnings.map(w => `  - ${w}`).join('\n')}${credHint}`
+        : '';
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Updated test execution ${execKey} successfully.\n${JSON.stringify({
+            executionKey: execKey,
+            status: status ?? '(unchanged)',
+            updatedFields: Object.keys(payload),
+            linkedBugs: linkedCount,
+          }, null, 2)}${warningText}`,
+        }],
+      };
+    } catch (error) {
+      if (error instanceof McpError) throw error;
+      throw new McpError(ErrorCode.InternalError, `Failed to update test execution: ${this.formatError(error)}`);
+    }
+  }
+
+  async getTestCyclesForIssue(args: GetTestCyclesForIssueArgs) {
+    if (this.jiraConfig.type !== 'cloud') {
+      throw new McpError(
+        ErrorCode.InvalidRequest,
+        'get_test_cycles_for_issue is only supported on Zephyr Scale Cloud. The Data Center API (v1) does not expose issue-link lookups.'
+      );
+    }
+
+    const { issue_key, resolve_keys = true } = args;
+    if (!issue_key) {
+      throw new McpError(ErrorCode.InvalidParams, 'issue_key is required (e.g. "PROJ-123").');
+    }
+
+    try {
+      // GET /issuelinks/{issueKey}/testcycles → TestCycleIdList: [{ id, self }, ...]
+      const response = await this.axiosInstance.get(`/issuelinks/${issue_key}/testcycles`);
+      const raw = Array.isArray(response.data)
+        ? response.data
+        : response.data?.values ?? [];
+
+      const cycleIds: string[] = raw
+        .map((c: any) => c.id ?? c.self?.match(/testcycles\/(\d+)/)?.[1])
+        .filter((id: any) => id !== undefined && id !== null)
+        .map((id: any) => String(id));
+
+      // Optionally resolve each numeric cycle ID to its human-readable key + name.
+      let cycles: any[];
+      if (resolve_keys) {
+        cycles = [];
+        for (const id of cycleIds) {
+          try {
+            const cyc = await this.axiosInstance.get(`/testcycles/${id}`);
+            cycles.push({ id, key: cyc.data?.key ?? null, name: cyc.data?.name ?? null });
+          } catch (e) {
+            cycles.push({ id, key: null, name: null, error: this.formatError(e) });
+          }
+        }
+      } else {
+        cycles = cycleIds.map((id) => ({ id }));
+      }
+
+      return {
+        content: [{
+          type: 'text',
+          text: `✅ Found ${cycles.length} test cycle(s) linked to ${issue_key}:\n${JSON.stringify({
+            issueKey: issue_key,
+            totalCount: cycles.length,
+            testCycles: cycles,
+          }, null, 2)}`,
+        }],
+      };
+    } catch (error) {
+      if (error instanceof McpError) throw error;
+      throw new McpError(ErrorCode.InternalError, `Failed to get test cycles for issue: ${this.formatError(error)}`);
+    }
+  }
+
+  /** Find the latest execution key for a test case within a cycle (Cloud). */
+  private async resolveExecutionByCycleAndCase(
+    cycleKey: string, caseKey: string, projectKey?: string
+  ): Promise<string> {
+    const derivedProject = projectKey || cycleKey.split('-')[0];
+    try {
+      const response = await this.axiosInstance.get('/testexecutions', {
+        params: {
+          projectKey: derivedProject,
+          testCycle: cycleKey,
+          onlyLastExecutions: true,
+          maxResults: 1000,
+        },
+      });
+
+      const executions = Array.isArray(response.data)
+        ? response.data
+        : response.data?.values ?? [];
+
+      const match = executions.find((ex: any) => {
+        const key = ex.testCase?.self?.match(/testcases\/(.+?)\/versions/)?.[1]
+          ?? ex.testCase?.key;
+        return key === caseKey;
+      });
+
+      if (!match) {
+        throw new McpError(
+          ErrorCode.InvalidParams,
+          `No execution found for test case ${caseKey} in cycle ${cycleKey}. Ensure the test case is part of the cycle.`
+        );
+      }
+
+      const execKey = match.key ?? (match.id !== undefined ? String(match.id) : undefined);
+      if (!execKey) {
+        throw new McpError(
+          ErrorCode.InternalError,
+          `Found a matching execution for ${caseKey} in ${cycleKey} but it has no key or id.`
+        );
+      }
+      return execKey;
+    } catch (error) {
+      if (error instanceof McpError) throw error;
+      throw new McpError(ErrorCode.InternalError, `Failed to resolve execution for ${caseKey} in ${cycleKey}: ${this.formatError(error)}`);
+    }
+  }
+
   private async resolveJiraIssueId(issueKey: string): Promise<number> {
     // The Zephyr API key is NOT valid for the Jira REST API — Jira Cloud requires
     // Basic Auth: base64(email:api_token) via JIRA_USERNAME + JIRA_API_TOKEN env vars.

package/src/tool-schemas.ts

@@ -466,6 +466,83 @@ export const toolSchemas = [
       required: ['test_run_key'],
     },
   },
+  {
+    name: 'update_test_execution',
+    description: 'Update a test case execution\'s status within a test cycle, and optionally attach bug(s) as Jira issue links. Identify the execution either by execution_id directly, or by test_cycle_key + test_case_key (the latest execution is used). Cloud only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        execution_id: {
+          type: 'string',
+          description: 'Test execution key or ID (e.g. "PROJ-E123" or 5805255). Takes precedence over test_cycle_key/test_case_key.',
+        },
+        test_cycle_key: {
+          type: 'string',
+          description: 'Test cycle key (e.g. "PROJ-R123"). Used together with test_case_key to locate the execution when execution_id is not given.',
+        },
+        test_case_key: {
+          type: 'string',
+          description: 'Test case key (e.g. "PROJ-T456"). Used together with test_cycle_key to locate the execution.',
+        },
+        project_key: {
+          type: 'string',
+          description: 'Project key for the cycle lookup (optional — derived from test_cycle_key when omitted).',
+        },
+        status: {
+          type: 'string',
+          description: 'New execution status name. Common values: "Pass", "Fail", "In Progress", "Blocked", "Not Executed". Must match a status configured in your Zephyr project.',
+        },
+        comment: {
+          type: 'string',
+          description: 'Comment against the overall execution (e.g. failure details).',
+        },
+        environment: {
+          type: 'string',
+          description: 'Environment name assigned to the execution (e.g. "Chrome Latest Version").',
+        },
+        execution_time: {
+          type: 'number',
+          description: 'Actual execution time in milliseconds (optional).',
+        },
+        actual_end_date: {
+          type: 'string',
+          description: 'Actual end date in ISO format, e.g. "2024-05-20T13:15:13Z" (optional).',
+        },
+        executed_by_id: {
+          type: 'string',
+          description: 'Jira Account ID of the user who executed the test (optional).',
+        },
+        assigned_to_id: {
+          type: 'string',
+          description: 'Jira Account ID of the user the execution is assigned to (optional).',
+        },
+        bug_keys: {
+          type: 'array',
+          description: 'Jira issue keys to attach to the execution as bugs (e.g. ["PROJ-789"]). Each key is resolved to a numeric ID via the Jira REST API (requires JIRA_USERNAME + JIRA_API_TOKEN) and linked via POST /testexecutions/{key}/links/issues. Failures are reported as warnings and do not fail the call.',
+          items: { type: 'string' },
+        },
+      },
+    },
+  },
+  {
+    name: 'get_test_cycles_for_issue',
+    description: 'Get the Zephyr test cycles linked to a Jira issue (e.g. a story or epic). Calls GET /issuelinks/{issueKey}/testcycles and, by default, resolves each numeric cycle ID to its key (e.g. "PROJ-R123") and name. Use this to discover the test cycle referenced by a Jira ticket, then feed the key into list_executions_by_cycle / update_test_execution. Cloud only.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        issue_key: {
+          type: 'string',
+          description: 'Jira issue key whose linked test cycles to fetch (e.g. "PROJ-123").',
+        },
+        resolve_keys: {
+          type: 'boolean',
+          description: 'When true (default), resolve each cycle ID to its key + name via GET /testcycles/{id}. Set false to return raw numeric IDs only (faster, no extra calls).',
+          default: true,
+        },
+      },
+      required: ['issue_key'],
+    },
+  },
   {
     name: 'delete_test_run',
     description: 'Delete a specific test run (Data Center only — not supported on Cloud v2)',

package/src/types.ts

@@ -102,6 +102,34 @@ export interface ListExecutionsByCycleArgs {
   max_results?: number;
 }
 
+export interface UpdateTestExecutionArgs {
+  /** Direct execution key/ID (e.g. "PROJ-E123" or 5805255). Takes precedence over cycle+case lookup. */
+  execution_id?: string;
+  /** Test cycle key (e.g. "PROJ-R123") — used with test_case_key to locate the execution. */
+  test_cycle_key?: string;
+  /** Test case key (e.g. "PROJ-T456") — used with test_cycle_key to locate the execution. */
+  test_case_key?: string;
+  /** Project key for the cycle lookup. Derived from test_cycle_key when omitted. */
+  project_key?: string;
+  /** New execution status name (e.g. "Pass", "Fail", "In Progress", "Blocked", "Not Executed"). */
+  status?: string;
+  comment?: string;
+  environment?: string;
+  execution_time?: number;
+  actual_end_date?: string;
+  executed_by_id?: string;
+  assigned_to_id?: string;
+  /** Jira issue keys to link to the execution as bugs (e.g. ["PROJ-789"]). Resolved to numeric IDs via the Jira REST API. */
+  bug_keys?: string[];
+}
+
+export interface GetTestCyclesForIssueArgs {
+  /** Jira issue key whose linked test cycles to fetch (e.g. "PROJ-123"). */
+  issue_key: string;
+  /** When true (default), resolve each cycle ID to its key + name via GET /testcycles/{id}. */
+  resolve_keys?: boolean;
+}
+
 export type JiraType = 'cloud' | 'datacenter';
 
 export interface ApiEndpoints {