feat: add epics-create-comment tool

Add support for creating comments on epics, mirroring the existing
stories-create-comment tool. The Shortcut API and SDK already support
epic comments, but the MCP server did not expose this capability.

Changes:
- Add createEpicComment method to ShortcutClientWrapper
- Register epics-create-comment tool with write access
- Add unit tests for the new tool

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: pasha-tw

src/client/shortcut.ts

@@ -5,6 +5,7 @@ import type {
 	ShortcutClient as BaseClient,
 	CreateDoc,
 	CreateEpic,
+	CreateEpicComment,
 	CreateIteration,
 	CreateLabelParams,
 	CreateStoryComment,
@@ -26,6 +27,7 @@ import type {
 	StoryLink,
 	StorySlim,
 	Task,
+	ThreadedComment,
 	UpdateDoc,
 	UpdateEpic,
 	UpdateIteration,
@@ -446,6 +448,18 @@ export class ShortcutClientWrapper {
 		await this.client.deleteIteration(iterationPublicId);
 	}
 
+	async createEpicComment(
+		epicPublicId: number,
+		params: CreateEpicComment,
+	): Promise<ThreadedComment> {
+		const response = await this.client.createEpicComment(epicPublicId, params);
+		const epicComment = response?.data ?? null;
+
+		if (!epicComment) throw new Error(`Failed to create the comment: ${response.status}`);
+
+		return epicComment;
+	}
+
 	async createEpic(params: CreateEpic): Promise<Epic> {
 		const response = await this.client.createEpic(params);
 		const epic = response?.data ?? null;

src/tools/epics.test.ts

@@ -113,10 +113,11 @@ describe("EpicTools", () => {
 			expect(mockToolRead.mock.calls?.[0]?.[0]).toBe("epics-get-by-id");
 			expect(mockToolRead.mock.calls?.[1]?.[0]).toBe("epics-search");
 
-			expect(mockToolWrite).toHaveBeenCalledTimes(3);
+			expect(mockToolWrite).toHaveBeenCalledTimes(4);
 			expect(mockToolWrite.mock.calls?.[0]?.[0]).toBe("epics-create");
 			expect(mockToolWrite.mock.calls?.[1]?.[0]).toBe("epics-update");
-			expect(mockToolWrite.mock.calls?.[2]?.[0]).toBe("epics-delete");
+			expect(mockToolWrite.mock.calls?.[2]?.[0]).toBe("epics-create-comment");
+			expect(mockToolWrite.mock.calls?.[3]?.[0]).toBe("epics-delete");
 		});
 	});
 
@@ -425,6 +426,70 @@ describe("EpicTools", () => {
 		});
 	});
 
+	describe("createEpicComment method", () => {
+		const getEpicMock = mock(async (id: number) => mockEpics.find((epic) => epic.id === id));
+		const createEpicCommentMock = mock(async (_id: number, _params: { text: string }) => ({
+			id: 100,
+			text: "Test comment",
+			app_url: "https://app.shortcut.com/test/epic/1/comments/100",
+		}));
+
+		beforeEach(() => {
+			createEpicCommentMock.mockClear();
+		});
+
+		test("should create a comment on an epic", async () => {
+			const mockClient = createMockClient({
+				getEpic: getEpicMock,
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+			const result = await epicTools.createEpicComment({
+				epicPublicId: 1,
+				text: "Test comment",
+			});
+
+			expect(getTextContent(result)).toBe(
+				"Created comment on epic 1. Comment URL: https://app.shortcut.com/test/epic/1/comments/100.",
+			);
+			expect(createEpicCommentMock).toHaveBeenCalledTimes(1);
+			expect(createEpicCommentMock.mock.calls?.[0]?.[0]).toBe(1);
+			expect(createEpicCommentMock.mock.calls?.[0]?.[1]).toMatchObject({
+				text: "Test comment",
+			});
+		});
+
+		test("should throw error when epic is not found", async () => {
+			const mockClient = createMockClient({
+				getEpic: mock(async () => null),
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+
+			await expect(() =>
+				epicTools.createEpicComment({
+					epicPublicId: 999,
+					text: "Test comment",
+				}),
+			).toThrow("Failed to retrieve Shortcut epic with public ID: 999");
+		});
+
+		test("should throw error when text is empty", async () => {
+			const mockClient = createMockClient({
+				getEpic: getEpicMock,
+				createEpicComment: createEpicCommentMock,
+			});
+			const epicTools = new EpicTools(mockClient);
+
+			await expect(() =>
+				epicTools.createEpicComment({
+					epicPublicId: 1,
+					text: "",
+				}),
+			).toThrow("Epic comment text is required");
+		});
+	});
+
 	describe("deleteEpic method", () => {
 		const getEpicMock = mock(async (id: number) => mockEpics.find((epic) => epic.id === id));
 		const deleteEpicMock = mock(async (_id: number) => undefined);

src/tools/epics.ts

@@ -93,6 +93,16 @@ export class EpicTools extends BaseTools {
 			async (params) => await tools.updateEpic(params),
 		);
 
+		server.addToolWithWriteAccess(
+			"epics-create-comment",
+			"Add a comment to an epic.",
+			{
+				epicPublicId: z.number().positive().describe("Epic ID"),
+				text: z.string().min(1).describe("Comment text"),
+			},
+			async (params) => await tools.createEpicComment(params),
+		);
+
 		server.addToolWithWriteAccess(
 			"epics-delete",
 			"Delete an epic (cannot be undone).",
@@ -196,6 +206,29 @@ export class EpicTools extends BaseTools {
 		return this.toResult(`Updated epic ${epicPublicId}. Epic URL: ${updatedEpic.app_url}`);
 	}
 
+	async createEpicComment({
+		epicPublicId,
+		text,
+	}: {
+		epicPublicId: number;
+		text: string;
+	}): Promise<CallToolResult> {
+		if (!epicPublicId) throw new Error("Epic public ID is required");
+		if (!text) throw new Error("Epic comment text is required");
+
+		const epic = await this.client.getEpic(epicPublicId);
+		if (!epic)
+			throw new Error(`Failed to retrieve Shortcut epic with public ID: ${epicPublicId}`);
+
+		const epicComment = await this.client.createEpicComment(epicPublicId, {
+			text,
+		});
+
+		return this.toResult(
+			`Created comment on epic ${epicPublicId}. Comment URL: ${epicComment.app_url}.`,
+		);
+	}
+
 	async deleteEpic(epicPublicId: number): Promise<CallToolResult> {
 		const epic = await this.client.getEpic(epicPublicId);
 		if (!epic) throw new Error(`Failed to retrieve Shortcut epic with public ID: ${epicPublicId}`);