MCP Apps support

.changeset/eighty-dryers-yawn.md

@@ -0,0 +1,5 @@
+---
+'@storybook/addon-mcp': patch
+---
+
+Add support for MCP App, rendering stories directly in the agent chat in MCP clients that support it

.claude/settings.local.json

@@ -5,7 +5,7 @@
 			"Bash(git checkout:*)",
 			"Bash(git add:*)",
 			"mcp__storybook-addon-mcp__get-storybook-story-instructions",
-			"mcp__storybook-addon-mcp__get-story-urls"
+			"mcp__storybook-addon-mcp__preview-stories"
 		],
 		"deny": [],
 		"ask": []

.github/copilot-instructions.md

@@ -33,8 +33,8 @@ The addon supports configuring which toolsets are enabled:
     name: '@storybook/addon-mcp',
     options: {
       toolsets: {
-        dev: true,   // get-story-urls, get-storybook-story-instructions
-        docs: true,  // list-all-components, get-component-documentation
+        dev: true,      // preview-stories, get-storybook-story-instructions
+        docs: true,  // list-all-documentation, get-component-documentation
       },
       experimentalFormat: 'markdown'  // Output format: 'markdown' (default) or 'xml'
     }
@@ -171,7 +171,7 @@ import pkgJson from '../package.json' with { type: 'json' };
 
 **Naming:**
 
-- Constants: `SCREAMING_SNAKE_CASE` (e.g., `GET_STORY_URLS_TOOL_NAME`)
+- Constants: `SCREAMING_SNAKE_CASE` (e.g., `PREVIEW_STORIES_TOOL_NAME`)
 - Functions: `camelCase`
 - Types: `PascalCase`
 
@@ -376,3 +376,7 @@ When working on data validation, refer to the following resources:
 
 - https://valibot.dev/
 - https://github.com/paoloricciuti/tmcp/tree/main/packages/adapter-valibot
+
+When working with MCP Apps and/or the `preview-stories.ts` file, refer to the MCP App specification:
+
+- https://raw.githubusercontent.com/modelcontextprotocol/ext-apps/refs/heads/main/specification/draft/apps.mdx

.github/instructions/addon-mcp.instructions.md

@@ -25,7 +25,7 @@ This is a Storybook addon that runs an MCP (Model Context Protocol) server withi
 The addon supports two toolsets that can be enabled/disabled:
 
 1. **`dev`** (default: true)
-   - `get-story-urls`: Retrieve story URLs from Storybook
+   - `preview-stories`: Retrieve story preview URLs from Storybook
    - `get-storybook-story-instructions`: Provide UI development guidelines
 
 2. **`docs`** (default: true)
@@ -80,7 +80,7 @@ src/
   types.ts                         # Valibot schemas and AddonContext type
   ui-building-instructions.md      # Template for agent UI development instructions
   tools/
-    get-story-urls.ts              # Tool to retrieve story URLs from Storybook
+    preview-stories.ts             # Tool to retrieve story preview URLs from Storybook
     get-storybook-story-instructions.ts # Tool to provide UI development guidelines
   utils/
     errors.ts                      # Error handling utilities
@@ -173,7 +173,7 @@ pnpm test:ci       # Run tests with coverage and CI reporters
 
 - **Overall Target**: >70% statement coverage
 - **src/utils**: 100% coverage (errors.ts, fetch-story-index.ts)
-- **src/tools**: >90% coverage (get-story-urls.ts, get-storybook-story-instructions.ts)
+- **src/tools**: >90% coverage (preview-stories.ts, get-storybook-story-instructions.ts)
 - **src**: Integration files (preset.ts, mcp-handler.ts, telemetry.ts) have partial coverage
 
 **Key Testing Patterns:**
@@ -244,8 +244,8 @@ Tests run automatically on PRs and main branch pushes via `.github/workflows/che
 
 ### Naming Conventions
 
-- Constants: SCREAMING_SNAKE_CASE (e.g., `GET_STORY_URLS_TOOL_NAME`)
-- Functions: camelCase (e.g., `addGetStoryUrlsTool`, `createAddonMcpHandler`)
+- Constants: SCREAMING_SNAKE_CASE (e.g., `PREVIEW_STORIES_TOOL_NAME`)
+- Functions: camelCase (e.g., `addPreviewStoriesTool`, `createAddonMcpHandler`)
 - Types/Interfaces: PascalCase (e.g., `AddonContext`, `StoryInput`)
 
 ## Important Files
@@ -263,7 +263,7 @@ Tests run automatically on PRs and main branch pushes via `.github/workflows/che
 - `src/mcp-handler.ts` - Main MCP server handler factory using tmcp
 - `src/telemetry.ts` - Telemetry tracking for usage analytics
 - `src/types.ts` - Valibot schemas and AddonContext interface
-- `src/tools/get-story-urls.ts` - Tool to fetch story URLs from index.json
+- `src/tools/preview-stories.ts` - Tool to preview stories from Storybook
 - `src/tools/get-storybook-story-instructions.ts` - Tool to provide framework-specific UI instructions
 - `src/utils/errors.ts` - Error handling utilities
 - `src/utils/fetch-story-index.ts` - Utility to fetch Storybook's story index
