@smartbear/mcp 0.22.0 → 0.24.0

package/dist/qtm4j/schema/test-cycle.schema.js

@@ -0,0 +1,39 @@
+import * as zod from "zod";
+const CreateTestCycleBody = zod.object({
+  summary: zod.string().min(1).max(255).describe(
+    "Short title of the test cycle. Must not be blank. Max 255 chars."
+  ),
+  description: zod.string().max(65535).optional().describe("Detailed description of the test cycle. Max 65 535 characters."),
+  priority: zod.string().optional().describe(
+    "Priority name (e.g., 'High', 'Medium', 'Low'). Auto-resolved to ID."
+  ),
+  status: zod.string().optional().describe(
+    "Status name (e.g., 'To Do', 'In Progress', 'Done'). Auto-resolved to ID."
+  ),
+  assignee: zod.string().optional().describe("Assignee account ID"),
+  reporter: zod.string().optional().describe("Reporter account ID"),
+  labels: zod.array(zod.string()).optional().describe(
+    "List of label names (e.g., ['Release_1', 'Sprint 1']). Auto-resolved to IDs."
+  ),
+  components: zod.array(zod.string()).optional().describe(
+    "List of component names (e.g., ['UI', 'Cloud']). Auto-resolved to IDs."
+  ),
+  plannedStartDate: zod.string().regex(/^\d{2}\/[A-Za-z]{3}\/\d{4} \d{2}:\d{2}$/).optional().describe(
+    "Planned start date. Format: 'dd/MMM/yyyy HH:mm' e.g. '10/May/2026 00:00'. Must be ≤ plannedEndDate when both are provided."
+  ),
+  plannedEndDate: zod.string().regex(/^\d{2}\/[A-Za-z]{3}\/\d{4} \d{2}:\d{2}$/).optional().describe(
+    "Planned end date. Format: 'dd/MMM/yyyy HH:mm' e.g. '15/May/2026 00:00'. Must be ≥ plannedStartDate when both are provided."
+  )
+});
+const CreateTestCycleResponse = zod.object({
+  id: zod.string().describe(
+    "Opaque permanent identifier of the created test cycle. Use this in all subsequent API calls."
+  ),
+  key: zod.string().describe(
+    "Human-readable project-scoped key in format '<PROJECT_KEY>-TR-<number>'. e.g. 'TRWT-TR-218'."
+  )
+});
+export {
+  CreateTestCycleBody,
+  CreateTestCycleResponse
+};

package/dist/qtm4j/schema/update-test-cycle.schema.js

