Add support for using story ID as input for preview and test tools by JReinhold · Pull Request #175 · storybookjs/mcp

JReinhold · 2026-02-25T10:03:11Z

This pull request introduces story ID-based inputs to the preview and testing tools, making it easier for agents and tools to reference stories directly.

Added story ID-based input shapes for preview-stories and run-story-tests, while retaining path-based story inputs.
Included story IDs in documentation outputs (list-all-documentation and get-documentation), allowing agents to discover and reuse IDs without extra filesystem lookup steps.
New evaluation tasks are added to ensure agents use the most context-appropriate input strategy.

Previously, we saw numerous times that the agent would use the docs tools to get information about a component, then traverse the file system to find the story files so it could get story IDs for previewing/testing stories. That was inefficient. Now story IDs can be used directly, so if the agent doesn't have the file already in context, it will use the docs tool to get the IDs, and then preview/test stories.
In situations where it already has the file in context, it will still used the path-based inputs.

Evals shows that this is both faster and cheaper (in the minimal scenario).

…as an alternative to story paths

changeset-bot · 2026-02-25T10:03:19Z

🦋 Changeset detected

Latest commit: b8bf0a1

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 2 packages

Name	Type
@storybook/mcp	Patch
@storybook/addon-mcp	Patch

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

pkg-pr-new · 2026-02-25T10:03:46Z

npm i https://pkg.pr.new/storybookjs/mcp/@storybook/addon-mcp@175

npm i https://pkg.pr.new/storybookjs/mcp/@storybook/mcp@175

commit: b8bf0a1

Copilot

Pull request overview

This PR extends the Storybook MCP addon + MCP library to support story ID–based workflows (storyId) alongside the existing path/export-based story addressing, and surfaces story IDs in documentation output to enable that flow end-to-end.

Changes:

Add { storyId } as an alternative StoryInput shape and wire it into preview-stories and run-story-tests via shared ID resolution logic.
Enhance docs output/formatters to include story IDs (plus withStoryIds option for list-all-documentation).
Add/adjust unit + E2E coverage and introduce eval tasks (914/915) to validate strategy selection (path-based vs docs-first ID flow).

Reviewed changes

