nimit9/design-stack-mcp-server

BrowserStack Design Stack MCP Server

A standalone Model Context Protocol (MCP) server that provides AI assistants with comprehensive access to BrowserStack's design system components. This server extracts and serves structured metadata about React components from both source code (using react-docgen) and Storybook files.

Features

• 🔍 Component Search: Search for components by name, functionality, or use case
• 📖 Detailed Component Info: Get comprehensive prop information from both react-docgen and Storybook
• 📋 Component Listing: Browse all available components in the design system
• 🔍 Props Analysis: Compare prop information between different sources
• 🎯 Real Usage Examples: Extract actual usage examples from Storybook stories
• ⚙️ Configurable Paths: Use environment variables to point to any design system location

Installation

1. Clone or copy this repository to your desired location (outside the frontend repo)
2. Install dependencies:

npm install

3. Configure the design system path:

cp .env.example .env
# Edit .env and set DESIGN_STACK_PATH to your design system location

Configuration

Set the following environment variables in your .env file:

# Required: Path to your design system package
DESIGN_STACK_PATH=/path/to/your/design-stack

# Optional: Enable debug logging
DEBUG=false

# Optional: Enable caching (future feature)
ENABLE_CACHE=false

Usage

As an MCP Server

Start the server for use with MCP-compatible tools:

npm start

Testing Locally

Run the test script to verify functionality:

npm test

Available MCP Tools

The server provides these tools to AI assistants:

1. search_components

Search for components by name or functionality.

Parameters:

• query (string): Search term
• limit (number, optional): Max results (default: 10)

2. get_component_info

Get detailed information about a specific component.

Parameters:

• componentName (string): Name of the component (e.g., "Accordion", "Button")

3. list_all_components

Get a list of all available components in the design system.

Parameters: None

4. analyze_component_props

Compare prop information between react-docgen and Storybook sources.

Parameters:

• componentName (string): Name of the component to analyze

Integration with AI Tools

Claude Desktop (MCP)

Add this configuration to your Claude Desktop MCP settings:

{
  "mcpServers": {
    "design-stack": {
      "command": "node",
      "args": ["/path/to/design-stack-mcp-server/src/index.js"],
      "env": {
        "DESIGN_STACK_PATH": "/path/to/your/design-stack"
      }
    }
  }
}

VS Code Extensions

The server can be integrated with VS Code extensions that support MCP protocol.

How It Works

Component Analysis

The server analyzes components from two sources:

1. React-docgen: Extracts props from component source code, including:

   • Prop types and names
   • Required/optional status
   • Default values
   • JSDoc descriptions

2. Storybook argTypes: Extracts props from Storybook configuration:

   • Rich descriptions
   • Control types
   • Default values
   • Type summaries

Example Extraction

The server extracts real usage examples from Storybook stories:

• Template-based stories: Extracts simple props from .args configurations
• Functional stories: Extracts component usage from exported functions
• Complex examples: Handles nested JSX and complex prop values

Data Merging

Props from both sources are intelligently merged:

• Storybook descriptions are preferred (usually more comprehensive)
• Type information is combined from both sources
• Source tracking shows where each piece of information originated

Example Output

# Accordion

**Description:** The Accordion component provides a way to toggle the visibility of content sections.

## Props:
  • **defaultOpen**: boolean [storybook]
    Determines whether the Accordion is to be open by default.
  • **children**: node (required) [react-docgen, storybook]
    The content to be rendered inside the Accordion.
  • **wrapperClassName**: string [storybook]
    A custom CSS class name to style the wrapper of the Accordion component.

## Examples from Storybook:
  **InteractiveAccordion**:
  ```jsx
  <Accordion defaultOpen={true} />

InteractiveAccordion example from Storybook

File Locations:

• Component: /path/to/design-stack/modules/Accordion/index.jsx
• Storybook: /path/to/design-stack/modules/Accordion/Accordion.stories.jsx

## Development

### Project Structure

design-stack-mcp-server/ ├── src/ │ ├── index.js # MCP server implementation │ └── component-analyzer.js # Component analysis logic ├── .env.example # Environment configuration template ├── .env # Local environment configuration ├── package.json # Dependencies and scripts └── README.md # This file

### Adding New Features

The server is designed to be extensible. You can add new tools by:

1. Adding new functions to `component-analyzer.js`
2. Registering new tools in `index.js` using `server.tool()`
3. Testing with the test script

### Debug Mode

Enable debug logging to troubleshoot issues:

```bash
echo "DEBUG=true" >> .env
npm start

Requirements

• Node.js 18+
• Design system with React components
• Storybook files (optional but recommended for better descriptions)

License

MIT License - see package.json for details.