@smartbear/mcp 0.23.0 → 0.25.0

package/dist/qtm4j/tool/test-cycle/link-testcases.js

@@ -0,0 +1,118 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+import { TestCycleLinkResponse, LinkTestCasesToCycleBody } from "../../schema/test-cycle.link.schema.js";
+class LinkTestCasesToCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.LINK_TESTCASES_TO_CYCLE.TITLE,
+    summary: TOOL_NAMES.LINK_TESTCASES_TO_CYCLE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: LinkTestCasesToCycleBody,
+    outputSchema: TestCycleLinkResponse,
+    purpose: "Link test cases to a QTM4J test cycle using the cycle's human-readable key. The cycle key (e.g. 'SCRUM-TR-1') is resolved to the internal UID automatically. Test cases can be specified by their human-readable keys (e.g. 'SCRUM-TC-1'), which are also resolved to internal IDs and latest versions automatically. Alternatively, use a filter object to select test cases by criteria such as status, priority, labels, or folder. The active project ID is injected automatically into the filter. Test cases that cannot be linked are reported in warnings. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Add specific test cases to a test cycle by key",
+      "Populate a test cycle with test cases matching a filter (e.g., all High priority test cases)",
+      "Link test cases from a specific folder to a test cycle",
+      "Add test cases to a cycle with a specific assignee or environment"
+    ],
+    examples: [
+      {
+        description: "Link two test cases by key",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          testCaseKeys: ["SCRUM-TC-10", "SCRUM-TC-11"]
+        },
+        expectedOutput: "Test cases linked to test cycle"
+      },
+      {
+        description: "Link test cases matching a filter with assignee",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          filter: { priority: ["High"], status: ["To Do"] },
+          assignee: "5b10a2844c20165700ede21f",
+          startNewExecution: true
+        },
+        expectedOutput: "Filtered test cases linked to cycle with assignee"
+      },
+      {
+        description: "Link test cases in a folder to a cycle with planned date",
+        parameters: {
+          cycleKey: "SCRUM-TR-5",
+          filter: { folderId: 42, withChild: true },
+          executionPlannedDate: "2024-03-31",
+          sort: "key:asc"
+        },
+        expectedOutput: "Folder test cases linked to cycle with planned date"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "CYCLE KEY FORMAT: '{PROJECT_KEY}-TR-{id}' — e.g. 'SCRUM-TR-1'. Resolved to internal UID automatically.",
+      "TEST CASE KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'.",
+      "Provide either testCaseKeys or filter — not both.",
+      "projectId in filter is auto-filled from the active project context — do not set it manually.",
+      "filter.excludeCycleId excludes test cases already in another cycle.",
+      "startNewExecution: true creates a fresh execution record for each linked test case.",
+      "executionPlannedDate must be in yyyy-MM-dd format (e.g., '2024-03-31').",
+      "actualTime must be in HH:mm format (e.g., '02:30').",
+      "If a test case key cannot be resolved, it is reported in warnings and others are still linked."
+    ],
+    outputDescription: "Confirmation with the cycle key and linked: true. Warnings included if any test cases could not be resolved or linked."
+  };
+  handle = async (rawArgs) => {
+    const args = LinkTestCasesToCycleBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const warnings = [];
+    const cycleMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CYCLE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.cycleKey]);
+    const cycleEntry = cycleMap[args.cycleKey];
+    if (!cycleEntry) {
+      throw new ToolError(
+        `Test cycle '${args.cycleKey}' not found in project '${context.projectKey}'. Verify the key is a valid QTM4J test cycle key.`
+      );
+    }
+    const body = {};
+    if (args.testCaseKeys?.length) {
+      const uidMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, args.testCaseKeys);
+      const testCases = [];
+      for (const tcKey of args.testCaseKeys) {
+        const resolved = uidMap[tcKey];
+        if (resolved) {
+          testCases.push({
+            id: resolved.uid,
+            versionNo: resolved.latestVersion
+          });
+        } else {
+          warnings.push(
+            `Test case '${tcKey}' could not be resolved and was skipped.`
+          );
+        }
+      }
+      if (testCases.length > 0) body.testCases = testCases;
+    }
+    if (args.filter) {
+      body.filter = { ...args.filter, projectId: context.projectId };
+    }
+    const {
+      cycleKey: _cycleKey,
+      testCaseKeys: _tcKeys,
+      filter: _filter,
+      ...rest
+    } = args;
+    Object.assign(body, rest);
+    await this.client.getApiClient().post(ENDPOINTS.LINK_TESTCASES_TO_CYCLE(cycleEntry.uid), body);
+    return {
+      structuredContent: TestCycleLinkResponse.parse({
+        cycleKey: args.cycleKey,
+        linked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  LinkTestCasesToCycle
+};

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

@@ -0,0 +1,114 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+import { SearchLinkedTestCasesInCycleResponse, SearchLinkedTestCasesInCycleBody } from "../../schema/test-cycle.link.schema.js";
+class SearchLinkedTestCasesInCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.SEARCH_LINKED_TESTCASES_IN_CYCLE.TITLE,
+    summary: TOOL_NAMES.SEARCH_LINKED_TESTCASES_IN_CYCLE.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: SearchLinkedTestCasesInCycleBody,
+    outputSchema: SearchLinkedTestCasesInCycleResponse,
+    purpose: "Search and filter test case executions linked to a QTM4J test cycle. The cycle key (e.g. 'SCRUM-TR-1') is resolved to the internal UID automatically. Supports pagination, field selection, sorting, and rich filter criteria such as execution result, priority, status, environment, assignee, and date ranges. The active project ID is injected automatically into the filter. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "List all test cases linked to a test cycle",
+      "Find failed or blocked test case executions in a cycle",
+      "Search for test cases in a cycle by execution result (Pass, Fail, Blocked)",
+      "Filter test cases in a cycle by priority or status",
+      "Retrieve test cases assigned to a specific executor in a cycle",
+      "Get test cases with defects in a cycle",
+      "Paginate through large test cycle execution lists",
+      "Request only specific fields to reduce response size"
+    ],
+    examples: [
+      {
+        description: "List all test cases in a cycle",
+        parameters: { cycleKey: "SCRUM-TR-1" },
+        expectedOutput: "Paginated list of test case executions in the cycle (first 50 results)"
+      },
+      {
+        description: "Find failed test cases in a cycle",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          filter: { executionResult: ["Fail"] },
+          fields: ["key", "summary", "executionResult", "priority"]
+        },
+        expectedOutput: "Test case executions with Fail result"
+      },
+      {
+        description: "Search with pagination and sort",
+        parameters: {
+          cycleKey: "SCRUM-TR-5",
+          maxResults: 25,
+          startAt: 0,
+          sort: "key:asc",
+          filter: { status: ["To Do"] }
+        },
+        expectedOutput: "First 25 To Do test cases in the cycle sorted by key ascending"
+      },
+      {
+        description: "Filter by execution assignee and environment",
+        parameters: {
+          cycleKey: "SCRUM-TR-2",
+          filter: {
+            executionAssignee: ["5b10a2844c20165700ede21f"],
+            environment: ["Staging"]
+          },
+          fields: [
+            "key",
+            "summary",
+            "executionResult",
+            "environment",
+            "actualTime"
+          ]
+        },
+        expectedOutput: "Test cases assigned to the specified user in the Staging environment"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "CYCLE KEY FORMAT: '{PROJECT_KEY}-TR-{id}' — e.g. 'SCRUM-TR-1'. Resolved to internal UID automatically.",
+      "projectId in filter is auto-filled from the active project context — do not set it manually.",
+      "fields is sent as a query parameter; filter is sent in the request body.",
+      "Allowed fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, seqNo, latestTcExecutionId, customFields, flakyScore, passRateScore.",
+      "Allowed sort fields: id, key, summary, description, executionResult, status, priority, environment, tcWithDefects, estimatedTime, actualTime, createdOn, updatedOn, sprint, flakyScore, passRateScore.",
+      "Date range format for filter fields: 'dd/mmm/yyyy,dd/mmm/yyyy' (e.g., '01/Jan/2024,31/Mar/2024').",
+      "maxResults defaults to 50, maximum is 100. Use startAt to paginate.",
+      "executionResult filter accepts values like 'Pass', 'Fail', 'Blocked', 'Unexecuted'."
+    ],
+    outputDescription: "JSON object with total (total matching executions), startAt, maxResults, and data (array of test case execution objects for this page)."
+  };
+  handle = async (rawArgs) => {
+    const args = SearchLinkedTestCasesInCycleBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const cycleMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CYCLE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.cycleKey]);
+    const cycleEntry = cycleMap[args.cycleKey];
+    if (!cycleEntry) {
+      throw new ToolError(
+        `Test cycle '${args.cycleKey}' not found in project '${context.projectKey}'. Verify the key is a valid QTM4J test cycle key.`
+      );
+    }
+    const params = new URLSearchParams();
+    if (args.fields?.length) {
+      params.set(RESPONSE_FIELDS.FIELDS, args.fields.join(","));
+    }
+    if (args.sort) {
+      params.set(RESPONSE_FIELDS.SORT, args.sort);
+    }
+    params.set(RESPONSE_FIELDS.MAX_RESULTS, String(args.maxResults));
+    params.set(RESPONSE_FIELDS.START_AT, String(args.startAt));
+    const endpoint = `${ENDPOINTS.SEARCH_LINKED_TESTCASES_IN_CYCLE(cycleEntry.uid)}?${params.toString()}`;
+    const filter = args.filter ? { ...args.filter, projectId: [context.projectId] } : { projectId: [context.projectId] };
+    const response = await this.client.getApiClient().post(endpoint, { filter });
+    return {
+      structuredContent: SearchLinkedTestCasesInCycleResponse.parse(response),
+      content: []
+    };
+  };
+}
+export {
+  SearchLinkedTestCasesInCycle
+};

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