Copilot reviewed 37 out of 37 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/mcp/src/utils/manifest-formatter/markdown.ts	Surfaces story IDs in component markdown and adds optional story ID sub-bullets for list formatting.
packages/mcp/src/utils/manifest-formatter/markdown.test.ts	Updates/extends formatter tests to assert story ID rendering and list sub-bullets.
packages/mcp/src/utils/manifest-formatter/snapshots/markdown.test.ts.snap	Snapshot updates reflecting story ID lines and story ID-labeled “Other Stories”.
packages/mcp/src/tools/list-all-documentation.ts	Adds `withStoryIds` input and passes list-format options through.
packages/mcp/src/tools/list-all-documentation.test.ts	Adds test coverage for `withStoryIds: true` behavior.
packages/mcp/src/tools/get-documentation.ts	Updates tool description to clarify story IDs are included.
packages/mcp/src/tools/get-documentation.test.ts	Updates expectations to include “Story ID:” lines.
packages/mcp/fixtures/small-manifest.fixture.json	Adds `id` fields to fixture stories to support story ID output/tests.
packages/addon-mcp/src/utils/find-story-ids.ts	Adds `{ storyId }` resolution path and normalizes importPath matching for path-based inputs.
packages/addon-mcp/src/utils/find-story-ids.test.ts	Adds tests for storyId lookup + adjusts typing assertions.
packages/addon-mcp/src/types.ts	Refactors `StoryInput` to a union of path-based and `storyId` shapes (shared props/globals).
packages/addon-mcp/src/tools/run-story-tests.ts	Updates schema descriptions to document when to prefer `storyId` vs path-based input.
packages/addon-mcp/src/tools/run-story-tests.test.ts	Adds focused test run coverage using `{ storyId }` inputs.
packages/addon-mcp/src/tools/preview-stories.ts	Switches to shared `findStoryIds` to support `{ storyId }` inputs in preview URLs.
packages/addon-mcp/src/tools/preview-stories.test.ts	Adds preview coverage for `{ storyId }` input shape.
packages/addon-mcp/README.md	Documents both path-based and ID-based inputs and `withStoryIds` usage guidance.
eval/variant-configs/preview-by-id-internal.ts	Adds internal eval variant matrix covering tasks 914–915.
eval/templates/grading/.storybook/main.ts	Enables `experimentalComponentsManifest` for grading template runs.
eval/tasks/915-preview-story-by-id/prompt.md	New eval prompt for previewing existing stories (docs-first ID flow).
eval/tasks/915-preview-story-by-id/prompt.docs-first.md	Prompt variant that explicitly forces docs-first behavior.
eval/tasks/915-preview-story-by-id/post-prepare-trial/stories/Button.stories.tsx	Trial fixture story file for task 915.
eval/tasks/915-preview-story-by-id/post-prepare-trial/src/components/Button.tsx	Trial fixture component for task 915.
eval/tasks/915-preview-story-by-id/post-prepare-trial/.storybook/preview.tsx	Trial fixture Storybook preview config for task 915.
eval/tasks/915-preview-story-by-id/hooks.ts	Adds quality hooks asserting `storyId` input strategy usage.
eval/tasks/915-preview-story-by-id/config.json	Defines expected MCP tool calls, including `withStoryIds: true`.
eval/tasks/915-preview-story-by-id/README.md	Documents purpose + scoring for task 915.
eval/tasks/914-preview-story-by-path/prompt.md	New eval prompt to write a story then preview via path-based inputs.
eval/tasks/914-preview-story-by-path/post-prepare-trial/stories/Button.stories.tsx	Trial fixture story file for task 914.
eval/tasks/914-preview-story-by-path/post-prepare-trial/src/components/Button.tsx	Trial fixture component for task 914.
eval/tasks/914-preview-story-by-path/post-prepare-trial/.storybook/preview.tsx	Trial fixture Storybook preview config for task 914.
eval/tasks/914-preview-story-by-path/hooks.ts	Adds quality hooks asserting path-based preview inputs and avoiding unnecessary docs calls.
eval/tasks/914-preview-story-by-path/config.json	Defines expected MCP tool calls for task 914.
eval/tasks/914-preview-story-by-path/README.md	Documents purpose + scoring for task 914.
apps/internal-storybook/tests/mcp-endpoint.e2e.test.ts	Updates tool JSON-schema snapshots for new input shapes/options and updated descriptions.
apps/internal-storybook/tests/mcp-composition.e2e.test.ts	Updates composition expectations to include story IDs in docs output.
apps/internal-storybook/tests/mcp-composition-auth.e2e.test.ts	Updates auth composition expectations to include story IDs in docs output.
.changeset/smart-clouds-glow.md	Changeset entry for patch releases of `@storybook/mcp` and `@storybook/addon-mcp`.

codecov · 2026-02-25T10:54:58Z

Bundle Report

Changes will decrease total bundle size by 58.52kB (-54.99%) ⬇️. This is within the configured threshold ✅

Detailed changes

Bundle name	Size	Change
@storybook/mcp-esm	42.85kB	730 bytes (1.73%) ⬆️
@storybook/addon-mcp-esm	5.05kB	-59.25kB (-92.14%) ⬇️

Affected Assets, Files, and Routes:

view changes for bundle: @storybook/addon-mcp-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
*`preview-.js`** (New)	5.05kB	5.05kB	100.0% 🚀
~~`preset.js`~~ (Deleted)	-64.3kB	0 bytes	-100.0% 🗑️

view changes for bundle: @storybook/mcp-esm

Assets Changed:

Asset Name	Size Change	Total Size	Change (%)
`index.js`	730 bytes	29.9kB	2.5%

Files in index.js:

./src/types.ts → Total Size: 1.78kB

JReinhold · 2026-02-25T14:33:58Z

I've changed the findStoryIds function to return an array instead of an object, so that tools can maintain the same input->output order of the results, even when there are mixed found/not-found cases.

codecov · 2026-02-25T14:35:12Z

❌ 1 Tests Failed:

Tests completed	Failed	Passed	Skipped
436	1	435	0

View the full list of 1 ❄️ flaky test(s)

apps/internal-storybook/tests/check-deps.e2e.test.ts > Storybook Dependencies > should be using latest versions from registry

Flake rate in main: 27.27% (Passed 40 times, Failed 15 times)

Stack Traces | 4.61s run time

Error: Storybook dependencies are outdated. Update the catalog in pnpm-workspace.yaml:

  sed -i '' 's/10\.3\.0-alpha\.11/10.3.0-alpha.12/g' pnpm-workspace.yaml && pnpm install

Outdated packages:
  - @storybook/addon-docs: 10.3.0-alpha.11 → 10.3.0-alpha.12
  - @storybook/react-vite: 10.3.0-alpha.11 → 10.3.0-alpha.12
  - storybook: 10.3.0-alpha.11 → 10.3.0-alpha.12
 ❯ tests/check-deps.e2e.test.ts:42:10

