@storybook/addon-mcp 0.2.0 → 0.2.2

package/README.md

@@ -125,6 +125,7 @@ This addon should work with any MCP-compatible client that supports the `tool` c
 - [Cline](https://docs.cline.bot/mcp/configuring-mcp-servers)
 - [Zed Editor](https://zed.dev/docs/ai/mcp#as-custom-servers)
 - [Continue](https://docs.continue.dev/customize/deep-dives/mcp#how-to-configure-mcp-servers)
+- [Codex](https://github.com/openai/codex/blob/main/docs/config.md#mcp_servers)
 
 For clients not listed above, consult their documentation for MCP server configuration. The server configuration typically requires:
 
@@ -152,7 +153,7 @@ Provides agents with standardized instructions for UI component development with
 
 The instructions ensure agents follow your project's conventions when creating or modifying UI components and their corresponding stories.
 
-#### 2. Get Story URLs (`get_story_urls`)
+#### 2. Preview Stories (`preview-stories`)
 
 Allows agents to retrieve direct URLs to specific stories in your Storybook. The agent can request URLs for multiple stories by providing:
 

package/dist/preset.js

@@ -2,16 +2,19 @@ import { McpServer } from "tmcp";
 import { ValibotJsonSchemaAdapter } from "@tmcp/adapter-valibot";
 import { HttpTransport } from "@tmcp/transport-http";
 import path from "node:path";
+import url from "node:url";
 import { storyNameFromExport } from "storybook/internal/csf";
 import { logger } from "storybook/internal/node-logger";
 import * as v from "valibot";
 import { telemetry } from "storybook/internal/telemetry";
+import { stringify } from "picoquery";
+import fs from "node:fs/promises";
 import { addGetDocumentationTool, addListAllDocumentationTool } from "@storybook/mcp";
 import { buffer } from "node:stream/consumers";
 
 //#region package.json
 var name = "@storybook/addon-mcp";
-var version = "0.2.0";
+var version = "0.2.2";
 var description = "Help agents automatically write and test stories for your UI components";
 
 //#endregion
@@ -30,6 +33,61 @@ async function collectTelemetry({ event, server, ...payload }) {
 	}
 }
 
+//#endregion
+//#region src/utils/build-args-param.ts
+const HEX_REGEXP = /^#([a-f0-9]{3,4}|[a-f0-9]{6}|[a-f0-9]{8})$/i;
+const COLOR_REGEXP = /^(rgba?|hsla?)\(([0-9]{1,3}),\s?([0-9]{1,3})%?,\s?([0-9]{1,3})%?,?\s?([0-9](\.[0-9]{1,2})?)?\)$/i;
+/**
+* Encodes special values for Storybook's args URL format.
+* Handles undefined, null, booleans, dates, hex colors, and rgba/hsla colors.
+*/
+function encodeSpecialValues(value) {
+	if (value === void 0) return "!undefined";
+	if (value === null) return "!null";
+	if (typeof value === "string") {
+		if (HEX_REGEXP.test(value)) return `!hex(${value.slice(1)})`;
+		if (COLOR_REGEXP.test(value)) return `!${value.replace(/[\s%]/g, "")}`;
+		return value;
+	}
+	if (typeof value === "boolean") return `!${value}`;
+	if (value instanceof Date) return `!date(${value.toISOString()})`;
+	if (Array.isArray(value)) return value.map(encodeSpecialValues);
+	if (typeof value === "object" && value !== null) return Object.entries(value).reduce((acc, [key, val]) => Object.assign(acc, { [key]: encodeSpecialValues(val) }), {});
+	return value;
+}
+/**
+* Replaces some url-encoded characters with their decoded equivalents.
+* The URI RFC specifies these should be encoded, but all browsers will
+* tolerate them being decoded, so we opt to go with it for cleaner looking URIs.
+*/
+function decodeKnownQueryChar(chr) {
+	switch (chr) {
+		case "%20": return "+";
+		case "%5B": return "[";
+		case "%5D": return "]";
+		case "%2C": return ",";
+		case "%3A": return ":";
+	}
+	return chr;
+}
+const KNOWN_QUERY_CHAR_REGEXP = /%[0-9A-F]{2}/g;
+/**
+* Builds a Storybook args query parameter string from an object of props.
+*
+* The format uses semicolons as delimiters and colons for key:value pairs,
+* with special encoding for booleans, null, undefined, dates, and colors.
+*
+* Example output: "disabled:!true;label:Hello+World;count:42"
+*/
+function buildArgsParam(args) {
+	if (!args || Object.keys(args).length === 0) return "";
+	return stringify(encodeSpecialValues(args), {
+		delimiter: ";",
+		nesting: true,
+		nestingSyntax: "js"
+	}).replace(KNOWN_QUERY_CHAR_REGEXP, decodeKnownQueryChar).split(";").map((part) => part.replace("=", ":")).join(";");
+}
+
 //#endregion
 //#region src/utils/fetch-story-index.ts
 /**
@@ -67,95 +125,9 @@ const errorToMCPContent = (error) => {
 	};
 };
 
-//#endregion
-//#region src/types.ts
-const AddonOptions = v.object({
-	toolsets: v.optional(v.object({
-		dev: v.exactOptional(v.boolean(), true),
-		docs: v.exactOptional(v.boolean(), true)
-	}), {
-		dev: true,
-		docs: true
-	}),
-	experimentalFormat: v.optional(v.picklist(["xml", "markdown"]), "markdown")
-});
-/**
-* Schema for a single story input when requesting story URLs.
-*/
-const StoryInput = v.object({
-	exportName: v.string(),
-	explicitStoryName: v.optional(v.string()),
-	absoluteStoryPath: v.string()
-});
-/**
-* Schema for the array of stories to fetch URLs for.
-*/
-const StoryInputArray = v.array(StoryInput);
-/**
-* Schema for the output URL array.
-*/
-const StoryUrlArray = v.array(v.string());
-
-//#endregion
-//#region src/tools/get-story-urls.ts
-const GET_STORY_URLS_TOOL_NAME = "get-story-urls";
-const GetStoryUrlsInput = v.object({ stories: StoryInputArray });
-async function addGetStoryUrlsTool(server) {
-	server.tool({
-		name: GET_STORY_URLS_TOOL_NAME,
-		title: "Get stories' URLs",
-		description: `Get the URL for one or more stories.`,
-		schema: GetStoryUrlsInput,
-		enabled: () => server.ctx.custom?.toolsets?.dev ?? true
-	}, async (input) => {
-		try {
-			const { origin: origin$1, disableTelemetry: disableTelemetry$1 } = server.ctx.custom ?? {};
-			if (!origin$1) throw new Error("Origin is required in addon context");
-			const index = await fetchStoryIndex(origin$1);
-			const entriesList = Object.values(index.entries);
-			const result = [];
-			let foundStoryCount = 0;
-			for (const { exportName, explicitStoryName, absoluteStoryPath } of input.stories) {
-				const relativePath = `./${path.relative(process.cwd(), absoluteStoryPath)}`;
-				logger.debug("Searching for:");
-				logger.debug({
-					exportName,
-					explicitStoryName,
-					absoluteStoryPath,
-					relativePath
-				});
-				const foundStoryId = entriesList.find((entry) => entry.importPath === relativePath && [explicitStoryName, storyNameFromExport(exportName)].includes(entry.name))?.id;
-				if (foundStoryId) {
-					logger.debug(`Found story ID: ${foundStoryId}`);
-					result.push(`${origin$1}/?path=/story/${foundStoryId}`);
-					foundStoryCount++;
-				} else {
-					logger.debug("No story found");
-					let errorMessage = `No story found for export name "${exportName}" with absolute file path "${absoluteStoryPath}"`;
-					if (!explicitStoryName) errorMessage += ` (did you forget to pass the explicit story name?)`;
-					result.push(errorMessage);
-				}
-			}
-			if (!disableTelemetry$1) await collectTelemetry({
-				event: "tool:getStoryUrls",
-				server,
-				toolset: "dev",
-				inputStoryCount: input.stories.length,
-				outputStoryCount: foundStoryCount
-			});
-			return { content: result.map((text) => ({
-				type: "text",
-				text
-			})) };
-		} catch (error) {
-			return errorToMCPContent(error);
-		}
-	});
-}
-
 //#endregion
 //#region src/storybook-story-instructions.md
-var storybook_story_instructions_default = "# Writing User Interfaces\n\nWhen writing UI, prefer breaking larger components up into smaller parts.\n\nALWAYS write a Storybook story for any component written. If editing a component, ensure appropriate changes have been made to stories for that component.\n\n## How to write good stories\n\nGoal: Cover every distinct piece of business logic and state the component can reach (happy paths, error/edge states, loading, permissions/roles, empty states, variations from props/context). Avoid redundant stories that show the same logic.\n\nInteractivity: If the component is interactive, add Interaction tests using play functions that drive the UI with storybook/test utilities (e.g., fn, userEvent, expect). Simulate key user flows: clicking buttons/links, typing, focus/blur, keyboard nav, form submit, async responses, toggle/selection changes, pagination/filters, etc. When passing `fn` functions as `args` for callback functions, make sure to add a play function which interacts with the component and assert whether the callback function was actually called.\n\nData/setup: Provide realistic props, state, and mocked data. Include meaningful labels/text to make behaviors observable. Stub network/services with deterministic fixtures; keep stories reliable.\n\nAssertions: In play functions, assert the visible outcome of the interaction (text, aria state, enabled/disabled, class/state changes, emitted events). Prefer role/label-based queries.\n\nVariants to consider (pick only those that change behavior): default vs. alternate themes; loading vs. loaded vs. empty vs. error; validated vs. invalid input; permissions/roles/capabilities; feature flags; size/density/layout variants that alter logic.\n\nAccessibility: Use semantic roles/labels; ensure focusable/keyboard interactions are test-covered where relevant.\n\nNaming/structure: Use clear story names that describe the scenario (“Error state after failed submit”). Group related variants logically; don’t duplicate.\n\nImports/format: Import Meta/StoryObj from the framework package; import test helpers from storybook/test (not @storybook/test). Keep stories minimal—only what's needed to demonstrate behavior.\n\n## Storybook 9 Essential Changes for Story Writing\n\n### Package Consolidation\n\n#### `Meta` and `StoryObj` imports\n\nUpdate story imports to use the framework package:\n\n```diff\n- import { Meta, StoryObj } from '{{RENDERER}}';\n+ import { Meta, StoryObj } from '{{FRAMEWORK}}';\n```\n\n#### Test utility imports\n\nUpdate test imports to use `storybook/test` instead of `@storybook/test`\n\n```diff\n- import { fn } from '@storybook/test';\n+ import { fn } from 'storybook/test';\n```\n\n### Global State Changes\n\nThe `globals` annotation has be renamed to `initialGlobals`:\n\n```diff\n// .storybook/preview.js\nexport default {\n- globals: { theme: 'light' }\n+ initialGlobals: { theme: 'light' }\n};\n```\n\n### Autodocs Configuration\n\nInstead of `parameters.docs.autodocs` in main.js, use tags:\n\n```js\n// .storybook/preview.js or in individual stories\nexport default {\n	tags: ['autodocs'], // generates autodocs for all stories\n};\n```\n\n### Mocking imports in Storybook\n\nTo mock imports in Storybook, use Storybook's mocking features. ALWAYS mock external dependencies to ensure stories render consistently.\n\n1. **Register in the mock in Storybook's preview file**:\n   To mock dependendencies, you MUST register a module mock in `.storybook/preview.ts` (or equivalent):\n\n```js\nimport { sb } from 'storybook/test';\n\n// Prefer spy mocks (keeps functions, but allows to override them and spy on them)\nsb.mock(import('some-library'), { spy: true });\n```\n\n**Important: Use file extensions when referring to relative files!**\n\n```js\nsb.mock(import('./relative/module.ts'), { spy: true });\n```\n\n2. **Specify mock values in stories**:\n   You can override the behaviour of the mocks per-story using `beforeEach` and the `mocked()` type function:\n\n```js\nimport { expect, mocked, fn } from 'storybook/test';\nimport { library } from 'some-library';\n\nconst meta = {\n  component: AuthButton,\n  beforeEach: async () => {\n    mocked(library).mockResolvedValue({  user: 'data' });\n  },\n};\n\nexport const LoggedIn: Story = {\n  play: async ({ canvas }) => {\n    await expect(library).toHaveBeenCalled();\n  },\n};\n```\n\nBefore doing this ensure you have mocked the import in the preview file.\n\n### Play Function Parameters\n\n- The play function has a `canvas` parameter that can be used directly with testing-library-like query methods.\n- It also has a `canvasElement` which is the actual DOM element.\n- The `within`-function imported from `storybook/test` transforms a DOM element to an object with query methods, similar to `canvas`.\n\n**DO NOT** use `within(canvas)` - it is redundant because `canvas` already has the query methods, `canvas` is not a DOM element.\n\n```ts\n// ✅ Correct: Use canvas directly\nplay: async ({ canvas }) => {\n	await canvas.getByLabelText('Submit').click();\n};\n\n// ⚠️ Also acceptable: Use `canvasElement` with `within`\nimport { within } from 'storybook/test';\n\nplay: async ({ canvasElement }) => {\n	const canvas = within(canvasElement);\n	await canvas.getByLabelText('Submit').click();\n};\n\n// ❌ Wrong: Do NOT use within(canvas)\nplay: async ({ canvas }) => {\n	const screen = within(canvas); // Error!\n};\n```\n\n### Key Requirements\n\n- **Node.js 20+**, **TypeScript 4.9+**, **Vite 5+**\n- React Native uses `.rnstorybook` directory\n\n## Story Linking Agent Behavior\n\n- ALWAYS provide story links after any changes to stories files, including changes to existing stories.\n- 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.\n- Use the {{GET_STORY_URLS_TOOL_NAME}} tool to get the correct URLs for links to stories.\n";
+var storybook_story_instructions_default = "# Writing User Interfaces\n\nWhen writing UI, prefer breaking larger components up into smaller parts.\n\nALWAYS write a Storybook story for any component written. If editing a component, ensure appropriate changes have been made to stories for that component.\n\n## How to write good stories\n\nGoal: Cover every distinct piece of business logic and state the component can reach (happy paths, error/edge states, loading, permissions/roles, empty states, variations from props/context). Avoid redundant stories that show the same logic.\n\nInteractivity: If the component is interactive, add Interaction tests using play functions that drive the UI with storybook/test utilities (e.g., fn, userEvent, expect). Simulate key user flows: clicking buttons/links, typing, focus/blur, keyboard nav, form submit, async responses, toggle/selection changes, pagination/filters, etc. When passing `fn` functions as `args` for callback functions, make sure to add a play function which interacts with the component and assert whether the callback function was actually called.\n\nData/setup: Provide realistic props, state, and mocked data. Include meaningful labels/text to make behaviors observable. Stub network/services with deterministic fixtures; keep stories reliable.\n\nAssertions: In play functions, assert the visible outcome of the interaction (text, aria state, enabled/disabled, class/state changes, emitted events). Prefer role/label-based queries.\n\nVariants to consider (pick only those that change behavior): default vs. alternate themes; loading vs. loaded vs. empty vs. error; validated vs. invalid input; permissions/roles/capabilities; feature flags; size/density/layout variants that alter logic.\n\nAccessibility: Use semantic roles/labels; ensure focusable/keyboard interactions are test-covered where relevant.\n\nNaming/structure: Use clear story names that describe the scenario (“Error state after failed submit”). Group related variants logically; don’t duplicate.\n\nImports/format: Import Meta/StoryObj from the framework package; import test helpers from storybook/test (not @storybook/test). Keep stories minimal—only what's needed to demonstrate behavior.\n\n## Storybook 9 Essential Changes for Story Writing\n\n### Package Consolidation\n\n#### `Meta` and `StoryObj` imports\n\nUpdate story imports to use the framework package:\n\n```diff\n- import { Meta, StoryObj } from '{{RENDERER}}';\n+ import { Meta, StoryObj } from '{{FRAMEWORK}}';\n```\n\n#### Test utility imports\n\nUpdate test imports to use `storybook/test` instead of `@storybook/test`\n\n```diff\n- import { fn } from '@storybook/test';\n+ import { fn } from 'storybook/test';\n```\n\n### Global State Changes\n\nThe `globals` annotation has be renamed to `initialGlobals`:\n\n```diff\n// .storybook/preview.js\nexport default {\n- globals: { theme: 'light' }\n+ initialGlobals: { theme: 'light' }\n};\n```\n\n### Autodocs Configuration\n\nInstead of `parameters.docs.autodocs` in main.js, use tags:\n\n```js\n// .storybook/preview.js or in individual stories\nexport default {\n	tags: ['autodocs'], // generates autodocs for all stories\n};\n```\n\n### Mocking imports in Storybook\n\nTo mock imports in Storybook, use Storybook's mocking features. ALWAYS mock external dependencies to ensure stories render consistently.\n\n1. **Register in the mock in Storybook's preview file**:\n   To mock dependendencies, you MUST register a module mock in `.storybook/preview.ts` (or equivalent):\n\n```js\nimport { sb } from 'storybook/test';\n\n// Prefer spy mocks (keeps functions, but allows to override them and spy on them)\nsb.mock(import('some-library'), { spy: true });\n```\n\n**Important: Use file extensions when referring to relative files!**\n\n```js\nsb.mock(import('./relative/module.ts'), { spy: true });\n```\n\n2. **Specify mock values in stories**:\n   You can override the behaviour of the mocks per-story using `beforeEach` and the `mocked()` type function:\n\n```js\nimport { expect, mocked, fn } from 'storybook/test';\nimport { library } from 'some-library';\n\nconst meta = {\n  component: AuthButton,\n  beforeEach: async () => {\n    mocked(library).mockResolvedValue({  user: 'data' });\n  },\n};\n\nexport const LoggedIn: Story = {\n  play: async ({ canvas }) => {\n    await expect(library).toHaveBeenCalled();\n  },\n};\n```\n\nBefore doing this ensure you have mocked the import in the preview file.\n\n### Play Function Parameters\n\n- The play function has a `canvas` parameter that can be used directly with testing-library-like query methods.\n- It also has a `canvasElement` which is the actual DOM element.\n- The `within`-function imported from `storybook/test` transforms a DOM element to an object with query methods, similar to `canvas`.\n\n**DO NOT** use `within(canvas)` - it is redundant because `canvas` already has the query methods, `canvas` is not a DOM element.\n\n```ts\n// ✅ Correct: Use canvas directly\nplay: async ({ canvas }) => {\n	await canvas.getByLabelText('Submit').click();\n};\n\n// ⚠️ Also acceptable: Use `canvasElement` with `within`\nimport { within } from 'storybook/test';\n\nplay: async ({ canvasElement }) => {\n	const canvas = within(canvasElement);\n	await canvas.getByLabelText('Submit').click();\n};\n\n// ❌ Wrong: Do NOT use within(canvas)\nplay: async ({ canvas }) => {\n	const screen = within(canvas); // Error!\n};\n```\n\n### Key Requirements\n\n- **Node.js 20+**, **TypeScript 4.9+**, **Vite 5+**\n- React Native uses `.rnstorybook` directory\n\n## Story Linking Agent Behavior\n\n- ALWAYS provide story links after any changes to stories files, including changes to existing stories.\n- 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.\n- Use the {{PREVIEW_STORIES_TOOL_NAME}} tool to get the correct URLs for links to stories.\n";
 
 //#endregion
 //#region src/tools/get-storybook-story-instructions.ts
@@ -198,7 +170,7 @@ Even if you're familiar with Storybook, call this tool to ensure you're followin
 			const renderer = frameworkToRendererMap[framework];
 			return { content: [{
 				type: "text",
-				text: storybook_story_instructions_default.replace("{{FRAMEWORK}}", framework).replace("{{RENDERER}}", renderer ?? framework).replace("{{GET_STORY_URLS_TOOL_NAME}}", GET_STORY_URLS_TOOL_NAME)
+				text: storybook_story_instructions_default.replace("{{FRAMEWORK}}", framework).replace("{{RENDERER}}", renderer ?? framework).replace("{{PREVIEW_STORIES_TOOL_NAME}}", PREVIEW_STORIES_TOOL_NAME)
 			}] };
 		} catch (error) {
 			return errorToMCPContent(error);
@@ -221,6 +193,163 @@ const frameworkToRendererMap = {
 	"@storybook/html-vite": "@storybook/html"
 };
 
+//#endregion
+//#region src/types.ts
+const AddonOptions = v.object({
+	toolsets: v.optional(v.object({
+		dev: v.exactOptional(v.boolean(), true),
+		docs: v.exactOptional(v.boolean(), true)
+	}), {
+		dev: true,
+		docs: true
+	}),
+	experimentalFormat: v.optional(v.picklist(["xml", "markdown"]), "markdown")
+});
+/**
+* Schema for a single story input when requesting story URLs.
+*/
+const StoryInput = v.object({
+	exportName: v.string(),
+	explicitStoryName: v.pipe(v.optional(v.string()), v.description(`If the story has an explicit name set via the "name" propoerty, that is different from the export name, provide it here.
+Otherwise don't set this.`)),
+	absoluteStoryPath: v.string(),
+	props: v.pipe(v.optional(v.record(v.string(), v.any())), v.description(`Optional custom props to pass to the story for rendering. Use this when you don't want to render the default story,
+but you want to customize some args or other props.
+You can look up the component's documentation using the ${GET_UI_BUILDING_INSTRUCTIONS_TOOL_NAME} tool to see what props are available.`)),
+	globals: v.pipe(v.optional(v.record(v.string(), v.any())), v.description(`Optional Storybook globals to set for the story preview. Globals are used for things like theme, locale, viewport, and other cross-cutting concerns.
+Common globals include 'theme' (e.g., 'dark', 'light'), 'locale' (e.g., 'en', 'fr'), and 'backgrounds' (e.g., { value: '#000' }).`))
+});
+/**
+* Schema for the array of stories to fetch URLs for.
+*/
+const StoryInputArray = v.array(StoryInput);
+
+//#endregion
+//#region src/tools/preview-stories/preview-stories-app-template.html
+var preview_stories_app_template_default = "<!doctype html>\n<html>\n	<head>\n		<meta charset=\"utf-8\" />\n		<meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" />\n		<style>\n			* {\n				margin: 0;\n				padding: 0;\n				box-sizing: border-box;\n			}\n			html[data-theme='light'] {\n				color-scheme: light;\n			}\n			html[data-theme='dark'] {\n				color-scheme: dark;\n			}\n			html,\n			body {\n				width: 100%;\n				margin: 0;\n				padding: 0;\n				background-color: var(--color-background-secondary);\n			}\n			body {\n				display: flex;\n				flex-direction: column;\n				gap: 1rem;\n			}\n			:root {\n				/*\n				These are fallback values, if the MCP client doesn't set them.\n				See https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/draft/apps.mdx#theming\n				*/\n				--color-text-primary: light-dark(black, white);\n				--color-border-primary: light-dark(#ccc, #444);\n				--color-background-secondary: light-dark(#f9f9f9, #1e1e1e);\n				--font-sans:\n					-apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Oxygen-Sans',\n					Ubuntu, Cantarell, 'Helvetica Neue', sans-serif;\n				--font-heading-xs-size: 1rem;\n				--font-heading-xs-line-height: 1.25;\n				--border-width-regular: 1px;\n			}\n			.story-heading {\n				font-family: var(--font-sans);\n				font-size: var(--font-heading-xs-size);\n				line-height: var(--font-heading-xs-line-height);\n				color: var(--color-text-primary);\n				padding: 0.5rem 0;\n			}\n			.story-iframe {\n				background-color: white;\n				border: var(--border-width-regular) solid var(--color-border-primary);\n			}\n			body:has(> article:only-child) h1 {\n				/* if there is only one story rendered, hide its heading */\n				display: none;\n			}\n		</style>\n		<template id=\"preview-template\">\n			<article>\n				<h1 class=\"story-heading\"></h1>\n				<iframe class=\"story-iframe\"></iframe>\n			</article>\n		</template>\n		<script type=\"module\">\n			// APP_SCRIPT_PLACEHOLDER\n		<\/script>\n	</head>\n	<body></body>\n</html>\n";
+
+//#endregion
+//#region src/utils/slash.ts
+/**
+* Normalize paths to forward slashes for cross-platform compatibility
+* Storybook import paths always use forward slashes
+*/
+function slash(path$1) {
+	return path$1.replace(/\\/g, "/");
+}
+
+//#endregion
+//#region src/tools/preview-stories.ts
+const PREVIEW_STORIES_TOOL_NAME = "preview-stories";
+const PREVIEW_STORIES_RESOURCE_URI = `ui://${PREVIEW_STORIES_TOOL_NAME}/preview.html`;
+const PreviewStoriesInput = v.object({ stories: StoryInputArray });
+const PreviewStoriesOutput = v.object({ stories: v.array(v.union([v.object({
+	title: v.string(),
+	name: v.string(),
+	previewUrl: v.string()
+}), v.object({
+	input: StoryInput,
+	error: v.string()
+})])) });
+async function addPreviewStoriesTool(server) {
+	const previewStoryAppScript = await fs.readFile(url.fileURLToPath(import.meta.resolve("@storybook/addon-mcp/internal/preview-stories-app-script")), "utf-8");
+	const appHtml = preview_stories_app_template_default.replace("// APP_SCRIPT_PLACEHOLDER", previewStoryAppScript);
+	server.resource({
+		name: PREVIEW_STORIES_RESOURCE_URI,
+		description: "App resource for the Preview Stories tool",
+		uri: PREVIEW_STORIES_RESOURCE_URI,
+		mimeType: "text/html;profile=mcp-app"
+	}, () => {
+		const origin$1 = server.ctx.custom.origin;
+		return { contents: [{
+			uri: PREVIEW_STORIES_RESOURCE_URI,
+			mimeType: "text/html;profile=mcp-app",
+			text: appHtml,
+			_meta: { ui: {
+				prefersBorder: false,
+				domain: origin$1,
+				csp: {
+					connectDomains: [origin$1],
+					resourceDomains: [origin$1],
+					frameDomains: [origin$1],
+					baseUriDomains: [origin$1]
+				}
+			} }
+		}] };
+	});
+	server.tool({
+		name: PREVIEW_STORIES_TOOL_NAME,
+		title: "Preview stories",
+		description: `Use this tool to preview one or more stories, rendering them as an MCP App using the UI Resource or returning the raw URL for users to visit.`,
+		schema: PreviewStoriesInput,
+		outputSchema: PreviewStoriesOutput,
+		enabled: () => server.ctx.custom?.toolsets?.dev ?? true,
+		_meta: { ui: { resourceUri: PREVIEW_STORIES_RESOURCE_URI } }
+	}, async (input) => {
+		try {
+			const { origin: origin$1, disableTelemetry: disableTelemetry$1 } = server.ctx.custom ?? {};
+			if (!origin$1) throw new Error("Origin is required in addon context");
+			const index = await fetchStoryIndex(origin$1);
+			const entriesList = Object.values(index.entries);
+			const structuredResult = [];
+			const textResult = [];
+			for (const inputParams of input.stories) {
+				const { exportName, explicitStoryName, absoluteStoryPath } = inputParams;
+				const normalizedCwd = slash(process.cwd());
+				const normalizedAbsolutePath = slash(absoluteStoryPath);
+				const relativePath = `./${path.posix.relative(normalizedCwd, normalizedAbsolutePath)}`;
+				logger.debug("Searching for:");
+				logger.debug({
+					exportName,
+					explicitStoryName,
+					absoluteStoryPath,
+					relativePath
+				});
+				const foundStory = entriesList.find((entry) => entry.importPath === relativePath && [explicitStoryName, storyNameFromExport(exportName)].includes(entry.name));
+				if (foundStory) {
+					logger.debug(`Found story ID: ${foundStory.id}`);
+					let previewUrl = `${origin$1}/?path=/story/${foundStory.id}`;
+					const argsParam = buildArgsParam(inputParams.props ?? {});
+					if (argsParam) previewUrl += `&args=${argsParam}`;
+					const globalsParam = buildArgsParam(inputParams.globals ?? {});
+					if (globalsParam) previewUrl += `&globals=${globalsParam}`;
+					structuredResult.push({
+						title: foundStory.title,
+						name: foundStory.name,
+						previewUrl
+					});
+					textResult.push(previewUrl);
+				} else {
+					logger.debug("No story found");
+					let errorMessage = `No story found for export name "${exportName}" with absolute file path "${absoluteStoryPath}"`;
+					if (!explicitStoryName) errorMessage += ` (did you forget to pass the explicit story name?)`;
+					structuredResult.push({
+						input: inputParams,
+						error: errorMessage
+					});
+					textResult.push(errorMessage);
+				}
+			}
+			if (!disableTelemetry$1) await collectTelemetry({
+				event: "tool:previewStories",
+				server,
+				toolset: "dev",
+				inputStoryCount: input.stories.length,
+				outputStoryCount: structuredResult.length
+			});
+			return {
+				content: textResult.map((text) => ({
+					type: "text",
+					text
+				})),
+				structuredContent: { stories: structuredResult }
+			};
+		} catch (error) {
+			return errorToMCPContent(error);
+		}
+	});
+}
+
 //#endregion
 //#region src/tools/is-manifest-available.ts
 const getManifestStatus = async (options) => {
@@ -306,7 +435,10 @@ const initializeMCPServer = async (options) => {
 		description
 	}, {
 		adapter: new ValibotJsonSchemaAdapter(),
-		capabilities: { tools: { listChanged: true } }
+		capabilities: {
+			tools: { listChanged: true },
+			resources: { listChanged: true }
+		}
 	}).withContext();
 	if (!disableTelemetry) server.on("initialize", async () => {
 		await collectTelemetry({
@@ -314,7 +446,7 @@ const initializeMCPServer = async (options) => {
 			server
 		});
 	});
-	await addGetStoryUrlsTool(server);
+	await addPreviewStoriesTool(server);
 	await addGetUIBuildingInstructionsTool(server);
 	if ((await getManifestStatus(options)).available) {
 		logger.info("Experimental components manifest feature detected - registering component tools");
@@ -370,9 +502,9 @@ const mcpServerHandler = async ({ req, res, options, addonOptions }) => {
 async function incomingMessageToWebRequest(req) {
 	const host = req.headers.host || "localhost";
 	const protocol = "encrypted" in req.socket && req.socket.encrypted ? "https" : "http";
-	const url = new URL(req.url || "/", `${protocol}://${host}`);
+	const url$1 = new URL(req.url || "/", `${protocol}://${host}`);
 	const bodyBuffer = await buffer(req);
-	return new Request(url, {
+	return new Request(url$1, {
 		method: req.method,
 		headers: req.headers,
 		body: bodyBuffer.length > 0 ? new Uint8Array(bodyBuffer) : void 0
@@ -417,10 +549,13 @@ function getToolsets(request, addonOptions) {
 
 //#endregion
 //#region src/template.html
-var template_default = "<!doctype html>\n<html>\n	<head>\n		{{REDIRECT_META}}\n		<style>\n			@font-face {\n				font-family: 'Nunito Sans';\n				font-style: normal;\n				font-weight: 400;\n				font-display: swap;\n				src: url('./sb-common-assets/nunito-sans-regular.woff2') format('woff2');\n			}\n\n			* {\n				margin: 0;\n				padding: 0;\n				box-sizing: border-box;\n			}\n\n			html,\n			body {\n				height: 100%;\n				font-family:\n					'Nunito Sans',\n					-apple-system,\n					BlinkMacSystemFont,\n					'Segoe UI',\n					Roboto,\n					Oxygen,\n					Ubuntu,\n					Cantarell,\n					sans-serif;\n			}\n\n			body {\n				display: flex;\n				flex-direction: column;\n				justify-content: center;\n				align-items: center;\n				text-align: center;\n				padding: 2rem;\n				background-color: #ffffff;\n				color: rgb(46, 52, 56);\n				line-height: 1.6;\n			}\n\n			p {\n				margin-bottom: 1rem;\n			}\n\n			code {\n				font-family: 'Monaco', 'Courier New', monospace;\n				background: #f5f5f5;\n				padding: 0.2em 0.4em;\n				border-radius: 3px;\n			}\n\n			a {\n				color: #1ea7fd;\n			}\n\n			.container {\n				display: flex;\n				flex-direction: column;\n				align-items: center;\n			}\n\n			.toolsets {\n				margin: 1.5rem 0;\n				text-align: left;\n				max-width: 500px;\n			}\n\n			.toolsets h3 {\n				font-size: 1rem;\n				margin-bottom: 0.75rem;\n				text-align: center;\n			}\n\n			.toolset {\n				margin-bottom: 1rem;\n				padding: 0.75rem 1rem;\n				border-radius: 6px;\n				background: #f8f9fa;\n				border: 1px solid #e9ecef;\n			}\n\n			.toolset-header {\n				display: flex;\n				align-items: center;\n				gap: 0.5rem;\n				font-weight: 600;\n				margin-bottom: 0.5rem;\n			}\n\n			.toolset-status {\n				display: inline-block;\n				padding: 0.15em 0.5em;\n				border-radius: 3px;\n				font-size: 0.75rem;\n				font-weight: 500;\n				text-transform: uppercase;\n			}\n\n			.toolset-status.enabled {\n				background: #d4edda;\n				color: #155724;\n			}\n\n			.toolset-status.disabled {\n				background: #f8d7da;\n				color: #721c24;\n			}\n\n			.toolset-tools {\n				font-size: 0.875rem;\n				color: #6c757d;\n				padding-left: 1.5rem;\n				margin: 0;\n			}\n\n			.toolset-tools li {\n				margin-bottom: 0.25rem;\n			}\n\n			.toolset-tools code {\n				font-size: 0.8rem;\n			}\n\n			.toolset-notice {\n				font-size: 0.8rem;\n				color: #856404;\n				background: #fff3cd;\n				padding: 0.5rem;\n				border-radius: 4px;\n				margin-top: 0.5rem;\n			}\n\n			.toolset-notice a {\n				color: #533f03;\n			}\n\n			@media (prefers-color-scheme: dark) {\n				body {\n					background-color: rgb(34, 36, 37);\n					color: rgb(201, 205, 207);\n				}\n\n				code {\n					background: rgba(255, 255, 255, 0.1);\n				}\n\n				.toolset {\n					background: rgba(255, 255, 255, 0.05);\n					border-color: rgba(255, 255, 255, 0.1);\n				}\n\n				.toolset-tools {\n					color: #adb5bd;\n				}\n\n				.toolset-status.enabled {\n					background: rgba(40, 167, 69, 0.2);\n					color: #75d67e;\n				}\n\n				.toolset-status.disabled {\n					background: rgba(220, 53, 69, 0.2);\n					color: #f5a6ad;\n				}\n\n				.toolset-notice {\n					background: rgba(255, 193, 7, 0.15);\n					color: #ffc107;\n				}\n\n				.toolset-notice a {\n					color: #ffe066;\n				}\n			}\n		</style>\n	</head>\n	<body>\n		<div class=\"container\">\n			<p>\n				Storybook MCP server successfully running via\n				<code>@storybook/addon-mcp</code>.\n			</p>\n			<p>\n				See how to connect to it from your coding agent in\n				<a\n					target=\"_blank\"\n					href=\"https://github.com/storybookjs/mcp/tree/main/packages/addon-mcp#configuring-your-agent\"\n					>the addon's README</a\n				>.\n			</p>\n\n			<div class=\"toolsets\">\n				<h3>Available Toolsets</h3>\n\n				<div class=\"toolset\">\n					<div class=\"toolset-header\">\n						<span>dev</span>\n						<span class=\"toolset-status {{DEV_STATUS}}\">{{DEV_STATUS}}</span>\n					</div>\n					<ul class=\"toolset-tools\">\n						<li><code>get-story-urls</code></li>\n						<li><code>get-storybook-story-instructions</code></li>\n					</ul>\n				</div>\n\n				<div class=\"toolset\">\n					<div class=\"toolset-header\">\n						<span>docs</span>\n						<span class=\"toolset-status {{DOCS_STATUS}}\">{{DOCS_STATUS}}</span>\n					</div>\n					<ul class=\"toolset-tools\">\n						<li><code>list-all-documentation</code></li>\n						<li><code>get-component-documentation</code></li>\n					</ul>\n					{{DOCS_NOTICE}}\n				</div>\n			</div>\n\n			<p id=\"redirect-message\">\n				Automatically redirecting to\n				<a href=\"/manifests/components.html\">component manifest</a>\n				in <span id=\"countdown\">10</span> seconds...\n			</p>\n		</div>\n		<script>\n			let countdown = 10;\n			const countdownElement = document.getElementById('countdown');\n			if (countdownElement) {\n				setInterval(() => {\n					countdown -= 1;\n					countdownElement.textContent = countdown.toString();\n				}, 1000);\n			}\n		<\/script>\n	</body>\n</html>\n";
+var template_default = "<!doctype html>\n<html>\n	<head>\n		{{REDIRECT_META}}\n		<style>\n			@font-face {\n				font-family: 'Nunito Sans';\n				font-style: normal;\n				font-weight: 400;\n				font-display: swap;\n				src: url('./sb-common-assets/nunito-sans-regular.woff2') format('woff2');\n			}\n\n			* {\n				margin: 0;\n				padding: 0;\n				box-sizing: border-box;\n			}\n\n			html,\n			body {\n				height: 100%;\n				font-family:\n					'Nunito Sans',\n					-apple-system,\n					BlinkMacSystemFont,\n					'Segoe UI',\n					Roboto,\n					Oxygen,\n					Ubuntu,\n					Cantarell,\n					sans-serif;\n			}\n\n			body {\n				display: flex;\n				flex-direction: column;\n				justify-content: center;\n				align-items: center;\n				text-align: center;\n				padding: 2rem;\n				background-color: #ffffff;\n				color: rgb(46, 52, 56);\n				line-height: 1.6;\n			}\n\n			p {\n				margin-bottom: 1rem;\n			}\n\n			code {\n				font-family: 'Monaco', 'Courier New', monospace;\n				background: #f5f5f5;\n				padding: 0.2em 0.4em;\n				border-radius: 3px;\n			}\n\n			a {\n				color: #1ea7fd;\n			}\n\n			.container {\n				display: flex;\n				flex-direction: column;\n				align-items: center;\n			}\n\n			.toolsets {\n				margin: 1.5rem 0;\n				text-align: left;\n				max-width: 500px;\n			}\n\n			.toolsets h3 {\n				font-size: 1rem;\n				margin-bottom: 0.75rem;\n				text-align: center;\n			}\n\n			.toolset {\n				margin-bottom: 1rem;\n				padding: 0.75rem 1rem;\n				border-radius: 6px;\n				background: #f8f9fa;\n				border: 1px solid #e9ecef;\n			}\n\n			.toolset-header {\n				display: flex;\n				align-items: center;\n				gap: 0.5rem;\n				font-weight: 600;\n				margin-bottom: 0.5rem;\n			}\n\n			.toolset-status {\n				display: inline-block;\n				padding: 0.15em 0.5em;\n				border-radius: 3px;\n				font-size: 0.75rem;\n				font-weight: 500;\n				text-transform: uppercase;\n			}\n\n			.toolset-status.enabled {\n				background: #d4edda;\n				color: #155724;\n			}\n\n			.toolset-status.disabled {\n				background: #f8d7da;\n				color: #721c24;\n			}\n\n			.toolset-tools {\n				font-size: 0.875rem;\n				color: #6c757d;\n				padding-left: 1.5rem;\n				margin: 0;\n			}\n\n			.toolset-tools li {\n				margin-bottom: 0.25rem;\n			}\n\n			.toolset-tools code {\n				font-size: 0.8rem;\n			}\n\n			.toolset-notice {\n				font-size: 0.8rem;\n				color: #856404;\n				background: #fff3cd;\n				padding: 0.5rem;\n				border-radius: 4px;\n				margin-top: 0.5rem;\n			}\n\n			.toolset-notice a {\n				color: #533f03;\n			}\n\n			@media (prefers-color-scheme: dark) {\n				body {\n					background-color: rgb(34, 36, 37);\n					color: rgb(201, 205, 207);\n				}\n\n				code {\n					background: rgba(255, 255, 255, 0.1);\n				}\n\n				.toolset {\n					background: rgba(255, 255, 255, 0.05);\n					border-color: rgba(255, 255, 255, 0.1);\n				}\n\n				.toolset-tools {\n					color: #adb5bd;\n				}\n\n				.toolset-status.enabled {\n					background: rgba(40, 167, 69, 0.2);\n					color: #75d67e;\n				}\n\n				.toolset-status.disabled {\n					background: rgba(220, 53, 69, 0.2);\n					color: #f5a6ad;\n				}\n\n				.toolset-notice {\n					background: rgba(255, 193, 7, 0.15);\n					color: #ffc107;\n				}\n\n				.toolset-notice a {\n					color: #ffe066;\n				}\n			}\n		</style>\n	</head>\n	<body>\n		<div class=\"container\">\n			<p>\n				Storybook MCP server successfully running via\n				<code>@storybook/addon-mcp</code>.\n			</p>\n			<p>\n				See how to connect to it from your coding agent in\n				<a\n					target=\"_blank\"\n					href=\"https://github.com/storybookjs/mcp/tree/main/packages/addon-mcp#configuring-your-agent\"\n					>the addon's README</a\n				>.\n			</p>\n\n			<div class=\"toolsets\">\n				<h3>Available Toolsets</h3>\n\n				<div class=\"toolset\">\n					<div class=\"toolset-header\">\n						<span>dev</span>\n						<span class=\"toolset-status {{DEV_STATUS}}\">{{DEV_STATUS}}</span>\n					</div>\n					<ul class=\"toolset-tools\">\n						<li><code>preview-stories</code></li>\n						<li><code>get-storybook-story-instructions</code></li>\n					</ul>\n				</div>\n\n				<div class=\"toolset\">\n					<div class=\"toolset-header\">\n						<span>docs</span>\n						<span class=\"toolset-status {{DOCS_STATUS}}\">{{DOCS_STATUS}}</span>\n					</div>\n					<ul class=\"toolset-tools\">\n						<li><code>list-all-documentation</code></li>\n						<li><code>get-component-documentation</code></li>\n					</ul>\n					{{DOCS_NOTICE}}\n				</div>\n			</div>\n\n			<p id=\"redirect-message\">\n				Automatically redirecting to\n				<a href=\"/manifests/components.html\">component manifest</a>\n				in <span id=\"countdown\">10</span> seconds...\n			</p>\n		</div>\n		<script>\n			let countdown = 10;\n			const countdownElement = document.getElementById('countdown');\n			if (countdownElement) {\n				setInterval(() => {\n					countdown -= 1;\n					countdownElement.textContent = countdown.toString();\n				}, 1000);\n			}\n		<\/script>\n	</body>\n</html>\n";
 
 //#endregion
 //#region src/preset.ts
+const previewAnnotations = async (existingAnnotations = []) => {
+	return [...existingAnnotations, path.join(import.meta.dirname, "preview.js")];
+};
 const experimental_devServer = async (app, options) => {
 	const addonOptions = v.parse(AddonOptions, {
 		toolsets: "toolsets" in options ? options.toolsets : {},
@@ -458,4 +593,4 @@ const experimental_devServer = async (app, options) => {
 };
 
 //#endregion
-export { experimental_devServer };
+export { experimental_devServer, previewAnnotations };

package/dist/preview-stories-app-script.js

@@ -0,0 +1,142 @@
+//#region src/constants.ts
+const MCP_APP_PARAM = "mcp-app";
+const MCP_APP_SIZE_CHANGED_EVENT = "storybook-mcp:size-changed";
+
+//#endregion
+//#region package.json
+var version = "0.2.2";
+
+//#endregion
+//#region src/tools/preview-stories/preview-stories-app-script.ts
+/**
+* Current protocol version - must match LATEST_PROTOCOL_VERSION from ext-apps
+* @see https://github.com/modelcontextprotocol/ext-apps
+*/
+const LATEST_PROTOCOL_VERSION = "2025-11-21";
+/**
+* MCP Apps SEP protocol method constants
+* These match the `method` field values from @modelcontextprotocol/ext-apps type definitions:
+* - McpUiInitializeRequest: "ui/initialize"
+* - McpUiInitializedNotification: "ui/notifications/initialized"
+* - McpUiToolInputNotification: "ui/notifications/tool-input"
+* - McpUiToolInputPartialNotification: "ui/notifications/tool-input-partial"
+* - McpUiToolResultNotification: "ui/notifications/tool-result"
+* - McpUiHostContextChangedNotification: "ui/notifications/host-context-changed"
+* - McpUiSizeChangedNotification: "ui/notifications/size-changed"
+* - McpUiResourceTeardownRequest: "ui/resource-teardown"
+*
+* @see https://github.com/modelcontextprotocol/ext-apps/blob/main/src/spec.types.ts
+*/
+const METHODS = {
+	INITIALIZE: "ui/initialize",
+	INITIALIZED: "ui/notifications/initialized",
+	TOOL_INPUT: "ui/notifications/tool-input",
+	TOOL_INPUT_PARTIAL: "ui/notifications/tool-input-partial",
+	TOOL_RESULT: "ui/notifications/tool-result",
+	TOOL_CANCELLED: "ui/notifications/tool-cancelled",
+	HOST_CONTEXT_CHANGED: "ui/notifications/host-context-changed",
+	SIZE_CHANGED: "ui/notifications/size-changed",
+	RESOURCE_TEARDOWN: "ui/resource-teardown",
+	TOOLS_CALL: "tools/call",
+	NOTIFICATIONS_MESSAGE: "notifications/message",
+	OPEN_LINK: "ui/open-link",
+	MESSAGE: "ui/message"
+};
+let nextId = 1;
+function sendHostRequest(method, params) {
+	const id = nextId++;
+	const { promise, resolve, reject } = Promise.withResolvers();
+	window.parent.postMessage({
+		jsonrpc: "2.0",
+		id,
+		method,
+		params
+	}, "*");
+	window.addEventListener("message", function listener(event) {
+		if (event.data?.id !== id) return;
+		window.removeEventListener("message", listener);
+		if (event.data?.result) resolve(event.data.result);
+		else if (event.data?.error) reject(new Error(String(event.data.error)));
+	});
+	return promise;
+}
+function sendHostNotification(method, params) {
+	window.parent.postMessage({
+		jsonrpc: "2.0",
+		method,
+		params
+	}, "*");
+}
+function onHostNotification(method, handler) {
+	window.addEventListener("message", function listener(event) {
+		if (event.data?.method === method) handler(event.data.params);
+	});
+}
+applyHostStyles((await sendHostRequest(METHODS.INITIALIZE, {
+	appInfo: {
+		name: "storybook-story-preview",
+		version
+	},
+	appCapabilities: {},
+	protocolVersion: LATEST_PROTOCOL_VERSION
+}))?.hostContext);
+onHostNotification(METHODS.TOOL_RESULT, loadStoryIframes);
+onHostNotification(METHODS.HOST_CONTEXT_CHANGED, applyHostStyles);
+sendHostNotification(METHODS.INITIALIZED, {});
+window.addEventListener("message", function(event) {
+	if (event.data?.type !== MCP_APP_SIZE_CHANGED_EVENT) return;
+	const iframes = document.querySelectorAll(".story-iframe");
+	let hasResizedIframes = false;
+	for (const iframe of iframes) if (iframe.contentWindow === event.source) {
+		iframe.style.height = (event.data.height ?? 0) + "px";
+		hasResizedIframes = true;
+		break;
+	}
+	if (hasResizedIframes) resizeApp();
+});
+function applyHostStyles(hostContext) {
+	if (hostContext?.theme) document.documentElement.setAttribute("data-theme", hostContext.theme);
+	if (!hostContext?.styles?.variables) return;
+	for (const [key, value] of Object.entries(hostContext.styles.variables)) if (value) document.documentElement.style.setProperty(key, value);
+	resizeApp();
+}
+function resizeApp() {
+	console.log("Resizing app to fit content", {
+		width: document.body.scrollWidth,
+		height: document.body.scrollHeight
+	});
+	sendHostNotification(METHODS.SIZE_CHANGED, {
+		width: document.body.scrollWidth,
+		height: document.body.scrollHeight
+	});
+}
+function loadStoryIframes(params) {
+	const stories = params.structuredContent?.stories;
+	if (!stories || stories.length === 0) {
+		console.warn("No preview URLs found in tool result.");
+		return;
+	}
+	const template = document.getElementById("preview-template");
+	for (const storyResult of stories) {
+		if ("error" in storyResult) {
+			console.warn("Skipping story with error:", storyResult.error);
+			continue;
+		}
+		const clone = template.content.cloneNode(true);
+		const article = clone.querySelector("article");
+		const heading = clone.querySelector("h1");
+		const iframe = clone.querySelector("iframe");
+		heading.textContent = `${storyResult.title} - ${storyResult.name}`;
+		iframe.style.width = "100%";
+		iframe.style.height = "0";
+		const iframeSrc = storyResult.previewUrl.replace("/?path=/story/", "/iframe.html?id=");
+		const url = new URL(iframeSrc);
+		url.searchParams.set(MCP_APP_PARAM, "true");
+		iframe.src = url.toString();
+		document.body.appendChild(article);
+	}
+	resizeApp();
+}
+
+//#endregion
+export {  };

package/dist/preview.js

@@ -0,0 +1,46 @@
+//#region src/constants.ts
+const MCP_APP_PARAM = "mcp-app";
+const MCP_APP_SIZE_CHANGED_EVENT = "storybook-mcp:size-changed";
+
+//#endregion
+//#region src/preview.ts
+/**
+* Storybook MCP App Script
+*
+* This script runs inside Storybook's iframe and communicates dimensions
+* to the parent preview.html frame via postMessage (cross-origin safe).
+*
+* Only activates when the iframe is loaded with `mcp-app=true` query parameter,
+* which is set by the MCP Apps preview.html wrapper.
+*/
+if (new URLSearchParams(window.location.search).has(MCP_APP_PARAM)) {
+	const SIZE_CHANGE_THRESHOLD = 2;
+	let debounceTimer = null;
+	let lastSentHeight = 0;
+	const DEBOUNCE_MS = 100;
+	function sendSizeToParent() {
+		const height = document.body.scrollHeight;
+		if (Math.abs(height - lastSentHeight) <= SIZE_CHANGE_THRESHOLD) return;
+		lastSentHeight = height;
+		window.parent.postMessage({
+			type: MCP_APP_SIZE_CHANGED_EVENT,
+			height
+		}, "*");
+	}
+	function debouncedSendSize() {
+		if (debounceTimer) clearTimeout(debounceTimer);
+		debounceTimer = setTimeout(sendSizeToParent, DEBOUNCE_MS);
+	}
+	if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", sendSizeToParent);
+	else sendSizeToParent();
+	window.addEventListener("load", sendSizeToParent);
+	new ResizeObserver(debouncedSendSize).observe(document.body);
+	new MutationObserver(debouncedSendSize).observe(document.body, {
+		childList: true,
+		subtree: true,
+		attributes: true
+	});
+}
+
+//#endregion
+export {  };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/addon-mcp",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Help agents automatically write and test stories for your UI components",
   "keywords": [
     "storybook-addon",
@@ -16,6 +16,7 @@
   "type": "module",
   "exports": {
     "./preset": "./dist/preset.js",
+    "./internal/preview-stories-app-script": "./dist/preview-stories-app-script.js",
     "./package.json": "./package.json"
   },
   "files": [
@@ -27,12 +28,13 @@
   "dependencies": {
     "@tmcp/adapter-valibot": "^0.1.4",
     "@tmcp/transport-http": "^0.8.0",
+    "picoquery": "^2.5.0",
     "tmcp": "^1.16.0",
     "valibot": "1.2.0",
     "@storybook/mcp": "0.2.1"
   },
   "devDependencies": {
-    "storybook": "10.2.0-alpha.14"
+    "storybook": "10.3.0-alpha.0"
   },
   "peerDependencies": {
     "storybook": "^9.1.16 || ^10.0.0 || ^10.1.0-0 || ^10.2.0-0 || ^10.3.0-0 || ^10.4.0-0"