@@ -0,0 +1,137 @@
+import { Tool } from "../../../common/tools.js";
+import { TOOL_NAMES, TOOLSETS, 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,
+    toolset: TOOLSETS.TEST_CYCLES,
+    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
+};

package/dist/qtm4j/tool/test-cycle/unlink-requirements.js

@@ -0,0 +1,87 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+import { UnlinkRequirementsFromCycleResponse, UnlinkRequirementsFromCycleBody } from "../../schema/test-cycle.link.schema.js";
+class UnlinkRequirementsFromCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.UNLINK_REQUIREMENTS_FROM_CYCLE.TITLE,
+    summary: TOOL_NAMES.UNLINK_REQUIREMENTS_FROM_CYCLE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: UnlinkRequirementsFromCycleBody,
+    outputSchema: UnlinkRequirementsFromCycleResponse,
+    purpose: "Unlink Jira requirements from a QTM4J test cycle using the cycle's human-readable key. The cycle key (e.g. 'SCRUM-TR-1') is resolved to the internal UID automatically. Requirements can be specified by their human-readable keys (e.g. 'SCRUM-1') which are resolved to internal IDs automatically, or set unLinkAll to true to remove all requirements from the cycle in one call. Requirements that cannot be unlinked are reported as warnings. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Remove one or more Jira requirements from a test cycle by key",
+      "Unlink all requirements from a test cycle at once",
+      "Clean up requirement links before repopulating a test cycle"
+    ],
+    examples: [
+      {
+        description: "Unlink two requirements by key",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          requirementKeys: ["SCRUM-1", "SCRUM-2"]
+        },
+        expectedOutput: "Requirements SCRUM-1 and SCRUM-2 unlinked from test cycle"
+      },
+      {
+        description: "Unlink all requirements from a cycle",
+        parameters: { cycleKey: "SCRUM-TR-1", unLinkAll: true },
+        expectedOutput: "All requirements unlinked from test cycle"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "CYCLE KEY FORMAT: '{PROJECT_KEY}-TR-{id}' — e.g. 'SCRUM-TR-1'. Resolved to internal UID automatically.",
+      "Requirement keys follow Jira issue key format: '{PROJECT_KEY}-{number}' (e.g. 'SCRUM-1').",
+      "Provide either requirementKeys or unLinkAll: true — not both.",
+      "unLinkAll: true removes every requirement from the cycle — no need to list them individually.",
+      "If a requirement key cannot be resolved or unlinked, it is reported in warnings and other requirements are still unlinked."
+    ],
+    outputDescription: "Confirmation with the cycle key and unlinked: true. Warnings are included if any requirements could not be resolved or unlinked."
+  };
+  handle = async (rawArgs) => {
+    const args = UnlinkRequirementsFromCycleBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const warnings = [];
+    const cycleMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CYCLE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.cycleKey]);
+    const cycleEntry = cycleMap[args.cycleKey];
+    if (!cycleEntry) {
+      throw new ToolError(
+        `Test cycle '${args.cycleKey}' not found in project '${context.projectKey}'. Verify the key is a valid QTM4J test cycle key.`
+      );
+    }
+    const body = {};
+    if (args.unLinkAll) {
+      body.unLinkAll = true;
+    } else if (args.requirementKeys?.length) {
+      const reqMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.REQUIREMENT_KEY_TO_ID).resolveAndReturn(context.projectId, args.requirementKeys);
+      const requirementIds = [];
+      for (const reqKey of args.requirementKeys) {
+        const resolved = reqMap[reqKey];
+        if (resolved) {
+          requirementIds.push(Number(resolved.id));
+        } else {
+          warnings.push(
+            `Requirement '${reqKey}' could not be resolved and was skipped.`
+          );
+        }
+      }
+      if (requirementIds.length > 0) body.requirementIds = requirementIds;
+    }
+    await this.client.getApiClient().post(ENDPOINTS.UNLINK_REQUIREMENTS_FROM_CYCLE(cycleEntry.uid), body);
+    return {
+      structuredContent: UnlinkRequirementsFromCycleResponse.parse({
+        cycleKey: args.cycleKey,
+        unlinked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  UnlinkRequirementsFromCycle
+};

package/dist/qtm4j/tool/test-cycle/unlink-testcases.js

@@ -0,0 +1,103 @@
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+import { TestCycleLinkResponse, UnlinkTestCasesFromCycleBody } from "../../schema/test-cycle.link.schema.js";
+class UnlinkTestCasesFromCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.UNLINK_TESTCASES_FROM_CYCLE.TITLE,
+    summary: TOOL_NAMES.UNLINK_TESTCASES_FROM_CYCLE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: UnlinkTestCasesFromCycleBody,
+    outputSchema: TestCycleLinkResponse,
+    purpose: "Unlink test cases from a QTM4J test cycle using the cycle's human-readable key. The cycle key (e.g. 'SCRUM-TR-1') is resolved to the internal UID automatically. Test cases can be specified by their human-readable keys (e.g. 'SCRUM-TC-1'), which are also resolved to internal IDs and latest versions automatically. Alternatively, set unlinkAll to true to remove all test cases from the cycle in one call, or use a filter to select which test cases to unlink by criteria. The active project ID is injected automatically into the filter. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Remove specific test cases from a test cycle by key",
+      "Unlink all test cases from a test cycle at once",
+      "Remove test cases matching a filter from a cycle (e.g., all 'Done' test cases)",
+      "Clean up a test cycle before repopulating it"
+    ],
+    examples: [
+      {
+        description: "Unlink two specific test cases",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          testCaseKeys: ["SCRUM-TC-10", "SCRUM-TC-11"]
+        },
+        expectedOutput: "Test cases unlinked from test cycle"
+      },
+      {
+        description: "Unlink all test cases from a cycle",
+        parameters: { cycleKey: "SCRUM-TR-1", unlinkAll: true },
+        expectedOutput: "All test cases unlinked from cycle"
+      },
+      {
+        description: "Unlink test cases matching a status filter",
+        parameters: {
+          cycleKey: "SCRUM-TR-5",
+          filter: { status: ["Done"], labels: ["Deprecated"] }
+        },
+        expectedOutput: "Filtered test cases unlinked from cycle"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "CYCLE KEY FORMAT: '{PROJECT_KEY}-TR-{id}' — e.g. 'SCRUM-TR-1'. Resolved to internal UID automatically.",
+      "TEST CASE KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'.",
+      "Provide exactly one of: testCaseKeys, unlinkAll, or filter.",
+      "unlinkAll: true removes every test case from the cycle — no need to list them individually.",
+      "projectId in filter is auto-filled from the active project context — do not set it manually.",
+      "If a test case key cannot be resolved, it is reported in warnings and others are still unlinked."
+    ],
+    outputDescription: "Confirmation with the cycle key and unlinked: true. Warnings included if any test cases could not be resolved or unlinked."
+  };
+  handle = async (rawArgs) => {
+    const args = UnlinkTestCasesFromCycleBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const warnings = [];
+    const cycleMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CYCLE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.cycleKey]);
+    const cycleEntry = cycleMap[args.cycleKey];
+    if (!cycleEntry) {
+      throw new ToolError(
+        `Test cycle '${args.cycleKey}' not found in project '${context.projectKey}'. Verify the key is a valid QTM4J test cycle key.`
+      );
+    }
+    const body = {};
+    if (args.unlinkAll) {
+      body.unlinkAll = true;
+    } else if (args.testCaseKeys?.length) {
+      const uidMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, args.testCaseKeys);
+      const testCases = [];
+      for (const tcKey of args.testCaseKeys) {
+        const resolved = uidMap[tcKey];
+        if (resolved) {
+          testCases.push({
+            id: resolved.uid,
+            versionNo: resolved.latestVersion
+          });
+        } else {
+          warnings.push(
+            `Test case '${tcKey}' could not be resolved and was skipped.`
+          );
+        }
+      }
+      if (testCases.length > 0) body.testCases = testCases;
+    }
+    if (args.filter) {
+      body.filter = { ...args.filter, projectId: context.projectId };
+    }
+    await this.client.getApiClient().delete(ENDPOINTS.UNLINK_TESTCASES_FROM_CYCLE(cycleEntry.uid), body);
+    return {
+      structuredContent: TestCycleLinkResponse.parse({
+        cycleKey: args.cycleKey,
+        unlinked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  UnlinkTestCasesFromCycle
+};