@@ -0,0 +1,54 @@
+import * as zod from "zod";
+const MetadataAddDelete = zod.object({
+  add: zod.array(zod.string()).optional().describe(
+    "Names to add (e.g., ['Regression', 'Smoke']). Auto-resolved to IDs."
+  ),
+  delete: zod.array(zod.string()).optional().describe("Names to remove (e.g., ['Sprint1']). Auto-resolved to IDs.")
+}).describe(
+  "Add or remove entries by name. Both add and delete are optional — omit either to skip that operation."
+);
+const DATETIME_REGEX = /^\d{2}\/[A-Za-z]{3}\/\d{4} \d{2}:\d{2}$/;
+const DATETIME_DESCRIPTION = "Format: 'dd/MMM/yyyy HH:mm' e.g. '15/May/2026 09:00'. Month must be capitalised (May not may). Pass null to clear the existing value.";
+const UpdateTestCycleBody = zod.object({
+  key: zod.string().describe(
+    "Test cycle key in the format '{PROJECT_KEY}-TR-{number}', e.g. 'SCRUM-TR-101'. Used directly as the API path parameter."
+  ),
+  summary: zod.string().min(1, "Summary cannot be blank.").max(255, "Summary must not exceed 255 characters.").optional().describe("Updated test cycle name / title. Max 255 characters."),
+  description: zod.string().max(65535, "Description must not exceed 65,535 characters.").nullable().optional().describe(
+    "Updated description. Pass null to clear the existing value. Max 65 535 characters."
+  ),
+  status: zod.string().nullable().optional().describe(
+    "Status name (e.g., 'To Do', 'In Progress', 'Done'). Auto-resolved to ID. Use values from set_project_context response. Pass null to clear."
+  ),
+  priority: zod.string().nullable().optional().describe(
+    "Priority name (e.g., 'High', 'Medium', 'Low'). Auto-resolved to ID. Use values from set_project_context response. Pass null to clear."
+  ),
+  plannedStartDate: zod.string().regex(
+    DATETIME_REGEX,
+    "Invalid format. Use dd/MMM/yyyy HH:mm e.g. 15/May/2026 09:00"
+  ).nullable().optional().describe(DATETIME_DESCRIPTION),
+  plannedEndDate: zod.string().regex(
+    DATETIME_REGEX,
+    "Invalid format. Use dd/MMM/yyyy HH:mm e.g. 30/May/2026 18:00"
+  ).nullable().optional().describe(DATETIME_DESCRIPTION),
+  assignee: zod.string().nullable().optional().describe(
+    "Assignee Jira account ID (e.g., '5b10a2844c20165700ede21f'). Pass null to unassign."
+  ),
+  reporter: zod.string().nullable().optional().describe(
+    "Reporter Jira account ID (e.g., '5b10a2844c20165700ede21f'). Pass null to clear."
+  ),
+  labels: MetadataAddDelete.optional().describe(
+    "Labels to add or remove by name. Each name is auto-resolved to its ID."
+  ),
+  components: MetadataAddDelete.optional().describe(
+    "Components to add or remove by name. Each name is auto-resolved to its ID."
+  )
+});
+const UpdateTestCycleResponse = zod.object({
+  key: zod.string().describe("Human-readable key of the updated test cycle"),
+  updated: zod.literal(true).describe("Confirms the update was applied")
+});
+export {
+  UpdateTestCycleBody,
+  UpdateTestCycleResponse
+};

package/dist/qtm4j/tool/test-automation/get-automation-history.js

@@ -0,0 +1,69 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { GetAutomationHistoryResponse, GetAutomationHistoryBody } from "../../schema/automation.schema.js";
+class GetAutomationHistory extends Tool {
+  specification = {
+    title: TOOL_NAMES.GET_AUTOMATION_HISTORY.TITLE,
+    summary: TOOL_NAMES.GET_AUTOMATION_HISTORY.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    inputSchema: GetAutomationHistoryBody,
+    outputSchema: GetAutomationHistoryResponse,
+    purpose: "Retrieve a paginated list of past automation result uploads from QTM4J. Use this to review upload history, check upload statuses, and audit past CI/CD automation runs. No set_project_context call is required.",
+    useCases: [
+      "Review past automation result uploads for a project",
+      "Check the status of recent automation imports",
+      "Audit CI/CD automation upload history",
+      "Paginate through all historical automation uploads"
+    ],
+    examples: [
+      {
+        description: "Get the first page of automation upload history (default page size 20)",
+        parameters: {},
+        expectedOutput: "Paginated list of automation history records with upload status and metadata"
+      },
+      {
+        description: "Get the second page of automation upload history",
+        parameters: {
+          startAt: 20,
+          maxResults: 20
+        },
+        expectedOutput: "Next 20 automation history records"
+      },
+      {
+        description: "Get up to 50 records starting from the beginning",
+        parameters: {
+          startAt: 0,
+          maxResults: 50
+        },
+        expectedOutput: "Up to 50 automation history records"
+      }
+    ],
+    hints: [
+      "NO PROJECT CONTEXT REQUIRED: Do NOT call set_project_context and do NOT ask the user for a project key, project ID, or any other project details. This tool works independently.",
+      "PAGINATION: startAt is zero-indexed (default: 0), maxResults controls page size (default: 20, max: 100). Increment startAt by maxResults to fetch the next page.",
+      "Returns an empty data array (not an error) when no history records exist.",
+      "DISPLAY FORMAT: Show '1–N of <total>' above all cards. Render each record as a card separated by --- dividers. Each card has two sections:\n\nPRIMARY SECTION (always first): heading with status emoji (✅ SUCCESS / ❌ FAILED) + test cycle key and name; then format, start→end time, message, summary stats (test cases/versions created/reused/test steps), tracking ID.\n\nEXTRA DETAILS SECTION (at the bottom of the card, under a 'Details' sub-label): any remaining non-null fields from the record such as fileSize, extraAttributes values, etc.\n\nSkip any field that is null, missing, or false. NEVER show the raw fileName. NEVER use a table."
+    ],
+    outputDescription: "Paginated list of automation import history. Each record includes: format, processStatus, importStatus, startTime, endTime, trackingId, detailedMessage, and a summary array. summary[0] contains: testCycleIssueKey, testCycleSummary, testCasesCreated, testCaseVersionsCreated, testCaseVersionsReused, testStepsCreated. Render as individual cards separated by dividers, NOT a table. Show '1–N of total' count above. Never show raw fileName."
+  };
+  handle = async (rawArgs) => {
+    const args = GetAutomationHistoryBody.parse(rawArgs);
+    const apiClient = this.client.getApiClient();
+    const response = await apiClient.getAutomation(
+      ENDPOINTS.AUTOMATION_HISTORY,
+      {
+        startAt: args.startAt,
+        maxResults: args.maxResults
+      }
+    );
+    const result = GetAutomationHistoryResponse.parse(response);
+    return {
+      structuredContent: result,
+      content: []
+    };
+  };
+}
+export {
+  GetAutomationHistory
+};

