Storybook MCP Server

官方

帮助智能体自动编写和测试你的UI组件的故事

GitHub

258

文档

Storybook MCP - 贡献者指南

欢迎来到 Storybook MCP Addon 单体仓库！本项目通过提供 MCP（模型上下文协议）服务器来暴露 UI 组件信息和开发工作流，使 AI 代理能够更高效地使用 Storybook。

📦 包

此单体仓库包含四个主要包：

@storybook/mcp - 独立的 MCP 库，用于提供 Storybook 组件知识（可独立使用）
@storybook/addon-mcp - Storybook 插件，在你的 Storybook 开发服务器中运行 MCP 服务器，并包含来自本地 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

仓库有意将市场目录保留在两个位置。根目录目录支持从 storybookjs/mcp 进行 GitHub 安装；包本地目录支持本地包开发脚本。除了相对插件源路径外，它们应保持相同，包验证会检查这一点。

先决条件

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

测试

单体仓库在根级别使用集中式 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，然后你可以将编码代理连接到位于 http://localhost:6006/mcp（或你配置的插件端点）的它，并进行试用。

使用 MCP 应用程序

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

使用 VSCode 的 Insiders 版本
确保 chat.mcp.apps.enabled 设置已启用
通过在根目录运行 pnpm storybook 以监视模式启动仓库的 Storybook
重启 VSCode，打开 .vscode/mcp.json 文件并确保 Storybook MCP 标记为“正在运行”，否则点击“启动”。
在 VSCode 中打开聊天并编写如下提示：

使用 Storybook MCP 向我展示所有按钮故事的外观

在第一次提示之后，每当你进行更改时，Storybook 都会自动重启。等待它完全就绪，然后你可以提示_“再次运行该工具”_。

你还可以使用来自 MCPJam 的 inspector 来对工具调用进行更底层的控制。

格式化和代码检查

# 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

🔍 质量检查

单体仓库包含多个在 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 pkg from '../package.json' with { type: 'json' };

🚢 发布流程

本项目使用 Changesets 进行版本管理：

# 1. Create a changeset describing your changes
pnpm changeset

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

补丁：错误修复、文档更新
次要：新功能、向后兼容的更改
主要：破坏性更改

🤝 贡献

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

Fork 仓库并创建一个功能分支
进行更改，遵循上述代码约定
使用内部 Storybook 实例测试你的更改
如果你的更改需要发布，创建一个 changeset
提交一个包含清晰描述的拉取请求

提交前检查

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

获取帮助

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

📄 许可证

MIT - 详情请参阅 LICENSE

注意：本项目是实验性的，并处于积极开发中。随着我们探索将 AI 代理与 Storybook 集成的最佳方式，API 和架构可能会发生变化。