chore: Upgrade Storybook and add Storybook MCP addon by georgewrmarshall · Pull Request #987 · MetaMask/metamask-design-system

georgewrmarshall · 2026-03-19T21:03:47Z

Description

This change upgrades React web Storybook from 10.2.3 to 10.3.1 and adds the official @storybook/addon-mcp so agents can use Storybook as dynamic context while authoring or consuming the design system.

https://storybook.js.org/ai

Why

Storybook MCP exposes documentation, story metadata, preview URLs, and (where supported) story tests over an HTTP endpoint, which reduces prop/API hallucination and speeds up AI-assisted workflows.
The 10.3.x line aligns peer dependencies for the new addon and related transitive updates in the lockfile.

What

Register @storybook/addon-mcp in apps/storybook-react/.storybook/main.ts.
Bump Storybook packages in apps/storybook-react/package.json and refresh yarn.lock.
Allow @chromatic-com/* in npmPreapprovedPackages (.yarnrc.yml) for approved dependency resolution.
Document the MCP endpoint (http://localhost:6006/mcp), available tools, and maintainer vs consumer guidance in apps/storybook-react/README.md and docs/ai-agents.md.
Extend .cursor/rules/component-documentation.md with MCP workflow notes and checklist items.

Related issues

Fixes:

Manual testing steps

From the repo root, run yarn install (if needed).
Run yarn storybook and confirm Storybook starts without errors.
Open the running dev URL (default port 6006) and spot-check a few stories.
Optionally verify the MCP endpoint is reachable at http://localhost:6006/mcp while Storybook is running (per apps/storybook-react/README.md).

Screenshots/Recordings

Before

N/A

After

N/A

Pre-merge author checklist

I've followed MetaMask Contributor Docs
I've completed the PR template to the best of my ability
I’ve included tests if applicable
I’ve documented my code using JSDoc format if applicable
I’ve applied the right labels on the PR (see labeling guidelines). Not required for external contributors.

Pre-merge reviewer checklist

I've manually tested the PR (e.g. pull and build branch, run the app, test code being changed).
I confirm that this PR addresses all acceptance criteria described in the ticket it closes and includes the necessary testing evidence such as recordings and or screenshots.

Note

Medium Risk
Moderate risk due to a Storybook minor-version upgrade plus introduction of the @storybook/addon-mcp server endpoint and new transitive dependencies, which could affect local Storybook build/runtime behavior.

Overview
Upgrades the React web Storybook stack from 10.2.3 to 10.3.1 and updates the lockfile accordingly.

Enables Storybook MCP by adding @storybook/addon-mcp to the Storybook addons list, and documents the local MCP endpoint (http://localhost:6006/mcp) plus recommended preview-stories/run-story-tests workflows in Storybook and contributor docs.

Relaxes the Yarn minimal-age gate allowlist to include @chromatic-com/* for dependency resolution.

^{Written by Cursor Bugbot for commit 6a9e82c. This will update automatically on new commits. Configure here.}

socket-security · 2026-03-19T21:04:49Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Package	Supply Chain Security	Vulnerability	Quality	Maintenance
@storybook/react-vite@10.2.3 ⏵ 10.3.1
@storybook/addon-mcp@0.4.1
@storybook/addon-vitest@10.2.3 ⏵ 10.3.1			⁺¹
@storybook/addon-a11y@10.2.3 ⏵ 10.3.1	⁺¹		⁺¹
storybook@10.2.3 ⏵ 10.3.1	⁺¹	⁺¹⁶	⁺¹	⁺¹
@testing-library/jest-dom@6.6.3 ⏵ 6.9.1
@storybook/addon-docs@10.2.3 ⏵ 10.3.1	⁺¹

View full report

socket-security · 2026-03-19T21:04:50Z

All alerts resolved. Learn more about Socket for GitHub.

This PR previously contained dependency changes with security issues that have been resolved, removed, or ignored.

Ignoring alerts on:

glob@13.0.6

View full report

github-actions · 2026-03-19T21:05:39Z

📖 Storybook Preview

View PR Storybook

Made-with: Cursor

github-actions · 2026-03-19T23:17:48Z

📖 Storybook Preview

View PR Storybook

georgewrmarshall · 2026-03-20T01:01:35Z

docs/ai-agents.md

+### Documentation ownership
+
+- Keep maintainers' standards in `.cursor/rules/` and contributor docs.
+- Keep Storybook MCP setup and endpoint usage in Storybook app docs (for example, `apps/storybook-react/README.md`).
+- Do not require repository-global MCP client config in this repo; consumers should configure their own agent clients.


Not sure if we need this section?

Suggested change

### Documentation ownership

- Keep maintainers' standards in `.cursor/rules/` and contributor docs.

- Keep Storybook MCP setup and endpoint usage in Storybook app docs (for example, `apps/storybook-react/README.md`).

- Do not require repository-global MCP client config in this repo; consumers should configure their own agent clients.

georgewrmarshall · 2026-03-24T21:19:39Z

@SocketSecurity ignore npm/glob@13.0.6

Socket Security review: `npm/glob@13.0.6` (#987 (comment))

Dependency path: transitive via @storybook/react-vite@10.3.1 → glob@13.0.6 (introduced by the Storybook upgrade in this PR, not a direct dependency we can swap without upstream changes).

“Network access” / globalThis["fetch"]: glob is the standard, npm-maintained filesystem glob implementation. Static analysis that flags any reference to fetch on globalThis does not, by itself, mean the package performs outbound network calls in normal Node/Storybook usage. In practice this pattern is often optional-environment detection (e.g. availability of fetch in newer runtimes) or bundler-related surface area, not intentional remote I/O for this library’s core job (local path matching).

Risk scope: This chain is dev-only (Storybook / Vite tooling for @metamask/storybook-react). It is not part of the published design-system packages consumers ship to wallets.

AI anomaly alert: Socket’s own notes on the low-severity alert describe conventional glob-walking logic with no indication of malicious behavior or exfiltration; residual risk is framed around how callers use emitted paths, not the library acting as a supply-chain backdoor.

Conclusion: Acceptable risk for this PR: trusted maintainer ecosystem package, dev-tooling-only exposure, and alert characteristics consistent with static over-approximation plus a benign code-path signal—not a reviewed finding of malicious network use.

georgewrmarshall · 2026-03-24T21:21:44Z

apps/storybook-react/.storybook/main.ts

    getAbsolutePath('@storybook/addon-a11y'),
    getAbsolutePath('@storybook/addon-docs'),
    getAbsolutePath('@storybook/addon-vitest'),
+    getAbsolutePath('@storybook/addon-mcp'),


Why register MCP here? @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.

Reviewer note: 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.

georgewrmarshall · 2026-03-24T21:21:45Z

.yarnrc.yml

  - '@metamask/*'
  - '@lavamoat/*'
  - '@storybook/*'
+  - '@chromatic-com/*'


Why pre-approve @chromatic-com/*? The Chromatic integration already uses @chromatic-com/storybook in main.ts; Yarn's minimal-age gate blocks scopes, not just package names.

Reviewer note: Adding this scope lets legitimate Chromatic packages resolve under the same supply-chain rules as @storybook/* without weakening other namespaces.

georgewrmarshall · 2026-03-24T21:21:47Z

apps/storybook-react/package.json

-    "@storybook/react-vite": "^10.2.3",
+    "@storybook/addon-a11y": "^10.3.1",
+    "@storybook/addon-docs": "^10.3.1",
+    "@storybook/addon-mcp": "^0.4.1",


Why pin every Storybook package to ^10.3.1? Storybook addons and storybook share tight peer dependency ranges; mixing minors commonly breaks installs or runtime peer warnings.

Reviewer note: @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.

georgewrmarshall · 2026-03-24T21:21:52Z

apps/storybook-react/README.md

+- `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.


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).

georgewrmarshall · 2026-03-24T21:21:54Z

docs/ai-agents.md

+### Documentation ownership
+
+- Keep maintainers' standards in `.cursor/rules/` and contributor docs.
+- Keep Storybook MCP setup and endpoint usage in Storybook app docs (for example, `apps/storybook-react/README.md`).


Why add a whole section to ai-agents.md? The three-layer doc model stays canonical for how we write code; Storybook MCP is an optional runtime context source on top of .cursor/rules/.

Reviewer note: Explicit documentation ownership avoids duplicating MCP setup in every rule file and sets the expectation that consumers configure their own agent clients rather than checking shared IDE config into this monorepo.

georgewrmarshall · 2026-03-24T21:21:55Z

.cursor/rules/component-documentation.md

 - [ ] 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


Why extend the component-doc checklist? 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.

Reviewer note: 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.

chore: upgrading storybook and adding storybook mcp functionality

eb9a396

chore: dedupe yarn.lock

6a9e82c

Made-with: Cursor

georgewrmarshall self-assigned this Mar 20, 2026

georgewrmarshall commented Mar 20, 2026

View reviewed changes

georgewrmarshall commented Mar 24, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

chore: Upgrade Storybook and add Storybook MCP addon#987

chore: Upgrade Storybook and add Storybook MCP addon#987
georgewrmarshall wants to merge 2 commits intomainfrom
storybook-mcp

georgewrmarshall commented Mar 19, 2026 •

edited

Loading

Uh oh!

socket-security bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

socket-security bot commented Mar 19, 2026 •

edited

Loading

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

github-actions bot commented Mar 19, 2026

Uh oh!

georgewrmarshall Mar 20, 2026

Uh oh!

georgewrmarshall commented Mar 24, 2026 •

edited

Loading

Uh oh!

georgewrmarshall Mar 24, 2026

Uh oh!

georgewrmarshall Mar 24, 2026

Uh oh!

georgewrmarshall Mar 24, 2026

Uh oh!

georgewrmarshall Mar 24, 2026 •

edited

Loading

Uh oh!

georgewrmarshall Mar 24, 2026

Uh oh!

georgewrmarshall Mar 24, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

georgewrmarshall commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Related issues

Manual testing steps

Screenshots/Recordings

Before

After

Pre-merge author checklist

Pre-merge reviewer checklist

Uh oh!

socket-security bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

socket-security bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot commented Mar 19, 2026

📖 Storybook Preview

Uh oh!

github-actions bot commented Mar 19, 2026

📖 Storybook Preview

Uh oh!

georgewrmarshall Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall commented Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Socket Security review: npm/glob@13.0.6 (#987 (comment))

Uh oh!

georgewrmarshall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 24, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

georgewrmarshall Mar 24, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

georgewrmarshall commented Mar 19, 2026 •

edited

Loading

socket-security bot commented Mar 19, 2026 •

edited

Loading

socket-security bot commented Mar 19, 2026 •

edited

Loading

georgewrmarshall commented Mar 24, 2026 •

edited

Loading

Socket Security review: `npm/glob@13.0.6` (#987 (comment))

georgewrmarshall Mar 24, 2026 •

edited

Loading