Add display-review tool for agentic review

.changeset/cold-otters-wait.md

@@ -0,0 +1,5 @@
+---
+"@storybook/addon-mcp": minor
+---
+
+Added the `display-review` tool. The agent pushes a curated review of current changes and returns the review-page URL. Pairs with the `@storybook/addon-review` Storybook addon.

packages/addon-mcp/src/constants.ts

@@ -1,2 +1,20 @@
 export const MCP_APP_PARAM = 'mcp-app';
 export const MCP_APP_SIZE_CHANGED_EVENT = 'storybook-mcp:size-changed';
+
+/**
+ * Channel event shared with `@storybook/addon-review` (cross-repo contract).
+ * Emitted by the `display-review` tool to hand the agent's payload off to the
+ * addon-review server preset
+ */
+export const PUSH_REVIEW_EVENT = 'storybook/addon-review/push-review';
+
+/** Storybook manager route the review page is registered at. */
+export const REVIEW_PAGE_PATH = '/review/';
+
+/**
+ * Default path the MCP server is mounted at on the Storybook dev server.
+ * The user can override this via the addon's `endpoint` option; everywhere
+ * else in the codebase that needs to compare against or fall back to the
+ * default should import this constant rather than hard-coding `'/mcp'`.
+ */
+export const DEFAULT_MCP_ENDPOINT = '/mcp';

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

