Merge pull request #159 from useshortcut/amcd/list-label-stories

Add tool for listing label stories.

Author: andreasmcdermott

README.md

@@ -92,6 +92,7 @@ If your IDE doesn't support HTTP-based MCP servers, or you'd prefer to run the s
 | Tool | Description |
 |------|-------------|
 | `labels-list` | List all labels in the Shortcut workspace |
+| `labels-get-stories` | Get all stories with a specific label |
 | `labels-create` | Create a new label in Shortcut |
 
 ### Custom Fields

manifest.json

@@ -75,6 +75,7 @@
 		{ "name": "documents-search", "description": "Find documents" },
 		{ "name": "documents-get-by-id", "description": "Get a document as markdown by its ID" },
 		{ "name": "labels-list", "description": "List all labels in the Shortcut workspace" },
+		{ "name": "labels-get-stories", "description": "Get all stories with a specific label" },
 		{ "name": "labels-create", "description": "Create a new label in Shortcut" }
 	],
 	"keywords": ["shortcut", "mcp", "project-management", "stories", "epics", "iterations", "agile"],

package-lock.json

@@ -1,6 +1,6 @@
 {
 	"name": "@shortcut/mcp",
-	"version": "0.22.0",
+	"version": "0.23.0",
 	"description": "Shortcut MCP Server",
 	"repository": {
 		"type": "git",

package.json

@@ -483,6 +483,11 @@ export class ShortcutClientWrapper {
 		return response?.data ?? [];
 	}
 
+	async listLabelStories(labelPublicId: number): Promise<StorySlim[]> {
+		const response = await this.client.listLabelStories(labelPublicId);
+		return response?.data ?? [];
+	}
+
 	async addTaskToStory(
 		storyPublicId: number,
 		taskParams: {

src/client/shortcut.ts

@@ -1,5 +1,5 @@
 import { beforeEach, describe, expect, mock, test } from "bun:test";
-import type { CreateLabelParams, Label } from "@shortcut/client";
+import type { CreateLabelParams, Label, Story } from "@shortcut/client";
 import type { ShortcutClientWrapper } from "@/client/shortcut";
 import type { CustomMcpServer } from "@/mcp/CustomMcpServer";
 import { LabelTools } from "./labels";
@@ -69,6 +69,41 @@ describe("LabelTools", () => {
 		} as unknown as Label,
 	];
 
+	const mockStories: Story[] = [
+		{
+			entity_type: "story",
+			id: 123,
+			name: "Story with label one",
+			story_type: "feature",
+			owner_ids: ["user1"],
+			group_id: null,
+			epic_id: null,
+			iteration_id: null,
+			workflow_id: null,
+			workflow_state_id: 1,
+			requested_by_id: null,
+			follower_ids: [],
+			app_url: "https://app.shortcut.com/test/story/123",
+			archived: false,
+		} as unknown as Story,
+		{
+			entity_type: "story",
+			id: 456,
+			name: "Story with label two",
+			story_type: "bug",
+			owner_ids: ["user2"],
+			group_id: null,
+			epic_id: null,
+			iteration_id: null,
+			workflow_id: null,
+			workflow_state_id: 2,
+			requested_by_id: null,
+			follower_ids: [],
+			app_url: "https://app.shortcut.com/test/story/456",
+			archived: false,
+		} as unknown as Story,
+	];
+
 	const createMockClient = (methods?: object) =>
 		({
 			...methods,
@@ -86,14 +121,55 @@ describe("LabelTools", () => {
 
 			LabelTools.create(mockClient, mockServer);
 
-			expect(mockToolRead).toHaveBeenCalledTimes(1);
+			expect(mockToolRead).toHaveBeenCalledTimes(2);
 			expect(mockToolRead.mock.calls?.[0]?.[0]).toBe("labels-list");
+			expect(mockToolRead.mock.calls?.[1]?.[0]).toBe("labels-get-stories");
 
 			expect(mockToolWrite).toHaveBeenCalledTimes(1);
 			expect(mockToolWrite.mock.calls?.[0]?.[0]).toBe("labels-create");
 		});
 	});
 
+	describe("getLabelStories method", () => {
+		const listLabelStoriesMock = mock(async () => mockStories);
+
+		beforeEach(() => {
+			listLabelStoriesMock.mockClear();
+		});
+
+		test("should return formatted stories for a label", async () => {
+			const mockClient = createMockClient({
+				listLabelStories: listLabelStoriesMock,
+				getUserMap: mock(async () => new Map()),
+				getWorkflowMap: mock(async () => new Map()),
+				getTeamMap: mock(async () => new Map()),
+				getMilestone: mock(async () => null),
+				getIteration: mock(async () => null),
+				getEpic: mock(async () => null),
+				getCustomFieldMap: mock(async () => new Map()),
+			});
+			const labelTools = new LabelTools(mockClient);
+			const result = await labelTools.getLabelStories(42);
+
+			expect(listLabelStoriesMock).toHaveBeenCalledWith(42);
+
+			const textContent = getTextContent(result);
+			expect(textContent).toContain("Result (2 stories found for label 42):");
+			expect(textContent).toContain('"name": "Story with label one"');
+			expect(textContent).toContain('"name": "Story with label two"');
+		});
+
+		test("should return no stories found message when label has no stories", async () => {
+			const mockClient = createMockClient({
+				listLabelStories: mock(async () => []),
+			});
+			const labelTools = new LabelTools(mockClient);
+			const result = await labelTools.getLabelStories(42);
+
+			expect(getTextContent(result)).toBe("Result: No stories found for label 42.");
+		});
+	});
+
 	describe("listLabels method", () => {
 		const listLabelsMock = mock(async () => mockLabels);
 

src/tools/labels.test.ts

@@ -21,6 +21,15 @@ export class LabelTools extends BaseTools {
 			async (params) => await tools.listLabels(params),
 		);
 
+		server.addToolWithReadAccess(
+			"labels-get-stories",
+			"Get all stories with a specific label.",
+			{
+				labelPublicId: z.number().positive().describe("Label ID"),
+			},
+			async ({ labelPublicId }) => await tools.getLabelStories(labelPublicId),
+		);
+
 		server.addToolWithWriteAccess(
 			"labels-create",
 			"Create a new label.",
@@ -97,4 +106,17 @@ export class LabelTools extends BaseTools {
 			label: this.formatLabel(label, { includeDescription: true }),
 		});
 	}
+
+	async getLabelStories(labelPublicId: number): Promise<CallToolResult> {
+		const stories = await this.client.listLabelStories(labelPublicId);
+
+		if (!stories.length) {
+			return this.toResult(`Result: No stories found for label ${labelPublicId}.`);
+		}
+
+		return this.toResult(
+			`Result (${stories.length} stories found for label ${labelPublicId}):`,
+			await this.entitiesWithRelatedEntities(stories, "stories"),
+		);
+	}
 }