[Zephyr] TM4J-14631 -Create Test Cycle Issue link tool (#359)

* [Zephyr] TM4J-14631 -Create Test Cycle Issue link tool

* [Zephyr] TM4J-14631 - Remove manually added schema from auto-generated file

Remove CreateTestCycleIssueLink201Response from rest-api-schemas.ts
as this file is auto-generated. The tool already reuses
CreateTestCaseIssueLink201Response which has the same structure.

* remove output

* merge with main

* update zephyr integration

* update changelog

* fix: correct test cycle issue link to reflect empty API response

The Zephyr API does not return any object when creating a test cycle
issue link. Updated tool examples, tests, and docs accordingly.

* remove expectedOutput and structuredContent for no-output API

The test cycle issue link API returns no body, so remove expectedOutput
from examples, return structuredContent: {} and drop response assertions
from tests.

* add blank line between imports and class declaration

* Resolve comments

Author: AdamSmartBear

CHANGELOG.md

@@ -14,6 +14,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - [Zephyr] Added a tool `create-test-script` for creating Test Script [#328](https://github.com/SmartBear/smartbear-mcp/pull/328)
 - [Zephyr] Added a tool `create-test-steps` for creating Test Steps for a Test Case [#353](https://github.com/SmartBear/smartbear-mcp/pull/353)
 - [Zephyr] Added a tool `update-test-execution` for updating a test execution [#345](https://github.com/SmartBear/smartbear-mcp/pull/345)
+- [Zephyr] Added a tool `create-test-cycle-issue-link` for creating a link between a Jira issue and a Test Cycle [#359](https://github.com/SmartBear/smartbear-mcp/pull/359)
 - [Zephyr] Added a tool `get-test-steps` for getting a list of test steps for test case [#355](https://github.com/SmartBear/smartbear-mcp/pull/355)
 - [Zephyr] Added a tool `get-test-cases` for fetching test cases linked to a Jira issue [#358](https://github.com/SmartBear/smartbear-mcp/pull/358)
 - [Zephyr] Added a tool `create-web-link` for creating a Web link for a Test Cycle [#354](https://github.com/SmartBear/smartbear-mcp/pull/354)

docs/products/SmartBear MCP Server/zephyr-integration.md

@@ -130,6 +130,15 @@ The following environment variables configure the Zephyr integration:
 - **Returns**: The created Test Case Issue Link ID and the API self URL that can be used to delete the link.
 - **Use case**: Creates a link between a test case and a Jira Issue.
 
+#### Create Test Cycle Issue Link
+
+- **Purpose**: Creates an Issue link that associates a test cycle with a Jira Issue.
+- **Parameters:**
+  - Test Cycle ID or key (`testCycleIdOrKey`)
+  - Jira Issue Id (`issueId`)
+- **Returns**: A confirmation that the link was successfully created.
+- **Use case**: Creates a link between a test cycle and a Jira Issue.
+
 ## Test Scripts
 
 ### Creation Operations

src/tests/unit/zephyr/tool/test-cycle/create-issue-link.test.ts

@@ -0,0 +1,135 @@
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type {
+  ServerNotification,
+  ServerRequest,
+} from "@modelcontextprotocol/sdk/types.js";
+import { beforeEach, describe, expect, it, vi } from "vitest";
+import { CreateTestCycleIssueLink } from "../../../../../zephyr/tool/test-cycle/create-issue-link";
+
+describe("CreateTestCycleIssueLink", () => {
+  let mockClient: any;
+  let instance: CreateTestCycleIssueLink;
+
+  const EXTRA_REQUEST_HANDLER: RequestHandlerExtra<
+    ServerRequest,
+    ServerNotification
+  > = {
+    signal: AbortSignal.timeout(5000),
+    requestId: "",
+    sendNotification: (_notification) => {
+      throw new Error("Function not implemented.");
+    },
+    sendRequest: (_request, _resultSchema, _options?) => {
+      throw new Error("Function not implemented.");
+    },
+  };
+
+  beforeEach(() => {
+    mockClient = {
+      getApiClient: vi.fn().mockReturnValue({
+        post: vi.fn(),
+      }),
+    };
+    instance = new CreateTestCycleIssueLink(mockClient as any);
+  });
+
+  it("should set specification correctly", () => {
+    expect(instance.specification.title).toBe("Create Test Cycle Issue Link");
+    expect(instance.specification.summary).toBe(
+      "Create a new link between an issue in Jira and a Test Cycle in Zephyr",
+    );
+    expect(instance.specification.readOnly).toBe(false);
+    expect(instance.specification.idempotent).toBe(false);
+    expect(instance.specification.inputSchema).toBeDefined();
+  });
+
+  it("should call apiClient.post with correct params using test cycle key", async () => {
+    mockClient.getApiClient().post.mockResolvedValueOnce(undefined);
+
+    const args = {
+      testCycleIdOrKey: "SA-R1",
+      issueId: 53,
+    };
+
+    await instance.handle(args, EXTRA_REQUEST_HANDLER);
+
+    expect(mockClient.getApiClient().post).toHaveBeenCalledWith(
+      "/testcycles/SA-R1/links/issues",
+      {
+        issueId: args.issueId,
+      },
+    );
+  });
+
+  it("should call apiClient.post with correct params using test cycle ID", async () => {
+    mockClient.getApiClient().post.mockResolvedValueOnce(undefined);
+
+    const args = {
+      testCycleIdOrKey: "1001",
+      issueId: 54,
+    };
+
+    await instance.handle(args, EXTRA_REQUEST_HANDLER);
+
+    expect(mockClient.getApiClient().post).toHaveBeenCalledWith(
+      "/testcycles/1001/links/issues",
+      {
+        issueId: args.issueId,
+      },
+    );
+  });
+
+  it("should ignore extra parameters not in the schema", async () => {
+    mockClient.getApiClient().post.mockResolvedValueOnce(undefined);
+
+    const args = {
+      testCycleIdOrKey: "SA-R1",
+      issueId: 55,
+      extraField: "should be ignored",
+    };
+
+    await instance.handle(args, EXTRA_REQUEST_HANDLER);
+
+    expect(mockClient.getApiClient().post).toHaveBeenCalledWith(
+      "/testcycles/SA-R1/links/issues",
+      {
+        issueId: args.issueId,
+      },
+    );
+  });
+
+  it("should handle apiClient.post throwing error", async () => {
+    mockClient
+      .getApiClient()
+      .post.mockRejectedValueOnce(new Error("API error"));
+
+    const args = {
+      testCycleIdOrKey: "SA-R1",
+      issueId: 53,
+    };
+
+    await expect(instance.handle(args, EXTRA_REQUEST_HANDLER)).rejects.toThrow(
+      "API error",
+    );
+  });
+
+  it("should throw validation error if issueId is missing", async () => {
+    const args = {
+      testCycleIdOrKey: "SA-R1",
+    };
+
+    await expect(
+      instance.handle(args, EXTRA_REQUEST_HANDLER),
+    ).rejects.toThrow();
+  });
+
+  it("should throw validation error if testCycleIdOrKey is missing", async () => {
+    const args = {
+      issueId: 53,
+    };
+
+    await expect(
+      instance.handle(args, EXTRA_REQUEST_HANDLER),
+    ).rejects.toThrow();
+  });
+});

src/zephyr/client.ts

@@ -22,6 +22,7 @@ import { GetTestCase } from "./tool/test-case/get-test-case";
 import { GetTestCases } from "./tool/test-case/get-test-cases";
 import { GetTestCaseSteps } from "./tool/test-case/get-test-steps.ts";
 import { UpdateTestCase } from "./tool/test-case/update-test-case.ts";
+import { CreateTestCycleIssueLink } from "./tool/test-cycle/create-issue-link";
 import { CreateTestCycle } from "./tool/test-cycle/create-test-cycle";
 import { CreateTestCycleWebLink } from "./tool/test-cycle/create-web-link.ts";
 import { GetTestCycle } from "./tool/test-cycle/get-test-cycle";
@@ -96,6 +97,7 @@ export class ZephyrClient implements Client {
       new CreateTestCaseWebLink(this),
       new CreateTestSteps(this),
       new CreateTestCaseIssueLink(this),
+      new CreateTestCycleIssueLink(this),
       new CreateFolder(this),
       new CreateTestScript(this),
       new UpdateTestExecution(this),

src/zephyr/tool/test-cycle/create-issue-link.ts

@@ -0,0 +1,55 @@
+import type { ToolCallback } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ZodRawShape } from "zod";
+import { Tool } from "../../../common/tools";
+import type { ToolParams } from "../../../common/types";
+import type { ZephyrClient } from "../../client";
+import {
+  CreateTestCycleIssueLinkBody,
+  CreateTestCycleIssueLinkParams,
+} from "../../common/rest-api-schemas";
+
+export class CreateTestCycleIssueLink extends Tool<ZephyrClient> {
+  specification: ToolParams = {
+    title: "Create Test Cycle Issue Link",
+    summary:
+      "Create a new link between an issue in Jira and a Test Cycle in Zephyr",
+    readOnly: false,
+    idempotent: false,
+    inputSchema: CreateTestCycleIssueLinkParams.and(
+      CreateTestCycleIssueLinkBody,
+    ),
+    examples: [
+      {
+        description:
+          "Create a link between the test cycle with key SA-R1 and the Jira Issue ID 10100",
+        parameters: {
+          testCycleIdOrKey: "SA-R1",
+          issueId: 10100,
+        },
+        expectedOutput:
+          "The link between Test Cycle and Jira issue should be created, but no output is expected.",
+      },
+      {
+        description:
+          "Create a link between the test cycle with ID 1001 and the Jira issue ID 20200",
+        parameters: {
+          testCycleIdOrKey: "1001",
+          issueId: 20200,
+        },
+        expectedOutput:
+          "The link between Test Cycle and Jira issue should be created, but no output is expected.",
+      },
+    ],
+  };
+  handle: ToolCallback<ZodRawShape> = async (args) => {
+    const { testCycleIdOrKey } = CreateTestCycleIssueLinkParams.parse(args);
+    const body = CreateTestCycleIssueLinkBody.parse(args);
+    await this.client
+      .getApiClient()
+      .post(`/testcycles/${testCycleIdOrKey}/links/issues`, body);
+    return {
+      structuredContent: {},
+      content: [],
+    };
+  };
+}