@storybook/addon-mcp 0.3.2 → 0.3.3

package/README.md

@@ -156,9 +156,12 @@ The instructions ensure agents follow your project's conventions when creating o
 
 Allows agents to retrieve direct URLs to specific stories in your Storybook. The agent can request URLs for multiple stories by providing:
 
-- `absoluteStoryPath`: Absolute path to the story file
-- `exportName`: The export name of the story
-- `explicitStoryName`: Optional explicit story name
+- **Path-based input** (best when the agent is already editing a `.stories.*` file):
+  - `absoluteStoryPath`: Absolute path to the story file
+  - `exportName`: The export name of the story
+  - `explicitStoryName`: Optional explicit story name
+- **ID-based input** (best when the agent discovered stories via docs tools):
+  - `storyId`: Full Storybook story ID (for example `example-button--primary`)
 
 Example agent usage:
 
@@ -195,10 +198,14 @@ export default {
 
 Returns a list of all available UI components as well as standalone docs in your component library. Useful for the LLM as discovery and understanding what components are available to use.
 
+You can pass `withStoryIds: true` to include nested story entries (story name + story ID) under each component, which is useful before calling `preview-stories` or `run-story-tests` with `storyId`.
+
 #### 4. Get Documentation (`get-documentation`)
 
 Retrieves detailed documentation for a specific component or docs entry.
 
+Component documentation includes component ID and story IDs for listed stories, so agents can directly feed those IDs into `preview-stories` and `run-story-tests`.
+
 The agent provides a component/docs ID to retrieve its documentation. To get documentation for multiple entries, call this tool multiple times.
 
 ## Contributing

package/dist/preset.js

@@ -1,21 +1,21 @@
 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 { normalizeStoryPath } from "storybook/internal/common";
-import { storyNameFromExport } from "storybook/internal/csf";
-import { logger } from "storybook/internal/node-logger";
 import * as v from "valibot";
+import { logger } from "storybook/internal/node-logger";
 import { telemetry } from "storybook/internal/telemetry";
 import { stringify } from "picoquery";
+import path from "node:path";
+import { normalizeStoryPath } from "storybook/internal/common";
+import { storyNameFromExport } from "storybook/internal/csf";
+import { ComponentManifestMap, DocsManifestMap, GET_TOOL_NAME, LIST_TOOL_NAME, addGetDocumentationTool, addGetStoryDocumentationTool, addListAllDocumentationTool } from "@storybook/mcp";
 import fs from "node:fs/promises";
-import { ComponentManifestMap, DocsManifestMap, addGetDocumentationTool, addListAllDocumentationTool } from "@storybook/mcp";
 import { buffer } from "node:stream/consumers";
 
 //#region package.json
 var name = "@storybook/addon-mcp";
-var version = "0.3.2";
+var version = "0.3.3";
 var description = "Help agents automatically write and test stories for your UI components";
 
 //#endregion
@@ -108,6 +108,83 @@ async function fetchStoryIndex(origin) {
 	return index;
 }
 
+//#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) {
+	return path.replace(/\\/g, "/");
+}
+
+//#endregion
+//#region src/utils/find-story-ids.ts
+function isStoryIdInput(input) {
+	return "storyId" in input;
+}
+function normalizeImportPath(importPath) {
+	return slash(normalizeStoryPath(path.posix.normalize(slash(importPath))));
+}
+/**
+* Finds story IDs in the story index that match the given story inputs.
+*
+* @param index - The Storybook story index
+* @param stories - Array of story inputs to search for
+* @returns Array of per-input lookup results in the exact same order as the input stories
+*/
+function findStoryIds(index, stories) {
+	const entriesList = Object.values(index.entries);
+	const result = [];
+	for (const storyInput of stories) {
+		if (isStoryIdInput(storyInput)) {
+			const foundEntry = index.entries[storyInput.storyId];
+			if (foundEntry) {
+				logger.debug(`Found story ID: ${foundEntry.id}`);
+				result.push({
+					id: foundEntry.id,
+					input: storyInput
+				});
+			} else {
+				logger.debug("No story found");
+				result.push({
+					input: storyInput,
+					errorMessage: `No story found for story ID "${storyInput.storyId}"`
+				});
+			}
+			continue;
+		}
+		const { exportName, explicitStoryName, absoluteStoryPath } = storyInput;
+		const normalizedCwd = slash(process.cwd());
+		const normalizedAbsolutePath = slash(absoluteStoryPath);
+		const relativePath = normalizeImportPath(path.posix.relative(normalizedCwd, normalizedAbsolutePath));
+		logger.debug("Searching for:");
+		logger.debug({
+			exportName,
+			explicitStoryName,
+			absoluteStoryPath,
+			relativePath
+		});
+		const foundEntry = entriesList.find((entry) => normalizeImportPath(entry.importPath) === relativePath && [explicitStoryName, storyNameFromExport(exportName)].includes(entry.name));
+		if (foundEntry) {
+			logger.debug(`Found story ID: ${foundEntry.id}`);
+			result.push({
+				id: foundEntry.id,
+				input: storyInput
+			});
+		} 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({
+				input: storyInput,
+				errorMessage
+			});
+		}
+	}
+	return result;
+}
+
 //#endregion
 //#region src/utils/errors.ts
 /**
@@ -146,20 +223,30 @@ const AddonOptions = v.object({ toolsets: v.optional(v.object({
 	docs: true,
 	test: true
 }) });
-/**
-* 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(),
+const StoryInputProps = {
 	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 a single story input when requesting story URLs.
+*/
+const StoryInput = v.union([v.object({
+	exportName: v.pipe(v.string(), v.description(`The export name of the story from the story file.
+Use this path-based shape only when you're already editing a .stories.* file and know the export names in that file.
+If you do not already have story file context, prefer the storyId shape instead of searching files.`)),
+	explicitStoryName: v.pipe(v.optional(v.string()), v.description(`If the story has an explicit name set via the "name" property, that is different from the export name, provide it here.
+Otherwise don't set this.`)),
+	absoluteStoryPath: v.pipe(v.string(), v.description("Absolute path to the story file. Use together with exportName only when story file context is already available.")),
+	...StoryInputProps
+}), v.object({
+	storyId: v.pipe(v.string(), v.description(`The full Storybook story ID (for example "button--primary").
+Prefer this shape whenever you are not already working in a specific story file.
+Use IDs discovered from ${LIST_TOOL_NAME} (withStoryIds=true) or ${GET_TOOL_NAME}.`)),
+	...StoryInputProps
+})]);
 /**
 * Schema for the array of stories to fetch URLs for.
 */
