diff --git a/docs/_assets/ai/addon-mcp-splash.png b/docs/_assets/ai/addon-mcp-splash.png new file mode 100644 index 000000000000..b6e18f9c009a Binary files /dev/null and b/docs/_assets/ai/addon-mcp-splash.png differ diff --git a/docs/_assets/ai/manifest-debugger.png b/docs/_assets/ai/manifest-debugger.png new file mode 100644 index 000000000000..7beb6fc28de6 Binary files /dev/null and b/docs/_assets/ai/manifest-debugger.png differ diff --git a/docs/_snippets/addon-mcp-add.md b/docs/_snippets/addon-mcp-add.md new file mode 100644 index 000000000000..bec2b02aa8e9 --- /dev/null +++ b/docs/_snippets/addon-mcp-add.md @@ -0,0 +1,11 @@ +```shell renderer="common" language="js" packageManager="npm" +npx storybook add @storybook/addon-mcp +``` + +```shell renderer="common" language="js" packageManager="pnpm" +pnpm exec storybook add @storybook/addon-mcp +``` + +```shell renderer="common" language="js" packageManager="yarn" +yarn exec storybook add @storybook/addon-mcp +``` diff --git a/docs/_snippets/addon-mcp-options.md b/docs/_snippets/addon-mcp-options.md new file mode 100644 index 000000000000..af9ef5f12521 --- /dev/null +++ b/docs/_snippets/addon-mcp-options.md @@ -0,0 +1,86 @@ +```js filename=".storybook/main.js" renderer="common" language="js" tabTitle="CSF 3" +export default { + // Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.) + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + addons: [ + // ... your existing addons + { + name: '@storybook/addon-mcp', + options: { + toolsets: { + dev: false, + }, + }, + }, + ], +}; +``` + +```ts filename=".storybook/main.ts" renderer="common" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using (e.g., react-vite, vue3-vite, angular, etc.) +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + addons: [ + // ... your existing addons + { + name: '@storybook/addon-mcp', + options: { + toolsets: { + dev: false, + }, + }, + }, + ], +}; + +export default config; +``` + +```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + addons: [ + // ... your existing addons + { + name: '@storybook/addon-mcp', + options: { + toolsets: { + dev: false, + }, + }, + }, + ], +}); +``` + + + +```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + // Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + addons: [ + // ... your existing addons + { + name: '@storybook/addon-mcp', + options: { + toolsets: { + dev: false, + }, + }, + }, + ], +}); +``` diff --git a/docs/_snippets/best-practices-in-story.md b/docs/_snippets/best-practices-in-story.md new file mode 100644 index 000000000000..17d1f8ea0b28 --- /dev/null +++ b/docs/_snippets/best-practices-in-story.md @@ -0,0 +1,188 @@ +```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="CSF 3" +import { Button } from './Button'; + +export default { + component: Button, +}; + +// βœ… Good - shows the default state +export const Basic = {}; + +// βœ… Good - demonstrates a specific use case +export const Primary = { + args: { primary: true }, +}; + +// βœ… Good - even though this story renders more than one button, +// they both demonstrate the same concept of a disabled button +export const Disabled = { + args: { disabled: true }, + render: (args) => ( + <> + + + + ), +}; + +// ❌ Bad - demonstrates too many concepts at once, making +// it less clear and less useful as a reference for agents +export const SizesAndVariants = { + render: () => ( + <> + + + + + + + ), +}; +``` + +```ts filename="Button.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc. +import type { Meta, StoryObj } from '@storybook/your-framework'; + +import { Button } from './Button'; + +const meta = { + component: Button, +} satisfies Meta; + +export default meta; + +type Story = StoryObj; + +// βœ… Good to show the default state +export const Basic: Story = {}; + +// βœ… Good to demonstrate a specific use case +export const Primary: Story = { + args: { primary: true }, +}; + +// βœ… Good - even though this story renders more than one button, +// they both demonstrate the same concept of a disabled button +export const Disabled: Story = { + args: { disabled: true }, + render: (args) => ( + <> + + + + ), +}; + +// ❌ Bad - demonstrates too many concepts at once, making +// it less clear and less useful as a reference for agents +export const SizesAndVariants: Story = { + render: () => ( + <> + + + + + + + ), +}; +``` + +```ts filename="Button.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { Button } from './Button'; + +const meta = preview.meta({ + component: Button, +}); + +// βœ… Good to show the default state +export const Basic = meta.story(); + +// βœ… Good to demonstrate a specific use case +export const Primary = meta.story({ + args: { primary: true }, +}); + +// βœ… Good - even though this story renders more than one button, +// they both demonstrate the same concept of a disabled button +export const Disabled = meta.story({ + args: { disabled: true }, + render: (args) => ( + <> + + + + ), +}); + +// ❌ Bad - demonstrates too many concepts at once, making +// it less clear and less useful as a reference for agents +export const SizesAndVariants = meta.story({ + render: () => ( + <> + + + + + + + ), +}); +``` + + + +```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { Button } from './Button'; + +const meta = preview.meta({ + component: Button, +}); + +// βœ… Good to show the default state +export const Basic = meta.story(); + +// βœ… Good to demonstrate a specific use case +export const Primary = meta.story({ + args: { primary: true }, +}); + +// βœ… Good - even though this story renders more than one button, +// they both demonstrate the same concept of a disabled button +export const Disabled = meta.story({ + args: { disabled: true }, + render: (args) => ( + <> + + + + ), +}); + +// ❌ Bad - demonstrates too many concepts at once, making +// it less clear and less useful as a reference for agents +export const SizesAndVariants = meta.story({ + render: () => ( + <> + + + + + + + ), +}); +``` diff --git a/docs/_snippets/main-config-features-components-manifest.md b/docs/_snippets/main-config-features-components-manifest.md new file mode 100644 index 000000000000..367608c2e165 --- /dev/null +++ b/docs/_snippets/main-config-features-components-manifest.md @@ -0,0 +1,53 @@ +```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3" +export default { + // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + componentsManifest: false, + }, +}; +``` + +```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + componentsManifest: false, + }, +}; + +export default config; +``` + +```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + componentsManifest: false, + }, +}); +``` + + + +```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + componentsManifest: false, + }, +}); +``` diff --git a/docs/_snippets/main-config-features-experimental-code-examples.md b/docs/_snippets/main-config-features-experimental-code-examples.md new file mode 100644 index 000000000000..378ab9472eae --- /dev/null +++ b/docs/_snippets/main-config-features-experimental-code-examples.md @@ -0,0 +1,53 @@ +```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF 3" +export default { + // Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + experimentalCodeExamples: true, + }, +}; +``` + +```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, vue3-vite, etc. +import type { StorybookConfig } from '@storybook/your-framework'; + +const config: StorybookConfig = { + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + experimentalCodeExamples: true, + }, +}; + +export default config; +``` + +```ts filename=".storybook/main.ts" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + experimentalCodeExamples: true, + }, +}); +``` + + + +```js filename=".storybook/main.js" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +// Replace your-framework with the framework you are using (e.g., react-vite, nextjs, nextjs-vite) +import { defineMain } from '@storybook/your-framework/node'; + +export default defineMain({ + framework: '@storybook/your-framework', + stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'], + features: { + experimentalCodeExamples: true, + }, +}); +``` diff --git a/docs/_snippets/mcp-add.md b/docs/_snippets/mcp-add.md new file mode 100644 index 000000000000..143818194f7d --- /dev/null +++ b/docs/_snippets/mcp-add.md @@ -0,0 +1,11 @@ +```shell renderer="common" language="js" packageManager="npm" +npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project +``` + +```shell renderer="common" language="js" packageManager="pnpm" +pnpm exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project +``` + +```shell renderer="common" language="js" packageManager="yarn" +yarn exec mcp-add --type http --url "http://localhost:6006/mcp" --scope project +``` diff --git a/docs/_snippets/story-description-and-summary.md b/docs/_snippets/story-description-and-summary.md new file mode 100644 index 000000000000..2fe47c955ed6 --- /dev/null +++ b/docs/_snippets/story-description-and-summary.md @@ -0,0 +1,84 @@ +```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="CSF 3" +import { Button } from './Button'; + +export default { + component: Button, +}; + +/** + * Primary buttons are used for the main action in a view. + * There should not be more than one primary button per view. + * + * @summary for the main action in a view + */ +export const Primary = { + args: { primary: true }, +}; +``` + +```ts filename="Button.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc. +import type { Meta, StoryObj } from '@storybook/your-framework'; + +import { Button } from './Button'; + +const meta = { + component: Button, +} satisfies Meta; + +export default meta; + +type Story = StoryObj; + +/** + * Primary buttons are used for the main action in a view. + * There should not be more than one primary button per view. + * + * @summary for the main action in a view + */ +export const Primary: Story = { + args: { primary: true }, +}; +``` + +```ts filename="Button.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { Button } from './Button'; + +const meta = preview.meta({ + component: Button, +}); + +/** + * Primary buttons are used for the main action in a view. + * There should not be more than one primary button per view. + * + * @summary for the main action in a view + */ +export const Primary = meta.story({ + args: { primary: true }, +}); +``` + + + +```js filename="Button.stories.js|jsx" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { Button } from './Button'; + +const meta = preview.meta({ + component: Button, +}); + +/** + * Primary buttons are used for the main action in a view. + * There should not be more than one primary button per view. + * + * @summary for the main action in a view + */ +export const Primary = meta.story({ + args: { primary: true }, +}); +``` diff --git a/docs/_snippets/tag-manifest-remove-in-story.md b/docs/_snippets/tag-manifest-remove-in-story.md new file mode 100644 index 000000000000..7d49137f1364 --- /dev/null +++ b/docs/_snippets/tag-manifest-remove-in-story.md @@ -0,0 +1,72 @@ +```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="CSF 3" +import { MyComponent } from './MyComponent'; + +export default { + component: MyComponent, +}; + +// πŸ‘‡ This story will be included in the manifest because it has the implicit 'manifest' tag +export const Basic = {}; + +export const ForInstructionOnly = { + tags: ['!manifest'], // πŸ‘ˆ Remove the 'manifest' tag to exclude this story from the manifests +}; +``` + +```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF 3" +// Replace your-framework with the framework you are using, e.g. react-vite, nextjs, nextjs-vite, etc. +import type { Meta, StoryObj } from '@storybook/your-framework'; + +import { MyComponent } from './MyComponent'; + +const meta = { + component: MyComponent, +} satisfies Meta; + +export default meta; + +type Story = StoryObj; + +// πŸ‘‡ This story will be included in the manifest because it has the implicit 'manifest' tag +export const Basic = {}; + +export const ForInstructionOnly = { + tags: ['!manifest'], // πŸ‘ˆ Remove the 'manifest' tag to exclude this story from the manifests +}; +``` + +```ts filename="MyComponent.stories.ts|tsx" renderer="react" language="ts" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { MyComponent } from './MyComponent'; + +const meta = preview.meta({ + component: MyComponent, +}); + +// πŸ‘‡ This story will be included in the manifest because it has the implicit 'manifest' tag +export const Basic = meta.story(); + +export const ForInstructionOnly = meta.story({ + tags: ['!manifest'], // πŸ‘ˆ Remove the 'manifest' tag to exclude this story from the manifests +}); +``` + + + +```js filename="MyComponent.stories.js|jsx" renderer="react" language="js" tabTitle="CSF Next πŸ§ͺ" +import preview from '../.storybook/preview'; + +import { MyComponent } from './MyComponent'; + +const meta = preview.meta({ + component: MyComponent, +}); + +// πŸ‘‡ This story will be included in the manifest because it has the implicit 'manifest' tag +export const Basic = meta.story(); + +export const ForInstructionOnly = meta.story({ + tags: ['!manifest'], // πŸ‘ˆ Remove the 'manifest' tag to exclude this story from the manifests +}); +``` diff --git a/docs/addons/index.mdx b/docs/addons/index.mdx index 885de36c8845..f164e16f0746 100644 --- a/docs/addons/index.mdx +++ b/docs/addons/index.mdx @@ -2,7 +2,7 @@ title: 'Introduction to addons' hideRendererSelector: true sidebar: - order: 7 + order: 9 title: Addons --- diff --git a/docs/ai/best-practices.mdx b/docs/ai/best-practices.mdx new file mode 100644 index 000000000000..3143c2d8c303 --- /dev/null +++ b/docs/ai/best-practices.mdx @@ -0,0 +1,135 @@ +--- +title: Best practices for using Storybook with AI +sidebar: + order: 2 + title: Best practices +--- + + + The best practices here relate to the [generated manifests](./manifests.mdx), which are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +Use Storybook together with an AI agent effectively by following these best practices. + +## Writing effective stories + +Stories are referenced by the [MCP server](./mcp/overview.mdx) to provide examples of how your components are used. They are also tested to ensure your components work as expected. Whenever possible, they should demonstrate one concept or use case, and be as descriptive about the "why" behind the story, not just the "what". This will help agents understand when and why to use certain components or patterns. + + + +You might be wondering how well an agent handles abstractions like [`args`](../writing-stories/args.mdx) or [decorators](../writing-stories/decorators.mdx). The manifest generation process evaluates the final rendered story with all args, decorators, etc. applied, so it can focus on the concept being demonstrated, rather than the specifics of how it's implemented. + +## Documenting your components + +To reuse your components effectively, agents depend on how well you document their purpose, usage, and APIs. There are a few key aspects that are well worth taking the time to document (ask your agent to help!). To provide these details, you can use [JSDoc comments](https://jsdoc.app/about-getting-started) in your code, which Storybook will automatically extract and include in the generated [manifest](./manifests.mdx) for the agent. + +Of course, with [Autodocs](../writing-docs/autodocs.mdx), any documentation efforts you make will help human developers, too! + +### Component summary and description + +Help the agent understand what a component should be used for by providing a description (and optional summary) as a JSDoc comment above the export of the component. + +The agent will receive the summary, if present, or a truncated version of the description. + +```ts title="Button.tsx" +/** + * Button is used for user interactions that do not navigate to another route. + * For navigation, use [Link](?path=/docs/link--default) instead. + * + * @summary for user interactions that do not navigate to another route + */ +export const Button = // ... +``` + +You can use Markdown syntax in your description to add formatting or links. + +### Story summary and descriptions + +Similarly, you can provide descriptions (and summaries) for each story, which serve as usage examples for the agent. Don't just repeat what the story is demonstrating; describe _why_ you would use whatever is demonstrated. + +The agent will receive the summary, if present, or the first 60 characters of the description. + + + +### Prop type extraction + +We highly recommend using `react-docgen-typescript` for prop type extraction (set with the [`reactDocgen`](../api/main-config/main-config-typescript.mdx#reactdocgen) config option), because it provides more accurate and comprehensive information about your components' props, which will help agents use them more effectively. If manifest generation seems too slow, you can switch to `react-docgen`, which is faster but less detailed. + +### Prop descriptions + +It's also helpful to provide descriptions for your component's props in the JSDoc comments in your component code, as agents will use these to understand how to use the component effectively. + +```ts title="Button.tsx" +export interface ButtonProps { + /** The icon to render before the button text */ + icon?: ReactNode; +} +``` + +## Docs summaries + +For unattached MDX docs pages (such as documentation for design tokens, guidelines, etc.), you can provide a summary in the `Meta` tag, which will be included in the manifest and provided to the agent. + +```jsx title="Colors.mdx" +import { Meta } from '@storybook/addon-docs/blocks'; + + +``` + +## Docs content + +Storybook generates this docs manifest through static analysis of your MDX files, which means it is limited to the information that is explicitly present in those files. For example, the manifest will _not_ include the color tokens in the document below, because their values are not explicitly in the source: + +```jsx title="Colors.mdx" +import { Meta, ColorPalette, ColorItem } from '@storybook/addon-docs/blocks'; +import { colors } from '../src/tokens/colors'; + + + +# Colors + +{/* πŸ‘‡ These colors are *not* included in the manifest, because their values are not explicitly in the source */} + + {colors.map((color) => ( + + ))} + +``` + +To ensure that your agents have access to all the necessary information, it's important to include any relevant details directly in your MDX files, rather than referencing external sources. + +We hope to improve this in the future, possibly by evaluating the MDX files and including the result in the manifest. + +## Manifest curation + +It's possible to provide too little _or_ too much context to your agent. If your manifest is missing key information about your components, the agent may not be able to use them effectively. On the other hand, if your manifest includes information irrelevant to the task at hand, it may be overwhelming for the agent and lead to worse performance. + +For stories or docs which the agent does not need to reference (e.g. a story demonstrating an anti-pattern or a docs page about deprecated components), you can exclude them from the manifest by removing the `manifest` [tag](../writing-stories/tags.mdx): + + + +You can also remove an entire component from the manifest, by removing the tag in the meta (or default export) of the file, which will exclude all stories in that file from the manifests. + +Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: + +```jsx title="DocForHumansOnly.mdx" +import { Meta } from '@storybook/addon-docs/blocks'; + + +``` + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server overview](./mcp/overview.mdx) +- [MCP server API](./mcp/api.mdx) +- [Sharing your MCP server](./mcp/sharing.mdx) +- [Manifests](./manifests.mdx) + + diff --git a/docs/ai/index.mdx b/docs/ai/index.mdx new file mode 100644 index 000000000000..809e20ad6533 --- /dev/null +++ b/docs/ai/index.mdx @@ -0,0 +1,90 @@ +--- +title: Using Storybook with AI +sidebar: + order: 5 + title: AI +--- + + + While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](./manifests.mdx) and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +With Storybook's AI capabilities, you can leverage the power of AI agents to speed up your development workflow. By connecting your Storybook to an AI agent via the [Storybook MCP server](./mcp/overview.mdx), you can enable your agent to understand your components and documentation, generate stories, run tests, and more. + +## Get started + +### 1. Install the addon + +Run this command to install and register the Storybook MCP addon: + + + +Now, when running Storybook's dev server, you can access the MCP server at `http://localhost:6006/mcp` (your port may be different). When viewed in the browser, you'll see a page showing which tools are available and a link to the [manifest debugger](./manifests.mdx#debugging). + +![The MCP server page in the browser](../_assets/ai/addon-mcp-splash.png) + +### 2. Add the MCP server to your agent + +Then run this command to configure your agent to use the MCP server: + + + +You may need to update the port number in the URL. You will be prompted for a name for your MCP server (e.g. "my-project-sb-mcp"). This is the name you'll use when calling the tools from your agent, so choose something descriptive and unique to avoid confusion with other tools. + +[`mcp-add`](https://github.com/paoloricciuti/mcp-add) is a CLI tool designed to simplify adding MCP servers to various agents. + +You can also follow your agent's documentation to add the MCP server as a tool provider manually, e.g. [Claude Code](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server), [Google Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#adding-an-http-server), [OpenAI Codex](https://developers.openai.com/codex/mcp/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file), etc. + +### 3. Adjust your agent instructions + +To guide your agent to use your MCP server, you should adjust your [`AGENTS.md`](https://agents.md/) (or [`CLAUDE.md`](https://code.claude.com/docs/en/memory#claude-md-files), if you're using Claude). The specifics will depend on your project and how you use agents in your development process, but something like this is a good starting point. Just make sure to replace `your-project-sb-mcp` with the name you chose for your MCP server toolset in the previous step. + +
+Example instructions for AGENTS.md + +```md title="AGENTS.md" +When working on UI components, always use the `your-project-sb-mcp` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action. + +- **CRITICAL: Never hallucinate component properties!** Before using ANY property on a component from a design system (including common-sounding ones like `shadow`, etc.), you MUST use the MCP tools to check if the property is actually documented for that component. +- Query `list-all-documentation` to get a list of all components +- Query `get-documentation` for that component to see all available properties and examples +- Only use properties that are explicitly documented or shown in example stories +- If a property isn't documented, do not assume properties based on naming conventions or common patterns from other libraries. Check back with the user in these cases. +- Use the `get-storybook-story-instructions` tool to fetch the latest instructions for creating or updating stories. This will ensure you follow current conventions and recommendations. +- Check your work by running `run-story-tests`. + +Remember: A story name might not reflect the property name correctly, so always verify properties through documentation or example stories before using them. +``` + +
+ +Finally, test your agent's access to the MCP server. First, make sure your Storybook is running, then run a prompt like "List all documented components". You should see a call to the [`list-all-documentation`](./mcp/overview.mdx#list-all-documentation) tool with a response listing components from your Storybook. + +## Key concepts + +Understanding these concepts will help you make the most of Storybook's AI capabilities and guide you in using the MCP server to enhance your development workflow. + +### Manifests + +Storybook collects all of the metadata about your components, stories, and docs into [manifests](./manifests.mdx). Each manifest is a JSON object that serves as a comprehensive map of your Storybook's content and structure. There are manifests for components, based on stories files, and for documentation, based on MDX files. + +These manifests are automatically generated and updated as you work on your Storybook, ensuring that your agent always has access to the latest information about your project. + +### MCP server + +[Model Context Protocol](https://modelcontextprotocol.io/) (MCP) is a standard for communication between AI agents and external tools. Storybook's [MCP server](./mcp/index.mdx) exposes your Storybook's content and functionality as a set of tools that your agent can call to retrieve component information, generate stories, run component tests, and more. + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server overview](./mcp/overview.mdx) +- [MCP server API](./mcp/api.mdx) +- [Sharing your MCP server](./mcp/sharing.mdx) +- [Best practices for using Storybook with AI](./best-practices.mdx) +- [Manifests](./manifests.mdx) diff --git a/docs/ai/manifests.mdx b/docs/ai/manifests.mdx new file mode 100644 index 000000000000..685be46d286c --- /dev/null +++ b/docs/ai/manifests.mdx @@ -0,0 +1,286 @@ +--- +title: Manifests +sidebar: + order: 3 +--- + + + While they are in [preview](../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the manifests and [MCP server](./mcp/overview.mdx)) are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +Your Storybook holds a wealth of information about your components: their names, descriptions, API, usage examples, and more. Manifests are JSON objects that describe the contents of your Storybook in a concise, structured way that is easy for AI agents to understand and use. The manifests are generated automatically from your Storybook's CSF and MDX files, and they are designed to be comprehensive and up-to-date representations of your Storybook's contents. + +There are two types of manifests generated by Storybook: components and docs. + +## Components manifest + +The components manifest is generated from static analysis of the CSF files in your Storybook and prop type extraction from their associated component source code. It contains information about the components you have documented, such as their names, descriptions, props, and usage examples. This manifest is designed to help AI agents understand which components are available and how to use them. + +For prop type extraction, the manifest generation will use whatever is specified in the [`reactDocgen`](../api/main-config/main-config-typescript.mdx#reactdocgen) option, or `react-docgen` by default. We recommend using `react-docgen-typescript` for most projects, because it provides more accurate and comprehensive information about your components' props. If manifest generation seems too slow, you can switch to `react-docgen`, which is faster but less detailed. + +While the types themselves provide a basic level of information, JSDoc comments in your component source code can provide additional metadata for the manifest, which can be helpful for AI agents. We highly recommend adding JSDoc comments to your components and their props to provide as much context as possible for the agents. For example: + +```ts title="Button.tsx" +import React from 'react'; + +type ButtonProps = { + /** + * Optional click handler + */ + onClick?: () => void; +}; + +/** + * Button is used for user interactions that do not navigate to another route. + * For navigation, use [Link](?path=/docs/link--default) instead. + */ +export const Button: React.FC = ({ onClick }) => { /* ... */ }; +``` + + + Check the [best practices](./best-practices.mdx) guide for tips on writing effective JSDoc comments for your components and other ways to provide helpful context for the agents. + + +The raw JSON components manifest can be accessed at `http://localhost:6006/manifests/components.json` (your port may vary) when your Storybook is running or at the `/manifests/components.json` route in a built Storybook. + +
+Example components manifest entry + + + While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + + +```json +{ + "components": { + "components-button": { + "id": "components-button", + "name": "Button", + "path": "./src/components/Button/Button.stories.tsx", + "stories": [ + { + "id": "components-button--default", + "name": "Default", + "snippet": "const Default = () =\u003E \u003CButton\u003EButton\u003C/Button\u003E;" + }, + { + "id": "components-button--disabled", + "name": "Disabled", + "snippet": "const Disabled = () =\u003E \u003CButton disabled\u003EButton\u003C/Button\u003E;" + } + ], + "import": "import { Button } from \"@mealdrop/ui\";", + "jsDocTags": { + + }, + "description": "Primary UI component for user interaction", + "reactDocgen": { + "description": "Primary UI component for user interaction", + "methods": [], + "displayName": "Button", + "definedInFile": "/path/to/project/src/components/Button/Button.tsx", + "actualName": "Button", + "exportName": "Button", + "props": { + "clear": { + "required": false, + "tsType": { + "name": "boolean" + }, + "description": "Clear button styles leaving just a text", + "defaultValue": { + "value": "false", + "computed": false + } + }, + "round": { + "required": false, + "tsType": { + "name": "boolean" + }, + "description": "", + "defaultValue": { + "value": "false", + "computed": false + } + }, + "large": { + "required": false, + "tsType": { + "name": "boolean" + }, + "description": "Is the button large?", + "defaultValue": { + "value": "false", + "computed": false + } + }, + "icon": { + "required": false, + "tsType": { + "name": "union", + "raw": "| 'arrow-right'\n| 'arrow-left'\n| 'cross'\n| 'cart'\n| 'minus'\n| 'plus'\n| 'moon'\n| 'sun'\n| 'star'", + "elements": [ + { + "name": "literal", + "value": "'arrow-right'" + }, + { + "name": "literal", + "value": "'arrow-left'" + }, + { + "name": "literal", + "value": "'cross'" + }, + { + "name": "literal", + "value": "'cart'" + }, + { + "name": "literal", + "value": "'minus'" + }, + { + "name": "literal", + "value": "'plus'" + }, + { + "name": "literal", + "value": "'moon'" + }, + { + "name": "literal", + "value": "'sun'" + }, + { + "name": "literal", + "value": "'star'" + } + ] + }, + "description": "Does the button have an icon?" + }, + "iconSize": { + "required": false, + "tsType": { + "name": "number" + }, + "description": "Size of the icon" + }, + "disabled": { + "required": false, + "tsType": { + "name": "boolean" + }, + "description": "Is the button disabled?" + }, + "children": { + "required": false, + "tsType": { + "name": "union", + "raw": "string | React.ReactNode", + "elements": [ + { + "name": "string" + }, + { + "name": "ReactReactNode", + "raw": "React.ReactNode" + } + ] + }, + "description": "The content of the button" + }, + "onClick": { + "required": false, + "tsType": { + "name": "signature", + "type": "function", + "raw": "() =\u003E void", + "signature": { + "arguments": [], + "return": { + "name": "void" + } + } + }, + "description": "Optional click handler" + } + } + } + } + } +} +``` +
+ +## Docs (MDX) manifest + +The docs manifest is generated from the [MDX files](../writing-docs/mdx.mdx) in your Storybook. These files are used to document specific components or to create standalone documentation pages (e.g. a "Getting Started" guide, accessibility guidelines, design tokens, etc.), all of which can offer helpful context to the agent. + +The raw JSON docs manifest can be accessed at `http://localhost:6006/manifests/docs.json` (your port may vary) when your Storybook is running or at the `/manifests/docs.json` route in a built Storybook. + + + Check the [best practices](./best-practices.mdx) guide for tips on writing effective documentation and providing helpful context for the agents. + + +
+Example docs manifest entry + + + While in [preview](../releases/features.mdx#preview), this manifest schema is not yet stable and should not be considered a public API. We include it here only as an aid for understanding. + + +```json +{ + "docs": { + "design-system-typography--docs": { + "id": "design-system-typography--docs", + "name": "Docs", + "path": "./src/docs/Typography.mdx", + "title": "Design System/Typography", + "content": "import { Meta, Typeset } from '@storybook/addon-docs/blocks'\n\n\u003CMeta title=\"Design System/Typography\" /\u003E\n\n# Typography\n\n## Font: Hind\n\nUsed for body texts, descriptions and general info\n\n**Weight:** 400(regular)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={400}\n fontFamily=\"Hind\"\n/\u003E\n\n**Weight:** 500(medium)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={500}\n fontFamily=\"Hind\"\n/\u003E\n\n## Font: Montserrat\n\nUsed for headings and titles\n\n**Weight:** 400 (regular)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={400}\n fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 500 (medium)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={500}\n fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 700 (bold)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={700}\n fontFamily=\"Montserrat\"\n/\u003E\n\n**Weight:** 900 (black)\n\n\u003CTypeset\n sampleText=\"Feel like having pizza, sushi or your favourite dish from Tatooine?\"\n fontSizes={[12, 14, 18, 24]}\n fontWeight={900}\n fontFamily=\"Montserrat\"\n/\u003E\n" + } + } +} +``` +
+ +## Debugging + +To help you get a better picture of what is and is not in the manifests, Storybook provides a combined manifest debugger at `http://localhost:6006/manifests/components.html` (your port may vary). This page shows the contents of both the component and docs manifests in a human-readable format, along with any errors or warnings that were encountered during manifest generation. + +![Manifest debugger](../_assets/ai/manifest-debugger.png) + +At the top of the page, you can see any errors or warnings that were encountered during manifest generation. You can click these buttons to filter the manifest to show only the relevant entries, which can be helpful for debugging. + +## Curating + +By default, all stories and independent docs pages have the `manifest` [tag](../writing-stories/tags.mdx) applied, which means they will be included in the manifests. You can curate what is included in the manifests by adding or removing the `manifest` tag from your stories and docs pages. For example, if you have a story that is for instructional purposes only and the agent should not be aware of it, you can remove the `manifest` tag from that story to exclude it from the manifests: + + + +You can also remove an entire component from the manifest by removing the tag in the file's meta (or default export), which will exclude all stories in that file from the manifests. + +Similarly, to exclude an entire MDX docs page from the manifests, you can remove the `manifest` tag from the page's metadata: + +```jsx title="DocForHumansOnly.mdx" +import { Meta } from '@storybook/addon-docs/blocks'; + + +``` + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server overview](./mcp/overview.mdx) +- [MCP server API](./mcp/api.mdx) +- [Sharing your MCP server](./mcp/sharing.mdx) +- [Best practices for using Storybook with AI](./best-practices.mdx) diff --git a/docs/ai/mcp/api.mdx b/docs/ai/mcp/api.mdx new file mode 100644 index 000000000000..7d825cab597a --- /dev/null +++ b/docs/ai/mcp/api.mdx @@ -0,0 +1,78 @@ +--- +title: MCP server API +sidebar: + order: 2 + title: API +--- + + + While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +## `@storybook/addon-mcp` options + +The MCP server addon accepts the following options to configure the tools provided by the MCP server. You can provide these options when registering the addon in your `main.js|ts` file: + + + +### `toolsets` + +Type: + +```ts +{ + dev?: boolean; + docs?: boolean; + test?: boolean; +} +``` + +Default: + +```ts +{ + dev: true, + docs: true, + test: true, +} +``` + +Configuration object to toggle which toolsets are enabled in the MCP server. By default, all toolsets are enabled. + +#### `dev` + +Type: `boolean` + +Default: `true` + +The development toolset includes the [`get-storybook-story-instructions`](./overview.mdx#get-storybook-story-instructions) and [`preview-stories`](./overview.mdx#preview-stories) tools. + +#### `docs` + +Type: `boolean` + +Default: `true` + +The docs toolset includes the [`get-documentation`](./overview.mdx#get-documentation), [`get-documentation-for-story`](./overview.mdx#get-documentation-for-story), and [`list-all-documentation`](./overview.mdx#list-all-documentation) tools. + +#### `test` + +Type: `boolean` + +Default: `true` + +The testing toolset includes the [`run-story-tests`](./overview.mdx#run-story-tests) tool. + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server overview](./overview.mdx) +- [Sharing your MCP server](./sharing.mdx) +- [Best practices for using Storybook with AI](../best-practices.mdx) +- [Manifests](../manifests.mdx) diff --git a/docs/ai/mcp/index.mdx b/docs/ai/mcp/index.mdx new file mode 100644 index 000000000000..94c3fe0347ee --- /dev/null +++ b/docs/ai/mcp/index.mdx @@ -0,0 +1,12 @@ +--- +title: MCP server +hideRendererSelector: true +sidebar: + order: 1 +--- + +Storybook's MCP server connects your Storybook to AI agents, enabling them to understand your components and documentation, generate stories, run tests, and more. It follows the [Model Context Protocol](https://modelcontextprotocol.io/) standard so that any MCP-compatible agent can use it. + +- [**Overview**](./overview.mdx) β€” Learn how the MCP server works, how to install and configure it, and see a walkthrough of a typical workflow. +- [**API**](./api.mdx) β€” Reference documentation for the addon configuration options and MCP server tools. +- [**Sharing**](./sharing.mdx) β€” Publish or self-host your MCP server so your team or community can use it. diff --git a/docs/ai/mcp/overview.mdx b/docs/ai/mcp/overview.mdx new file mode 100644 index 000000000000..dab0b2f8a7a4 --- /dev/null +++ b/docs/ai/mcp/overview.mdx @@ -0,0 +1,175 @@ +--- +title: MCP server +sidebar: + order: 1 + title: Overview +--- + + + While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and MCP server) are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +Storybook's MCP server connects your Storybook to AI agents, allowing them to understand your components and documentation, generate stories, run tests, and more. Agents will be equipped to reuse your existing components and follow your documented usage guidelines when generating UI, helping ensure the generated UI is consistent with your existing design system. Then they can write stories so you can preview the generated UI and automatically run interaction tests (and accessibility checks) on those stories to validate their work. If any issues are found, the agent can fix them and re-run the tests to confirm they are resolved, creating a self-healing loop that helps ensure the quality of the generated UI without requiring you to intervene. + +## Installation + +### 1. Install the addon + +Run this command to install and register the Storybook MCP addon: + + + +Now, when running Storybook's dev server, you can access the MCP server at `http://localhost:6006/mcp` (your port may be different). When viewed in the browser, you'll see a page showing which tools are available and a link to the [manifest debugger](../manifests.mdx#debugging). + +![The MCP server page in the browser](../../_assets/ai/addon-mcp-splash.png) + +### 2. Add the MCP server to your agent + +Then run this command to configure your agent to use the MCP server: + + + +You may need to update the port number in the URL. You will be prompted for a name for your MCP server (e.g. "my-project-sb-mcp"). This is the name you'll use when calling the tools from your agent, so choose something descriptive and unique to avoid confusion with other tools. + +[`mcp-add`](https://github.com/paoloricciuti/mcp-add) is a CLI tool designed to simplify adding MCP servers to various agents. + +You can also follow your agent's documentation to add the MCP server as a tool provider manually, e.g. [Claude Code](https://code.claude.com/docs/en/mcp#option-1-add-a-remote-http-server), [Google Gemini CLI](https://geminicli.com/docs/tools/mcp-server/#adding-an-http-server), [OpenAI Codex](https://developers.openai.com/codex/mcp/), [VS Code Copilot](https://code.visualstudio.com/docs/copilot/customization/mcp-servers#_configure-the-mcpjson-file), etc. + +### 3. Adjust your agent instructions + +To guide your agent to use your MCP server, you should adjust your [`AGENTS.md`](https://agents.md/) (or [`CLAUDE.md`](https://code.claude.com/docs/en/memory#claude-md-files), if you're using Claude). The specifics will depend on your project and how you use agents in your development process, but something like this is a good starting point. Just make sure to replace `your-project-sb-mcp` with the name you chose for your MCP server toolset in the previous step. + +```md title="AGENTS.md" +When working on UI components, always use the `your-project-sb-mcp` MCP tools to access Storybook's component and documentation knowledge before answering or taking any action. + +- **CRITICAL: Never hallucinate component properties!** Before using ANY property on a component from a design system (including common-sounding ones like `shadow`, etc.), you MUST use the MCP tools to check if the property is actually documented for that component. +- Query `list-all-documentation` to get a list of all components +- Query `get-documentation` for that component to see all available properties and examples +- Only use properties that are explicitly documented or shown in example stories +- If a property isn't documented, do not assume properties based on naming conventions or common patterns from other libraries. Check back with the user in these cases. +- Use the `get-storybook-story-instructions` tool to fetch the latest instructions for creating or updating stories. This will ensure you follow current conventions and recommendations. +- Check your work by running `run-story-tests`. + +Remember: A story name might not reflect the property name correctly, so always verify properties through documentation or example stories before using them. +``` + +Finally, test your agent's access to the MCP server. First, make sure your Storybook is running, then run a prompt like "List all documented components". You should see a call to the [`list-all-documentation`](#list-all-documentation) tool with a response listing components from your Storybook. + +## Usage + +Once you have your MCP server and agent configured, using it is as simple as prompting your agent to do some UI development. Let's demonstrate how these toolsets can work together in some typical workflows. + +**1. Generating UI with existing components** + +_Prompt: Build a login form_ + +1. The agent queries the [docs toolset](#docs) to find components that match the requirements of a login form, e.g. a `TextInput` component for the username and password fields, and a `Button` component for the submit button. + +1. The agent queries the [docs toolset](#docs) again to reference more detailed information about specific components, e.g., it learns that the `TextInput` component has a `type` prop that can be set to "password" to obscure the input. + +1. The agent generates a LoginForm component that composes those components together. + +1. The agent uses the [development toolset](#development) to generate stories that render LoginForm in its various states. + +1. The agent uses the [testing toolset](#testing) to run tests on the generated component, and finds that the submit button does not have an accessible level of color contrast. + +1. The agent updates the LoginForm component to use a different color (found by using the [docs toolset](#docs) to reference your documented theme colors) for the submit button. + +1. The agent uses the [testing toolset](#testing) to re-run the tests to confirm that the issue is resolved. +1. The agent uses the [development toolset](#development) to show you previews of each relevant story. + +**2. Previewing work with stories** + +_Prompt: Show me the Button in dark mode_ + +1. The agent uses the [development toolset](#development) to share a preview of or link to the default Button story in dark mode. + +**3. Running tests** + +_Prompt: Run tests for all the stories that contain the Header component_ + +1. Agent uses grep (or "file system lookup") to determine which components use Header. + +1. Agent finds all the stories for those components. + +1. The agent uses the [testing toolset](#testing) to run tests on those stories, and returns a summary of the results. + +**4. Generating tests** + +_Prompt: Write a story to test the login form submit action_ + +1. The agent uses the [development toolset](#development) to generate a story that demonstrates the submit action of the login form, e.g. by writing a [play function](../../writing-tests/interaction-testing.mdx#writing-interaction-tests) to simulate a user filling out the form and clicking the submit button, then asserting that the expected outcome occurs (e.g. a success message appears, the user is redirected, etc.). + +## Toolsets + +The MCP server provides a set of tools that an agent can call to interact with your Storybook. The available tools are organized into three toolsets: development, docs, and testing. Each toolset provides a different set of capabilities for the agent to use when developing UI. + +### Development + +The development toolset provides tools for authoring well-considered stories (including [interaction tests](../../writing-tests/interaction-testing.mdx)) and previewing those stories in the agent's chat interface. This allows you to easily check the agent's work, and the generated stories can serve as tests (which the agent can run, with the [testing toolset](#testing), to validate that the generated UI works as intended). + +The development toolset includes the following tools: + +#### `get-storybook-story-instructions` + +Returns instructions on how to write useful stories, including which props to capture and how to write interaction tests for the story (if applicable). + +#### `preview-stories` + +Returns story previews rendered in the agent's chat interface, if the agent supports [MCP Apps](https://modelcontextprotocol.io/extensions/apps/overview#client-support). Otherwise, it returns links to relevant stories in Storybook. + +### Docs + +The docs toolset provides tools that help the agent reuse components from your Storybook when generating UI. The agent can query the manifests to find components that match the requirements of the UI it's trying to build, and reference your documentation to understand how to use those components correctly. This helps ensure the generated UI is consistent with your existing design system and uses the components you've already built. + +The docs toolset includes the following tools: + +#### `get-documentation` + +Returns the detailed documentation for a specific component, including its props, the first three stories, an index of the remaining stories, and any additional documentation you've provided. + +#### `get-documentation-for-story` + +Returns the full story and associated documentation for a specific story. The agent calls this tool when `get-documentation` doesn't provide enough information for the agent to use a component effectively. + +#### `list-all-documentation` + +Returns an index containing components and unattached docs entries. + +### Testing + +If you have [Storybook Test](../../writing-tests/index.mdx) set up in your Storybook, the testing toolset provides tools that allow the agent to run component tests (including [accessibility checks](../../writing-tests/accessibility-testing.mdx), if set up) and interpret their results. It also includes instructions to resolve issues. As the agent develops, it can choose to run tests to validate its work. If it finds issues, it can fix them and re-run the tests to confirm they are resolved. This creates a _self-healing_ loop that helps ensure the quality of the generated UI, without requiring you to intervene. + +The testing toolset includes the following tool: + +#### `run-story-tests` + +Runs tests for specific stories and returns results, including any accessibility issues (if configured). Also instructs the agent to interpret the results and resolve any issues found. + +## Composition + +If you need to develop UI using components from multiple Storybooks, you can take advantage of [Storybook composition](../../sharing/storybook-composition.mdx). If a composed Storybook has [manifests](../manifests.mdx), the MCP server will automatically include the content from those manifests in its responses, allowing your agent to access the combined knowledge from all composed Storybooks. This means that your agent can find and reference components from any of the composed Storybooks when generating UI. + +## FAQ + +### Which agents are supported? + +We built Storybook's capabilities as an MCP server, which is a standard protocol for AI agent tool providers. Any agent that supports MCP can be connected to Storybook's MCP server, and will be able to use Storybook's manifests and tools. This includes popular agents like [Claude](https://claude.ai/), [Google Gemini](https://gemini.google.dev/), [Microsoft Copilot](https://copilot.microsoft.com/), and many more. + +### Why is the docs toolset React-only? + +The docs toolset relies on the [manifests](../manifests.mdx) generated by Storybook, which is currently limited to React projects. After we ensure a solid experience with React projects, we plan to expand support to the other core Storybook renderers: Vue, Angular, Web Components, and Svelte. + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server API](./api.mdx) +- [Sharing your MCP server](./sharing.mdx) +- [Best practices for using Storybook with AI](../best-practices.mdx) +- [Manifests](../manifests.mdx) diff --git a/docs/ai/mcp/sharing.mdx b/docs/ai/mcp/sharing.mdx new file mode 100644 index 000000000000..0ec12a48d753 --- /dev/null +++ b/docs/ai/mcp/sharing.mdx @@ -0,0 +1,75 @@ +--- +title: Sharing your MCP server +sidebar: + order: 3 + title: Sharing +--- + + + While they are in [preview](../../releases/features.mdx#preview), Storybook's AI capabilities (specifically, the [manifests](../manifests.mdx) and [MCP server](./overview.mdx)) are currently only supported for [React](?renderer=react) projects. + + Additionally, the API may change in future releases. We welcome feedback and contributions to help improve this feature. + + + + +Just as [publishing your Storybook](../../sharing/publish-storybook.mdx) can help your team work more effectively, sharing your MCP server can enable your team to share the benefits of AI-assisted development. + +The MCP server is made of [development](./overview.mdx#development), [docs](./overview.mdx#docs), and [testing](./overview.mdx#testing) toolsets that an agent can call to interact with your Storybook. The development and testing toolsets are only relevant to the locally-running Storybook instance, but the docs toolset can be published and shared so that agents outside of your local environment can access the knowledge from your Storybook's [manifest](../manifests.mdx) to reference your components and documentation when generating UI. + +There are two different ways you can share your MCP server. + +## Automatic publishing with Chromatic + +The easiest way to share your MCP server is to [publish your Storybook with Chromatic](../../sharing/publish-storybook.mdx#publish-storybook-with-chromatic), which will [automatically publish your MCP server](https://chromatic.com/docs/mcp/) as well. If your Storybook is private, your MCP server will be private as well, and only accessible to those you invite to your Chromatic project. If your Storybook is public, your MCP server will be public as well, and accessible to anyone with the URL. + +Once published, you can share the [MCP server URL](https://chromatic.com/docs/mcp/#grab-your-mcp-server-url) with your team or community, and they can configure their agent to use that URL to access it. + +By publishing with Chromatic, you can be sure that your MCP server is always up-to-date with your latest Storybook, it's safeguarded by UI tests, and you don't have to worry about hosting or maintaining it yourself. + +## Self-hosting with `@storybook/mcp` + +If you prefer full control over your MCP server, you can self-host it. This approach allows you to manage the server's infrastructure, security, and updates according to your team's requirements. You will need to ensure your MCP server is accessible to your team or community and properly maintained. + +We provide a package, `@storybook/mcp`, which is a library that creates a [`tmcp`-based](https://github.com/paoloricciuti/tmcp/) MCP server exposing Storybook component/docs knowledge from [manifests](../manifests.mdx). + +### Prerequisites + +- Node.js 20+ +- A [manifest](../manifests.mdx) source containing: + - `components.json` (required) + - `docs.json` (optional) + +### API + +The full API for `@storybook/mcp` is documented in the [package's repository](https://github.com/storybookjs/mcp/tree/main/packages/mcp). + +### Example implementation + +You can reference [self-hosting patterns](https://github.com/storybookjs/mcp/tree/main/apps/self-host-mcp) for both a Node.js process and a Netlify Function. + +This is the minimal implementation of a server using `@storybook/mcp`: + +```ts title="server.ts" +import { createStorybookMcpHandler } from '@storybook/mcp'; + +const storybookMcpHandler = await createStorybookMcpHandler(); + +export async function handleRequest(request: Request): Promise { + if (new URL(request.url).pathname === '/mcp') { + return storybookMcpHandler(request); + } + + return new Response('Not found', { status: 404 }); +} +``` + + +{/* End supported renderers */} + +**More AI resources** + +- [MCP server overview](./overview.mdx) +- [MCP server API](./api.mdx) +- [Best practices for using Storybook with AI](../best-practices.mdx) +- [Manifests](../manifests.mdx) diff --git a/docs/api/index.mdx b/docs/api/index.mdx index 7fcbe13736fe..36be8e4c9114 100644 --- a/docs/api/index.mdx +++ b/docs/api/index.mdx @@ -2,7 +2,7 @@ title: 'API references' hideRendererSelector: true sidebar: - order: 10 + order: 12 title: API --- diff --git a/docs/api/main-config/main-config-features.mdx b/docs/api/main-config/main-config-features.mdx index 270cd3e9f99e..63c0452c95ba 100644 --- a/docs/api/main-config/main-config-features.mdx +++ b/docs/api/main-config/main-config-features.mdx @@ -16,8 +16,10 @@ Type: actions?: boolean; argTypeTargetsV7?: boolean; backgrounds?: boolean; + componentsManifest?: boolean; controls?: boolean; developmentModeForBuild?: boolean; + experimentalCodeExamples?: boolean; experimentalTestSyntax?: boolean; highlight?: boolean; interactions?: boolean; @@ -110,6 +112,20 @@ Type: `boolean` Enable the [Backgrounds](../../essentials/backgrounds.mdx) feature. + + +## `componentsManifest` + +Type: `boolean` + +Default: `true` + +Generate [manifests](../../ai/manifests.mdx), used by the [MCP server](../../ai/mcp/overview.mdx). + + + + + ## `controls` Type: `boolean` @@ -130,6 +146,18 @@ Set `NODE_ENV` to `'development'` in built Storybooks for better testing and deb +## `experimentalCodeExamples` + +(⚠️ **Experimental**) + +Type: `boolean` + +Enable the new code example generation method for React components (as seen in the story previews in an [autodocs](../../writing-docs/autodocs.mdx) page). + +Unlike the current implementation, this method reads the actual stories source file, which is faster to generate, more readable, and more accurate. However, they are not dynamic: they won't update if you change values in the Controls table. + + + ## `experimentalTestSyntax` (⚠️ **Experimental**) diff --git a/docs/builders/index.mdx b/docs/builders/index.mdx index c6bc163b87f0..3f97cce37681 100644 --- a/docs/builders/index.mdx +++ b/docs/builders/index.mdx @@ -2,7 +2,7 @@ title: 'Builders' hideRendererSelector: true sidebar: - order: 9 + order: 11 title: Builders --- diff --git a/docs/configure/index.mdx b/docs/configure/index.mdx index dd3d854afa49..f0904d1190da 100644 --- a/docs/configure/index.mdx +++ b/docs/configure/index.mdx @@ -1,7 +1,7 @@ --- title: 'Configure Storybook' sidebar: - order: 8 + order: 10 title: Configure --- diff --git a/docs/contribute/index.mdx b/docs/contribute/index.mdx index 90a52a10b17f..0b5eaab3e452 100644 --- a/docs/contribute/index.mdx +++ b/docs/contribute/index.mdx @@ -2,7 +2,7 @@ title: 'How to contribute' hideRendererSelector: true sidebar: - order: 12 + order: 14 title: Contribute --- diff --git a/docs/essentials/index.mdx b/docs/essentials/index.mdx index 3d69d7361d6d..2eeddd0c4b1e 100644 --- a/docs/essentials/index.mdx +++ b/docs/essentials/index.mdx @@ -2,7 +2,7 @@ title: Essentials hideRendererSelector: true sidebar: - order: 6 + order: 8 title: Essentials --- diff --git a/docs/faq.mdx b/docs/faq.mdx index f062d5f1878e..1740ffeaac70 100644 --- a/docs/faq.mdx +++ b/docs/faq.mdx @@ -1,7 +1,7 @@ --- title: 'Frequently Asked Questions' sidebar: - order: 13 + order: 15 title: FAQ --- diff --git a/docs/releases/index.mdx b/docs/releases/index.mdx index 8a0bbe8e0c98..646dabc6fd0b 100644 --- a/docs/releases/index.mdx +++ b/docs/releases/index.mdx @@ -1,7 +1,7 @@ --- title: 'How we release Storybook' sidebar: - order: 11 + order: 13 title: Releases --- diff --git a/docs/sharing/index.mdx b/docs/sharing/index.mdx index f5038e03d640..801599b8b470 100644 --- a/docs/sharing/index.mdx +++ b/docs/sharing/index.mdx @@ -2,7 +2,7 @@ title: 'Sharing' hideRendererSelector: true sidebar: - order: 5 + order: 7 title: Sharing --- diff --git a/docs/writing-stories/tags.mdx b/docs/writing-stories/tags.mdx index 810c9bb04b9f..71920ac2cc32 100644 --- a/docs/writing-stories/tags.mdx +++ b/docs/writing-stories/tags.mdx @@ -11,15 +11,16 @@ Tags allow you to control which stories are included in your Storybook, enabling The following tags are available in every Storybook project: -| Tag | AppliedΒ byΒ default? | Description | -| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `dev` | Yes | Stories tagged with `dev` are rendered in Storybook's sidebar. | +| Tag | AppliedΒ byΒ default? | Description | +| ---------- | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `dev` | Yes | Stories tagged with `dev` are rendered in Storybook's sidebar. | +| `manifest` | Yes | Stories and docs tagged with `manifest` are included in the [component or docs manifests](../ai/manifests.mdx) (Currently React-only). | | `test` | Yes | Stories tagged with `test` are included in [test runner](../writing-tests/integrations/test-runner.mdx#run-tests-for-a-subset-of-stories) or [Vitest addon](../writing-tests/integrations/vitest-addon/index.mdx#including-excluding-or-skipping-tests) runs. | -| `autodocs` | No | Stories tagged with `autodocs` are included in the [docs page](../writing-docs/autodocs.mdx). If a CSF file does not contain at least one story tagged with `autodocs`, that component will not generate a docs page. | -| `play-fn` | No | Applied automatically to stories with a [play function](./play-function.mdx) defined. | -| `test-fn` | No | Applied automatically to tests defined using the [experimental `.test` method on CSF Factories](https://github.com/storybookjs/storybook/discussions/30119). | +| `autodocs` | No | Stories tagged with `autodocs` are included in the [docs page](../writing-docs/autodocs.mdx). If a CSF file does not contain at least one story tagged with `autodocs`, that component will not generate a docs page. | +| `play-fn` | No | Applied automatically to stories with a [play function](./play-function.mdx) defined. | +| `test-fn` | No | Applied automatically to tests defined using the [experimental `.test` method on CSF Factories](../api/csf/csf-next.mdx#storytest). | -The `dev` and `test` tags are automatically, implicitly applied to every story in your Storybook project. +The `dev`, `manifest`, and `test` tags are automatically, implicitly applied to every story in your Storybook project. ## Custom tags