You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
{{ message }}
Repository navigation
[RFC] Configurable story selection in the MCP docs-show tool
#37343
When an agent asks the Storybook MCP server about a component, docs-show returns docgen data, its first three stories in full, and the remaining stories as a list of names. Users have no control over how many stories, and which stories, are included by default. An agent that wants another story calls docs-show-story, one story at a time.
We looked at why agents make those docs-show-story calls in our agentic reference evaluations. Demand concentrates on a handful of stories, for a handful of reasons. There is no guarantee the three default stories align well with what agents might want, and story ordering is not a robust basis for them to be shown in docs-show.
This RFC lists a few proposed ways to let users influence that selection process. We want to hear from design system maintainers which of these would help them, and which would be a burden.
Problem Statement
How selection works today
docs-show inlines the first three stories that have a code snippet, in the order they're exported; other stories are listed by name and ID with a short summary when the story has one
docs-show-story returns the full snippet of one story
The only curation lever is the !manifest tag: applying it entirely removes a story from the MCP (but not just from the docs-show default selection)
What agents do with stories
We reconstructed the reason behind docs-show-story calls in eval runs and grouped them. Broadly speaking:
Agents rarely call docs-story-show and most stories never get looked at
Two needs dominate: agents want examples of real product UI, to understand how to use a DS well; or they want facts about the component that aren't captured by docgen, like HTML attrs or prop pass-through behaviour
Written docs remove some needs, but not all: with component descriptions present, agents stopped loading stories to learn parts, variants or accessibility behaviour but still loaded example stories and still hunted for undocumented facts
The agent's task influences their need: bug fixing prompts and UI creation prompts looked for different types of stories
The name is usually all the agent has
Non-goals
Advising users on which stories to write (being done separately)
Changing the output of docs-show-story (but changing its signature is a goal)
Changing how components are included in docs-list (but changing how they're displayed is a goal)
Measuring whether loading a story improves an agent’s output (left to future work)
Proposals
1. Let maintainers set how many stories are inlined
Still relies on file order, so adds little flexibility
2. Let maintainers pin or skip stories with tags
Add special tags that tell docs-show what to do with stories. Pinned stories are inlined first, then file order fills the remaining slots. Skipped stories are never inlined even if among the first three stories.
// Checkout.stories.tsexportconstMealdropCheckoutForm=meta.story({tags: ['mcp:pinned'],});exportconstUnimportantTest=meta.story({tags: ['mcp:skipped'],// never inlined in `docs-show`});exportconstEvenLessImportantTest=meta.story({tags: ['mcp:hidden'],// equivalent to !manifest});
Pros:
Maintainers can prioritise the most useful stories without reordering files
Stories useful to humans as a showcase, but not adapted to agents, can be skipped
Cons:
Creates a few extra tags for users to learn
Unresolved:
What happens if more than 3 stories are pinned?
3. Return tags next to story names
Show a story's user-defined tags in the docs-show list for a component, and in docs-list when story IDs are requested. System tags such as dev, test or play-fn would be left out.
### Other Stories- Mealdrop Checkout Form (input--mealdrop-checkout-form): The checkout form as built in the app [app-example, form]- Test Defaults To Type Button (button--test-defaults-to-type-button) [test, attribute]
Pros:
Agents can better reason about what a story might show them
Cons:
Tool output grows by a few tokens per story
Tags written for other purposes, such as badges, would show up unless filtered
This is only as good as the amount of time and effort spent by DS teams building a tag taxonomy
4. Let agents specify what kind of task they're doing
Add a task param to docs-show, chosen from a preset list, such as ui-generation, bug-fixing, accessibility etc. Maintainers map tags to tasks, and we inline stories relevant to the task at hand.
A variant is to ship a separate tool per task, so that the tool description itself tells the agent when to call it. That multiplies the tool count, which some agents handle poorly, but it removes the risk of the agent forgetting the input.
Pros:
One of the most flexible options
Lets DS teams optimise for specific agent tasks
Cons:
We do not know yet what the final list of tasks should be
Agents may misreport their task or ignore the input
Maintainers have to annotate stories and configure a new field
More conceptually complex than other options
5. Order stories by agent demand
The dev server or published MCP host keeps count of which stories get requested through docs-show-story, and inlines the most requested ones first. The order adapts to what agents in a project actually ask for.
Pros:
No annotation work or configuration needed
Improves agent performance over time
Can be applied per-task to optimise for different agent tasks
Costs:
Needs the information to be stored somewhere, both for local and deployed MCPs (introducing new infra challenges)
Popular stories get more popular under this proposal, so poorly-named stories may never get a chance to prove their usefulness
Output changes over time, which makes agent behaviour harder to reproduce
Risks
Ecological validity
Our eval data comes from one design system, one application, five tasks and one model. Read these findings as hypotheses to confirm, not as established facts.
We believe the data is enough to act on extensibility controls because it already shows discrepancies between the MCP's behaviour and our eval agents' needs. More diverse eval data would surface more diverse discrepancies rather than no discrepancy at all.
Annotation fatigue
Some proposals are only as good as the tags maintainers write. A DS with hundreds of stories and no tags behaves exactly as today.
This risk can be addressed by providing a story annotation skill that analyses stories and recommends tags based on presets we've chosen.
Fragmented configuration
Spreading MCP behaviour over addon options, tag configuration and tool inputs recreates the problem #35905 tries to fix for sidebar filters.
We should prefer to limit the number of places where user controls are added.
Agent compliance
Proposals 4 and 6 rely on agents reading tool descriptions and passing inputs. Some do, some do not. This has not stopped us in the past and we expect users to use mid-high effort agents for good results.
Unresolved Questions
Should per-story MCP metadata live in tags, in parameters, or in a new field?
Should manifests carry user-defined tags at all, and which tags should be filtered out?
Should a task preset list be fixed by Storybook, extensible by maintainers, or both? What would the first version contain?
In composition, should selection rules come from the composed Storybook’s manifest or from the host’s configuration?
Should docs-show-story accept several story IDs in one call?
Alternatives considered / Abandoned Ideas
Do nothing
docs-show-story already exists, and agents did find the stories they wanted when the name gave them away. This remains the baseline. We think it is not enough on its own: file order stays arbitrary, and maintainers have no lever at all.
Inline every story
In one evaluation condition every story was inlined. This resulted in very high output token costs. Agents then re-loaded single stories to isolate them from a long page, further increasing token cost. We don't believe this to be a credible option.
A selection function in main.ts
A function receiving the component and its stories and returning the ones to inline would give full control. It turns configuration into code, which automigrations, telemetry and editor tooling cannot read, and it cannot travel inside a manifest for composition. We would rather start from declarative options and add a function only if they prove insufficient.
reacted with thumbs up emoji reacted with thumbs down emoji reacted with laugh emoji reacted with hooray emoji reacted with confused emoji reacted with heart emoji reacted with rocket emoji reacted with eyes emoji
Uh oh!
There was an error while loading. Please reload this page.
Uh oh!
There was an error while loading. Please reload this page.
Summary
When an agent asks the Storybook MCP server about a component,
docs-showreturns docgen data, its first three stories in full, and the remaining stories as a list of names. Users have no control over how many stories, and which stories, are included by default. An agent that wants another story callsdocs-show-story, one story at a time.We looked at why agents make those
docs-show-storycalls in our agentic reference evaluations. Demand concentrates on a handful of stories, for a handful of reasons. There is no guarantee the three default stories align well with what agents might want, and story ordering is not a robust basis for them to be shown indocs-show.This RFC lists a few proposed ways to let users influence that selection process. We want to hear from design system maintainers which of these would help them, and which would be a burden.
Problem Statement
How selection works today
docs-showinlines the first three stories that have a code snippet, in the order they're exported; other stories are listed by name and ID with a short summary when the story has onedocs-show-storyreturns the full snippet of one story!manifesttag: applying it entirely removes a story from the MCP (but not just from thedocs-showdefault selection)What agents do with stories
We reconstructed the reason behind
docs-show-storycalls in eval runs and grouped them. Broadly speaking:docs-story-showand most stories never get looked atNon-goals
docs-show-story(but changing its signature is a goal)docs-list(but changing how they're displayed is a goal)Proposals
1. Let maintainers set how many stories are inlined
Replacing the hard-coded 3 by an addon option.
Pros:
Cons:
2. Let maintainers pin or skip stories with tags
Add special tags that tell
docs-showwhat to do with stories. Pinned stories are inlined first, then file order fills the remaining slots. Skipped stories are never inlined even if among the first three stories.Pros:
Cons:
tagsfor users to learnUnresolved:
3. Return tags next to story names
Show a story's user-defined tags in the
docs-showlist for a component, and indocs-listwhen story IDs are requested. System tags such asdev,testorplay-fnwould be left out.Pros:
Cons:
4. Let agents specify what kind of task they're doing
Add a
taskparam todocs-show, chosen from a preset list, such asui-generation,bug-fixing,accessibilityetc. Maintainers map tags to tasks, and we inline stories relevant to the task at hand.A variant is to ship a separate tool per task, so that the tool description itself tells the agent when to call it. That multiplies the tool count, which some agents handle poorly, but it removes the risk of the agent forgetting the input.
Pros:
Cons:
5. Order stories by agent demand
The dev server or published MCP host keeps count of which stories get requested through
docs-show-story, and inlines the most requested ones first. The order adapts to what agents in a project actually ask for.Pros:
Costs:
Risks
Ecological validity
Our eval data comes from one design system, one application, five tasks and one model. Read these findings as hypotheses to confirm, not as established facts.
We believe the data is enough to act on extensibility controls because it already shows discrepancies between the MCP's behaviour and our eval agents' needs. More diverse eval data would surface more diverse discrepancies rather than no discrepancy at all.
Annotation fatigue
Some proposals are only as good as the tags maintainers write. A DS with hundreds of stories and no tags behaves exactly as today.
This risk can be addressed by providing a story annotation skill that analyses stories and recommends tags based on presets we've chosen.
Fragmented configuration
Spreading MCP behaviour over addon options, tag configuration and tool inputs recreates the problem #35905 tries to fix for sidebar filters.
We should prefer to limit the number of places where user controls are added.
Agent compliance
Proposals 4 and 6 rely on agents reading tool descriptions and passing inputs. Some do, some do not. This has not stopped us in the past and we expect users to use mid-high effort agents for good results.
Unresolved Questions
docs-show-storyaccept several story IDs in one call?Alternatives considered / Abandoned Ideas
Do nothing
docs-show-storyalready exists, and agents did find the stories they wanted when the name gave them away. This remains the baseline. We think it is not enough on its own: file order stays arbitrary, and maintainers have no lever at all.Inline every story
In one evaluation condition every story was inlined. This resulted in very high output token costs. Agents then re-loaded single stories to isolate them from a long page, further increasing token cost. We don't believe this to be a credible option.
A selection function in
main.tsA function receiving the component and its stories and returning the ones to inline would give full control. It turns configuration into code, which automigrations, telemetry and editor tooling cannot read, and it cannot travel inside a manifest for composition. We would rather start from declarative options and add a function only if they prove insufficient.
All reactions