Storybook MCP Server 工具集配置指南：全面解析 @storybook/addon-mcp 的 toolsets 选项

2026-09-06 19:07:48作者：仰钰奇

导读：@storybook/addon-mcp 为 Storybook 提供标准 MCP（Model Context Protocol）服务端点，让 AI Agent 能够读取组件文档、生成 Stories、运行测试。但不同团队对 Agent 能力的边界诉求不同——本文以该 addon 的 options.toolsets 为核心，详细讲解如何在 main.js|ts 中按需启用 dev、docs、test 三大工具集，并结合仓库源码说明选项的解析与生效机制。读完后你将掌握 addon options 的完整配置语法、各工具集包含的具体工具及其前置条件，能够为你的 Storybook 项目精确裁剪 Agent 可用的能力面。

预览状态说明：Storybook 的 AI 能力当前处于 preview 阶段（见 docs/ai/releases 特性页与 preview 说明），API 在未来版本中可能调整，社区欢迎反馈与贡献以帮助改进这一能力。

一、MCP Server 与 addon options 的关系

Storybook 的 MCP Server 把开发、文档、测试三类能力组织为工具集（toolset），Agent 通过标准 MCP 协议调用其中的工具来理解组件、编写 Story、运行测试。addon options 正是用户在 Storybook 配置文件中控制"暴露哪些工具集"的入口。

在注册 addon 时，main.js|ts 中 addons 数组的字符串简写形式无法携带额外配置，因此要传入 options，就需要把 addon 条目改写为对象形式：

{
  name: '@storybook/addon-mcp',
  options: {
    // 在此配置
  },
}

二、完整配置示例：三种 `main` 文件风格

以下四段代码分别对应 CommonJS/ESM 的 JS 写法、TypeScript 的 CSF 3 写法，以及 Storybook 最新的 CSF Next（defineMain）写法的 JS/TS 版本。它们功能等价，均用于关闭 dev 开发工具集（dev: false），仅按项目需要选择其一：

export default {
  // Replace your-framework with the framework you are using
  // (e.g., react-vite, vue3-vite, angular, etc.)
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
};

// Replace your-framework with the framework you are using
// (e.g., react-vite, vue3-vite, angular, etc.)
import type { StorybookConfig } from '@storybook/your-framework';

const config: StorybookConfig = {
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
};

export default config;

// Replace your-framework with the framework you are using
// (e.g., react-vite, angular-vite, vue3-vite)
import { defineMain } from '@storybook/your-framework/node';

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
});

// Replace your-framework with the framework you are using
// (e.g., react-vite, angular-vite, vue3-vite)
import { defineMain } from '@storybook/your-framework/node';

