storybook-mcp-integration

Storybook MCP 集成

使用 Storybook MCP 服务（@storybook/addon-mcp），让 Agent 了解项目中实际的组件库，包括属性、故事、测试和实时预览。

适用场景

• 生成组件 — 创建新组件前，先检查 Storybook 中已有的组件
• 测试组件 — 通过 MCP 运行故事测试和无障碍审查，而不是使用 CLI
• 视觉验证 — 在聊天中嵌入故事预览，供用户确认
• 审查组件 — 通过 MCP 获取包含完整元数据的组件清单

快速参考 — 6 个工具，3 个工具集

工具集	工具	用途	关键输入
dev	get-storybook-story-instructions	编写故事和交互测试的指南	无
dev	preview-stories	返回故事的预览 URL（可嵌入）	stories[]: {storyId} 或 {absoluteStoryPath, exportName}
docs	list-all-documentation	完整的组件和文档清单索引	无
docs	get-documentation	属性、前 3 个故事、故事索引和文档	id（必填），storybookId（可选）
docs	get-documentation-for-story	完整的故事源码和组件文档	componentId、storyName（必填）
testing	run-story-tests	运行组件和无障碍测试，返回通过/失败状态及违规项	stories[]（可选），a11y 布尔值（默认为 true）

前提条件

# Storybook 10.3+ with Vite builder (no webpack)
npx storybook@latest upgrade

# Install the addon (current: @storybook/[email protected], Apr 2026)
npx storybook add @storybook/addon-mcp

# Enable docs toolset (required for component discovery)
# In .storybook/main.ts:
#   componentsManifest: true
# NOTE: the old `experimentalComponentsManifest` flag was renamed in
# Storybook 10.3; it is now `componentsManifest` and default-on. Any
# code still passing the `experimental` prefix will warn-then-ignore.

# For Chromatic remote setups, use the standalone package instead of
# the addon (same tool surface, no local Storybook required):
#   npm i -D @storybook/mcp
#   npx storybook-mcp --registry https://chromatic.storybook.cloud

# Enable testing toolset (requires addon-vitest)
# npx storybook add @storybook/addon-vitest

# Register with Claude Code
npx mcp-add --type http --url "http://localhost:6006/mcp" --scope project

检测模式

使用 Storybook MCP 工具前，先检查其是否可用：

# Probe for storybook-mcp tools
ToolSearch(query="+storybook list-all-documentation")

# If tools found → Storybook MCP is available
# If not found → fallback to filesystem-based component discovery

规则详情

使用 Read("rules/<file>") 按需加载规则：

规则	影响	描述
component-discovery	HIGH	生成新组件前，使用 list-all-documentation 和 get-documentation
story-preview-verification	HIGH	嵌入 preview-stories URL 以便进行视觉确认
mcp-test-runner	CRITICAL	生成组件后，使用 a11y:true 运行 run-story-tests

工具集选择

通过 X-MCP-Toolsets 标头筛选工具集，以减少 Agent 上下文：

Agent 角色	工具集	原因
component-curator	docs	仅获取清单和属性，不运行测试
frontend-ui-developer	dev,docs,testing	完整访问权限，支持生成 → 验证循环
design-system-architect	docs	获取组件元数据以进行治理

Chromatic 远程发布

对于使用 Chromatic 的团队，docs 工具集可远程发布：

• 发布地址：https://<chromatic-storybook-url>/mcp
• 远程仅提供 docs 工具集（dev 和 testing 需要本地 Storybook）
• 无需在本地运行 Storybook，即可用于跨团队发现设计系统

优雅降级

Storybook MCP	备用方案	行为
可用	—	使用 MCP 工具发现、测试和预览组件
不可用	文件系统	使用 Glob("**/components/**/*.tsx") 和 Grep 获取组件清单
不可用	21st.dev	通过 21st-dev-magic MCP 搜索公共注册表
不可用	手动	使用 Claude 多模态分析截图

相关技能

• storybook-testing — CSF3 模式、Vitest 集成、Chromatic TurboSnap
• component-search — 21st.dev 注册表搜索（外部组件）
• design-to-code — 从模型图到组件的完整流程（第 2 阶段使用此技能）
• ui-components — shadcn/ui 和 Radix 组件模式