@smartbear/mcp 0.24.0 → 0.25.0

package/dist/qtm4j/tool/test-case/get-linked-requirements.js

@@ -0,0 +1,67 @@
+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 { GetLinkedRequirementsResponse, GetLinkedRequirementsBody } from "../../schema/linked-items.schema.js";
+class GetLinkedRequirements extends Tool {
+  specification = {
+    title: TOOL_NAMES.GET_LINKED_REQUIREMENTS.TITLE,
+    summary: TOOL_NAMES.GET_LINKED_REQUIREMENTS.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    toolset: TOOLSETS.TEST_CASES,
+    inputSchema: GetLinkedRequirementsBody,
+    outputSchema: GetLinkedRequirementsResponse,
+    purpose: "Retrieve all Jira requirements linked to a specific test case in QTM4J. The test case's human-readable key (e.g. 'SCRUM-TC-145') is resolved to the internal UID automatically. Returns a paginated list of linked requirements with their Jira metadata (key, summary, status, priority, issue type). PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Check which Jira stories or bugs a test case covers",
+      "Audit requirement traceability for a test case",
+      "Retrieve requirement keys to use in other operations",
+      "Verify that the correct requirements are linked to a test case before a release"
+    ],
+    examples: [
+      {
+        description: "Get all requirements linked to a test case",
+        parameters: { key: "SCRUM-TC-145" },
+        expectedOutput: "Paginated list of linked requirements with Jira metadata"
+      },
+      {
+        description: "Get requirements for a specific version",
+        parameters: { key: "SCRUM-TC-85", versionNo: 2, maxResults: 20 },
+        expectedOutput: "Requirements linked to version 2 of the test case"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'.",
+      "versionNo defaults to the latest version. Use search_test_cases to find available versions.",
+      "Paginate using startAt — increment by maxResults until startAt >= total."
+    ],
+    outputDescription: "Paginated list with total, startAt, maxResults, and data array of linked requirement objects (id, key, summary, status, priority, issueType)."
+  };
+  handle = async (rawArgs) => {
+    const args = GetLinkedRequirementsBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const uidMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.key]);
+    const entry = uidMap[args.key];
+    if (!entry) {
+      throw new ToolError(
+        `Test case '${args.key}' not found in project '${context.projectKey}'. Verify the key using the search_test_cases tool.`
+      );
+    }
+    const params = {
+      maxResults: args.maxResults,
+      startAt: args.startAt,
+      sort: args.sort,
+      tcVersionNo: args.versionNo
+    };
+    const response = await this.client.getApiClient().get(ENDPOINTS.GET_LINKED_REQUIREMENTS(entry.uid), params);
+    return {
+      structuredContent: GetLinkedRequirementsResponse.parse(response),
+      content: []
+    };
+  };
+}
+export {
+  GetLinkedRequirements
+};

package/dist/qtm4j/tool/test-case/get-test-cases.js

@@ -1,9 +1,10 @@
 import { Tool } from "../../../common/tools.js";