export default defineMain({
  framework: '@storybook/your-framework',
  stories: ['../src/**/*.mdx', '../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
  addons: [
    // ... your existing addons
    {
      name: '@storybook/addon-mcp',
      options: {
        toolsets: {
          dev: false,
        },
      },
    },
  ],
});

提示：main.js|ts 是 Storybook 唯一接受 addon options 的位置。若你更希望以类型安全的方式编写配置，CSF Next 的 defineMain 会基于你的 framework 包（如 @storybook/react-vite/node）提供完整类型推导。

三、`toolsets` 选项的类型、结构与默认值

toolsets 是 MCP addon options 中的核心配置对象，用于开关 MCP Server 暴露的工具集。官方文档（docs/ai/mcp/api.mdx）给出的类型与默认值如下：

// 类型
{
  dev?: boolean;
  docs?: boolean;
  test?: boolean;
}

// 默认值
{
  dev: true,
  docs: true,
  test: true,
}

即默认情况下三个工具集全部启用；配置文件里未显式声明的键会沿用 true。你可以只声明需要关闭的键（如上面的 dev: false），也可以完整列出三个键以便团队阅读。

该结构与仓库源码完全吻合：在 code/addons/mcp/src/types.ts 中，addon options 通过 valibot schema 定义，dev、docs、test 均为可选布尔值且缺省回退为 true（v.exactOptional(v.boolean(), true)），并在对象整体上再次提供了 { dev: true, docs: true, test: true } 的兜底默认值：

export const AddonOptions = v.object({
  endpoint: v.optional(
    v.pipe(
      v.string(),
      v.check(isLiteralEndpointPathname, 'Endpoint must be a literal URL pathname')
    )
  ),
  toolsets: v.optional(
    v.object({
      dev: v.exactOptional(v.boolean(), true),
      docs: v.exactOptional(v.boolean(), true),
      test: v.exactOptional(v.boolean(), true),
    }),
    {
      dev: true,
      docs: true,
      test: true,
    }
  ),
});

值得注意的推断（依据 code/addons/mcp/src/preset.ts）：preset 在 Storybook 启动阶段会用该 schema 对传入的 options 做一次严格解析与校验（v.parse），若类型错误（例如把布尔值写成字符串 "false"）会直接抛出 ValiError。当前代码中没有为该解析单独做错误捕获，即配置错误可能导致整个 Storybook dev server 启动失败——因此务必保证 options 的类型正确。

四、`dev` 开发工具集

类型：boolean
默认值：true

dev 工具集面向"编写严谨 Story（含交互测试）并在 Agent 聊天界面中预览"的开发闭环，让开发者可以随时检查 Agent 的工作成果；生成的 Story 本身也可作为测试资产。该工具集没有任何框架前置要求，适用于所有 Storybook 项目。

dev 工具集包含以下工具（部分工具受额外 feature 门控，详见 docs/ai/mcp/overview.mdx）：

工具	能力	前置要求
`stories-changed`	返回受本地文件改动影响或可能受影响的故事列表	启用 change detection（`changeDetection` feature flag）
`get-storybook-story-instructions`	返回"如何写出高质量故事"的最新指令（应捕获哪些 props、如何为故事编写交互测试）	无
`stories-preview`	在 Agent 聊天界面渲染故事预览；若 Agent 不支持 MCP Apps，则返回故事在 Storybook 中的链接	无（预览能力依赖 Agent 对 MCP Apps 的支持）
`stories-find-by-component`	通过 Storybook 的实时反向依赖图，将组件源文件映射到渲染它的故事	Dev Server 的 builder 需支持模块图（Vite 或 Webpack 5）
`review-create`	推送当前变更的精编审查并返回审查页 URL	启用 review 特性（`changeDetection` 及 `experimentalReview`，或通过 `storybook ai` CLI / 官方插件通道）

从源码可见，单个工具的"能力门控"（如模块图、变更检测、review）与 toolsets.dev 这一静态开关是相互独立的：只有当两者同时满足时工具才真正注册（code/addons/mcp/src/preset.ts）。反过来，一旦通过 addon options 将整个 dev 工具集置为 false，无论其内部各工具的 feature 是否就绪，全部 dev 工具都会被禁用。

五、`docs` 文档工具集

类型：boolean
默认值：true

docs 工具集帮助 Agent 在生成 UI 时复用你已有的组件：Agent 可以查询组件清单（components manifest）匹配需求，并查阅组件文档以正确使用这些组件，从而保证生成 UI 与现有设计系统保持一致。docs 工具集包含三个工具（详见 docs/ai/mcp/overview.mdx）：

工具	能力
`docs-show`	返回某组件的详细文档：props、前三个示例故事、其余故事的索引，以及你补充的额外文档
`docs-show-story`	返回某个具体故事的完整源码与关联文档；当 `docs-show` 信息不足时由 Agent 调用
`docs-list`	返回组件与未挂接文档条目的索引

⚠️ 核心前置条件：components manifest

docs 工具集依赖 components manifest（默认关闭），因此仅当你的框架能生成组件清单时才可用。官方文档（docs/ai/mcp/overview.mdx）给出了当前框架支持矩阵：

框架	需要启用的 feature	`docs-show` 中的组件 API
所有 React 框架（`react-vite`、`react-webpack5`、`nextjs`、`nextjs-vite`、`tanstack-react`、`react-native-web-vite`）	`componentsManifest`	支持
`@storybook/angular-vite`	`componentsManifest`	支持
`@storybook/vue3-vite`	`componentsManifest` + `experimentalDocgenServer`	支持
`@storybook/angular`（Webpack）	不支持 manifest	不支持
其他框架	不支持 manifest	不支持

具体到配置：

@storybook/angular-vite 只需要 componentsManifest，因为它自身已默认启用 experimentalDocgenServer；
@storybook/vue3-vite 的 experimentalDocgenServer 默认未开启，需要两个 feature 同时开启，且必须写在同一个 features 对象中：
- main-config-features-components-manifest.md
- main-config-features-experimental-docgen-server.md
除 @storybook/vue3-vite 之外的其他 Vue 配置（包括 @nuxtjs/storybook）不会生成 manifest。

如果你的框架不生成 manifest，docs 工具集会报告为不可用（页面上会显示工具集 notice），但 dev 与 test 工具集不受影响。

六、`test` 测试工具集

类型：boolean
默认值：true

test 工具集让 Agent 能够运行组件测试并解读结果，是"自我修复循环"的关键环节：Agent 边开发边跑测试，发现问题（例如无障碍对比度不足）就修复并重跑直至通过。test 工具集包含的工具（见 docs/ai/mcp/overview.mdx）：

工具	能力
`test-run`	针对指定故事运行测试并返回结果（含无障碍问题，若已配置）；同时引导 Agent 解读结果并解决发现的问题

前置条件：需要在 Storybook 中配置好 Storybook Test（即安装并启用 @storybook/addon-vitest，并要求 Storybook 10.3.0+）。若已安装 @storybook/addon-a11y（docs 官方无障碍 addon），test-run 还会纳入可访问性检查并返回相关违规详情——这也解释了为何 MCP Server 页面会在测试工具集启用时额外显示 + accessibility 角标（依据 code/addons/mcp/src/preset.ts）。

从源码看（code/addons/mcp/src/preset.ts），test 工具集的实际可用性由 testSupported && (options.toolsets?.test ?? true) 决定——即使你的配置是默认 true，未安装 addon-vitest 时该工具集同样不会注册。

七、配置是如何生效的：从 options 到工具注册

要理解 toolsets 为何能精确控制工具暴露，可以把 code/addons/mcp/src/preset.ts 中的流程拆成三步：

校验与归一化：preset 的 experimental_devServer 钩子把 options.endpoint 与 options.toolsets 喂给 v.parse(AddonOptions, ...)，得到类型安全的规范对象；
计算"用户开关 × 环境能力"：代码分别计算出三个有效状态——
```
const isDevEnabled   = addonOptions.toolsets?.dev ?? true;
const isDocsEnabled  = docsEnabled && (addonOptions.toolsets?.docs ?? true);
const isTestEnabled  = testSupported && (addonOptions.toolsets?.test ?? true);
```
可见 docs/test 与框架能力、addon 安装情况做的是"与"运算：只有同时满足"用户未关闭 + 环境就绪"时工具集才真正可用；
渲染状态页面：dev server 在同一 endpoint 上响应 GET（浏览器请求）时，会把上述状态渲染进 HTML 页面，用 enabled/disabled 标记各工具集，并对每个被门控的工具给出具体原因提示（如"stories-find-by-component 需要支持模块图的 builder""test-run 需要 Storybook 10.3.0+ 与 @storybook/addon-vitest"），保证页面声明与实际注册的工具一致。

此外，该 preset 还默认把 componentsManifest feature 置为 true（code/addons/mcp/src/preset.ts），为 docs 工具集铺路。

关于服务端点：MCP Server 默认挂载在 /mcp（DEFAULT_MCP_ENDPOINT，见 code/addons/mcp/src/constants.ts），并允许通过 addon options 顶层的 endpoint 选项覆盖——该键在 types.ts 中被校验为"字面量 URL 路径名"。这是 toolsets 之外的另一个可选 options 键（官方 API 文档以 toolsets 为叙述重点，endpoint 属于源码已实现的能力）。

八、验证你的配置

配置完成后，按如下步骤确认结果：

安装并注册 addon（若尚未完成）：三种包管理器对应命令见 docs/_snippets/addon-mcp-add.md，例如 npm 项目执行：
```
npx storybook add @storybook/addon-mcp
```
启动 dev server，在浏览器访问 http://localhost:6006/mcp（端口以你的实际端口为准），页面会显示当前启用的工具集、每个工具的可用状态，以及指向组件清单调试器（component manifest debugger）的链接（详见 docs/ai/mcp/overview.mdx）。
给 Agent 配置 MCP Server 后，用一个简单 prompt（如"列出所有已记录的组件"）验证 Agent 能真实调用到工具。

九、实际调优建议

综合官方 API 文档（docs/ai/mcp/api.mdx）与源码行为，可归纳以下调优场景：

只想关闭某一条链路：例如不希望在本地开发时让 Agent 写测试，仅设 test: false；不想让 Agent 参考组件文档，仅设 docs: false。未声明的键保持默认 true，无需写全。
多项目统一策略：如果公司对 Agent 权限有统一规范，建议把三个键全部显式声明，让配置自解释、可审计。
注意隐性失效：docs: true 不等于 docs 工具集可用——还需组件清单支持（见第五节框架矩阵）；test: true 也不代表能跑测试——还需安装并启用 @storybook/addon-vitest。
类型安全优先：TS 项目建议使用 CSF Next 的 defineMain 写法以获得推导；无论哪种写法都要保证布尔值类型正确，因为 options 会在启动时被严格校验（参考 code/addons/mcp/src/types.ts 与 code/addons/mcp/src/preset.ts）。