@storybook/addon-mcp 0.1.4-next.1 → 0.1.4

package/README.md

@@ -7,7 +7,7 @@ It enables a workflow where for each UI component created, the agent will automa
 The addon provides tools to improve agents' UI development capabilities, retrieve story URLs, and access component documentation.
 
 <div align="center">
-   <img src="https://storybook.js.org/embed/addon-mcp-claude-code-showcase.gif" alt="Storybook MCP Addon Demo" />
+   <img src="./addon-mcp-claude-code-showcase.gif" alt="Storybook MCP Addon Demo" />
 </div>
 
 ## Getting Started
@@ -50,6 +50,7 @@ export default {
 					dev: true, // Tools for story URL retrieval and UI building instructions (default: true)
 					docs: true, // Tools for component manifest and documentation (default: true, requires experimental feature)
 				},
+				experimentalFormat: 'markdown', // Output format: 'markdown' (default) or 'xml'
 			},
 		},
 	],
@@ -193,12 +194,12 @@ Returns a list of all available UI components in your component library. Useful
 
 #### 4. Get Component Documentation (`get-component-documentation`)
 
-Retrieves detailed documentation for specific components, including:
+Retrieves detailed documentation for a specific component, including:
 
 - Component documentation
 - Usage examples
 
-The agent provides component IDs to retrieve their documentation.
+The agent provides a component ID to retrieve its documentation. To get documentation for multiple components, call this tool multiple times.
 
 ## Contributing
 

package/dist/preset.js

@@ -11,12 +11,12 @@ import { buffer } from "node:stream/consumers";
 
 //#region package.json
 var name = "@storybook/addon-mcp";
-var version = "0.1.4-next.1";
+var version = "0.1.4";
 var description = "Help agents automatically write and test stories for your UI components";
 
 //#endregion
 //#region src/telemetry.ts