package/dist/qtm4j/tool/test-automation/upload-automation-result.js

@@ -0,0 +1,143 @@
+import { readFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOL_NAMES, AUTOMATION_RESULT_DIRS, AUTOMATION_LIMITS, ENDPOINTS } from "../../config/constants.js";
+import { UploadAutomationResultResponse, UploadAutomationResultBody } from "../../schema/automation.schema.js";
+const SUPPORTED_EXTENSIONS = /* @__PURE__ */ new Set([".xml", ".json", ".zip"]);
+class UploadAutomationResult extends Tool {
+  specification = {
+    title: TOOL_NAMES.UPLOAD_AUTOMATION_RESULT.TITLE,
+    summary: TOOL_NAMES.UPLOAD_AUTOMATION_RESULT.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    inputSchema: UploadAutomationResultBody,
+    outputSchema: UploadAutomationResultResponse,
+    purpose: `Upload an automation result file from disk to QTM4J and map results to a test cycle. No set_project_context call is required — this tool works independently of any project context. When the user asks to upload or import automation results, search these directories: ${AUTOMATION_RESULT_DIRS.join(", ")}. Infer the format from the file name where possible; confirm with the user only when the format is ambiguous. Returns a trackingId to track the asynchronous import progress.`,
+    useCases: [
+      "Upload automation results to QTM4J",
+      "Import test results from a CI/CD pipeline run",
+      "Link test results to an existing test cycle",
+      "Create a new test cycle from automation results",
+      "Upload JUnit, TestNG, Cucumber, QAF, HP UFT, or SpecFlow result files"
+    ],
+    examples: [
+      {
+        description: "User says 'upload my test results to QTM4J' — scan workspace, find single result file, confirm and upload",
+        parameters: {
+          filePath: "./target/surefire-reports/TEST-results.xml",
+          format: "junit"
+        },
+        expectedOutput: "trackingId returned; import processing started in QTM4J"
+      },
+      {
+        description: "User wants results linked to an existing test cycle",
+        parameters: {
+          filePath: "./reports/cucumber.json",
+          format: "cucumber",
+          testCycleToReuse: "TR-PRJ-5",
+          environment: "Chrome",
+          build: "2.1.0"
+        },
+        expectedOutput: "Results mapped to test cycle TR-PRJ-5"
+      },
+      {
+        description: "Upload QAF ZIP and set test cycle metadata",
+        parameters: {
+          filePath: "./results/qaf-results.zip",
+          format: "qaf",
+          isZip: true,
+          fields: {
+            testCycle: {
+              summary: "Regression Run 2024-Q1",
+              labels: ["regression"],
+              priority: "High"
+            }
+          }
+        },
+        expectedOutput: "ZIP uploaded; test cycle created with summary, labels, and priority"
+      },
+      {
+        description: "User provides an unrecognised priority value — do NOT silently map to a similar word; ask the user first",
+        parameters: {
+          filePath: "./reports/cucumber.json",
+          format: "cucumber",
+          fields: { testCycle: { priority: "critical" } }
+        },
+        expectedOutput: "Tool is NOT called yet. Inform the user that 'critical' was not recognised as a valid priority and ask them to confirm the correct value (e.g. from the available options). Do not map 'critical' to 'Blocker' or any other value without explicit user confirmation."
+      }
+    ],
+    hints: [
+      "NO PROJECT CONTEXT REQUIRED: Do NOT call set_project_context and do NOT ask the user for a project key, project ID, or any other project details. This tool works independently — never prompt the user for project information.",
+      `FILE DISCOVERY: Always do a fresh scan — never reuse a path from a previous turn. If no path is provided, search in order: ${AUTOMATION_RESULT_DIRS.join(", ")}. If exactly one file is found, show the path and inferred format to the user and confirm before uploading. If multiple files are found, list them all and wait for the user to pick one. If nothing is found, ask for the path. Never pick or upload silently.`,
+      "FORMAT INFERENCE: .json → cucumber (unambiguous). For .xml, infer from the file name — 'junit'/'surefire' → junit, 'testng' → testng, 'specflow' → specflow, 'hpuft'/'uft' → hpuft. For .zip, ALWAYS set isZip: true, but do NOT assume qaf — the zip could contain junit, testng, or cucumber results; if the format cannot be determined from the file name, ask the user. If the file name gives no clear signal for .xml either, ask the user to confirm the format.",
+      "TEST CYCLE: Only ask for testCycleToReuse if the user explicitly wants to link to an existing cycle. If not mentioned, omit it — QTM4J creates a new test cycle automatically.",
+      "DATE FORMAT: plannedStartDate and plannedEndDate in fields.testCycle MUST be formatted as 'dd/MMM/yyyy HH:mm' (e.g. '14/May/2026 10:30'). Convert any user-provided date (ISO, natural language, relative) to this exact format before sending.",
+      "FOLDER ID: folderId is a numeric ID. Apply it ONLY to the level the user specifies; if unspecified, default to fields.testCycle only — never copy it to both levels. Get the ID from the user directly (right-click folder in QTM4J → 'Copy Folder Id').",
+      "ASSIGNEE / REPORTER: assignee and reporter in fields.testCycle and fields.testCase require a Jira Account ID (not a display name or email). Ask the user to provide their Account ID directly.",
+      "FIELD MAPPING CONFIRMATION: Apply formatting transformations (case correction, date/time conversion) automatically. Only ask for user confirmation when you cannot find a recognised match and need to substitute an unrecognised value with a guessed alternative — never silently substitute in that case.",
+      "TRACKING: Import processing is asynchronous. To check status, call get_automation_history and find the record whose trackingId matches the one returned from this tool."
+    ],
+    outputDescription: "trackingId to poll import status, a message from the API, the filePath uploaded, and the format used."
+  };
+  handle = async (rawArgs) => {
+    const args = UploadAutomationResultBody.parse(rawArgs);
+    const { filePath, format, isZip, fields, ...rest } = args;
+    const ext = extname(filePath).toLowerCase();
+    if (!SUPPORTED_EXTENSIONS.has(ext)) {
+      throw new ToolError(
+        `Unsupported file extension '${ext}'. Supported extensions: .xml, .json, .zip`
+      );
+    }
+    if (format === "qaf" && !isZip) {
+      throw new ToolError(
+        "QAF format requires a ZIP file. Set isZip: true and provide a .zip file."
+      );
+    }
+    let fileBuffer;
+    try {
+      fileBuffer = await readFile(filePath);
+    } catch (err) {
+      throw new ToolError(
+        `Could not read file at '${filePath}': ${err.message}`
+      );
+    }
+    if (fileBuffer.byteLength > AUTOMATION_LIMITS.MAX_FILE_SIZE_BYTES) {
+      const sizeMB = (fileBuffer.byteLength / (1024 * 1024)).toFixed(2);
+      throw new ToolError(
+        `File is too large (${sizeMB} MB). Maximum allowed size is 10 MB.`
+      );
+    }
+    const apiClient = this.client.getApiClient();
+    const importBody = {
+      format,
+      isZip: isZip ?? false,
+      ...rest,
+      ...fields ? { fields } : {}
+    };
+    const initResponse = await apiClient.postAutomation(
+      ENDPOINTS.AUTOMATION_IMPORT,
+      importBody
+    );
+    const uploadUrl = initResponse?.url;
+    const trackingId = initResponse?.trackingId;
+    if (!uploadUrl || !trackingId) {
+      throw new ToolError(
+        "QTM4J did not return a valid upload URL. Check your API key and project configuration."
+      );
+    }
+    await apiClient.uploadFileMultipart(uploadUrl, fileBuffer);
+    const result = {
+      trackingId,
+      message: initResponse.message ?? "File uploaded successfully. Import is processing.",
+      filePath,
+      format
+    };
+    return {
+      structuredContent: UploadAutomationResultResponse.parse(result),
+      content: []
+    };
+  };
+}
+export {
+  UploadAutomationResult
+};