To view more test analytics, go to the Test Analytics Dashboard
_{📋 Got 3 mins? Take this short survey to help us improve Test Analytics.}

…nto id-story-input

Copilot

Pull request overview

Copilot reviewed 38 out of 41 changed files in this pull request and generated 2 comments.

Files not reviewed (3)

apps/internal-storybook/pnpm-lock.yaml: Language not supported
eval/pnpm-lock.yaml: Language not supported
packages/addon-mcp/pnpm-lock.yaml: Language not supported

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 38 out of 41 changed files in this pull request and generated no new comments.

Files not reviewed (3)

apps/internal-storybook/pnpm-lock.yaml: Language not supported
eval/pnpm-lock.yaml: Language not supported
packages/addon-mcp/pnpm-lock.yaml: Language not supported

kasperpeulen

LGTM

add support for using story ids as input for preview and test tools, …

6a098f9

…as an alternative to story paths

JReinhold requested a review from Copilot February 25, 2026 10:06

Copilot started reviewing on behalf of JReinhold February 25, 2026 10:07 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Comment thread packages/addon-mcp/src/utils/find-story-ids.ts Outdated

Comment thread packages/addon-mcp/src/tools/preview-stories.ts Outdated

JReinhold and others added 5 commits February 25, 2026 13:53

maintain input order to test and preview story tools

bc07615

update tests

5ed0b1f

update storybook deps

312ca59

update eval tasks

a1a582e

Merge branch 'main' into id-story-input

18157ee

JReinhold commented Feb 25, 2026

View reviewed changes

JReinhold added 2 commits February 25, 2026 15:39

cleanup

7cb0b5d

Merge branch 'id-story-input' of https://github.com/storybookjs/mcp i…

e9da8a6

…nto id-story-input

JReinhold marked this pull request as ready for review February 25, 2026 14:39

Copilot AI review requested due to automatic review settings February 25, 2026 14:39

Copilot started reviewing on behalf of JReinhold February 25, 2026 14:39 View session

upgrade storybook

ddbdcbb

JReinhold requested a review from kasperpeulen February 25, 2026 14:41

Copilot AI reviewed Feb 25, 2026

View reviewed changes

Comment thread packages/addon-mcp/src/tools/preview-stories.test.ts

Comment thread eval/tasks/915-preview-story-by-id/README.md Outdated

Update eval/tasks/915-preview-story-by-id/README.md

90ea24d

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings February 25, 2026 21:06

Copilot started reviewing on behalf of JReinhold February 25, 2026 21:06 View session

Copilot AI reviewed Feb 25, 2026

View reviewed changes

kasperpeulen approved these changes Feb 26, 2026

View reviewed changes

JReinhold changed the title ~~Add support for using story iID as input for preview and test tools~~ Add support for using story ID as input for preview and test tools Feb 26, 2026

add more tests

b8bf0a1

JReinhold merged commit 94bb1c2 into main Feb 26, 2026
9 of 10 checks passed

JReinhold deleted the id-story-input branch February 26, 2026 12:48

storybook-app-bot bot mentioned this pull request Feb 26, 2026

Version Packages #174

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add support for using story ID as input for preview and test tools#175

Add support for using story ID as input for preview and test tools#175
JReinhold merged 11 commits intomainfrom
id-story-input

JReinhold commented Feb 25, 2026 •

edited

Loading

Uh oh!

changeset-bot bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

pkg-pr-new bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Feb 25, 2026 •

edited

Loading

Assets Changed:

Assets Changed:

Uh oh!

JReinhold Feb 25, 2026

Uh oh!

codecov bot commented Feb 25, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Uh oh!

kasperpeulen left a comment •

edited

Loading

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

Conversation

JReinhold commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

pkg-pr-new bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

codecov bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Bundle Report

Affected Assets, Files, and Routes:

Assets Changed:

Assets Changed:

Uh oh!

JReinhold Feb 25, 2026

Choose a reason for hiding this comment

Uh oh!

codecov bot commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

❌ 1 Tests Failed:

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

kasperpeulen left a comment • 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!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

JReinhold commented Feb 25, 2026 •

edited

Loading

changeset-bot bot commented Feb 25, 2026 •

edited

Loading

pkg-pr-new bot commented Feb 25, 2026 •

edited

Loading

codecov bot commented Feb 25, 2026 •

edited

Loading

codecov bot commented Feb 25, 2026 •

edited

Loading

kasperpeulen left a comment •

edited

Loading