@@ -483,7 +483,7 @@ pnpm test run --coverage  # With coverage report
 
 - `src/utils/errors.test.ts` - Tests error handling utilities
 - `src/utils/fetch-story-index.test.ts` - Tests story index fetching
-- `src/tools/get-story-urls.test.ts` - Tests story URL resolution tool
+- `src/tools/preview-stories.test.ts` - Tests story preview tool
 - `src/tools/get-storybook-story-instructions.test.ts` - Tests UI instructions tool
 - `src/mcp-handler.test.ts` - Tests HTTP conversion utilities
 

.github/instructions/eval.instructions.md

@@ -585,8 +585,7 @@ export default meta;
 type Story = StoryObj<typeof meta>;
 
 export const Default: Story = {
-  play: async ({ canvasElement }) => {
-    const canvas = within(canvasElement);
+  play: async ({ canvas }) => {
     await userEvent.click(canvas.getByTestId('submit'));
     await expect(canvas.getByText('Success')).toBeInTheDocument();
   }

README.md

@@ -150,6 +150,22 @@ pnpm storybook
 
 This will build everything and start up Storybook with addon-mcp, and you can then connect your coding agent to it at `http://localhost:6006/mcp` and try it out.
 
+### Working with the MCP App
+
+To work with and debug the MCP app that is rendered as part of the preview-stories tool, you can:
+
+1. Use the Insiders build of VSCode
+2. Ensure the [chat.mcp.apps.enabled](vscode-insiders://settings/chat.mcp.apps.enabled) setting is enabled
+3. Start up the repo's Storybook in watch mode by running `pnpm storybook` in the root
+4. Restart VSCode and, open the [`.vscode/mcp.json`](./.vscode/mcp.json) file and ensure the Storybook MCP is marked as Running, otherwise click Start.
+5. Open up a chat in VSCode and write a prompt like this:
+
+> Show me how all the button stories look, using the Storybook MCP
+
+6. After this first prompt, whenever you make changes, Storybook automatically restarts. Wait for it to be fully ready, then you can prompt _"Run the tool again"_.
+
+You can also use [the inspector from MCPJam](https://docs.mcpjam.com/getting-started) to have more low level control of the tool calls.
+
 ### Formatting & Linting
 
 ```bash

apps/internal-storybook/.claude/settings.local.json

@@ -1,8 +1,8 @@
 {
 	"permissions": {
 		"allow": [
+			"mcp__storybook-addon-mcp__preview-stories",
 			"mcp__storybook-addon-mcp__get-storybook-story-instructions",
-			"mcp__storybook-addon-mcp__get-story-urls",
 			"mcp__storybook-addon-mcp__list-all-documentation",
 			"mcp__storybook-addon-mcp__get-documentation"
 		]

apps/internal-storybook/.storybook/main.ts

@@ -12,6 +12,7 @@ const config = defineMain({
 	],
 	addons: [
 		'@storybook/addon-docs',
+		'@storybook/addon-themes',
 		{
 			name: '@storybook/addon-mcp',
 			options: {
@@ -23,7 +24,7 @@ const config = defineMain({
 		},
 	],
 	framework: '@storybook/react-vite',
-	logLevel: 'debug',
+	// logLevel: 'debug',
 	core: {
 		disableTelemetry: true,
 	},

apps/internal-storybook/.storybook/preview.ts

@@ -1,4 +1,7 @@
 import type { Preview } from '@storybook/react-vite';
+import { withThemeByDataAttribute } from '@storybook/addon-themes';
+
+import '../stories/theme.css';
 
 const preview: Preview = {
 	parameters: {
@@ -9,8 +12,18 @@ const preview: Preview = {
 			},
 		},
 	},
+	decorators: [
+		withThemeByDataAttribute({
+			themes: {
+				light: 'light',
+				dark: 'dark',
+			},
+			defaultTheme: 'light',
+			attributeName: 'data-theme',
+		}),
+	],
 	initialGlobals: {
-		background: { value: 'light' },
+		theme: 'light',
 	},
 };
 

apps/internal-storybook/package.json

@@ -12,6 +12,7 @@
 	"devDependencies": {
 		"@storybook/addon-docs": "catalog:",
 		"@storybook/addon-mcp": "workspace:*",
+		"@storybook/addon-themes": "^10.2.0",
 		"@storybook/react-vite": "catalog:",
 		"@types/react": "^18.2.65",
 		"@types/react-dom": "^18.2.21",

apps/internal-storybook/stories/components/button.css

@@ -6,15 +6,22 @@
 	cursor: pointer;
 	display: inline-block;
 	line-height: 1;
+	transition:
+		background-color 0.2s ease,
+		color 0.2s ease;
 }
 .storybook-button--primary {
 	color: white;
-	background-color: #1ea7fd;
+	background-color: var(--color-primary, #1ea7fd);
+}
+.storybook-button--primary:hover {
+	background-color: var(--color-primary-hover, #1890d4);
 }
 .storybook-button--secondary {
-	color: #333;
-	background-color: transparent;
-	box-shadow: rgba(0, 0, 0, 0.15) 0px 0px 0px 1px inset;
+	color: var(--color-secondary-text, #333);
+	background-color: var(--color-secondary-bg, transparent);
+	box-shadow: var(--color-secondary-border, rgba(0, 0, 0, 0.15)) 0px 0px 0px 1px
+		inset;
 }
 .storybook-button--small {
 	font-size: 12px;

apps/internal-storybook/stories/components/header.css

@@ -1,32 +1,41 @@
 .wrapper {
 	font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
-	border-bottom: 1px solid rgba(0, 0, 0, 0.1);
+	border-bottom: 1px solid var(--color-border, rgba(0, 0, 0, 0.1));
 	padding: 15px 20px;
 	display: flex;
 	align-items: center;
 	justify-content: space-between;
+	background-color: var(--color-bg, #ffffff);
+	transition:
+		background-color 0.2s ease,
+		border-color 0.2s ease;
 }
 
 svg {
 	display: inline-block;
 	vertical-align: top;
 }
 
+svg g path:first-child {
+	fill: var(--color-logo-bg, #ffffff);
+}
+
 h1 {
 	font-weight: 700;
 	font-size: 20px;
 	line-height: 1;
 	margin: 6px 0 6px 10px;
 	display: inline-block;
 	vertical-align: top;
+	color: var(--color-text, #333);
 }
 
 button + button {
 	margin-left: 10px;
 }
 
 .welcome {
-	color: #333;
+	color: var(--color-text, #333);
 	font-size: 14px;
 	margin-right: 10px;
 }

apps/internal-storybook/stories/components/page.css

@@ -5,7 +5,11 @@ section {
 	padding: 48px 20px;
 	margin: 0 auto;
 	max-width: 600px;
-	color: #333;
+	color: var(--color-text, #333);
+	background-color: var(--color-bg, #ffffff);
+	transition:
+		background-color 0.2s ease,
+		color 0.2s ease;
 }
 
 section h2 {
@@ -15,20 +19,23 @@ section h2 {
 	margin: 0 0 4px;
 	display: inline-block;
 	vertical-align: top;
+	color: var(--color-text, #333);
 }
 
 section p {
 	margin: 1em 0;
+	color: var(--color-text-secondary, #666);
 }
 
 section a {
 	text-decoration: none;
-	color: #1ea7fd;
+	color: var(--color-link, #1ea7fd);
 }
 
 section ul {
 	padding-left: 30px;
 	margin: 1em 0;
+	color: var(--color-text-secondary, #666);
 }
 
 section li {
@@ -41,8 +48,8 @@ section .tip {
 	font-size: 11px;
 	line-height: 12px;
 	font-weight: 700;
-	background: #e7fdd8;
-	color: #66bf3c;
+	background: var(--color-tip-bg, #e7fdd8);
+	color: var(--color-tip-text, #66bf3c);
 	padding: 4px 12px;
 	margin-right: 10px;
 	vertical-align: top;
@@ -53,6 +60,7 @@ section .tip-wrapper {
 	line-height: 20px;
 	margin-top: 40px;
 	margin-bottom: 40px;
+	color: var(--color-text-secondary, #666);
 }
 
 section .tip-wrapper svg {
@@ -65,5 +73,5 @@ section .tip-wrapper svg {
 }
 
 section .tip-wrapper svg path {
-	fill: #1ea7fd;
+	fill: var(--color-link, #1ea7fd);
 }

apps/internal-storybook/stories/other/card/card.css

@@ -1,18 +1,22 @@
 .storybook-card {
 	font-family: 'Nunito Sans', 'Helvetica Neue', Helvetica, Arial, sans-serif;
-	border: 1px solid #e1e5e9;
+	border: 1px solid var(--color-border-strong, #e1e5e9);
 	border-radius: 8px;
 	padding: 16px;
 	max-width: 300px;
-	background-color: white;
-	box-shadow: 0 2px 4px rgba(0, 0, 0, 0.1);
+	background-color: var(--color-bg, white);
+	box-shadow: 0 2px 4px var(--color-card-shadow, rgba(0, 0, 0, 0.1));
+	transition:
+		background-color 0.2s ease,
+		border-color 0.2s ease,
+		box-shadow 0.2s ease;
 }
 
 .storybook-card__title {
 	margin: 0 0 12px 0;
 	font-size: 18px;
 	font-weight: 700;
-	color: #333;
+	color: var(--color-text, #333);
 }
 
 .storybook-card__image {
@@ -27,7 +31,7 @@
 	margin: 0 0 16px 0;
 	font-size: 14px;
 	line-height: 1.5;
-	color: #666;
+	color: var(--color-text-secondary, #666);
 }
 
 .storybook-card__button {
@@ -41,10 +45,10 @@
 	display: inline-block;
 	line-height: 1;
 	color: white;
-	background-color: #1ea7fd;
+	background-color: var(--color-primary, #1ea7fd);
 	transition: background-color 0.2s ease;
 }
 
 .storybook-card__button:hover {
-	background-color: #1890d4;
+	background-color: var(--color-primary-hover, #1890d4);
 }