React design system library MCP

At Mintel we maintain our own internal React design system component library. Working with our product design team we embed our design system standards into component implementations, and document them using Storybook.

With increased adoption of AI agents in our development workflows, we wanted to explore how we could expose our design system documentation by providing a local MCP CLI with our design system npm package.

@storybook/addon-mcp

The Storybook team are in early development of @storybook/addon-mcp which exposes Storybook documentation via an MCP (Model Context Protocol) server. This allows AI agents to query the component library documentation in a structured way, as well as offering tools to aid generating storybook stories.

We upgraded to Storybook 10 and set-up the addon configuration in .storybook/main.ts:

const config: StorybookConfig = {
  addons: ['@storybook/addon-mcp'],
  features: {
    experimentalComponentsManifest: true,
  },
};

Both Storybook 10 and React are required for generating component manfiests, which exposes more details about each component including the props and API documentation.

The addon starts up the MCP server when Storybook is run locally, and we can access the server at http://localhost:6006/mcp.

{
  "mcpServers": {
    "storybook-mcp": {
      "url": "http://localhost:6006/mcp",
      "type": "http"
    }
  }
}

The MCP server works by generating files in manifests directory when the Storybook is built. These files contain the component metadata and documentation in a structured format.

Providing the MCP to other teams

The addon is useful for developers working on the design system itself, but we wanted to make the MCP server available to other development teams using the design system.

To do this we hooked into the underlying @storybook/mcp package to add a CLI to the library to allow starting the MCP server in stdio mode. Other teams can then run the latest version of the design system library MCP server with a single command: pnpm dlx <library-name>@latest.

Build process

We extended our library build process to also build the Storybook, and copy the generated manifests to the published package.

# Build the storybook
pnpm build-storybook
# Copy manifest files into package dist
mkdir -p ./dist/manifests
cp -r ./storybook-static/manifests/ ./dist/manifests/
# Build the library
pnpm vite build

Adding a CLI

We also added a CLI entry point to the package to start the MCP server in stdio mode.

// package.json
{
  "bin": "./dist/mcp.js"
}

#!/usr/bin/env node

import { McpServer } from 'tmcp';
import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
import { StdioTransport } from '@tmcp/transport-stdio';
import {
  type StorybookContext,
  addListAllDocumentationTool,
  addGetDocumentationTool,
} from '@storybook/mcp';
import fs from 'node:fs/promises';
import pkgJson from './package.json';

const adapter = new ValibotJsonSchemaAdapter();
const server = new McpServer(
  {
    name: pkgJson.name,
    version: pkgJson.version,
    description: pkgJson.description,
  },
  {
    adapter,
    capabilities: {
      tools: { listChanged: true },
    },
    instructions:
      'You can use this MCP server to access Mintel Design System documentation, with component API docs for the React component library.',
  },
).withContext<StorybookContext>();

addListAllDocumentationTool(server).then(() => {
  addGetDocumentationTool(server).then(() => {
    const transport = new StdioTransport(server);

    transport.listen({
      format: 'markdown',
      manifestProvider: async (_request, path) =>
        fs.readFile(`${__dirname}/${path}`, 'utf-8'),
    });
  });
});

Usage

Teams can now set up the MCP server to run locally by configuring IDEs like Cursor:

{
  "mcpServers": {
    "mintel-design-system": {
      "command": "pnpm",
      "args": ["dlx", "<package-name>@latest"],
    }
  }
}

It can also be configured to run per-project, using the specific version of the design system library used in the project:

{
  "mcpServers": {
    "mintel-design-system": {
      "command": "pnpm",
      "args": ["exec", "<package-name>"],
    }
  }
}

We're still figuring out the best ways to leverage the MCP server, but it's already proving useful with prompts like:

Evaluate if any components in this codebase can be swapped for Mintel Design System components

Create a plan for migrating to the new Mintel Design System Button component

Implement a filterable list of content using Mintel Design System components