[yannbf]

Summary

Add a read-only runtime MCP endpoint that lets agents query the application currently open in a browser, and install Storybook MCP in the playgrounds so both can be used together.

• Serve a dedicated MCP endpoint from the app's dev server (/__storybook-devtools/mcp on Vite, Nuxt and Rsbuild; /__devframes/storybook-devtools/mcp on Next). It exposes only the runtime tools, without the hub's terminals, story-writing actions, or shared-state resources.
• Tools: get-app-context (connected pages, mounted components, current selection), inspect-component (live props and matching stories for one instance), get-story-gaps (mounted components without a matching story), and get-component-tree (rendered React hierarchy, parent-first, capped at 500 nodes).
• The endpoint is on by default for local callers with no token. agent: false disables it and agent: { token } requires a matching bearer header. Origin checks apply in every mode.
• The component tree covers React 18/19 on Vite, Rsbuild and Next. Vue and Nuxt return status: "unsupported-framework" rather than an empty tree.
• Add @storybook/addon-mcp to the five playgrounds with a Storybook config, and move Storybook browser tests for React, Vue and Nuxt into separate vitest.config.ts files so the MCP test-run tool finds a test project without starting the app's DevTools plugins.
• Declare @devframes/agentic as a runtime dependency, since the Devframe MCP adapter loads its implementation from it. Production Next routes return 404 without allocating a development sidecar.
• Add .codex/config.toml with a ready-to-use connection to the React demo's runtime MCP and Storybook MCP.

Why

Storybook MCP knows a project's components, stories and docs, but not what is on screen in the running app. Runtime MCP supplies page, instance and selection identity plus current props and real ancestry, so an agent can go from "this button on this page" to its source file, its stories, and the states that have no story yet. It reuses the devtool's existing registry and story index instead of adding a second component catalogue.

Scope

• Supported framework impact considered: React 18/19, Vue, Nuxt, Rsbuild, and Next.js
• Shared E2E helpers and suites reused (e2e/common-agent-suite.ts runs on all six playgrounds)
• First-click dock activation checked through the real UI — no lifecycle changes

Validation

Passed locally:

pnpm install --frozen-lockfile
pnpm build
pnpm test --run
pnpm typecheck
PLAYWRIGHT_PORT_OFFSET=2000 STORYBOOK_E2E_URL=http://localhost:6026 \
  pnpm exec playwright test --workers=2 --reporter=line
PLAYWRIGHT_PORT_OFFSET=2000 STORYBOOK_E2E_URL=http://localhost:6026 \
  pnpm exec playwright test --config=playwright.storybook.config.ts --reporter=line

• 503 unit tests passed.
• 211 Chromium tests passed across all six playgrounds, with no agent option and no MCP Authorization header.
• 6 serial Storybook integration tests passed, including running the generated interaction story through Storybook MCP test-run on React, Vue and Nuxt.
• Protocol tests cover tool schemas, page selection, missing instances, peer timeouts, Origin rejection, and token enforcement when a token is configured.
• Tree unit tests cover fragments, portals, transparent ancestors, text and null output, multiple roots, and truncation. Browser tests verify ancestry, offscreen membership, stable IDs, and modal mount/unmount on the four React hosts.
• On the React demo, a tools/list request without an Authorization header returned all four tools, and opening then closing the modal changed the tree from 26 to 33 and back to 26 nodes with existing IDs unchanged.

Screenshots / Evidence

No visible UI changes.

Documentation

• Updated README, AGENTS, architecture, and supported-framework guidance
• Added docs/AGENT_MVP.md with setup, agent workflow, evidence limits, and validation history

PR Type

• Implementation
• Docs

Notes for Reviewers

• This is an MVP and read-only: it does not create stories, edit props, or expose recordings.
• The endpoint is meant for a local dev server, not a hosted or multi-user service. Vite, Nuxt and Rsbuild also require a loopback socket peer; Next's Fetch route has no socket-peer API and relies on the Origin check unless a token is set.
• The React tree depends on the existing private Fiber integration. The 500-node cap bounds response size, not traversal cost.
• Story matches are candidates: a matching story does not prove that the live prop state is covered.
• Earlier four-worker browser runs failed intermittently with server/connection errors; the cause is not established, and the results above use two workers.
• Local validation used Node 22.21.1 on macOS; CI uses Node 24.

🤖 Generated with Claude Code

[pkg-pr-new]

Open in StackBlitz

npm i https://pkg.pr.new/storybookjs/storybook-devtools/@storybook/experimental-devtools@33

commit: fb82a4f