package/dist/qtm4j/tool/test-cycle/create-test-cycle.js

@@ -0,0 +1,80 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys, InputField } from "../../config/field-resolution.types.js";
+import { CreateTestCycleResponse, CreateTestCycleBody } from "../../schema/test-cycle.schema.js";
+const FIELD_CONFIG = {
+  [InputField.PRIORITY]: ResolverKeys.CommonAttribute.PRIORITY,
+  [InputField.STATUS]: ResolverKeys.CommonAttribute.TEST_CYCLE_STATUS,
+  [InputField.FOLDER]: ResolverKeys.CommonAttribute.TEST_CYCLE_FOLDER,
+  [InputField.LABELS]: ResolverKeys.SearchableField.LABEL,
+  [InputField.COMPONENTS]: ResolverKeys.SearchableField.COMPONENTS
+};
+class CreateTestCycle extends Tool {
+  // ─── Tool Specification ────────────────────────────────────────────────────
+  specification = {
+    title: TOOL_NAMES.CREATE_TEST_CYCLE.TITLE,
+    summary: TOOL_NAMES.CREATE_TEST_CYCLE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    inputSchema: CreateTestCycleBody,
+    outputSchema: CreateTestCycleResponse,
+    purpose: "Create a new test cycle in QTM4J. projectId is auto-injected from the active project context. priority, status, labels, and components are auto-resolved from human-readable names.",
+    useCases: [
+      "Create a test cycle with summary, priority, status, labels, or components",
+      "Set planned start and end dates on a new test cycle"
+    ],
+    examples: [
+      {
+        description: "Create a simple test cycle (project must be set via set_project_context first)",
+        parameters: { summary: "Smoke Test Cycle" },
+        expectedOutput: "Test cycle created with key 'SCRUM-TR-xxx'"
+      },
+      {
+        description: "Create a test cycle with priority, status, labels, and components",
+        parameters: {
+          summary: "Regression Suite – Sprint 42",
+          description: "End-to-end regression covering payment and checkout modules.",
+          priority: "High",
+          status: "To Do",
+          labels: ["Release_1", "Sprint 1"],
+          components: ["UI", "Cloud"],
+          plannedStartDate: "10/May/2026 00:00",
+          plannedEndDate: "15/May/2026 00:00"
+        },
+        expectedOutput: "Test cycle created with resolved priority, status, labels, and components"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "If any priority, status, label, or component name cannot be resolved, the cycle is still created but a warning is returned. Suggest the closest available value from the set_project_context response and ask the user to confirm before retrying.",
+      "All cycles are placed in the 'MCP Generated' folder — do not pass folderId.",
+      "Date format: 'dd/MMM/yyyy HH:mm' e.g. '10/May/2026 00:00'. Month must be capitalised. plannedStartDate must be ≤ plannedEndDate."
+    ],
+    outputDescription: "JSON object with the new test cycle's id and key (e.g. 'TRWT-TR-218'). Warnings included if any fields were skipped."
+  };
+  // ─── Handle Implementation ──────────────────────────────────────────────────
+  handle = async (rawArgs) => {
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const body = {
+      ...CreateTestCycleBody.parse(rawArgs),
+      projectId: context.projectId,
+      folderId: "MCP Generated"
+    };
+    const warnings = [];
+    await Promise.all(
+      Object.entries(FIELD_CONFIG).map(
+        ([inputField, resolverKey]) => fieldResolver.getResolver(resolverKey).resolve(inputField, resolverKey, body, context, warnings)
+      )
+    );
+    const response = await this.client.getApiClient().post(ENDPOINTS.CREATE_TEST_CYCLE, body);
+    const validated = CreateTestCycleResponse.parse(response);
+    return {
+      structuredContent: validated,
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  CreateTestCycle
+};

package/dist/qtm4j/tool/test-cycle/search-test-cycle.js

@@ -0,0 +1,136 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { SearchTestCycleResponse, SearchTestCycleBody } from "../../schema/search-test-cycle.schema.js";
+class SearchTestCycles extends Tool {
+  specification = {
+    title: TOOL_NAMES.SEARCH_TEST_CYCLES.TITLE,
+    summary: TOOL_NAMES.SEARCH_TEST_CYCLES.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    inputSchema: SearchTestCycleBody,
+    outputSchema: SearchTestCycleResponse,
+    purpose: "Search and filter test cycles in a QTM4J project. projectId is auto-injected from the active project context — do not provide it.",
+    useCases: [
+      "Find test cycles by status, priority, assignee, reporter, or folder",
+      "Find test cycles by planned execution date range (plannedStartDate / plannedEndDate)",
+      "Find test cycles created or updated within a date range (createdOn / updatedOn)",
+      "Search test cycles by keyword across key, summary, and description",
+      "Paginate, sort, and select specific response fields"
+    ],
+    examples: [
+      {
+        description: "Find all in-progress and to-do cycles",
+        parameters: { filter: { status: ["In Progress", "To Do"] } },
+        expectedOutput: "Paginated list of matching test cycles"
+      },
+      {
+        description: "Find cycles owned by a specific user",
+        parameters: { filter: { assignee: ["5b10a2844c20165700ede21f"] } },
+        expectedOutput: "Test cycles assigned to that user"
+      },
+      {
+        description: "Find cycles with planned start date in a range, requesting date fields explicitly",
+        parameters: {
+          filter: { plannedStartDate: "01/Apr/2026,30/Apr/2026" },
+          fields: [
+            "key",
+            "summary",
+            "status",
+            "assignee",
+            "plannedStartDate",
+            "plannedEndDate"
+          ]
+        },
+        expectedOutput: "Cycles with planned start date in April 2026 including date fields"
+      },
+      {
+        description: "Keyword search with sort, pagination, and selected fields",
+        parameters: {
+          filter: { searchText: "regression" },
+          fields: ["key", "summary", "status", "assignee"],
+          sort: "plannedStartDate:asc",
+          startAt: 0,
+          maxResults: 25
+        },
+        expectedOutput: "Cycles matching 'regression', sorted by planned start date"
+      },
+      {
+        description: "Find cycles created last week",
+        parameters: {
+          filter: { createdOn: "01/May/2026,07/May/2026" },
+          fields: ["key", "summary", "status", "assignee"],
+          sort: "key:asc"
+        },
+        expectedOutput: "Test cycles created between 01 May and 07 May 2026"
+      },
+      {
+        description: "Find high-priority cycles updated recently by reporter",
+        parameters: {
+          filter: {
+            priority: ["High"],
+            reporter: ["5b10a2844c20165700ede21f"],
+            updatedOn: "01/May/2026,21/May/2026"
+          },
+          fields: ["key", "summary", "status", "priority", "assignee"]
+        },
+        expectedOutput: "High-priority cycles updated in May 2026 reported by that user"
+      },
+      {
+        description: "All filters combined with explicit field selection",
+        parameters: {
+          filter: {
+            status: ["In Progress"],
+            priority: ["High", "Medium"],
+            assignee: ["5b10a2844c20165700ede21f"],
+            folderId: 109987,
+            plannedStartDate: "02/Apr/2026,15/May/2026",
+            searchText: "regression"
+          },
+          fields: [
+            "key",
+            "summary",
+            "status",
+            "priority",
+            "assignee",
+            "plannedStartDate"
+          ],
+          sort: "plannedStartDate:asc",
+          maxResults: 25
+        },
+        expectedOutput: "Test cycles matching all specified filters with selected fields"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "SUPPORTED FILTER FIELDS: status, priority, assignee, reporter, folderId, labels, components, plannedStartDate, plannedEndDate, searchText, createdOn, updatedOn, isAutomated, aiGenerated. Do NOT use any other filter field names.",
+      "DATE FILTERS: createdOn = creation date; updatedOn = last-updated date; plannedStartDate / plannedEndDate = planned execution window. Format: 'dd/MMM/yyyy,dd/MMM/yyyy' e.g. '01/May/2026,21/May/2026'. Month is case-sensitive. 'Created last week' → createdOn, NOT plannedStartDate.",
+      "FIELDS: Pass as an array to select what to return. plannedStartDate and plannedEndDate are NOT in the default response — include them explicitly. Available: key, summary, description, status, priority, assignee, reporter, isAutomated, plannedStartDate, plannedEndDate, labels, components, fixVersions, sprint, defectCount, estimatedTime, actualTime, created, updated.",
+      "REQUEST STRUCTURE: filter → request body; fields, sort, startAt, maxResults → URL query params.",
+      "SORT: Allowed fields: key, summary, status, plannedStartDate, plannedEndDate, defectCount. Format: 'fieldName:asc' or 'fieldName:desc' e.g. 'plannedStartDate:asc'.",
+      "FOLDER ID: folderId in fields.testCycle and fields.testCase is a numeric ID. Tell the user they can get it by right-clicking the target folder in QTM4J and selecting 'Copy Folder Id'. Always ask the user for the numeric ID directly — never try to look it up."
+    ],
+    outputDescription: "JSON object with total (matching cycles across all pages), startAt, maxResults, and data (array of test cycle objects for this page). Each item always has id and key. Other fields depend on what was requested via the fields parameter."
+  };
+  handle = async (rawArgs) => {
+    const args = SearchTestCycleBody.parse(rawArgs);
+    const context = this.client.getResolverRegistry().requireProjectContext();
+    if (!args.filter) args.filter = {};
+    args.filter.projectId = context.projectId;
+    const params = new URLSearchParams();
+    if (args.fields?.length)
+      params.set(RESPONSE_FIELDS.FIELDS, args.fields.join(","));
+    params.set(RESPONSE_FIELDS.START_AT, String(args.startAt));
+    params.set(RESPONSE_FIELDS.MAX_RESULTS, String(args.maxResults));
+    params.set(RESPONSE_FIELDS.SORT, args.sort);
+    const endpoint = `${ENDPOINTS.SEARCH_TEST_CYCLES}?${params.toString()}`;
+    const response = await this.client.getApiClient().post(endpoint, { filter: args.filter });
+    const validated = SearchTestCycleResponse.parse(response);
+    return {
+      structuredContent: validated,
+      content: []
+    };
+  };
+}
+export {
+  SearchTestCycles
+};