-async function collectTelemetry({ event, server,...payload }) {
+async function collectTelemetry({ event, server, ...payload }) {
 	try {
 		return await telemetry("addon-mcp", {
 			event,
@@ -69,13 +69,16 @@ 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
-}) });
+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.
 */
@@ -106,7 +109,7 @@ async function addGetStoryUrlsTool(server) {
 		enabled: () => server.ctx.custom?.toolsets?.dev ?? true
 	}, async (input) => {
 		try {
-			const { origin: origin$1, disableTelemetry } = server.ctx.custom ?? {};
+			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);
@@ -133,9 +136,10 @@ async function addGetStoryUrlsTool(server) {
 					result.push(errorMessage);
 				}
 			}
-			if (!disableTelemetry) await collectTelemetry({
+			if (!disableTelemetry$1) await collectTelemetry({
 				event: "tool:getStoryUrls",
 				server,
+				toolset: "dev",
 				inputStoryCount: input.stories.length,
 				outputStoryCount: foundStoryCount
 			});
@@ -151,7 +155,7 @@ async function addGetStoryUrlsTool(server) {
 
 //#endregion
 //#region src/ui-building-instructions.md
-var ui_building_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## 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// Full mock (replaces with empty fn functions)\nsb.mock(import('some-library'));\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### Key Requirements\n\n- **Node.js 20+**, **TypeScript 4.9+**, **Vite 5+**\n- React Native uses `.rnstorybook` directory\n- `afterEach` hook is now stable (was `experimental_afterEach`)\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 ui_building_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## 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\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### 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";
 
 //#endregion
 //#region src/tools/get-ui-building-instructions.ts
@@ -167,11 +171,12 @@ async function addGetUIBuildingInstructionsTool(server) {
 		enabled: () => server.ctx.custom?.toolsets?.dev ?? true
 	}, async () => {
 		try {
-			const { options, disableTelemetry } = server.ctx.custom ?? {};
+			const { options, disableTelemetry: disableTelemetry$1 } = server.ctx.custom ?? {};
 			if (!options) throw new Error("Options are required in addon context");
-			if (!disableTelemetry) await collectTelemetry({
+			if (!disableTelemetry$1) await collectTelemetry({
 				event: "tool:getUIBuildingInstructions",
-				server
+				server,
+				toolset: "dev"
 			});
 			const frameworkPreset = await options.presets.apply("framework");
 			const framework = typeof frameworkPreset === "string" ? frameworkPreset : frameworkPreset?.name;
@@ -213,7 +218,9 @@ const isManifestAvailable = async (options) => {
 let transport;
 let origin;
 let initialize;
+let disableTelemetry;
 const initializeMCPServer = async (options) => {
+	disableTelemetry = (await options.presets.apply("core", {}))?.disableTelemetry ?? false;
 	const server = new McpServer({
 		name,
 		version,
@@ -222,8 +229,8 @@ const initializeMCPServer = async (options) => {
 		adapter: new ValibotJsonSchemaAdapter(),
 		capabilities: { tools: { listChanged: true } }
 	}).withContext();
-	server.on("initialize", () => {
-		if (!options.disableTelemetry) collectTelemetry({
+	if (!disableTelemetry) server.on("initialize", async () => {
+		await collectTelemetry({
 			event: "session:initialized",
 			server
 		});
@@ -241,32 +248,33 @@ const initializeMCPServer = async (options) => {
 	logger.debug("MCP server origin:", origin);
 	return server;
 };
-const mcpServerHandler = async ({ req, res, next, options, addonOptions }) => {
-	const disableTelemetry = options.disableTelemetry ?? false;
+const mcpServerHandler = async ({ req, res, options, addonOptions }) => {
 	if (!initialize) initialize = initializeMCPServer(options);
 	const server = await initialize;
 	const webRequest = await incomingMessageToWebRequest(req);
 	const addonContext = {
 		options,
 		toolsets: getToolsets(webRequest, addonOptions),
+		format: addonOptions.experimentalFormat,
 		origin,
 		disableTelemetry,
-		source: `${origin}/manifests/components.json`,
+		request: webRequest,
 		...!disableTelemetry && {
 			onListAllComponents: async ({ manifest }) => {
 				await collectTelemetry({
 					event: "tool:listAllComponents",
 					server,
+					toolset: "docs",
 					componentCount: Object.keys(manifest.components).length
 				});
 			},
-			onGetComponentDocumentation: async ({ input, foundComponents, notFoundIds }) => {
+			onGetComponentDocumentation: async ({ input, foundComponent }) => {
 				await collectTelemetry({
 					event: "tool:getComponentDocumentation",
 					server,
-					inputComponentCount: input.componentIds.length,
-					foundCount: foundComponents.length,
-					notFoundCount: notFoundIds.length
+					toolset: "docs",
+					componentId: input.componentId,
+					found: !!foundComponent
 				});
 			}
 		}
@@ -332,24 +340,27 @@ var template_default = "<!doctype html>\n<html>\n	<head>\n		{{REDIRECT_META}}\n
 //#endregion
 //#region src/preset.ts
 const experimental_devServer = async (app, options) => {
-	const addonOptions = v.parse(AddonOptions, { toolsets: options.toolsets ?? {} });
-	app.post("/mcp", (req, res, next) => mcpServerHandler({
+	const addonOptions = v.parse(AddonOptions, {
+		toolsets: "toolsets" in options ? options.toolsets : {},
+		experimentalFormat: "experimentalFormat" in options ? options.experimentalFormat : "markdown"
+	});
+	app.post("/mcp", (req, res) => mcpServerHandler({
 		req,
 		res,
-		next,
 		options,
 		addonOptions
 	}));
 	const shouldRedirect = await isManifestAvailable(options);
-	app.get("/mcp", async (req, res) => {
-		if ((req.headers["accept"] || "").includes("text/html")) {
-			res.writeHead(200, { "Content-Type": "text/html" });
-			const html = template_default.replace("{{REDIRECT_META}}", shouldRedirect ? "<meta http-equiv=\"refresh\" content=\"10;url=/manifests/components.html\" />" : "<style>#redirect-message { display: none; }</style>");
-			res.end(html);
-		} else {
-			res.writeHead(200, { "Content-Type": "text/plain" });
-			res.end("Storybook MCP server successfully running via @storybook/addon-mcp");
-		}
+	app.get("/mcp", (req, res) => {
+		if (!req.headers["accept"]?.includes("text/html")) return mcpServerHandler({
+			req,
+			res,
+			options,
+			addonOptions
+		});
+		res.writeHead(200, { "Content-Type": "text/html" });
+		const html = template_default.replace("{{REDIRECT_META}}", shouldRedirect ? "<meta http-equiv=\"refresh\" content=\"10;url=/manifests/components.html\" />" : "<style>#redirect-message { display: none; }</style>");
+		res.end(html);
 	});
 	return app;
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storybook/addon-mcp",
-  "version": "0.1.4-next.1",
+  "version": "0.1.4",
   "description": "Help agents automatically write and test stories for your UI components",
   "keywords": [
     "storybook-addon",
@@ -8,8 +8,7 @@
     "ai"
   ],
   "repository": {
-    "type": "git",
-    "url": "https://github.com/storybookjs/mcp.git",
+    "url": "git+https://github.com/storybookjs/mcp.git",
     "directory": "packages/addon-mcp"
   },
   "license": "MIT",
@@ -29,18 +28,11 @@
     "@tmcp/adapter-valibot": "^0.1.4",
     "@tmcp/transport-http": "^0.8.0",
     "tmcp": "^1.16.0",
-    "valibot": "^1.1.0",
-    "@storybook/mcp": "0.0.6"
+    "valibot": "1.1.0",
+    "@storybook/mcp": "0.1.0"
   },
   "devDependencies": {
-    "@types/node": "20.19.0",
-    "@vitest/coverage-v8": "3.2.4",
-    "storybook": "^10.1.0-alpha.2",
-    "ts-dedent": "^2.2.0",
-    "tsdown": "^0.15.12",
-    "typescript": "^5.9.3",
-    "vite": "^7.0.5",
-    "vitest": "3.2.4"
+    "storybook": "10.1.0-alpha.11"
   },
   "peerDependencies": {
     "storybook": "^9.1.16 || ^10.0.0 || ^10.1.0-0 || ^10.2.0-0 || ^10.3.0-0 || ^10.4.0-0"
@@ -69,10 +61,10 @@
   },
   "scripts": {
     "prebuild": "node -e \"fs.rmSync('./dist', { recursive: true, force: true })\"",
-    "build": "tsdown --config ../../tsdown.config.ts",
-    "dev": "pnpm run build -- --watch",
-    "test": "vitest",
+    "build": "tsdown",
     "inspect": "mcp-inspector --config ../../.mcp.inspect.json --server storybook-addon-mcp",
-    "typecheck": "tsc --noEmit"
+    "publint": "publint",
+    "test": "cd ../.. && pnpm vitest --project=@storybook/addon-mcp",
+    "typecheck": "tsc"
   }
 }