npm package: @gc-mcp/storybook
Description: MCP Server for Storybook - provides access to Storybook component documentation and props from Chromatic
Latest version: 1.2.1

# MCP Storybook Server

A Model Context Protocol (MCP) server that provides access to Storybook component documentation and props from Chromatic. This server connects to hosted Chromatic Storybook instances and provides tools to list components, get documentation, and extract component properties.

## Features

- **List Components**: Get a simple list of all available components
- **Component Documentation**: Get detailed documentation for specific components
- **Props Extraction**: Extract component props/properties using Playwright browser automation
- **Authentication Support**: GitHub PAT and cookie-based authentication for Chromatic
- **Dual Format Support**: Supports both Storybook v3 and v5 formats
- **Multiple Output Formats**: Markdown and XML formatting options

## Installation

```bash
# Install dependencies
npm install

# Install Playwright browsers (required for props scraping)
npx playwright install chromium
```

## Configuration

### Environment Variables

Create a `.env` file or set the following environment variables:

```bash
# Chromatic Storybook base URL (required)
STORYBOOK_URL=https://your-project.chromatic.com

# GitHub Personal Access Token for authentication (optional)
# Used for fetching index.json from Chromatic
GITHUB_PAT=your_github_pat_here

# Output format for documentation (markdown or xml, default: markdown)
STORYBOOK_FORMAT=markdown

# Playwright settings
PLAYWRIGHT_HEADLESS=true
PLAYWRIGHT_TIMEOUT=30000

# Chromatic cookies for authentication (optional)
# JSON string or cookie string format
CHROMATIC_COOKIES=
```

### Cursor MCP Configuration

Add to your Cursor MCP config (`.cursor/mcp.json` or similar):

```json
{
  "mcpServers": {
    "storybook": {
      "command": "node",
      "args": ["storybook/bin/mcp-storybook"],
      "env": {
        "STORYBOOK_URL": "https://your-project.chromatic.com",
        "GITHUB_PAT": "${GITHUB_PAT}",
        "STORYBOOK_FORMAT": "markdown"
      }
    }
  }
}
```

## Available Tools

### 1. `list-all-documentation`

List all available UI components and documentation entries from the Storybook.

**Example:**

```
Tool: list-all-documentation
```

Returns a formatted list of all components with their IDs and descriptions.

### 2. `get-documentation`

Get detailed documentation for a specific UI component or docs entry by ID.

**Parameters:**

- `id` (string, required): Component or documentation entry ID

**Example:**

```
Tool: get-documentation
Parameters: { "id": "atoms-avatar" }
```

Returns detailed component documentation including stories, descriptions, and metadata.

### 3. `get-component-list`

Get a simple list of all component names from the configured Storybook (fast, simple output).

**Example:**

```
Tool: get-component-list
```

Returns a simple list of component names.

### 4. `get-component-props`

Get props information for multiple components using Playwright to scrape from Chromatic pages.

**Parameters:**

- `componentNames` (array of strings, required): Array of component names to get props information for

**Example:**

```
Tool: get-component-props
Parameters: { "componentNames": ["Avatar", "Button", "Input"] }
```

Returns props tables for each component, including:

- Property names
- Types
- Default values
- Descriptions
- Required/optional status

**Note**: This tool requires Playwright and will launch a headless browser to scrape props from Chromatic pages.

## Authentication

For **private Chromatic Storybooks** (especially with GitHub SSO), you need to provide authentication. The server supports multiple authentication methods:

### Option 1: Chromatic Project Token (Recommended - Most Permanent)

Chromatic project tokens don't expire and are the best option for long-term use:

1. Go to your Chromatic project → **Manage** → **Configure**
2. Find your **Project Token**
3. Set it as `CHROMATIC_PROJECT_TOKEN` environment variable

**Note**: Project tokens may work for API access but might not work for UI-based Storybook access. If it doesn't work, use cookies (Option 2).

### Option 2: Chromatic Cookies (Required for Private Storybooks with SSO)

Session cookies are required for accessing private Storybooks. **⚠️ Important: Cookies expire when your Chromatic session expires** (typically after inactivity or logout).

#### Quick Cookie Extraction

Use the helper script to format cookies:

```bash
node scripts/extract-cookies.js
```

Then follow the prompts to paste your cookies.

#### Manual Cookie Extraction

**⚠️ Important:** Chromatic cookie names can vary. Look for cookies with **long, random values** (not simple values like `true` or `1`).

**Step-by-step:**

1. **Log in to Chromatic** in your browser
2. **Open DevTools** (F12) → **Application** (Chrome) or **Storage** (Firefox)
3. Go to **Cookies** → `https://your-project.chromatic.com`
4. **Look for authentication cookies** - Common names include:
   - `__session` (most common)
   - `chromatic_session`
   - `auth` or `auth_token`
   - `__chromatic_auth`
   - Any cookie with a **long, random-looking value** (like `eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...`)
