Storybook MCP

提示

自 Storybook v10.6.0 起，此仓库已迁移至 storybookjs/storybook。请前往该仓库查看最新文档。

---

Storybook MCP

欢迎使用 Storybook MCP Addon monorepo！此项目通过提供一个 MCP（Model Context Protocol）服务，公开 UI 组件信息和开发工作流，让 AI Agent 能够更高效地使用 Storybook。

📦 软件包

此 monorepo 包含四个主要软件包：

• @storybook/mcp - 用于提供 Storybook 组件知识的独立 MCP 库（可单独使用）
• @storybook/addon-mcp - 在 Storybook 开发服务中运行 MCP 服务的 Storybook 插件，并包含来自本地 Storybook 的 @storybook/mcp 功能
• @storybook/claude-code-plugin - 提供 Storybook 配置技能和 MCP 配置的 Claude Code 插件
• @storybook/codex-plugin - 提供 Storybook 配置技能和 MCP 配置的 Codex 插件

每个软件包都有自己的 README，其中包含面向用户的文档。本文档面向希望开发、测试或为这些软件包作出贡献的贡献者。

🚀 快速开始

从 GitHub 测试 Claude 和 Codex 插件

外部测试人员可以直接从此仓库的 main 分支安装插件市场。无需本地克隆。

Codex（更多详情）

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

验证市场和插件：

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code（更多详情）

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

验证插件和 MCP 服务：

claude plugin list --json
claude mcp list

此仓库有意在两个位置保留市场目录。根目录中的 目录支持通过 GitHub 从 storybookjs/mcp 安装；软件包本地的 目录支持本地软件包开发脚本。除了插件源路径的相对位置外，这些目录应保持一致， 软件包验证也会检查这一点。

先决条件

• Node.js 24+ - 项目需要 Node.js 24 或更高版本（参见 .nvmrc）
• pnpm 10.19.0+ - 严格的软件包管理器版本要求（在 package.json 中强制执行）

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g [email protected]

安装

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

开发工作流

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

Storybook 命令会启动：

• http://localhost:6006 上的内部测试 Storybook 实例
• 处于监视模式的插件，因此更改会自动生效
• 位于 http://localhost:6006/mcp 的 MCP 服务

🛠️ 常见任务

开发

turbo watch build 命令会以监视模式运行所有软件包，并在你进行更改时自动重新构建：

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

构建

# Build all packages
pnpm build

测试

此 monorepo 在根目录使用集中式 Vitest 配置，并为每个软件包配置了项目：

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

调试 MCP 服务

使用 MCP Inspector 调试和测试 MCP 服务功能：

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

此操作使用 .mcp.inspect.json 中的配置连接到本地 MCP 服务。

或者，你也可以使用以下 curl 命令检查一切是否正常：

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

使用 Storybook 调试

你可以通过以下命令启动 Storybook：

pnpm storybook

这会构建所有内容并启动带有 addon-mcp 的 Storybook。随后，你可以将编码 Agent 连接到 http://localhost:6006/mcp（或你配置的插件端点）并试用。

使用 MCP 应用

要使用和调试作为 preview-stories 工具一部分呈现的 MCP 应用，你可以：

1. 使用 VSCode Insiders 版本
2. 确保已启用 chat.mcp.apps.enabled 设置
3. 在根目录运行 pnpm storybook，以监视模式启动仓库的 Storybook
4. 重启 VSCode，然后打开 .vscode/mcp.json 文件，确保 Storybook MCP 显示为正在运行，否则点击 Start。
5. 在 VSCode 中打开聊天，并输入类似这样的提示词：

使用 Storybook MCP，向我展示所有按钮故事的效果

6. 首次输入提示词后，每次进行更改时，Storybook 都会自动重启。等待它完全就绪，然后你就可以输入 "再次运行该工具"。

你也可以使用 MCPJam 的检查器，更精细地控制工具调用。

格式化与 Lint

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 质量检查

此 monorepo 包含若干会在 CI 中运行的质量检查：

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 代码规范

TypeScript 与导入

相对导入始终包含文件扩展名：

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

• JSON 导入使用 import attributes 语法：

import pkg from '../package.json' with { type: 'json' };

🚢 发布流程

此项目使用 Changesets 管理版本：

# 1. Create a changeset describing your changes
pnpm changeset

创建 PR 时，如果你的更改应触发发布，请添加 changeset：

• Patch：错误修复、文档更新
• Minor：新功能、向后兼容的更改
• Major：破坏性更改

🤝 参与贡献

欢迎贡献！以下是入门方法：

1. Fork 此仓库并创建功能分支
2. 进行更改，并遵循上述代码规范
3. 使用内部 Storybook 实例测试更改
4. 如果更改需要发布，请创建 changeset
5. 提交拉取请求并附上清晰的说明

提交前

• 代码构建无错误（pnpm build）
• 测试通过（pnpm test:run）
• 代码已格式化（pnpm format）
• 代码已通过 lint 检查（pnpm lint）
• 类型检查通过（pnpm typecheck）
• 已使用 MCP 检查器或内部 Storybook 测试更改
• 如有必要，已创建 changeset（pnpm changeset）

获取帮助

• 想法与功能请求：发起讨论
• 错误报告：提交问题
• 提问：在 GitHub Discussions 中提问

📄 许可证

MIT - 详情请参阅 LICENSE

---

注意：此项目仍处于实验阶段，正在积极开发中。随着我们探索将 AI Agent 与 Storybook 集成的最佳方式，API 和架构可能会发生变化。