Storybook MCP - Contributor Guide

1# Storybook MCP - Contributor Guide
2 
3Welcome to the Storybook MCP Addon monorepo! This project enables AI agents to work more efficiently with Storybook by providing an MCP (Model Context Protocol) server that exposes UI component information and development workflows.
4 
5## 📦 Packages
6 
7This monorepo contains two main packages:
8 
9- **[@storybook/mcp](./packages/mcp)** - Standalone MCP library for serving Storybook component knowledge (can be used independently)
10- **[@storybook/addon-mcp](./packages/addon-mcp)** - Storybook addon that runs an MCP server within your Storybook dev server, and includes the functionality of **[@storybook/mcp](./packages/mcp)** from your local Storybook
11 
12Each package has its own README with user-facing documentation. This document is for **contributors** looking to develop, test, or contribute to these packages.
13 
14## 🚀 Quick Start
15 
16### Prerequisites
17 
18- **Node.js 24+** - The project requires Node.js 24 or higher (see `.nvmrc`)
19- **pnpm 10.19.0+** - Strict package manager requirement (enforced in `package.json`)
20 
21```bash
22# Use the correct Node version
23nvm use
24 
25# Install pnpm if you don't have it
26npm install -g pnpm@10.19.0
27```
28 
29### Installation
30 
31```bash
32# Clone the repository
33git clone https://github.com/storybookjs/mcp.git
34cd addon-mcp
35 
36# Install all dependencies (for all packages in the monorepo)
37pnpm install
38```
39 
40### Development Workflow
41 
42```bash
43# Build all packages
44pnpm build
45 
46# Start development mode (watches for changes in all packages)
47pnpm dev
48 
49# Run unit tests in watch mode
50pnpm test
51 
52# Run unit tests once
53pnpm test:run
54 
55# Run Storybook with the addon for testing
56pnpm --filter internal-storybook storybook
57```
58 
59The Storybook command starts:
60 
61- The internal test Storybook instance on `http://localhost:6006`
62- The addon in watch mode, so changes are reflected automatically
63- MCP server available at `http://localhost:6006/mcp`
64 
65## 🛠️ Common Tasks
66 
67### Development
68 
69The `turbo watch build` command runs all packages in watch mode, automatically rebuilding when you make changes:
70 
71```bash
72# Start development mode for all packages
73pnpm turbo watch build
74```
75 
76```bash
77# This is usually all you need - starts Storybook AND watches addon for changes
78pnpm storybook
79```
80 
81### Building
82 
83```bash
84# Build all packages
85pnpm build
86```
87 
88### Testing
89 
90The monorepo uses a centralized Vitest configuration at the root level with projects configured for each package:
91 
92```bash
93# Watch tests across all packages
94pnpm test
95 
96# Run tests once across all packages
97pnpm test:run
98 
99# Run tests with coverage and CI reporters
100pnpm test:ci
101```
102 
103### Debugging MCP Servers
104 
105Use the MCP Inspector to debug and test MCP server functionality:
106 
107```bash
108# Launches the MCP inspector (requires Storybook to be running)
109pnpm inspect
110```
111 
112This uses the configuration in `.mcp.inspect.json` to connect to your local MCP servers.
113 
114Alternatively, you can also use these `curl` comamnds to check that everything works:
115 
116```bash
117# test that the mcp server is running
118# use port 6006 to test the addon-mcp server instead
119curl -X POST \
120  http://localhost:13316/mcp      \
121  -H "Content-Type: application/json" \
122  -d '{
123    "jsonrpc": "2.0",
124    "id": 1,
125    "method": "tools/list",
126    "params": {}
127  }'
128 
129# test a specific tool call
130curl -X POST http://localhost:13316/mcp \
131  -H "Content-Type: application/json" \
132  -d '{
133    "jsonrpc": "2.0",
134    "id": 2,
135    "method": "tools/call",
136    "params": {
137      "name": "list-all-documentation",
138      "arguments": {}
139    }
140  }'
141```
142 
143### Debugging with Storybook
144 
145You can start Storybook with:
146 
147```bash
148pnpm storybook
149```
150 
151This 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.
152 
153### Working with the MCP App
154 
155To work with and debug the MCP app that is rendered as part of the preview-stories tool, you can:
156 
1571. Use the Insiders build of VSCode
1582. Ensure the [chat.mcp.apps.enabled](vscode-insiders://settings/chat.mcp.apps.enabled) setting is enabled
1593. Start up the repo's Storybook in watch mode by running `pnpm storybook` in the root
1604. Restart VSCode and, open the [`.vscode/mcp.json`](./.vscode/mcp.json) file and ensure the Storybook MCP is marked as Running, otherwise click Start.
1615. Open up a chat in VSCode and write a prompt like this:
162 
163> Show me how all the button stories look, using the Storybook MCP
164 
1656. 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"_.
166 
167You can also use [the inspector from MCPJam](https://docs.mcpjam.com/getting-started) to have more low level control of the tool calls.
168 
169### Formatting & Linting
170 
171```bash
172# Format all files with Prettier
173pnpm format
174 
175# Check formatting without changing files
176pnpm format:check
177 
178# Lint code with oxlint
179pnpm lint
180 
181# Lint with GitHub Actions format (for CI)
182pnpm lint:ci
183 
184# Check package exports with publint
185pnpm publint
186```
187 
188## 🔍 Quality Checks
189 
190The monorepo includes several quality checks that run in CI:
191 
192```bash
193# Run all checks (build, test, lint, format, typecheck, publint)
194pnpm check
195 
196# Run checks in watch mode (experimental)
197pnpm check:watch
198 
199# Type checking (uses tsc directly, not turbo)
200pnpm typecheck
201 
202# Type checking with turbo (for individual packages)
203pnpm turbo:typecheck
204 
205# Testing with turbo (for individual packages)
206pnpm turbo:test
207```
208 
209## 📝 Code Conventions
210 
211### TypeScript & Imports
212 
213**Always include file extensions** in relative imports:
214 
215```typescript
216// ✅ Correct
217import { foo } from './bar.ts';
218 
219// ❌ Wrong
220import { foo } from './bar';
221```
222 
223- **JSON imports** use the import attributes syntax:
224 
225```typescript
226import pkg from '../package.json' with { type: 'json' };
227```
228 
229## 🚢 Release Process
230 
231This project uses [Changesets](https://github.com/changesets/changesets) for version management:
232 
233```bash
234# 1. Create a changeset describing your changes
235pnpm changeset
236```
237 
238When you create a PR, add a changeset if your changes should trigger a release:
239 
240- Patch: Bug fixes, documentation updates
241- Minor: New features, backward-compatible changes
242- Major: Breaking changes
243 
244## 🤝 Contributing
245 
246We welcome contributions! Here's how to get started:
247 
2481. **Fork the repository** and create a feature branch
2492. **Make your changes** following the code conventions above
2503. **Test your changes** using the internal Storybook instance
2514. **Create a changeset** if your changes warrant a release
2525. **Submit a pull request** with a clear description
253 
254### Before Submitting
255 
256- [ ] Code builds without errors (`pnpm build`)
257- [ ] Tests pass (`pnpm test:run`)
258- [ ] Code is formatted (`pnpm format`)
259- [ ] Code is linted (`pnpm lint`)
260- [ ] Type checking passes (`pnpm typecheck`)
261- [ ] Changes tested with MCP inspector or internal Storybook
262- [ ] Changeset created if necessary (`pnpm changeset`)
263 
264### Getting Help
265 
266- **Ideas & Feature Requests**: [Start a discussion](https://github.com/storybookjs/mcp/discussions/new?category=ideas)
267- **Bug Reports**: [Open an issue](https://github.com/storybookjs/mcp/issues/new)
268- **Questions**: Ask in [GitHub Discussions](https://github.com/storybookjs/mcp/discussions)
269 
270## 📄 License
271 
272MIT - See [LICENSE](./LICENSE) for details
273 
274---
275 
276**Note**: This project is experimental and under active development. APIs and architecture may change as we explore the best ways to integrate AI agents with Storybook.
277