zephyr-scale-mcp-server 0.6.0 → 0.8.0

package/README.md

@@ -107,17 +107,22 @@ The server provides access to various resources through URI schemes:
 
 ### Test Run Management
 - `create_test_run`: Create a new test run.
-- `get_test_run`: Get detailed information about a specific test run.
+- `get_test_run`: Get detailed information about a specific test run, including resolved status name.
+- `update_test_run`: Update an existing test cycle — set owner, name, description, dates, or status. *(Cloud only)*
 - `get_test_run_cases`: Get test case keys from a test run.
 - `add_test_cases_to_run`: Add test cases to an existing test run. *(Cloud only)*
 
 ### Test Execution & Search
 - `get_test_execution`: Get detailed individual test execution results.
-- `search_test_cases_by_folder`: Search for test cases in a specific folder.
+- `list_executions_by_cycle`: List all test executions for a specific test cycle with status, executor, and date. *(Cloud only)*
+- `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
 
@@ -159,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

@@ -51,6 +51,8 @@ class ZephyrServer {
                         return await this.toolHandlers.updateTestCaseBdd(args);
                     case 'create_folder':
                         return await this.toolHandlers.createFolder(args);
+                    case 'get_folders':
+                        return await this.toolHandlers.getFolders(args);
                     case 'get_test_run_cases':
                         return await this.toolHandlers.getTestRunCases(args);
                     case 'delete_test_case':
@@ -73,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

@@ -743,6 +743,79 @@ export class ZephyrToolHandlers {
             throw new McpError(ErrorCode.InternalError, `Failed to create test run: ${this.formatError(error)}`);
         }
     }
+    async getFolders(args) {
+        const { project_key, folder_type, folder_path, max_results } = args;
+        try {
+            const pageSize = 1000;
+            const allFolders = [];
+            let startAt = 0;
+            let isLast = false;
+            while (!isLast) {
+                const params = { maxResults: pageSize, startAt };
+                if (project_key)
+                    params.projectKey = project_key;
+                if (folder_type)
+                    params.folderType = folder_type;
+                const response = await this.axiosInstance.get('/folders', { params });
+                const page = Array.isArray(response.data)
+                    ? response.data
+                    : response.data?.values ?? [];
+                allFolders.push(...page);
+                isLast = response.data?.isLast === true || page.length < pageSize;
+                startAt += page.length;
+                if (max_results && allFolders.length >= max_results)
+                    break;
+            }
+            let results;
+            if (folder_path) {
+                // Resolve the root folder ID from the path, then collect full subtree via BFS
+                const rootId = await resolveFolderIdByPath(this.axiosInstance, project_key, folder_path, folder_type ?? 'TEST_CASE');
+                if (rootId === null) {
+                    return {
+                        content: [{
+                                type: 'text',
+                                text: `⚠️ Folder not found: "${folder_path}" in project ${project_key}.`,
+                            }],
+                    };
+                }
+                // BFS over the already-fetched flat list — no extra API calls
+                const subtreeIds = new Set([rootId]);
+                const queue = [rootId];
+                while (queue.length > 0) {
+                    const current = queue.shift();
+                    for (const f of allFolders) {
+                        if ((f.parentId ?? null) === current && !subtreeIds.has(f.id)) {
+                            subtreeIds.add(f.id);
+                            queue.push(f.id);
+                        }
+                    }
+                }
+                results = allFolders.filter(f => subtreeIds.has(f.id));
+            }
+            else {
+                results = allFolders;
+            }
+            if (max_results)
+                results = results.slice(0, max_results);
+            return {
+                content: [{
+                        type: 'text',
+                        text: JSON.stringify({
+                            totalCount: results.length,
+                            folders: results.map((f) => ({
+                                id: f.id,
+                                name: f.name,
+                                parentId: f.parentId ?? null,
+                                folderType: f.folderType,
+                            })),
+                        }, null, 2),
+                    }],
+            };
+        }
+        catch (error) {
+            throw new McpError(ErrorCode.InternalError, `Failed to get folders: ${this.formatError(error)}`);
+        }
+    }
     async resolveStatusName(statusId) {
         try {
             const response = await this.axiosInstance.get(`/statuses/${statusId}`);
@@ -837,12 +910,27 @@ export class ZephyrToolHandlers {
                             }],
                     };
                 }
-                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 ?? [];
+                // Paginate through all results — the API returns up to 1000 per page
+                const pageSize = Math.min(max_results, 1000);
+                const allTestCases = [];
+                let startAt = 0;
+                let isLast = false;
+                while (!isLast && allTestCases.length < max_results) {
+                    const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.testcase, {
+                        params: { projectKey: project_key, folderId, maxResults: pageSize, startAt },
+                    });
+                    const page = Array.isArray(response.data)
+                        ? response.data
+                        : response.data?.values ?? [];
+                    allTestCases.push(...page);
+                    // Stop if the API signals last page, or we got fewer results than requested
+                    isLast = response.data?.isLast === true || page.length < pageSize;
+                    startAt += page.length;
+                    // Safety: never exceed max_results
+                    if (allTestCases.length >= max_results)
+                        break;
+                }
+                const testCases = allTestCases.slice(0, max_results);
                 return {
                     content: [{
                             type: 'text',
@@ -1063,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

@@ -196,6 +196,32 @@ export const toolSchemas = [
             required: ['project_key', 'name'],
         },
     },
+    {
+        name: 'get_folders',
+        description: 'Get folders from Zephyr Scale. All parameters are optional. If folder_path is provided, returns the full subtree (the folder and all its descendants at every depth) under that path. Otherwise returns all folders matching the filters.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                project_key: {
+                    type: 'string',
+                    description: 'Jira project key filter (e.g., "PROJ"). Optional.',
+                },
+                folder_type: {
+                    type: 'string',
+                    description: 'Folder type filter (optional)',
+                    enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_CYCLE'],
+                },
+                folder_path: {
+                    type: 'string',
+                    description: 'Folder path to filter by (e.g., "/CRM on Wechat"). Returns the matching folder and all folders nested beneath it at any depth. Requires project_key and folder_type to resolve the path.',
+                },
+                max_results: {
+                    type: 'number',
+                    description: 'Maximum total number of folders to return (optional). Defaults to all folders.',
+                },
+            },
+        },
+    },
     {
         name: 'get_test_run_cases',
         description: 'Get test case keys from a test run',
@@ -440,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/build/utils.js

@@ -4,18 +4,27 @@ export async function resolveFolderIdByPath(axiosInstance, projectKey, folderPat
     if (segments.length === 0)
         return null;
     try {
-        // Fetch all folders for the project + type (up to 1000)
-        const response = await axiosInstance.get('/folders', {
-            params: { projectKey, folderType, maxResults: 1000 },
-        });
-        const folders = Array.isArray(response.data)
-            ? response.data
-            : response.data?.values ?? [];
+        // Paginate through all folders for the project + type
+        const pageSize = 1000;
+        const allFolders = [];
+        let startAt = 0;
+        let isLast = false;
+        while (!isLast) {
+            const response = await axiosInstance.get('/folders', {
+                params: { projectKey, folderType, maxResults: pageSize, startAt },
+            });
+            const page = Array.isArray(response.data)
+                ? response.data
+                : response.data?.values ?? [];
+            allFolders.push(...page);
+            isLast = response.data?.isLast === true || page.length < pageSize;
+            startAt += page.length;
+        }
         // Walk segments top-down, matching by name under the correct parent
         let parentId = null;
         let matchedId = null;
         for (const segment of segments) {
-            const match = folders.find((f) => f.name === segment && (f.parentId ?? null) === parentId);
+            const match = allFolders.find((f) => f.name === segment && (f.parentId ?? null) === parentId);
             if (!match)
                 return null;
             matchedId = match.id;

package/package.json

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

@@ -71,6 +71,8 @@ class ZephyrServer {
             return await this.toolHandlers.updateTestCaseBdd(args as any);
           case 'create_folder':
             return await this.toolHandlers.createFolder(args as any);
+          case 'get_folders':
+            return await this.toolHandlers.getFolders(args as any);
           case 'get_test_run_cases':
             return await this.toolHandlers.getTestRunCases(args);
           case 'delete_test_case':
@@ -93,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';
@@ -800,6 +802,90 @@ export class ZephyrToolHandlers {
     }
   }
 
+  async getFolders(args: any) {
+    const { project_key, folder_type, folder_path, max_results } = args;
+
+    try {
+      const pageSize = 1000;
+      const allFolders: any[] = [];
+      let startAt = 0;
+      let isLast = false;
+
+      while (!isLast) {
+        const params: Record<string, any> = { maxResults: pageSize, startAt };
+        if (project_key) params.projectKey = project_key;
+        if (folder_type) params.folderType = folder_type;
+
+        const response = await this.axiosInstance.get('/folders', { params });
+
+        const page: any[] = Array.isArray(response.data)
+          ? response.data
+          : response.data?.values ?? [];
+
+        allFolders.push(...page);
+
+        isLast = response.data?.isLast === true || page.length < pageSize;
+        startAt += page.length;
+
+        if (max_results && allFolders.length >= max_results) break;
+      }
+
+      let results: any[];
+
+      if (folder_path) {
+        // Resolve the root folder ID from the path, then collect full subtree via BFS
+        const rootId = await resolveFolderIdByPath(
+          this.axiosInstance, project_key, folder_path, folder_type ?? 'TEST_CASE'
+        );
+
+        if (rootId === null) {
+          return {
+            content: [{
+              type: 'text',
+              text: `⚠️ Folder not found: "${folder_path}" in project ${project_key}.`,
+            }],
+          };
+        }
+
+        // BFS over the already-fetched flat list — no extra API calls
+        const subtreeIds = new Set<number>([rootId]);
+        const queue = [rootId];
+        while (queue.length > 0) {
+          const current = queue.shift()!;
+          for (const f of allFolders) {
+            if ((f.parentId ?? null) === current && !subtreeIds.has(f.id)) {
+              subtreeIds.add(f.id);
+              queue.push(f.id);
+            }
+          }
+        }
+
+        results = allFolders.filter(f => subtreeIds.has(f.id));
+      } else {
+        results = allFolders;
+      }
+
+      if (max_results) results = results.slice(0, max_results);
+
+      return {
+        content: [{
+          type: 'text',
+          text: JSON.stringify({
+            totalCount: results.length,
+            folders: results.map((f: any) => ({
+              id: f.id,
+              name: f.name,
+              parentId: f.parentId ?? null,
+              folderType: f.folderType,
+            })),
+          }, null, 2),
+        }],
+      };
+    } catch (error) {
+      throw new McpError(ErrorCode.InternalError, `Failed to get folders: ${this.formatError(error)}`);
+    }
+  }
+
   private async resolveStatusName(statusId: number): Promise<string | null> {
     try {
       const response = await this.axiosInstance.get(`/statuses/${statusId}`);
@@ -908,13 +994,32 @@ export class ZephyrToolHandlers {
           };
         }
 
-        const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.testcase, {
-          params: { projectKey: project_key, folderId, maxResults: max_results },
-        });
+        // Paginate through all results — the API returns up to 1000 per page
+        const pageSize = Math.min(max_results, 1000);
+        const allTestCases: any[] = [];
+        let startAt = 0;
+        let isLast = false;
 
-        const testCases = Array.isArray(response.data)
-          ? response.data
-          : response.data?.values ?? [];
+        while (!isLast && allTestCases.length < max_results) {
+          const response = await this.axiosInstance.get(this.jiraConfig.apiEndpoints.testcase, {
+            params: { projectKey: project_key, folderId, maxResults: pageSize, startAt },
+          });
+
+          const page = Array.isArray(response.data)
+            ? response.data
+            : response.data?.values ?? [];
+
+          allTestCases.push(...page);
+
+          // Stop if the API signals last page, or we got fewer results than requested
+          isLast = response.data?.isLast === true || page.length < pageSize;
+          startAt += page.length;
+
+          // Safety: never exceed max_results
+          if (allTestCases.length >= max_results) break;
+        }
+
+        const testCases = allTestCases.slice(0, max_results);
 
         return {
           content: [{
@@ -1156,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

@@ -196,6 +196,32 @@ export const toolSchemas = [
       required: ['project_key', 'name'],
     },
   },
+  {
+    name: 'get_folders',
+    description: 'Get folders from Zephyr Scale. All parameters are optional. If folder_path is provided, returns the full subtree (the folder and all its descendants at every depth) under that path. Otherwise returns all folders matching the filters.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project_key: {
+          type: 'string',
+          description: 'Jira project key filter (e.g., "PROJ"). Optional.',
+        },
+        folder_type: {
+          type: 'string',
+          description: 'Folder type filter (optional)',
+          enum: ['TEST_CASE', 'TEST_PLAN', 'TEST_CYCLE'],
+        },
+        folder_path: {
+          type: 'string',
+          description: 'Folder path to filter by (e.g., "/CRM on Wechat"). Returns the matching folder and all folders nested beneath it at any depth. Requires project_key and folder_type to resolve the path.',
+        },
+        max_results: {
+          type: 'number',
+          description: 'Maximum total number of folders to return (optional). Defaults to all folders.',
+        },
+      },
+    },
+  },
   {
     name: 'get_test_run_cases',
     description: 'Get test case keys from a test run',
@@ -440,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 {

package/src/utils.ts

@@ -11,22 +11,34 @@ export async function resolveFolderIdByPath(
   if (segments.length === 0) return null;
 
   try {
-    // Fetch all folders for the project + type (up to 1000)
-    const response = await axiosInstance.get('/folders', {
-      params: { projectKey, folderType, maxResults: 1000 },
-    });
-
-    const folders: Array<{ id: number; parentId: number | null; name: string }> =
-      Array.isArray(response.data)
-        ? response.data
-        : response.data?.values ?? [];
+    // Paginate through all folders for the project + type
+    const pageSize = 1000;
+    const allFolders: Array<{ id: number; parentId: number | null; name: string }> = [];
+    let startAt = 0;
+    let isLast = false;
+
+    while (!isLast) {
+      const response = await axiosInstance.get('/folders', {
+        params: { projectKey, folderType, maxResults: pageSize, startAt },
+      });
+
+      const page: Array<{ id: number; parentId: number | null; name: string }> =
+        Array.isArray(response.data)
+          ? response.data
+          : response.data?.values ?? [];
+
+      allFolders.push(...page);
+
+      isLast = response.data?.isLast === true || page.length < pageSize;
+      startAt += page.length;
+    }
 
     // Walk segments top-down, matching by name under the correct parent
     let parentId: number | null = null;
     let matchedId: number | null = null;
 
     for (const segment of segments) {
-      const match = folders.find(
+      const match = allFolders.find(
         (f) => f.name === segment && (f.parentId ?? null) === parentId
       );
       if (!match) return null;