@storybook/mcp

技能简介

@storybook/mcp 是 Storybook 官方推出的 MCP 服务器包，为 AI 助手提供组件和文档知识访问能力。它通过 Model Context Protocol（MCP）将 Storybook 的组件清单和文档暴露给 AI 模型，让 AI 在不离开编码环境的情况下理解项目中的组件结构、属性和文档。

该包是一个库包（library），本身不包含可执行文件，需要开发者将其集成到自己托管的 MCP 服务器中。配合 @storybook/addon-mcp 使用，可以通过 storybook dev 直接启动一个开箱即用的 MCP 服务器。

核心能力

• 组件知识服务：AI 可直接查询项目中所有 Storybook 组件的信息
• 文档浏览：支持 docs.json 中的文档内容查询
• Story 预览：通过 docs-show-story 工具查看特定 Story 的渲染结果
• HTTP 传输：使用 @tmcp/transport-http 实现标准 HTTP 传输
• 灵活的数据源：支持自定义 manifestProvider，从任意来源加载组件清单
• 零运行时依赖：发布包仅包含类型和逻辑，无外部依赖

安装配置

前置要求

• Node.js 20+
• 已配置 Storybook manifests 数据源（包含 components.json，必选；docs.json，可选）

最小化集成示例

import { createStorybookMcpHandler } from '@storybook/mcp';

const storybookMcpHandler = await createStorybookMcpHandler();

export async function handleRequest(request: Request): Promise {
  if (new URL(request.url).pathname === '/mcp') {
    return storybookMcpHandler(request);
  }
  return new Response('Not found', { status: 404 });
}

自定义数据源

const storybookMcpHandler = await createStorybookMcpHandler({
  manifestProvider: async (_request, path) => {
    return asyncReadManifestFromSomewhere(path);
  },
});

通过 storybook dev 启动

运行 storybook dev，服务器会自动在 /mcp 路径提供 MCP 服务。

使用步骤

1. 安装依赖：在项目中安装 @storybook/mcp
2. 配置 Manifests：确保项目有 components.json（必选）和 docs.json（可选）
3. 集成 MCP Handler：在现有服务器中集成 createStorybookMcpHandler
4. 启动服务：启动你的服务器，确保 /mcp 路径可访问
5. 连接 AI 客户端：在 Claude Code、Cursor 等 MCP 客户端中添加该服务器
6. 开始查询：用自然语言询问组件信息，如「这个组件有哪些属性？」

适用场景

• AI 辅助组件开发：向 AI 询问组件的正确用法和属性
• 设计系统文档查询：快速查找设计系统中组件的文档和示例
• 组件迁移辅助：在迁移组件时让 AI 理解原有组件的结构
• Storybook 项目知识共享：让非前端成员通过 AI 了解组件库
• 自动化文档生成：结合 AI 生成或补全组件文档

适用人群

• 使用 Storybook 管理组件库的前端团队
• 需要 AI 编程助手理解项目组件的开发者
• 希望在 IDE 中直接查询组件文档的工程师
• 构建内部设计系统的团队

工作原理

@storybook/mcp 读取项目中的 manifest 文件（components.json 和 docs.json），这些文件由 Storybook 的 AI 清单系统生成，包含了组件的元数据、属性定义和文档内容。MCP handler 将这些数据通过 MCP 协议暴露为工具（tools），AI 客户端可以调用 docs-list、docs-show、docs-show-story 等工具获取信息。

所有通信使用 HTTP 传输，遵循 MCP 规范，AI 客户端无需了解 Storybook 的内部实现即可获取组件知识。

官方链接

• NPM 页面：https://www.npmjs.com/package/@storybook/mcp
• GitHub 仓库：https://github.com/storybookjs/storybook/tree/next/code/lib/mcp
• Storybook 官方：https://storybook.js.org
• 官方文档：https://storybook.js.org/docs/next/ai/mcp/overview