@storybook/addon-mcp 0.0.4 → 0.0.6

package/README.md

@@ -1,12 +1,16 @@
 # Storybook MCP Addon
 
-This Storybook addon provides an MCP (Model Context Protocol) server, enabling AI agents to interact with your Storybook instance. The addon currently allows agents to get UI development instructions and retrieve story URLs directly from your running Storybook.
+This Storybook addon runs an MCP (Model Context Protocol) server to help develop UI components more efficiently.
+
+It enables a workflow where for each UI component created, the agent will automatically generate and link to example stories. These stories let you visually verify the new UI in each of its key states, and provide documentation and component tests.
+
+The server currently exposes two tools: one to provide UI development instructions to the agent, and the other to retrieve story URLs directly from your running Storybook.
 
 > [!IMPORTANT]
 > This addon currently only supports Vite-based Storybook setups, such as [`@storybook/react-vite`](https://storybook.js.org/docs/get-started/frameworks/react-vite), [`@storybook/nextjs-vite`](https://storybook.js.org/docs/get-started/frameworks/nextjs#with-vite), and [`@storybook/sveltekit`](https://storybook.js.org/docs/get-started/frameworks/sveltekit).
 
 <div align="center">
-   <img src="./addon-mcp-claude-code-showcase.gif" alt="Storybook MCP Addon Demo" />
+   <img src="https://storybook.js.org/embed/addon-mcp-claude-code-showcase.gif" alt="Storybook MCP Addon Demo" />
 </div>
 
 ## Getting Started
@@ -80,6 +84,8 @@ For clients not listed above, consult their documentation for MCP server configu
 
 This addon provides two main MCP tools that your agent can use. The goal is that the agent uses these tools automatically when doing UI development, but agents are unreliable and unpredictable, so sometimes you might need to explicitly tell it to use the tools.
 
+**If you are prompting from an IDE like VSCode or Cursor, be sure to use `Agent` mode and `sonnet-4.5` or better.**
+
 ### 1. UI Building Instructions (`get_ui_building_instructions`)
 
 Provides agents with standardized instructions for UI component development within your project. This tool returns guidelines for:
@@ -111,24 +117,31 @@ http://localhost:6006/?path=/story/example-button--primary
 
 We welcome contributions to improve Storybook's agent integration, within or outside of this addon! Here's how you can help:
 
-1. **Ideas and feature requests**: If you have ideas for what else we could do to improve the Storybook experience when using agents, please [start a discussion](https://github.com/storybookjs/addon-mcp/discussions/new?category=ideas) in this repository.
+1. **Ideas and feature requests**: If you have ideas for what else we could do to improve the Storybook experience when using agents, please [start a discussion](https://github.com/storybookjs/mcp/discussions/new?category=ideas) in this repository.
 
-2. **Report Issues**: If you find bugs, please open an issue on our [GitHub repository](https://github.com/storybookjs/addon-mcp), but keep in mind that this is currently highly experimental, explorative and probably filled with bugs.
+2. **Report Issues**: If you find bugs, please open an issue on our [GitHub repository](https://github.com/storybookjs/mcp), but keep in mind that this is currently highly experimental, explorative and probably filled with bugs.
 
 3. **Development Setup**:
 
+   This repository uses a monorepo structure with [pnpm workspaces](https://pnpm.io/workspaces) and [Turborepo](https://turborepo.com) for task orchestration.
+
    ```bash
    # Clone the repository
-   git clone https://github.com/storybookjs/addon-mcp.git
+   git clone https://github.com/storybookjs/mcp.git
    cd addon-mcp
 
-   # Install dependencies
+   # Install dependencies (installs for all packages in the workspace)
    pnpm install
 
-   # Start development
+   # Build all packages
+   pnpm build
+
+   # Start development (runs the addon-mcp package)
    pnpm start
    ```
 
+   The main addon package is located in `packages/addon-mcp`.
+
 4. **Testing**: Run the MCP inspector to test the server functionality (requires that the Storybook dev server is running):
 
    ```bash

package/dist/preset.js

@@ -16,9 +16,9 @@ var __export = (target, all) => {
 // package.json
 var package_default = {
   name: "@storybook/addon-mcp",
-  version: "0.0.4"};
+  version: "0.0.5"};
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/external.js
 var external_exports = {};
 __export(external_exports, {
   BRAND: () => BRAND,
@@ -130,7 +130,7 @@ __export(external_exports, {
   void: () => voidType
 });
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/util.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/util.js
 var util;
 (function(util2) {
   util2.assertEqual = (_) => {
@@ -264,7 +264,7 @@ var getParsedType = (data) => {
   }
 };
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/ZodError.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/ZodError.js
 var ZodIssueCode = util.arrayToEnum([
   "invalid_type",
   "invalid_literal",
@@ -382,7 +382,7 @@ ZodError.create = (issues) => {
   return error;
 };
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/locales/en.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/locales/en.js
 var errorMap = (issue, _ctx) => {
   let message;
   switch (issue.code) {
@@ -485,7 +485,7 @@ var errorMap = (issue, _ctx) => {
 };
 var en_default = errorMap;
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/errors.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/errors.js
 var overrideErrorMap = en_default;
 function setErrorMap(map) {
   overrideErrorMap = map;
@@ -494,7 +494,7 @@ function getErrorMap() {
   return overrideErrorMap;
 }
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/parseUtil.js
 var makeIssue = (params) => {
   const { data, path: path2, errorMaps, issueData } = params;
   const fullPath = [...path2, ...issueData.path || []];
@@ -604,14 +604,14 @@ var isDirty = (x) => x.status === "dirty";
 var isValid = (x) => x.status === "valid";
 var isAsync = (x) => typeof Promise !== "undefined" && x instanceof Promise;
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/errorUtil.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/helpers/errorUtil.js
 var errorUtil;
 (function(errorUtil2) {
   errorUtil2.errToObj = (message) => typeof message === "string" ? { message } : message || {};
   errorUtil2.toString = (message) => typeof message === "string" ? message : message?.message;
 })(errorUtil || (errorUtil = {}));
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/v3/types.js
 var ParseInputLazyPath = class {
   constructor(parent, value, path2, key) {
     this._cachedPath = [];
@@ -4058,7 +4058,7 @@ var coerce = {
 };
 var NEVER = INVALID;
 
-// node_modules/.pnpm/zod@3.25.76/node_modules/zod/index.js
+// ../../node_modules/.pnpm/zod@3.25.76/node_modules/zod/index.js
 var zod_default = external_exports;
 async function collectTelemetry({
   event,
@@ -4169,7 +4169,7 @@ function registerStoryUrlsTool({
 }
 
 // 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// 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";
 function registerUIBuildingTool({
   server,
   options

package/package.json

@@ -1,18 +1,19 @@
 {
   "name": "@storybook/addon-mcp",
-  "version": "0.0.4",
-  "description": "everything you need to build a Storybook addon",
+  "version": "0.0.6",
+  "description": "Help agents automatically write and test stories for your UI components",
   "keywords": [
-    "storybook-addons",
+    "storybook-addon",
     "mcp",
     "ai"
   ],
   "repository": {
     "type": "git",
-    "url": "https://github.com/storybookjs/addon-mcp"
+    "url": "https://github.com/storybookjs/mcp.git",
+    "directory": "packages/addon-mcp"
   },
   "license": "MIT",
-  "author": "Jeppe Reinhold <jeppe@chromatic.com>, Tom Coleman <tom@chromatic.com>",
+  "author": "Storybook Core Team",
   "type": "module",
   "exports": {
     "./preset": "./dist/preset.js",
@@ -28,38 +29,19 @@
     "@modelcontextprotocol/sdk": "^1.17.3"
   },
   "devDependencies": {
-    "@changesets/changelog-github": "^0.5.1",
-    "@changesets/cli": "^2.29.6",
-    "@modelcontextprotocol/inspector": "^0.16.5",
-    "@storybook/addon-docs": "^10.0.0-0",
-    "@storybook/icons": "^1.4.0",
-    "@storybook/react-vite": "^10.0.0-0",
     "@types/node": "^20",
-    "@types/react": "^18.2.65",
-    "@types/react-dom": "^18.2.21",
-    "@vitejs/plugin-react": "^4.7.0",
-    "auto": "^11.3.0",
-    "boxen": "^8.0.1",
-    "npm-run-all2": "^8.0.4",
-    "pkg-pr-new": "^0.0.57",
-    "prettier": "^3.6.2",
-    "prompts": "^2.4.2",
-    "react": "^18.2.0",
-    "react-dom": "^18.2.0",
     "storybook": "^10.0.0-0",
     "ts-dedent": "^2.2.0",
     "tsup": "^8.5.0",
     "typescript": "^5.8.3",
     "vite": "^7.0.5",
-    "zod": "^3.25.76",
-    "zx": "^8.7.1"
+    "zod": "^3.25.76"
   },
   "peerDependencies": {
     "storybook": "*"
   },
   "publishConfig": {
-    "access": "public",
-    "provenance": true
+    "access": "public"
   },
   "bundler": {
     "nodeEntries": [
@@ -83,13 +65,7 @@
   "scripts": {
     "prebuild": "node -e \"fs.rmSync('./dist', { recursive: true, force: true })\"",
     "build": "tsup",
-    "build-storybook": "storybook build",
-    "build:watch": "pnpm run build -- --watch",
-    "changeset": "changeset",
-    "inspect": "mcp-inspector --transport streamable-http --server-url http://localhost:6006/mcp",
-    "release": "pnpm run build && pnpm changeset publish",
-    "start": "run-p build:watch \"storybook --quiet\"",
-    "storybook": "storybook dev --port 6006 --loglevel debug",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "dev": "pnpm run build -- --watch",
+    "inspect": "mcp-inspector --config ../../.mcp.inspect.json --server storybook-addon-mcp"
   }
 }

package/preset.js

@@ -1 +1 @@
-export * from "./dist/preset.js";
+export * from './dist/preset.js';