# 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:

```bash
npm install
```

3. Configure the design system path:

```bash
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:

```env
# 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:

```bash
npm start
```

### Testing Locally

Run the test script to verify functionality:

```bash
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:

```json
{
  "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

```markdown
# 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.