Add get-changed-stories tool

.changeset/icy-walls-exist.md

@@ -0,0 +1,6 @@
+---
+"@storybook/addon-mcp": minor
+---
+
+Introduced the `get-changed-stories` tool to retrieve metadata for stories marked as new, modified, or affected.
+Updated `dev-instructions.md` and `storybook-story-instructions.md` to reflect the new workflow for calling `get-changed-stories` before `preview-stories`.

apps/internal-storybook/.storybook/main.ts

@@ -29,6 +29,7 @@ const config = defineMain({
 		disableTelemetry: true,
 	},
 	features: {
+		changeDetection: true,
 		experimentalComponentsManifest: true,
 	},
 	// No refs - single source mode

apps/internal-storybook/tests/helpers.ts

@@ -80,8 +80,20 @@ export async function stopStorybook(storybookProcess: ReturnType<typeof x> | nul
 	if (!storybookProcess || !storybookProcess.process) {
 		return;
 	}
-	const kill = Promise.withResolvers<void>();
-	storybookProcess.process.on('exit', kill.resolve);
+	const exitSignal = Promise.withResolvers<void>();
+	storybookProcess.process.on('exit', exitSignal.resolve);
 	storybookProcess.kill('SIGTERM');
-	await kill.promise;
+
+	// Storybook can ignore SIGTERM while workers are shutting down.
+	// Escalate to SIGKILL after a short grace period to keep tests bounded.
+	const killTimeout = setTimeout(() => {
+		try {
+			storybookProcess.kill('SIGKILL');
+		} catch {
+			// Process may already be gone.
+		}
+	}, 10_000);
+
+	await exitSignal.promise;
+	clearTimeout(killTimeout);
 }

apps/internal-storybook/tests/mcp-endpoint.e2e.test.ts

@@ -100,7 +100,7 @@ describe('MCP Endpoint E2E Tests', () => {
 
 			expect(response.result).toHaveProperty('tools');
 			// Dev, docs, and test tools should be present
-			expect(response.result.tools).toHaveLength(6);
+			expect(response.result.tools).toHaveLength(7);
 
 			expect(response.result.tools).toMatchInlineSnapshot(`
 				[
@@ -369,6 +369,15 @@ describe('MCP Endpoint E2E Tests', () => {
 				    "name": "get-storybook-story-instructions",
 				    "title": "Storybook Story Development Instructions",
 				  },
+				  {
+				    "description": "Get Storybook stories marked as new, modified, or related. Returns story metadata only (no URLs).",
+				    "inputSchema": {
+				      "properties": {},
+				      "type": "object",
+				    },
+				    "name": "get-changed-stories",
+				    "title": "Get changed stories metadata",
+				  },
 				  {
 				    "description": "Run story tests.
 				Provide stories for focused runs (faster while iterating),
@@ -846,6 +855,7 @@ describe('MCP Endpoint E2E Tests', () => {
 			expect(result1.result).toBeDefined();
 			expect(result1.result.content).toBeDefined();
 			expect(result1.result.content.length).toBeGreaterThan(0);
+
 			expect(result1.result.content[0].text).toContain('example-button--primary');
 			expect(result1.result.content[0].text).toContain('Passing Stories');
 
@@ -890,6 +900,7 @@ describe('MCP Endpoint E2E Tests', () => {
 				[
 				  "preview-stories",
 				  "get-storybook-story-instructions",
+				  "get-changed-stories",
 				]
 			`);
 		});

packages/addon-mcp/src/instructions/build-server-instructions.test.ts

@@ -7,6 +7,7 @@ describe('buildServerInstructions', () => {
 			devEnabled: true,
 			testEnabled: true,
 			docsEnabled: true,
+			changeDetectionEnabled: true,
 		});
 
 		expect(instructions).toMatchInlineSnapshot(`
@@ -16,7 +17,7 @@ describe('buildServerInstructions', () => {
 
 			- Before creating or editing components or stories, call **get-storybook-story-instructions**.
 			- Treat that tool's output as the source of truth for framework-specific imports, story patterns, and testing conventions.
-			- After changing any component or story, call **preview-stories**.
+			- After changing any component or story, call **get-changed-stories** to discover new/modified/related stories, then call **preview-stories** to retrieve preview URLs.
 			- Always include every returned preview URL in your user-facing response so the user can verify the visual result.
 
 			## Validation Workflow
@@ -51,6 +52,7 @@ describe('buildServerInstructions', () => {
 			devEnabled: true,
 			testEnabled: false,
 			docsEnabled: false,
+			changeDetectionEnabled: true,
 		});
 
 		expect(instructions).toMatchInlineSnapshot(`
@@ -60,7 +62,27 @@ describe('buildServerInstructions', () => {
 
 			- Before creating or editing components or stories, call **get-storybook-story-instructions**.
 			- Treat that tool's output as the source of truth for framework-specific imports, story patterns, and testing conventions.
-			- After changing any component or story, call **preview-stories**.
+			- After changing any component or story, call **get-changed-stories** to discover new/modified/related stories, then call **preview-stories** to retrieve preview URLs.
+			- Always include every returned preview URL in your user-facing response so the user can verify the visual result."
+		`);
+	});
+
+	it('omits get-changed-stories step when change detection is disabled', () => {
+		const instructions = buildServerInstructions({
+			devEnabled: true,
+			testEnabled: false,
+			docsEnabled: false,
+			changeDetectionEnabled: false,
+		});
+
+		expect(instructions).toMatchInlineSnapshot(`
+			"Follow these workflows when working with UI and/or Storybook.
+
+			## UI Building and Story Writing Workflow
+
+			- Before creating or editing components or stories, call **get-storybook-story-instructions**.
+			- Treat that tool's output as the source of truth for framework-specific imports, story patterns, and testing conventions.
+			- After changing any component or story, call **preview-stories** to retrieve preview URLs.
 			- Always include every returned preview URL in your user-facing response so the user can verify the visual result."
 		`);
 	});

packages/addon-mcp/src/instructions/build-server-instructions.ts

@@ -6,13 +6,23 @@ export type BuildServerInstructionsOptions = {
 	devEnabled: boolean;
 	testEnabled: boolean;
 	docsEnabled: boolean;
+	changeDetectionEnabled?: boolean;
 };
 
 export function buildServerInstructions(options: BuildServerInstructionsOptions): string {
 	const sections = ['Follow these workflows when working with UI and/or Storybook.'];
 
 	if (options.devEnabled) {
-		sections.push(devInstructions.trim());
+		sections.push(
+			devInstructions
+				.replace(
+					'{{PREVIEW_STORIES_STEP}}',
+					(options.changeDetectionEnabled ?? false)
+						? 'After changing any component or story, call **get-changed-stories** to discover new/modified/related stories, then call **preview-stories** to retrieve preview URLs.'
+						: 'After changing any component or story, call **preview-stories** to retrieve preview URLs.',
+				)
+				.trim(),
+		);
 	}
 
 	if (options.testEnabled) {

packages/addon-mcp/src/instructions/dev-instructions.md

@@ -2,5 +2,5 @@
 
 - Before creating or editing components or stories, call **get-storybook-story-instructions**.
 - Treat that tool's output as the source of truth for framework-specific imports, story patterns, and testing conventions.
-- After changing any component or story, call **preview-stories**.
+- {{PREVIEW_STORIES_STEP}}
 - Always include every returned preview URL in your user-facing response so the user can verify the visual result.

packages/addon-mcp/src/instructions/story-testing-instructions.md

@@ -5,7 +5,7 @@
 ### Workflow
 
 1. Make your change
-2. Run `{{RUN_STORY_TESTS_TOOL_NAME}}` with affected stories for focused feedback (faster while iterating)
+2. Run `{{RUN_STORY_TESTS_TOOL_NAME}}` with related stories for focused feedback (faster while iterating)
 3. If tests fail: analyze, fix{{A11Y_FIX_SUFFIX}}, re-run
 4. Repeat until all tests pass
 

packages/addon-mcp/src/instructions/storybook-story-instructions.md

@@ -146,5 +146,7 @@ play: async ({ canvas }) => {
 ## Story Linking Agent Behavior
 
 - ALWAYS provide story links after any changes to stories files, including changes to existing stories.
+- {{STORY_LINKING_WORKFLOW}}
+- When sharing links, choose the most relevant subset for the user and avoid long lists (generally no more than 5 links).
+- {{CHANGED_STORY_FALLBACK_LINK_GUIDANCE}}
 - After changing any UI components, ALWAYS search for related stories that might cover the changes you've made. If you find any, provide the story links to the user. THIS IS VERY IMPORTANT, as it allows the user to visually inspect the changes you've made. Even later in a session when changing UI components or stories that have already been linked to previously, YOU MUST PROVIDE THE LINKS AGAIN.
-- Use the {{PREVIEW_STORIES_TOOL_NAME}} tool to get the correct URLs for links to stories.

packages/addon-mcp/src/mcp-handler.ts

@@ -3,6 +3,7 @@ import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
 import { HttpTransport } from '@tmcp/transport-http';
 import pkgJson from '../package.json' with { type: 'json' };
 import { addPreviewStoriesTool } from './tools/preview-stories.ts';
+import { addGetChangedStoriesTool } from './tools/get-changed-stories.ts';
 import { addGetUIBuildingInstructionsTool } from './tools/get-storybook-story-instructions.ts';
 import {
 	addListAllDocumentationTool,
@@ -32,6 +33,8 @@ let a11yEnabled: boolean | undefined;
 
 const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 	const core = await options.presets.apply('core', {});
+	const features = await options.presets.apply('features', {});
+	const changeDetectionEnabled = features?.changeDetection ?? false;
 	disableTelemetry = core?.disableTelemetry ?? false;
 
 	// Determine tool availability before creating server so instructions can be tailored
@@ -48,6 +51,7 @@ const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 				devEnabled: server?.ctx.custom?.toolsets?.dev ?? true,
 				testEnabled: (server?.ctx.custom?.toolsets?.test ?? true) && !!addonVitestConstants,
 				docsEnabled: (server?.ctx.custom?.toolsets?.docs ?? true) && manifestStatus.available,
+				changeDetectionEnabled,
 			});
 		},
 		capabilities: {
@@ -75,6 +79,10 @@ const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 	await addPreviewStoriesTool(server);
 	await addGetUIBuildingInstructionsTool(server);
 
+	if (changeDetectionEnabled) {
+		await addGetChangedStoriesTool(server);
+	}
+
 	// Register test addon tools
 	await addRunStoryTestsTool(server, { a11yEnabled });