@@ -8,6 +8,7 @@ describe('buildServerInstructions', () => {
 			testEnabled: true,
 			docsEnabled: true,
 			changeDetectionEnabled: true,
+			reviewEnabled: true,
 		});
 
 		expect(instructions).toMatchInlineSnapshot(`
@@ -18,7 +19,9 @@ 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 **get-changed-stories** to discover new/modified/related stories, then call **preview-stories** to retrieve preview URLs.
+			- In final user-facing responses, order links consistently: review page first (if available), changed-stories fallback next (if relevant), then specific preview URLs.
 			- Always include every returned preview URL in your user-facing response so the user can verify the visual result.
+			- After completing the change, call **display-review** to publish a curated review to Storybook's review page. If the session has a browser-preview tool, navigate it to the returned \`reviewUrl\` so the user sees the review without leaving the chat. Always include the \`reviewUrl\` in your final response as a fallback. Call this tool again whenever the user iterates on the changes, so you keep the review up to date.
 
 			## Validation Workflow
 
@@ -53,6 +56,7 @@ describe('buildServerInstructions', () => {
 			testEnabled: false,
 			docsEnabled: false,
 			changeDetectionEnabled: true,
+			reviewEnabled: true,
 		});
 
 		expect(instructions).toMatchInlineSnapshot(`
@@ -63,7 +67,9 @@ 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 **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."
+			- In final user-facing responses, order links consistently: review page first (if available), changed-stories fallback next (if relevant), then specific preview URLs.
+			- Always include every returned preview URL in your user-facing response so the user can verify the visual result.
+			- After completing the change, call **display-review** to publish a curated review to Storybook's review page. If the session has a browser-preview tool, navigate it to the returned \`reviewUrl\` so the user sees the review without leaving the chat. Always include the \`reviewUrl\` in your final response as a fallback. Call this tool again whenever the user iterates on the changes, so you keep the review up to date."
 		`);
 	});
 
@@ -83,6 +89,29 @@ 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** to retrieve preview URLs.
+			- In final user-facing responses, order links consistently: review page first (if available), changed-stories fallback next (if relevant), then specific preview URLs.
+			- Always include every returned preview URL in your user-facing response so the user can verify the visual result."
+		`);
+	});
+
+	it('omits display-review step when reviewEnabled is false even with change detection on', () => {
+		const instructions = buildServerInstructions({
+			devEnabled: true,
+			testEnabled: false,
+			docsEnabled: false,
+			changeDetectionEnabled: true,
+			reviewEnabled: 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 **get-changed-stories** to discover new/modified/related stories, then call **preview-stories** to retrieve preview URLs.
+			- In final user-facing responses, order links consistently: review page first (if available), changed-stories fallback next (if relevant), then specific 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

@@ -7,20 +7,29 @@ export type BuildServerInstructionsOptions = {
 	testEnabled: boolean;
 	docsEnabled: boolean;
 	changeDetectionEnabled?: boolean;
+	reviewEnabled?: boolean;
 };
 
 export function buildServerInstructions(options: BuildServerInstructionsOptions): string {
 	const sections = ['Follow these workflows when working with UI and/or Storybook.'];
 
 	if (options.devEnabled) {
+		const changeDetection = options.changeDetectionEnabled ?? false;
+		const reviewEnabled = options.reviewEnabled ?? false;
 		sections.push(
 			devInstructions
 				.replace(
 					'{{PREVIEW_STORIES_STEP}}',
-					(options.changeDetectionEnabled ?? false)
+					changeDetection
 						? '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.',
 				)
+				.replace(
+					'{{DISPLAY_REVIEW_STEP}}',
+					reviewEnabled
+						? "\n- After completing the change, call **display-review** to publish a curated review to Storybook's review page. If the session has a browser-preview tool, navigate it to the returned `reviewUrl` so the user sees the review without leaving the chat. Always include the `reviewUrl` in your final response as a fallback. Call this tool again whenever the user iterates on the changes, so you keep the review up to date."
+						: '',
+				)
 				.trim(),
 		);
 	}

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

@@ -3,4 +3,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.
 - {{PREVIEW_STORIES_STEP}}
-- Always include every returned preview URL in your user-facing response so the user can verify the visual result.
+- In final user-facing responses, order links consistently: review page first (if available), changed-stories fallback next (if relevant), then specific preview URLs.
+- Always include every returned preview URL in your user-facing response so the user can verify the visual result.{{DISPLAY_REVIEW_STEP}}

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

@@ -147,6 +147,7 @@ play: async ({ canvas }) => {
 
 - ALWAYS provide story links after any changes to stories files, including changes to existing stories.
 - {{STORY_LINKING_WORKFLOW}}
+- In the final user-facing response, present links in this order: review page URL first (when available), changed-stories fallback URL second (when relevant), then specific story preview URLs.
 - 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.

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

@@ -4,6 +4,7 @@ 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 { addDisplayReviewTool } from './tools/display-review.ts';
 import { addGetUIBuildingInstructionsTool } from './tools/get-storybook-story-instructions.ts';
 import {
 	addListAllDocumentationTool,
@@ -18,11 +19,13 @@ import { collectTelemetry } from './telemetry.ts';
 import type { AddonContext, AddonOptionsOutput } from './types.ts';
 import { logger } from 'storybook/internal/node-logger';
 import { getManifestStatus } from './tools/is-manifest-available.ts';
+import { getReviewStatus } from './utils/is-review-available.ts';
 import { addRunStoryTestsTool, getAddonVitestConstants } from './tools/run-story-tests.ts';
 import { estimateTokens } from './utils/estimate-tokens.ts';
 import { isAddonA11yEnabled } from './utils/is-addon-a11y-enabled.ts';
 import type { CompositionAuth } from './auth/index.ts';
 import { buildServerInstructions } from './instructions/build-server-instructions.ts';
+import { DEFAULT_MCP_ENDPOINT } from './constants.ts';
 
 let transport: HttpTransport<AddonContext> | undefined;
 let origin: string | undefined;
@@ -37,9 +40,12 @@ const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 	const changeDetectionEnabled = features?.changeDetection ?? false;
 	disableTelemetry = core?.disableTelemetry ?? false;
 
-	// Determine tool availability before creating server so instructions can be tailored
+	// Determine tool availability before creating server so instructions can be tailored.
+	// Reuse the already-resolved `features` so getReviewStatus doesn't re-call
+	// `presets.apply('features', …)` and risk a different snapshot.
 	const addonVitestConstants = await getAddonVitestConstants();
 	const manifestStatus = await getManifestStatus(options);
+	const reviewStatus = await getReviewStatus(options, { features });
 	a11yEnabled = await isAddonA11yEnabled(options);
 
 	let server: McpServer<any, AddonContext>;
@@ -52,6 +58,7 @@ const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 				testEnabled: (server?.ctx.custom?.toolsets?.test ?? true) && !!addonVitestConstants,
 				docsEnabled: (server?.ctx.custom?.toolsets?.docs ?? true) && manifestStatus.available,
 				changeDetectionEnabled,
+				reviewEnabled: reviewStatus.available,
 			});
 		},
 		capabilities: {
@@ -83,6 +90,10 @@ const initializeMCPServer = async (options: Options, multiSource?: boolean) => {
 		await addGetChangedStoriesTool(server);
 	}
 
+	if (reviewStatus.available) {
+		await addDisplayReviewTool(server);
+	}
+
 	// Register test addon tools
 	await addRunStoryTestsTool(server, { a11yEnabled });
 
@@ -111,6 +122,13 @@ type McpServerHandlerParams = {
 	res: ServerResponse;
 	options: Options;
 	addonOptions: AddonOptionsOutput;
+	/**
+	 * The MCP endpoint path (e.g. `/mcp` or a user-configured override).
+	 * Used to derive the Storybook root from the incoming request URL inside
+	 * tools like `display-review`. Optional for backwards compatibility with
+	 * external callers; defaults to {@link DEFAULT_MCP_ENDPOINT}.
+	 */
+	endpoint?: string;
 	/** Sources for multi-source mode (when refs are configured) */
 	sources?: Source[];
 	/** Optional custom manifest provider, receives source as third param in multi-source mode */
@@ -128,6 +146,7 @@ export const mcpServerHandler = async ({
 	res,
 	options,
 	addonOptions,
+	endpoint = DEFAULT_MCP_ENDPOINT,
 	sources,
 	manifestProvider,
 	compositionAuth,
@@ -146,6 +165,7 @@ export const mcpServerHandler = async ({
 
 	const addonContext: AddonContext = {
 		options,
+		endpoint,
 		toolsets: getToolsets(webRequest, addonOptions),
 		origin: origin!,
 		disableTelemetry: disableTelemetry!,

packages/addon-mcp/src/preset.test.ts

@@ -96,6 +96,26 @@ describe('experimental_devServer', () => {
 		expect(mcpHandler).toBeDefined();
 	});
 
+	it('does not register any review-related channel listeners (handled by addon-review preset)', async () => {
+		const channel = { on: vi.fn(), emit: vi.fn() };
+		const optionsWithReview = {
+			...mockOptions,
+			channel,
+			presets: {
+				apply: vi.fn((key: string) => {
+					if (key === 'features') {
+						return Promise.resolve({ changeDetection: true });
+					}
+					return Promise.resolve(undefined);
+				}),
+			},
+		} as unknown as Options;
+
+		await (experimental_devServer as any)(mockApp, optionsWithReview);
+
+		expect(channel.on).not.toHaveBeenCalled();
+	});
+
 	it('should register /mcp GET endpoint', async () => {
 		await (experimental_devServer as any)(mockApp, mockOptions);
 

packages/addon-mcp/src/preset.ts

@@ -18,8 +18,8 @@ import {
 import { logger } from 'storybook/internal/node-logger';
 import type { Source } from '@storybook/mcp';
 import type { IncomingMessage, ServerResponse } from 'node:http';
+import { DEFAULT_MCP_ENDPOINT } from './constants.ts';
 
-const DEFAULT_MCP_ENDPOINT = '/mcp';
 const STORYBOOK_MCP_PROXY_HEADER_KEY = STORYBOOK_MCP_PROXY_HEADER.toLowerCase();
 
 export const previewAnnotations: PresetPropertyFn<'previewAnnotations'> = async (
@@ -103,6 +103,7 @@ export const experimental_devServer: PresetPropertyFn<
 			res,
 			options,
 			addonOptions,
+			endpoint,
 			sources,
 			manifestProvider: createManifestProvider?.(req),
 			compositionAuth,
@@ -126,6 +127,7 @@ export const experimental_devServer: PresetPropertyFn<
 				res,
 				options,
 				addonOptions,
+				endpoint,
 				sources,
 				manifestProvider: createManifestProvider?.(req),
 				compositionAuth,