-import { TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { TOOL_NAMES, TOOLSETS, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
 import { SearchTestCaseResponse, SearchTestCaseBody } from "../../schema/get-test-case.schema.js";
 class GetTestCases extends Tool {
   specification = {
     title: TOOL_NAMES.SEARCH_TEST_CASES.TITLE,
+    toolset: TOOLSETS.TEST_CASES,
     summary: TOOL_NAMES.SEARCH_TEST_CASES.SUMMARY,
     readOnly: true,
     idempotent: true,

package/dist/qtm4j/tool/test-case/get-test-steps.js

@@ -1,10 +1,11 @@
 import { Tool, ToolError } from "../../../common/tools.js";
-import { TOOL_NAMES, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
+import { TOOL_NAMES, TOOLSETS, RESPONSE_FIELDS, ENDPOINTS } from "../../config/constants.js";
 import { ResolverKeys } from "../../config/field-resolution.types.js";
 import { GetTestStepsResponse, GetTestStepsBody } from "../../schema/get-test-steps.schema.js";
 class GetTestSteps extends Tool {
   specification = {
     title: TOOL_NAMES.GET_TEST_STEPS.TITLE,
+    toolset: TOOLSETS.TEST_CASES,
     summary: TOOL_NAMES.GET_TEST_STEPS.SUMMARY,
     readOnly: true,
     idempotent: true,

package/dist/qtm4j/tool/test-case/link-requirements.js

@@ -0,0 +1,124 @@
+import zod__default from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+const LinkRequirementsBody = zod__default.object({
+  key: zod__default.string().describe(
+    "Test case key in '{PROJECT_KEY}-TC-{number}' format (e.g., 'SCRUM-TC-145'). Required."
+  ),
+  versionNo: zod__default.number().int().optional().describe("Test case version number. Defaults to the latest version."),
+  requirementKeys: zod__default.array(zod__default.string()).optional().describe(
+    "List of requirement keys to link (e.g., ['SCRUM-1', 'SCRUM-2']). Resolved to internal IDs automatically. Provide this OR filter.jql — not both."
+  ),
+  filter: zod__default.object({
+    jql: zod__default.string().describe(
+      'JQL query to filter requirements to link (e.g., "project = DEMO AND issuetype = Story").'
+    )
+  }).optional().describe(
+    "JQL filter to select requirements to link. Use instead of requirementKeys when filtering by JQL."
+  )
+});
+const LinkRequirementsResponse = zod__default.object({
+  key: zod__default.string(),
+  versionNo: zod__default.number().int(),
+  linked: zod__default.literal(true)
+});
+class LinkRequirements extends Tool {
+  specification = {
+    title: TOOL_NAMES.LINK_REQUIREMENTS.TITLE,
+    summary: TOOL_NAMES.LINK_REQUIREMENTS.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CASES,
+    inputSchema: LinkRequirementsBody,
+    outputSchema: LinkRequirementsResponse,
+    purpose: "Link Jira requirements to a test case in QTM4J using the test case's human-readable key. Requirements can be specified by their human-readable keys (e.g. 'SCRUM-1') which are resolved to internal IDs automatically, or via a JQL filter. Requirements that cannot be linked are reported as warnings. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Link one or more Jira requirements (stories, bugs, epics) to a test case",
+      "Associate requirements with a test case using a JQL filter",
+      "Build traceability between requirements and test cases",
+      "Link requirements to a specific test case version"
+    ],
+    examples: [
+      {
+        description: "Link two requirements by key",
+        parameters: {
+          key: "SCRUM-TC-145",
+          requirementKeys: ["SCRUM-1", "SCRUM-2"]
+        },
+        expectedOutput: "Requirements SCRUM-1 and SCRUM-2 linked to test case"
+      },
+      {
+        description: "Link requirements by JQL filter",
+        parameters: {
+          key: "SCRUM-TC-145",
+          filter: { jql: "project = DEMO AND issuetype = Story" }
+        },
+        expectedOutput: "Requirements matched by JQL linked to test case"
+      },
+      {
+        description: "Link a requirement to a specific version",
+        parameters: {
+          key: "SCRUM-TC-85",
+          versionNo: 2,
+          requirementKeys: ["SCRUM-10"]
+        },
+        expectedOutput: "Requirement linked to version 2 of test case"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'.",
+      "Requirement keys follow the Jira issue key format: '{PROJECT_KEY}-{number}' (e.g. 'SCRUM-1').",
+      "Provide either requirementKeys or filter.jql — not both.",
+      "If a requirement key cannot be resolved or linked, it is reported in warnings and other requirements are still linked.",
+      "versionNo defaults to the latest version. Use search_test_cases to find available versions if needed."
+    ],
+    outputDescription: "Confirmation with the test case key, version number, and linked: true. Warnings are included if any requirements could not be resolved or linked."
+  };
+  handle = async (rawArgs) => {
+    const args = LinkRequirementsBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const warnings = [];
+    const uidMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.key]);
+    const entry = uidMap[args.key];
+    if (!entry) {
+      throw new ToolError(
+        `Test case '${args.key}' not found in project '${context.projectKey}'. Verify the key using the search_test_cases tool.`
+      );
+    }
+    const versionNo = args.versionNo ?? entry.latestVersion;
+    const body = {};
+    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;
+    }
+    if (args.filter) {
+      body.filter = args.filter;
+    }
+    await this.client.getApiClient().post(ENDPOINTS.LINK_REQUIREMENTS(entry.uid, versionNo), body);
+    return {
+      structuredContent: LinkRequirementsResponse.parse({
+        key: args.key,
+        versionNo,
+        linked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  LinkRequirements
+};

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

@@ -0,0 +1,116 @@
+import zod__default from "zod";
+import { Tool, ToolError } from "../../../common/tools.js";
+import { TOOLSETS, TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { ResolverKeys } from "../../config/field-resolution.types.js";
+const UnlinkRequirementsBody = zod__default.object({
+  key: zod__default.string().describe(
+    "Test case key in '{PROJECT_KEY}-TC-{number}' format (e.g., 'SCRUM-TC-145'). Required."
+  ),
+  versionNo: zod__default.number().int().optional().describe("Test case version number. Defaults to the latest version."),
+  requirementKeys: zod__default.array(zod__default.string()).optional().describe(
+    "List of requirement keys to unlink (e.g., ['SCRUM-1', 'SCRUM-2']). Ignored when unLinkAll is true."
+  ),
+  unLinkAll: zod__default.boolean().optional().describe(
+    "If true, all linked requirements are unlinked from this test case. Ignores requirementKeys when set."
+  )
+});
+const UnlinkRequirementsResponse = zod__default.object({
+  key: zod__default.string(),
+  versionNo: zod__default.number().int(),
+  unlinked: zod__default.literal(true)
+});
+class UnlinkRequirements extends Tool {
+  specification = {
+    title: TOOL_NAMES.UNLINK_REQUIREMENTS.TITLE,
+    summary: TOOL_NAMES.UNLINK_REQUIREMENTS.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CASES,
+    inputSchema: UnlinkRequirementsBody,
+    outputSchema: UnlinkRequirementsResponse,
+    purpose: "Unlink Jira requirements from a test case in QTM4J using the test case's human-readable key. Specify individual requirement keys to unlink (resolved to internal IDs automatically), or set unLinkAll to true to remove all linked requirements in one call. Requirements that cannot be unlinked are reported as warnings. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Remove specific requirements from a test case",
+      "Unlink all requirements from a test case at once",
+      "Clean up stale or incorrect requirement links from a test case",
+      "Remove requirement associations from a specific test case version"
+    ],
+    examples: [
+      {
+        description: "Unlink specific requirements by key",
+        parameters: {
+          key: "SCRUM-TC-145",
+          requirementKeys: ["SCRUM-1", "SCRUM-2"]
+        },
+        expectedOutput: "Requirements SCRUM-1 and SCRUM-2 unlinked from test case"
+      },
+      {
+        description: "Unlink all requirements from a test case",
+        parameters: { key: "SCRUM-TC-145", unLinkAll: true },
+        expectedOutput: "All requirements unlinked from test case"
+      },
+      {
+        description: "Unlink a requirement from a specific version",
+        parameters: {
+          key: "SCRUM-TC-85",
+          versionNo: 2,
+          requirementKeys: ["SCRUM-10"]
+        },
+        expectedOutput: "Requirement unlinked from version 2 of test case"
+      }
+    ],
+    hints: [
+      "PREREQUISITE: set_project_context must be called before this tool. NEVER auto-select a project.",
+      "KEY FORMAT: '{PROJECT_KEY}-TC-{number}' — e.g. 'SCRUM-TC-145'.",
+      "Requirement keys follow the Jira issue key format: '{PROJECT_KEY}-{number}' (e.g. 'SCRUM-1').",
+      "Set unLinkAll to true to remove all requirements in one call — no need to list them individually.",
+      "If a requirement key cannot be resolved or unlinked, it is reported in warnings and others are still unlinked.",
+      "versionNo defaults to the latest version. Use search_test_cases to find available versions if needed."
+    ],
+    outputDescription: "Confirmation with the test case key, version number, and unlinked: true. Warnings are included if any requirements could not be resolved or unlinked."
+  };
+  handle = async (rawArgs) => {
+    const args = UnlinkRequirementsBody.parse(rawArgs);
+    const fieldResolver = this.client.getResolverRegistry();
+    const context = fieldResolver.requireProjectContext();
+    const warnings = [];
+    const uidMap = await fieldResolver.getResolver(ResolverKeys.SearchableField.TEST_CASE_KEY_TO_UID).resolveAndReturn(context.projectId, [args.key]);
+    const entry = uidMap[args.key];
+    if (!entry) {
+      throw new ToolError(
+        `Test case '${args.key}' not found in project '${context.projectKey}'. Verify the key using the search_test_cases tool.`
+      );
+    }
+    const versionNo = args.versionNo ?? entry.latestVersion;
+    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(entry.uid, versionNo), body);
+    return {
+      structuredContent: UnlinkRequirementsResponse.parse({
+        key: args.key,
+        versionNo,
+        unlinked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  UnlinkRequirements
+};

package/dist/qtm4j/tool/test-case/update-test-case.js

@@ -1,5 +1,5 @@
 import { Tool, ToolError } from "../../../common/tools.js";
-import { TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { TOOL_NAMES, TOOLSETS, ENDPOINTS } from "../../config/constants.js";
 import { ResolverKeys, InputField } from "../../config/field-resolution.types.js";
 import { UpdateTestCaseResponse, UpdateTestCaseBody } from "../../schema/update-test-case.schema.js";
 const SIMPLE_FIELD_CONFIG = {
@@ -33,6 +33,7 @@ async function resolveAddDelete(resolver, inputField, resolverKey, field, contex
 class UpdateTestCase extends Tool {
   specification = {
     title: TOOL_NAMES.UPDATE_TEST_CASE.TITLE,
+    toolset: TOOLSETS.TEST_CASES,
     summary: TOOL_NAMES.UPDATE_TEST_CASE.SUMMARY,
     readOnly: false,
     idempotent: true,

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

@@ -1,5 +1,5 @@
 import { Tool } from "../../../common/tools.js";
-import { TOOL_NAMES, ENDPOINTS } from "../../config/constants.js";
+import { TOOL_NAMES, TOOLSETS, 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 = {
@@ -13,6 +13,7 @@ class CreateTestCycle extends Tool {
   // ─── Tool Specification ────────────────────────────────────────────────────
   specification = {
     title: TOOL_NAMES.CREATE_TEST_CYCLE.TITLE,
+    toolset: TOOLSETS.TEST_CYCLES,
     summary: TOOL_NAMES.CREATE_TEST_CYCLE.SUMMARY,
     readOnly: false,
     idempotent: false,

package/dist/qtm4j/tool/test-cycle/get-linked-requirements.js

@@ -0,0 +1,71 @@
+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 { GetLinkedRequirementsResponse } from "../../schema/linked-items.schema.js";
+import { GetLinkedRequirementsForCycleBody } from "../../schema/test-cycle.link.schema.js";
+class GetLinkedRequirementsForCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.GET_LINKED_REQUIREMENTS_FOR_CYCLE.TITLE,
+    summary: TOOL_NAMES.GET_LINKED_REQUIREMENTS_FOR_CYCLE.SUMMARY,
+    readOnly: true,
+    idempotent: true,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: GetLinkedRequirementsForCycleBody,
+    outputSchema: GetLinkedRequirementsResponse,
+    purpose: "Retrieve all Jira requirements linked to a QTM4J test cycle. The cycle's human-readable key (e.g. 'SCRUM-TR-1') is resolved to the internal UID automatically. Returns a paginated list of linked requirements with their Jira metadata (key, summary, status, priority, issue type). PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Check which Jira stories or bugs are covered by a test cycle",
+      "Audit requirement traceability for a test cycle",
+      "Retrieve requirement keys linked to a cycle before a release",
+      "Verify correct requirements are linked to a test cycle"
+    ],
+    examples: [
+      {
+        description: "Get all requirements linked to a test cycle",
+        parameters: { cycleKey: "SCRUM-TR-1" },
+        expectedOutput: "Paginated list of linked requirements with Jira metadata"
+      },
+      {
+        description: "Get requirements sorted by priority with custom page size",
+        parameters: {
+          cycleKey: "SCRUM-TR-5",
+          sort: "priority:asc",
+          maxResults: 20
+        },
+        expectedOutput: "Requirements linked to cycle sorted by priority ascending"
+      }
+    ],
+    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.",
+      "Allowed sort fields: key, status, priority. Default sort: 'key:desc'.",
+      "Paginate using startAt — increment by maxResults until startAt >= total."
+    ],
+    outputDescription: "Paginated result with total, startAt, maxResults, and data array of linked requirement objects (id, key, summary, status, priority, issueType)."
+  };
+  handle = async (rawArgs) => {
+    const args = GetLinkedRequirementsForCycleBody.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 = {
+      maxResults: args.maxResults,
+      startAt: args.startAt,
+      sort: args.sort
+    };
+    const response = await this.client.getApiClient().get(ENDPOINTS.GET_LINKED_REQUIREMENTS_FOR_CYCLE(cycleEntry.uid), params);
+    return {
+      structuredContent: GetLinkedRequirementsResponse.parse(response),
+      content: []
+    };
+  };
+}
+export {
+  GetLinkedRequirementsForCycle
+};

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

@@ -0,0 +1,91 @@
+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 { LinkRequirementsToCycleResponse, LinkRequirementsToCycleBody } from "../../schema/test-cycle.link.schema.js";
+class LinkRequirementsToCycle extends Tool {
+  specification = {
+    title: TOOL_NAMES.LINK_REQUIREMENTS_TO_CYCLE.TITLE,
+    summary: TOOL_NAMES.LINK_REQUIREMENTS_TO_CYCLE.SUMMARY,
+    readOnly: false,
+    idempotent: false,
+    toolset: TOOLSETS.TEST_CYCLES,
+    inputSchema: LinkRequirementsToCycleBody,
+    outputSchema: LinkRequirementsToCycleResponse,
+    purpose: "Link Jira requirements 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. Requirements can be specified by their human-readable keys (e.g. 'SCRUM-1') which are resolved to internal IDs automatically, or via a JQL filter. Requirements that cannot be linked are reported as warnings. PREREQUISITE: set_project_context must be called before this tool.",
+    useCases: [
+      "Link one or more Jira requirements (stories, bugs, epics) to a test cycle",
+      "Associate requirements with a test cycle using a JQL filter",
+      "Build traceability between requirements and a test cycle",
+      "Link all stories from a sprint to a test cycle using JQL"
+    ],
+    examples: [
+      {
+        description: "Link two requirements by key",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          requirementKeys: ["SCRUM-1", "SCRUM-2"]
+        },
+        expectedOutput: "Requirements SCRUM-1 and SCRUM-2 linked to test cycle"
+      },
+      {
+        description: "Link requirements by JQL filter",
+        parameters: {
+          cycleKey: "SCRUM-TR-1",
+          filter: { jql: "project = DEMO AND issuetype = Story" }
+        },
+        expectedOutput: "Requirements matched by JQL linked to 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 filter.jql — not both.",
+      "If a requirement key cannot be resolved or linked, it is reported in warnings and other requirements are still linked."
+    ],
+    outputDescription: "Confirmation with the cycle key and linked: true. Warnings are included if any requirements could not be resolved or linked."
+  };
+  handle = async (rawArgs) => {
+    const args = LinkRequirementsToCycleBody.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.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;
+    }
+    if (args.filter) {
+      body.filter = args.filter;
+    }
+    await this.client.getApiClient().post(ENDPOINTS.LINK_REQUIREMENTS_TO_CYCLE(cycleEntry.uid), body);
+    return {
+      structuredContent: LinkRequirementsToCycleResponse.parse({
+        cycleKey: args.cycleKey,
+        linked: true
+      }),
+      content: warnings.length > 0 ? [{ type: "text", text: `Note: ${warnings.join(" | ")}` }] : []
+    };
+  };
+}
+export {
+  LinkRequirementsToCycle
+};

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
+};