@@ -169,24 +256,17 @@ const StoryInputArray = v.array(StoryInput);
 //#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', Ubuntu, Cantarell,\n					'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) {
-	return path.replace(/\\/g, "/");
-}
-
 //#endregion
 //#region src/tools/preview-stories.ts
 const PREVIEW_STORIES_RESOURCE_URI = `ui://${PREVIEW_STORIES_TOOL_NAME}/preview.html`;
-const PreviewStoriesInput = v.object({ stories: StoryInputArray });
+const PreviewStoriesInput = v.object({ stories: v.pipe(StoryInputArray, v.description(`Stories to preview.
+Prefer { storyId } when you don't already have story file context, since this avoids filesystem discovery.
+Use { storyId } when IDs were discovered from documentation tools.
+Use { absoluteStoryPath + exportName } only when you're already working in a specific .stories.* file and already have that context.`)) });
 const PreviewStoriesOutput = v.object({ stories: v.array(v.union([v.object({
 	title: v.string(),
 	name: v.string(),
-	previewUrl: v.string()
+	previewUrl: v.pipe(v.string(), v.description("Direct URL to open the story preview. Always include this URL in the final user-facing response so users can open it directly."))
 }), v.object({
 	input: StoryInput,
 	error: v.string()
@@ -194,9 +274,6 @@ const PreviewStoriesOutput = v.object({ stories: v.array(v.union([v.object({
 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);
-	const normalizeImportPath = (importPath) => {
-		return slash(normalizeStoryPath(path.posix.normalize(slash(importPath))));
-	};
 	server.resource({
 		name: PREVIEW_STORIES_RESOURCE_URI,
 		description: "App resource for the Preview Stories tool",
@@ -222,8 +299,9 @@ async function addPreviewStoriesTool(server) {
 	});
 	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.`,
+		title: "Get story preview URLs",
+		description: `Use this tool to get one or more Storybook preview URLs.
+Always include each returned preview URL in your final user-facing response so users can open them directly.`,
 		schema: PreviewStoriesInput,
 		outputSchema: PreviewStoriesOutput,
 		enabled: () => server.ctx.custom?.toolsets?.dev ?? true,
@@ -233,45 +311,38 @@ async function addPreviewStoriesTool(server) {
 			const { origin, disableTelemetry } = server.ctx.custom ?? {};
 			if (!origin) throw new Error("Origin is required in addon context");
 			const index = await fetchStoryIndex(origin);
-			const entriesList = Object.values(index.entries);
+			const resolvedStories = findStoryIds(index, input.stories);
 			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 = normalizeImportPath(path.posix.relative(normalizedCwd, normalizedAbsolutePath));
-				logger.debug("Searching for:");
-				logger.debug({
-					exportName,
-					explicitStoryName,
-					absoluteStoryPath,
-					relativePath
-				});
-				const foundStory = entriesList.find((entry) => normalizeImportPath(entry.importPath) === relativePath && [explicitStoryName, storyNameFromExport(exportName)].includes(entry.name));
-				if (foundStory) {
-					logger.debug(`Found story ID: ${foundStory.id}`);
-					let previewUrl = `${origin}/?path=/story/${foundStory.id}`;
-					const argsParam = buildArgsParam(inputParams.props ?? {});
-					if (argsParam) previewUrl += `&args=${argsParam}`;
-					const globalsParam = buildArgsParam(inputParams.globals ?? {});
-					if (globalsParam) previewUrl += `&globals=${globalsParam}`;
+			for (const story of resolvedStories) {
+				if ("errorMessage" in story) {
 					structuredResult.push({
-						title: foundStory.title,
-						name: foundStory.name,
-						previewUrl
+						input: story.input,
+						error: story.errorMessage
 					});
-					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?)`;
+					textResult.push(story.errorMessage);
+					continue;
+				}
+				const indexEntry = index.entries[story.id];
+				if (!indexEntry) {
 					structuredResult.push({
-						input: inputParams,
-						error: errorMessage
+						input: story.input,
+						error: `No story found for story ID "${story.id}"`
 					});
-					textResult.push(errorMessage);
+					textResult.push(`No story found for story ID "${story.id}"`);
+					continue;
 				}
+				let previewUrl = `${origin}/?path=/story/${story.id}`;
+				const argsParam = buildArgsParam(story.input.props ?? {});
+				if (argsParam) previewUrl += `&args=${argsParam}`;
+				const globalsParam = buildArgsParam(story.input.globals ?? {});
+				if (globalsParam) previewUrl += `&globals=${globalsParam}`;
+				structuredResult.push({
+					title: indexEntry.title,
+					name: indexEntry.name,
+					previewUrl
+				});
+				textResult.push(previewUrl);
 			}
 			if (!disableTelemetry) await collectTelemetry({
 				event: "tool:previewStories",
@@ -293,53 +364,6 @@ async function addPreviewStoriesTool(server) {
 	});
 }
 
-//#endregion
-//#region src/utils/find-story-ids.ts
-/**
-* Finds story IDs in the story index that match the given story inputs.
-*
-* @param index - The Storybook story index
-* @param stories - Array of story inputs to search for
-* @returns Object containing found stories with their IDs and not-found stories with error messages
-*/
-function findStoryIds(index, stories) {
-	const entriesList = Object.values(index.entries);
-	const result = {
-		found: [],
-		notFound: []
-	};
-	for (const storyInput of stories) {
-		const { exportName, explicitStoryName, absoluteStoryPath } = storyInput;
-		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 foundEntry = entriesList.find((entry) => entry.importPath === relativePath && [explicitStoryName, storyNameFromExport(exportName)].includes(entry.name));
-		if (foundEntry) {
-			logger.debug(`Found story ID: ${foundEntry.id}`);
-			result.found.push({
-				id: foundEntry.id,
-				input: storyInput
-			});
-		} 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.notFound.push({
-				input: storyInput,
-				errorMessage
-			});
-		}
-	}
-	return result;
-}
-
 //#endregion
 //#region src/tools/run-story-tests.ts
 /**
@@ -360,7 +384,10 @@ async function getAddonVitestConstants() {
 const RunStoryTestsInput = v.object({
 	stories: v.optional(v.pipe(StoryInputArray, v.description(`Stories to test for focused feedback. Omit this field to run tests for all available stories.
 Prefer running tests for specific stories while developing to get faster feedback,
-and only omit this when you explicitly need to run all tests for comprehensive verification.`))),
+and only omit this when you explicitly need to run all tests for comprehensive verification.
+Prefer { storyId } when you don't already have story file context, since this avoids filesystem discovery.
+Use { storyId } when IDs were discovered from documentation tools.
+Use { absoluteStoryPath + exportName } only when you're currently working in a story file and already know those values.`))),
 	a11y: v.optional(v.pipe(v.boolean(), v.description("Whether to run accessibility tests. Defaults to true. Disable if you only need component test results.")), true)
 });
 /**
@@ -417,11 +444,11 @@ For visual/design accessibility violations (for example color contrast), ask the
 			let storyIds;
 			let inputStoryCount = 0;
 			if (input.stories) {
-				const { found, notFound } = findStoryIds(await fetchStoryIndex(origin), input.stories);
-				storyIds = found.map((story) => story.id);
+				const resolvedStories = findStoryIds(await fetchStoryIndex(origin), input.stories);
+				storyIds = resolvedStories.filter((story) => "id" in story).map((story) => story.id);
 				inputStoryCount = input.stories.length;
 				if (storyIds.length === 0) {
-					const errorMessages = notFound.map((story) => story.errorMessage).join("\n");
+					const errorMessages = resolvedStories.filter((story) => "errorMessage" in story).map((story) => story.errorMessage).join("\n");
 					if (!disableTelemetry) await collectTelemetry({
 						event: "tool:runStoryTests",
 						server,
@@ -839,6 +866,7 @@ const initializeMCPServer = async (options, multiSource) => {
 		const contextAwareEnabled = () => server.ctx.custom?.toolsets?.docs ?? true;
 		await addListAllDocumentationTool(server, contextAwareEnabled);
 		await addGetDocumentationTool(server, contextAwareEnabled, { multiSource });
+		await addGetStoryDocumentationTool(server, contextAwareEnabled, { multiSource });
 	}
 	transport = new HttpTransport(server, { path: null });
 	origin = `http://localhost:${options.port}`;

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

@@ -4,7 +4,7 @@ const MCP_APP_SIZE_CHANGED_EVENT = "storybook-mcp:size-changed";
 
 //#endregion
 //#region package.json
-var version = "0.3.2";
+var version = "0.3.3";
 
 //#endregion
 //#region src/tools/preview-stories/preview-stories-app-script.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/addon-mcp",
-  "version": "0.3.2",
+  "version": "0.3.3",
   "description": "Help agents automatically write and test stories for your UI components",
   "keywords": [
     "ai",
@@ -34,12 +34,12 @@
     "picoquery": "^2.5.0",
     "tmcp": "^1.16.0",
     "valibot": "1.2.0",
-    "@storybook/mcp": "0.4.1"
+    "@storybook/mcp": "0.5.0"
   },
   "devDependencies": {
-    "@storybook/addon-a11y": "10.3.0-alpha.8",
-    "@storybook/addon-vitest": "10.3.0-alpha.8",
-    "storybook": "10.3.0-alpha.8"
+    "@storybook/addon-a11y": "10.3.0-alpha.12",
+    "@storybook/addon-vitest": "10.3.0-alpha.12",
+    "storybook": "10.3.0-alpha.12"
   },
   "peerDependencies": {
     "@storybook/addon-vitest": "^9.1.16 || ^10.0.0 || ^10.1.0-0 || ^10.2.0-0 || ^10.3.0-0 || ^10.4.0-0",