Merge pull request #33 from storybookjs/proxy-storybook-mcp-tools

Add tools from `@storybook/mcp` to `@storybook/addon-mcp`

Author: JReinhold

.changeset/gold-shirts-repeat.md

@@ -0,0 +1,7 @@
+---
+'@storybook/mcp': patch
+---
+
+Export tools to be merged into other MCP servers.
+
+Currently only [tmcp](https://github.com/paoloricciuti/tmcp)-based MCP servers supports using these tools directly.

.changeset/soft-chairs-push.md

@@ -0,0 +1,11 @@
+---
+'@storybook/addon-mcp': patch
+---
+
+Add tools to get documentation for components, based on the component manifest being generated in the Storybook dev server.
+
+Requirements:
+
+1. That the **experimental** feature flag `features.experimentalComponentsManifest` is set to `true` in the main config.
+2. Only React-based frameworks supports component manifest generation for now.
+3. Requires Storybook v10.1 (prereleases), which at the time of writing is available as a canary version `0.0.0-pr-32810-sha-af0645cd`.

.github/copilot-instructions.md

@@ -5,7 +5,12 @@
 This is a **pnpm monorepo** with two MCP implementations:
 
 - **`packages/addon-mcp`**: Storybook addon using `tmcp`, exposes MCP server at `/mcp` via Vite middleware
+  - Provides addon-specific tools (story URLs, UI building instructions)
+  - **Imports and reuses tools from `@storybook/mcp` package** for component manifest features
+  - Extends `StorybookContext` with addon-specific configuration (`AddonContext`)
 - **`packages/mcp`**: Standalone MCP library using `tmcp`, reusable outside Storybook
+  - Provides reusable component manifest tools (list components, get documentation)
+  - Exports tools and types for consumption by addon-mcp
 - **`apps/internal-storybook`**: Test environment for addon integration
 
 **Both packages use `tmcp`** with HTTP transport and Valibot schema validation for consistent APIs.
@@ -25,6 +30,7 @@ The `@storybook/mcp` package (in `packages/mcp`) is framework-agnostic:
 - Uses `tmcp` with HTTP transport and Valibot schema validation
 - Factory pattern: `createStorybookMcpHandler()` returns a request handler
 - Context-based: handlers accept `StorybookContext` to override source URLs
+- **Exports tools and types** for reuse by `addon-mcp` and other consumers
 
 ## Development Environment
 
@@ -95,6 +101,8 @@ import pkgJson from '../package.json' with { type: 'json' };
 
 ### In addon package (`packages/addon-mcp`):
 
+**Option 1: Addon-specific tools** (for tools that require Storybook addon context):
+
 1. Create `src/tools/my-tool.ts`:
 
 ```typescript
@@ -104,8 +112,8 @@ import type { AddonContext } from '../types.ts';
 
 export const MY_TOOL_NAME = 'my_tool';
 
-const MyToolInput = v.object({ 
-	param: v.string() 
+const MyToolInput = v.object({
+	param: v.string(),
 });
 
 type MyToolInput = v.InferOutput<typeof MyToolInput>;
@@ -128,30 +136,65 @@ export async function addMyTool(server: McpServer<any, AddonContext>) {
 }
 ```
 
-2. Import and call in `src/mcp-handler.ts` within `createAddonMcpHandler`
+2. Import and call in `src/mcp-handler.ts` within `initializeMCPServer`
+
+**Option 2: Reuse tools from `@storybook/mcp`** (for component manifest features):
+
+1. Import the tool from `@storybook/mcp` in `src/mcp-handler.ts`:
+
+```typescript
+import { addMyTool, MY_TOOL_NAME } from '@storybook/mcp';
+```
+
+2. Call it conditionally based on feature flags (see component manifest tools example)
+3. Ensure `AddonContext` extends `StorybookContext` for compatibility
+4. Pass the `source` URL in context for manifest-based tools
 
 ### In mcp package (`packages/mcp`):
 
 1. Create `src/tools/my-tool.ts`:
 
 ```typescript
+export const MY_TOOL_NAME = 'my-tool';
+
 export async function addMyTool(server: McpServer<any, StorybookContext>) {
-	server.tool({ name: 'my_tool', description: 'What it does' }, async () => ({
-		content: [{ type: 'text', text: 'result' }],
-	}));
+	server.tool(
+		{ name: MY_TOOL_NAME, description: 'What it does' },
+		async () => ({
+			content: [{ type: 'text', text: 'result' }],
+		}),
+	);
 }
 ```
 
 2. Import and call in `src/index.ts` within `createStorybookMcpHandler`
 
+3. **Export for reuse** in `src/index.ts`:
+
+```typescript
+export { addMyTool, MY_TOOL_NAME } from './tools/my-tool.ts';
+```
+
 ## Integration Points
 
+**Tool Reuse Between Packages:**
+
+- `addon-mcp` depends on `@storybook/mcp` (workspace dependency)
+- `AddonContext` extends `StorybookContext` to ensure type compatibility
+- Component manifest tools are conditionally registered based on feature flags:
+  - Checks `features.experimentalComponentsManifest` flag
+  - Checks for `experimental_componentManifestGenerator` preset
+  - Only registers `addListAllComponentsTool` and `addGetComponentDocumentationTool` when enabled
+- Context includes `source` URL pointing to `/manifests/components.json` endpoint
+
 **Storybook internals used:**
 
 - `storybook/internal/csf` - `storyNameFromExport()` for story name conversion
 - `storybook/internal/types` - TypeScript types for Options, StoryIndex
 - `storybook/internal/node-logger` - Logging utilities
 - Framework detection via `options.presets.apply('framework')`
+- Feature flags via `options.presets.apply('features')`
+- Component manifest generator via `options.presets.apply('experimental_componentManifestGenerator')`
 
 **Story URL generation:**
 

.github/workflows/check.yml

@@ -69,6 +69,9 @@ jobs:
       - name: Setup Node.js and Install Dependencies
         uses: ./.github/actions/setup-node-and-install
 
+      - name: Build @storybook/mcp (dependency)
+        run: pnpm build --filter @storybook/mcp
+
       - name: Run tests
         run: pnpm --filter @storybook/addon-mcp test -- run
 
@@ -95,6 +98,9 @@ jobs:
       - name: Setup Node.js and Install Dependencies
         uses: ./.github/actions/setup-node-and-install
 
+      - name: Build @storybook/mcp (dependency)
+        run: pnpm build --filter @storybook/mcp
+
       - name: Run type checking
         run: pnpm --filter @storybook/addon-mcp typecheck
 

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

@@ -1,12 +1,11 @@
 {
-  "permissions": {
-    "allow": [
-      "mcp__storybook-addon-mcp__get-ui-building-instructions",
-      "mcp__storybook-addon-mcp__get-story-urls"
-    ]
-  },
-  "enabledMcpjsonServers": [
-    "storybook-addon-mcp",
-    "storybook-mcp"
-  ]
+	"permissions": {
+		"allow": [
+			"mcp__storybook-addon-mcp__get-ui-building-instructions",
+			"mcp__storybook-addon-mcp__get-story-urls",
+			"mcp__storybook-addon-mcp__list-all-components",
+			"mcp__storybook-addon-mcp__get-component-documentation"
+		]
+	},
+	"enabledMcpjsonServers": ["storybook-addon-mcp", "storybook-mcp"]
 }

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

@@ -16,6 +16,9 @@ const config = defineMain({
 	core: {
 		disableTelemetry: true,
 	},
+	features: {
+		experimentalComponentsManifest: true,
+	},
 });
 
 export default config;

apps/internal-storybook/package.json

@@ -9,14 +9,14 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"devDependencies": {
-		"@storybook/addon-docs": "^10.0.0-0",
+		"@storybook/addon-docs": "0.0.0-pr-32810-sha-af0645cd",
 		"@storybook/addon-mcp": "workspace:*",
-		"@storybook/react-vite": "^10.0.0-0",
+		"@storybook/react-vite": "0.0.0-pr-32810-sha-af0645cd",
 		"@types/react": "^18.2.65",
 		"@types/react-dom": "^18.2.21",
 		"@vitejs/plugin-react": "^4.7.0",
 		"react": "^18.2.0",
 		"react-dom": "^18.2.0",
-		"storybook": "^10.0.0-0"
+		"storybook": "0.0.0-pr-32810-sha-af0645cd"
 	}
 }

apps/internal-storybook/stories/components/Button.tsx

@@ -26,6 +26,9 @@ interface ButtonProps {
 
 /**
  * Primary UI component for user interaction
+ *
+ * @import import { Button } from '@my-org/my-component-library';
+ * @summary A customizable button component for user interactions.
  */
 export const Button = ({
 	primary = false,

packages/addon-mcp/package.json

@@ -34,6 +34,7 @@
 		"typecheck": "tsc --noEmit"
 	},
 	"dependencies": {
+		"@storybook/mcp": "workspace:*",
 		"@tmcp/adapter-valibot": "catalog:",
 		"@tmcp/transport-http": "catalog:",
 		"tmcp": "catalog:",