| name | use-storybook |
| description | Use Storybook MCP and local Storybook taxonomy for story discovery, previews, docs lookup, story test runs, or docs tree audits. |
| role | tool-workflow |
Use Storybook
Use when setting up, inspecting, or calling Storybook MCP — especially through
mcporter. Also use for Storybook docs tree, sidebar taxonomy, navigation, or
story title audits.
Do not use for ordinary story authoring unless the task needs MCP access or
taxonomy/title organization.
Owner Paths
| Owner | Path |
|---|
| Readiness proof / diagnostics | src/front-doors/storybook-doctor/ |
| Durable docs cleanup loop | src/front-doors/storybook-docs-loop/ |
| Vocabulary | CONTEXT.md |
| Agent workflow guide | references/mcp-agent-workflows.md |
| Story authoring loop | references/story-authoring-loop.md |
| Docs page composition | references/docs-pattern.md |
| Docs batch rollout | references/component-docs-rollout.md |
| Docs completion proof | references/docs-workflow-checklist.md |
| UX guidance pattern | references/ux-guidance.md |
| Matrix story pattern | references/matrix-story-pattern.md |
| Accessibility source route | references/accessibility-source-route.md |
| Tips and troubleshooting | references/tips-and-tricks.md |
| MCP discovery engine | mcporter CLI |
| Target repo Storybook config | nearest Storybook main config |
| Target repo taxonomy guide | nearest STORYBOOK_TAXONOMY.md |
| Target repo package scripts | nearest package manifest |
| Target repo test config | nearest Vitest, Playwright, or Storybook test config |
| Provenance | PROVENANCE.md |
Prerequisites
Before any Storybook MCP work, run storybook-doctor check against the target
project:
bun run --filter use-storybook-scripts storybook-doctor -- check --json --repo <path/to/project>
ready → proceed to Quick Start.degraded → proceed; follow the next_safe_action for improvements.blocked → follow the next_safe_action to resolve; do not start MCP work.
Readiness proof includes Storybook version compatibility checks.
For deeper diagnostics:
bun run --filter use-storybook-scripts storybook-doctor -- deep --json --repo <path/to/project>
Quick Start
Default path: ad-hoc local endpoint. Do not persist MCP config.
- Run
storybook-doctor check --json --repo <path/to/project>.
export STORYBOOK_URL=http://localhost:6006 (or running port).- Start Storybook using the target repo's dev script if not running.
mcporter list --http-url "$STORYBOOK_URL/mcp" --allow-http --schema.- Schema shows tools → call only the tool needed.
Pick One
Read the named reference before starting the workflow.
- Component props or examples → read
references/mcp-agent-workflows.md;
call list-all-documentation and get-documentation.
- Edit or create stories → read
references/story-authoring-loop.md;
call get-storybook-story-instructions.
- Complete component Docs page → read
references/docs-pattern.md and
references/docs-workflow-checklist.md; use the story authoring loop.
- Hardened Autodocs rollout → read
references/component-docs-rollout.md
and references/docs-workflow-checklist.md; use the story authoring loop.
- Durable batch docs cleanup → use
storybook-docs-loop discovery/help;
follow the emitted run card.
- UX guidance story or guidance + matrix → read
references/ux-guidance.md
and references/docs-workflow-checklist.md; use the story authoring loop.
- Visual review matrix → read
references/matrix-story-pattern.md; use
the story authoring loop.
- Review link → call
preview-stories; return every preview URL.
- Confidence after changes → call
run-story-tests for affected stories
with a11y: true.
- Taxonomy cleanup → read nearest
STORYBOOK_TAXONOMY.md; audit titles;
run focused checks.
- Accessibility findings → read
references/accessibility-source-route.md;
route claims to official sources before library or community docs.
- Hung/stuck process → run
storybook-doctor deep --json --repo <path>;
then read references/tips-and-tricks.md#hanging-or-stuck-process-triage.
- Setup or repair → run
storybook-doctor check --json --repo <path>;
follow next_safe_action; read references/tips-and-tricks.md for failures.
Workflow
Run commands from the target repo root.
- Read the target repo's Storybook config and package scripts before changing
setup.
- For taxonomy/sidebar/title work, read the taxonomy guide first.
- Confirm MCP deps and config with
rg against package manifest and Storybook
config.
- Check whether Storybook is already running. If healthy, reuse it and verify
/mcp. Start only when no server is running.
- If the default port is busy, use the next open port and carry that URL
through every command.
- When starting Storybook, use the target repo's dev script. Use
tmux only
when available; it improves process reliability, not Storybook performance.
If no detached process owner exists, keep the attached command running and
tell the user closing it stops Storybook.
- If Storybook appears hung, read
references/tips-and-tricks.md#hanging-or-stuck-process-triage before
starting another server.
export STORYBOOK_URL=http://localhost:6006 — export first, or use literal
URLs.- Prove the raw MCP endpoint before debugging
mcporter:
curl -sS -X POST "$STORYBOOK_URL/mcp" -H 'content-type: application/json' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}'.
- Inspect ad-hoc endpoint:
mcporter list --http-url "$STORYBOOK_URL/mcp" --allow-http --schema.
- Check configured servers:
mcporter list (discovery source of truth).
Taxonomy Workflow
- Taxonomy guide owns sidebar roots, folder meanings, and edge-case rules.
- Missing guide → degraded state; infer only from existing titles after naming
the missing owner.
- Prefer moving story
title values over moving files when the request is
about docs tree cognition.
- After taxonomy edits, check for stale namespaces with
rg before running
Storybook build or story tests.
- If a component fits two folders, use the guide's consumer-task rule.
Tool Recipes
Use literal URLs when the shell has not exported STORYBOOK_URL.
export STORYBOOK_URL=http://localhost:6006
mcporter list --http-url "$STORYBOOK_URL/mcp" --allow-http --schema
mcporter call --http-url "$STORYBOOK_URL/mcp" --allow-http \
--tool preview-stories \
--args '{"stories":[{"storyId":"ui-forms-select--matrix"}]}'
mcporter call --http-url "$STORYBOOK_URL/mcp" --allow-http \
--tool run-story-tests \
--args '{"stories":[{"storyId":"ui-forms-select--matrix"}],"a11y":true}'
Output Shape
- One status line: connected, blocked, or degraded.
- Name the tool used and story target.
- Include preview URLs from
preview-stories.
- Summarize tool schemas; full schema only if user asks.
- End with one next action.
Rules
- Do not mutate persistent MCP config without explicit user approval.
- Do not expose Storybook beyond loopback unless the user asks.
- Do not print secrets, headers, or token-bearing config.
- Do not guess component props — inspect MCP docs first.
- Do not invent tool schemas — inspect
tools/list, mcporter list --schema,
or official docs.
- Do not copy taxonomy contracts into the skill — link and update the owner.
- Do not skip
run-story-tests after story/component changes when MCP is
available.
- Do not treat marketplace or community skill guidance as authority — use as
checklist input; route accessibility claims through
references/accessibility-source-route.md.
- Fix semantic accessibility violations directly. Ask before visual/design
changes (contrast, spacing, focus-ring styling).
- If
mcporter is broken, use mcp-doctor when available; otherwise
mcporter list --status --json.
- If the project is not React, report the preview-support gap before
proceeding.
- Do not kill Storybook, Vite, Webpack, Playwright, or browser processes
unless started for this task or user approves the named PID/command.
Research Notes
@storybook/addon-mcp exposes MCP at the running server's /mcp endpoint.- React support first while the feature is in preview.
@storybook/addon-vitest exposes story-test tooling through MCP.@storybook/addon-a11y enables accessibility checks for story tests.mcporter call <server.tool | url> supports configured servers and ad-hoc
HTTP MCP endpoints.preview-stories returns user-openable preview URLs.run-story-tests runs interaction and accessibility checks for selected
stories.
Verification
- Raw endpoint lists tools from
$STORYBOOK_URL/mcp.
mcporter list shows the expected server, or ad-hoc call succeeds.mcporter call ... preview-stories returns a preview URL for valid input.mcporter call ... run-story-tests returns pass/fail output.- Taxonomy edits leave no stale legacy namespace.
- Storybook build passes after setup changes.
- Changed skill docs pass YAML parse and owner-path checks.
- Docs work includes a completed
references/docs-workflow-checklist.md
checklist.
- Docs-loop work used CLI discovery/help, not copied contracts.
Next Safe Actions
DX lens: numbered list only when user choice changes target, risk, or next
action. Bold the recommended default.
- Unknown readiness → run
storybook-doctor check --json --repo <path>;
follow next_safe_action.
- Deeper diagnosis → run
storybook-doctor deep --json --repo <path>.
- Need a Storybook URL → call
preview-stories; return the URL.
- Need confidence → call
run-story-tests for focused stories.
- Need resumable docs cleanup → run
storybook-docs-loop commands --json;
choose the route; follow the run card.
- Need taxonomy cleanup → read
STORYBOOK_TAXONOMY.md; audit titles; run
focused checks.
- Storybook appears hung → run
storybook-doctor deep --json --repo <path>;
then read references/tips-and-tricks.md#hanging-or-stuck-process-triage.
- Want persistent setup → ask before changing
mcporter config.