5. **Copy the Name and Value** for each authentication cookie
6. Use one of these formats:

**📖 For detailed step-by-step instructions with screenshots, see [COOKIE_EXTRACTION_GUIDE.md](./COOKIE_EXTRACTION_GUIDE.md)**

**JSON Array Format (example with `__session` cookie):**

```json
[
  {
    "name": "__session",
    "value": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...",
    "domain": ".chromatic.com",
    "path": "/"
  }
]
```

**If you have multiple cookies:**

```json
[
  {
    "name": "__session",
    "value": "abc123...",
    "domain": ".chromatic.com",
    "path": "/"
  },
  {
    "name": "auth_token",
    "value": "xyz789...",
    "domain": ".chromatic.com",
    "path": "/"
  }
]
```

**Cookie String Format:**

```
__session=abc123...; auth_token=xyz789...
```

**💡 Don't know which cookies to use?** Copy ALL cookies from the Chromatic domain and test them. The authentication will work if you include the right ones.

#### Cookie Expiration & Refresh

**Cookies expire when:**

- Your Chromatic session expires (after inactivity)
- You log out of Chromatic
- Your session is invalidated

**When cookies expire, you'll see:**

```
Error: Unauthorized: Invalid or missing authentication credentials
```

**To refresh cookies:**

1. Log in to Chromatic again in your browser
2. Extract cookies using the steps above
3. Update `CHROMATIC_COOKIES` in your MCP config
4. Restart Cursor/MCP client

**Tip**: Consider using a browser extension like "Cookie-Editor" to quickly export cookies when needed.

### Option 3: GitHub PAT (Limited Support)

Set the `GITHUB_PAT` environment variable. This may work for some Chromatic setups but is not reliable for private Storybooks with GitHub SSO.

## How It Works

1. **Component List**: The server fetches the Storybook's `index.json` file and extracts component information
2. **Documentation**: Transforms index.json entries into structured ComponentManifest format
3. **Props Information**: For component props, the server:
   - Finds the component's story ID from index.json
   - Constructs the Chromatic story URL: `{STORYBOOK_URL}/?path=/story/{storyId}`
   - Uses Playwright to load the page in a headless browser
   - Extracts the props table from the Controls tab
   - Returns the props information

## Supported Storybook URLs

The server works with Chromatic-hosted Storybook instances that expose an `index.json` file. The URL should point to the base Chromatic URL:

- `https://your-project.chromatic.com`
- `https://your-project.chromatic.com/index.json`

## Testing Authentication Locally

Before using the MCP server, you can test authentication locally:

```bash
# Set your environment variables
export STORYBOOK_URL="https://your-project.chromatic.com"
export CHROMATIC_COOKIES='[{"name":"session","value":"..."}]'

# Or use project token
export CHROMATIC_PROJECT_TOKEN="your-project-token"

# Run the test
npm run test:auth
```

This will test:

- ✅ Configuration loading
- ✅ Authentication methods (Project Token, Cookies, GitHub PAT)
- ✅ Fetching `index.json` from Chromatic
- ✅ Authentication headers

See [TESTING.md](./TESTING.md) for detailed testing instructions.

## Development

### Local Development

```bash
# Install dependencies
npm install

# Install Playwright browsers
npx playwright install chromium

# Build the project
npm run build

# Run in development mode
npm run dev

# Test authentication locally
npm run test:auth

# Type check
npm run typecheck

# Lint
npm run lint
```

### Building

```bash
npm run build
```

### Testing

```bash
npm test
```

## Requirements

- Node.js 18.0.0 or higher
- Chromium browser (automatically installed with Playwright)

## Error Handling

The server includes comprehensive error handling for:

- Missing or invalid Storybook URLs
- Network connectivity issues
- Authentication failures (401, 403, redirects)
- Component not found scenarios
- Playwright browser automation failures
- Malformed index.json responses

## Architecture

The server follows the same architecture pattern as other MCP servers in this workspace:

- **Main entry**: `src/index.ts` - Server initialization
- **Tools**: `src/tools/index.ts` - MCP tool implementations
- **Configuration**: `src/config/` - Environment variable handling
- **Types**: `src/types/` - TypeScript type definitions
- **Utilities**: `src/utils/` - Manifest fetching, formatting, authentication, Playwright

## Key Features

- ✅ Supports both Storybook v3 and v5 formats
- ✅ GitHub PAT authentication for index.json fetching
- ✅ Cookie-based authentication for Playwright
- ✅ Dual approach: simple component list + structured documentation
- ✅ Playwright-based props scraping from Chromatic pages
- ✅ Markdown and XML output formats
- ✅ Comprehensive error handling

## License

MIT

## Repository

Part of the [mcp-servers](https://github.com/david-gracia/mcp-servers) monorepo.