Skip to content

chore: Upgrade Storybook and add Storybook MCP addon #987

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
georgewrmarshall merged 5 commits into from
Mar 26, 2026
Merged

chore: Upgrade Storybook and add Storybook MCP addon #987

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
eb9a396
chore: upgrading storybook and adding storybook mcp functionality
georgewrmarshall Mar 19, 2026
6a9e82c
chore: dedupe yarn.lock
georgewrmarshall Mar 19, 2026
ec15f71
Update docs/ai-agents.md
georgewrmarshall Mar 26, 2026
2521e34
chore: adding mcp settings for cursor and vscode
georgewrmarshall Mar 26, 2026
5b1e17d
Merge branch 'main' into storybook-mcp
georgewrmarshall Mar 26, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions .cursor/mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,7 @@
{
"mcpServers": {
"storybook-mcp": {
"url": "http://localhost:6006/mcp"
}
}
}
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Adding mcp config file to .cursor/ this was created using the addon docs https://storybook.js.org/docs/ai/mcp/overview?ref=readme

npx storybook add @storybook/addon-mcp

6 changes: 6 additions & 0 deletions .cursor/rules/component-documentation.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -66,6 +66,10 @@ yarn build-storybook # Build static site

# Test accessibility
yarn test:storybook # Run Storybook accessibility tests

# MCP-assisted Storybook workflows (requires Storybook running)
# MCP endpoint: http://localhost:6006/mcp
# Tools: preview-stories, run-story-tests
```

## Golden Path Examples
Expand Down Expand Up @@ -108,3 +112,5 @@ After adding/updating component documentation, verify:
- [ ] Cross-platform: same prop names and types
- [ ] Storybook builds without errors: `yarn build-storybook`
- [ ] Accessibility tests pass: `yarn test:storybook`
- [ ] If using Storybook MCP workflows, run `run-story-tests` after story/component changes and resolve failures
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

MCP workflows are optional, but when used they should gate the same quality bar as yarn test:storybook—especially story tests and shareable preview URLs for visual review. These items are additive; contributors who do not use MCP can ignore them, while teams using agents get an explicit reminder tied to the Storybook port and tool surface.

- [ ] If using Storybook MCP previews, include `preview-stories` URLs when sharing visual verification
8 changes: 8 additions & 0 deletions .vscode/mcp.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,8 @@
{
"servers": {
"storybook-mcp": {
"type": "http",
"url": "http://localhost:6006/mcp"
}
}
}
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 26, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same as above but for vscode

1 change: 1 addition & 0 deletions .yarnrc.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -27,4 +27,5 @@ npmPreapprovedPackages:
- '@metamask/*'
- '@lavamoat/*'
- '@storybook/*'
- '@chromatic-com/*'
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

The Chromatic integration already uses @chromatic-com/storybook in main.ts; Yarn's minimal-age gate blocks scopes, not just package names. Adding this scope lets legitimate Chromatic packages resolve under the same supply-chain rules as @storybook/* without weakening other namespaces.

- 'storybook'
1 change: 1 addition & 0 deletions apps/storybook-react/.storybook/main.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,7 @@ const config: StorybookConfig = {
getAbsolutePath('@storybook/addon-a11y'),
getAbsolutePath('@storybook/addon-docs'),
getAbsolutePath('@storybook/addon-vitest'),
getAbsolutePath('@storybook/addon-mcp'),
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@storybook/addon-mcp ships as a normal Storybook addon and must appear in addons so the dev server exposes the MCP route documented in the Storybook app README. This sits beside docs, a11y, and Vitest addons—same lifecycle as other dev-only tooling. Storybook 10.3.x aligns peer ranges with the addon; no separate runtime wiring is required beyond this entry.

],
framework: {
name: getAbsolutePath('@storybook/react-vite'),
Expand Down
19 changes: 19 additions & 0 deletions apps/storybook-react/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -23,6 +23,25 @@ For React Native components, please use:
yarn storybook:ios
```

## AI Integration (Storybook MCP)

When Storybook is running locally, an MCP endpoint is available at:

```text
http://localhost:6006/mcp
```

This endpoint helps AI agents work with the design system by exposing:

- `list-all-documentation` to discover documented components and docs entries
- `get-documentation` to retrieve component props, examples, and stories
- `get-documentation-for-story` to inspect a specific story variant
- `get-storybook-story-instructions` for Storybook's built-in story-writing guidance
- `preview-stories` to generate preview URLs for stories
- `run-story-tests` to execute story tests (when supported by the Storybook setup)

Maintainers can use these tools while authoring stories in this repo. Consumer repositories get the most value by connecting their agent clients to this endpoint (local) or a published Storybook MCP endpoint.
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agents and humans need a single, app-local reference for what the endpoint exposes and how it differs from static repo rules. The maintainer vs consumer split clarifies that this repo does not mandate global MCP client config—downstream teams point their own clients at a running Storybook (local or deployed).


## Accessibility Testing

Our Storybook setup includes accessibility testing capabilities. See [Accessibility Testing Documentation](../../docs/accessibility-testing.md).
Expand Down
11 changes: 6 additions & 5 deletions apps/storybook-react/package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17,10 +17,11 @@
"@metamask/design-tokens": "workspace:^",
"@metamask/utils": "^11.10.0",
"@playwright/test": "^1.52.0",
"@storybook/addon-a11y": "^10.2.3",
"@storybook/addon-docs": "^10.2.3",
"@storybook/addon-vitest": "^10.2.3",
"@storybook/react-vite": "^10.2.3",
"@storybook/addon-a11y": "^10.3.1",
"@storybook/addon-docs": "^10.3.1",
"@storybook/addon-mcp": "^0.4.1",
Copy link
Copy Markdown
Contributor Author

@georgewrmarshall georgewrmarshall Mar 24, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Storybook addons and storybook share tight peer dependency ranges; mixing minors commonly breaks installs or runtime peer warnings. @storybook/addon-mcp is pre-1.0 (^0.4.1) and is the only non-10.x Storybook devDependency here expected until the addon stabilizes.

"@storybook/addon-vitest": "^10.3.1",
"@storybook/react-vite": "^10.3.1",
"@testing-library/dom": "^9.0.0",
"@testing-library/react": "^16.0.1",
"@types/prop-types": "^15",
Expand All @@ -36,7 +37,7 @@
"prop-types": "^15.8.1",
"react": "^18.2.0",
"react-dom": "^18.2.0",
"storybook": "^10.2.3",
"storybook": "^10.3.1",
"tailwindcss": "^3.0.0",
"typescript": "~5.2.2",
"vite": "^6.3.6",
Expand Down
15 changes: 15 additions & 0 deletions docs/ai-agents.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -93,6 +93,21 @@ Engineers can reference `.cursor/rules/` directly when needed, but the primary i
- `reviewing-release-prs.md` - Release process
- `package-migration-process-guide.md` - Infrequent migrations

## Storybook MCP as Dynamic Context

The three-layer model provides static guidance (rules, conventions, and process). Storybook MCP adds a dynamic context layer that agents can query at runtime.

### What this adds

- Live component and docs metadata from Storybook manifests
- Story-level examples that reduce prop/API hallucination
- Optional story test execution and preview tooling when addon toolsets are enabled

### Maintainers vs consumers

- **Maintainers (this repo):** Continue using `.cursor/rules/` as the source of truth for conventions. Storybook MCP is a workflow accelerator for story authoring and validation.
- **Consumers (downstream repos):** Storybook MCP provides the highest value. Agents can discover components and props from a running or published Storybook without reading this repo's source.

## How AI Agents Use This

### Cursor
Expand Down
Loading
Loading