Metadata-Version: 2.4
Name: storybook-mcp
Version: 0.1.0
Summary: MCP server for Storybook integration – browse, inspect, and scaffold components
Project-URL: Homepage, https://github.com/stevebrownlee/storybook-mcp
Project-URL: Documentation, https://github.com/stevebrownlee/storybook-mcp#readme
Project-URL: Repository, https://github.com/stevebrownlee/storybook-mcp.git
Project-URL: Issues, https://github.com/stevebrownlee/storybook-mcp/issues
Author-email: Steve Brownlee <steve@stevebrownlee.com>
License: MIT
License-File: LICENSE
Keywords: ai-agents,components,design-system,mcp,storybook
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp[cli]>=1.0.0
Requires-Dist: pydantic>=2.0.0
Description-Content-Type: text/markdown

# Storybook MCP Server

An MCP (Model Context Protocol) server that integrates with a running **Storybook** instance. It lets AI-powered coding tools browse your component library, inspect individual components, and scaffold brand-new components from natural language.

## Features

| Tool | Description |
|---|---|
| `storybook_list_components` | List & search every component in your running Storybook |
| `storybook_get_component` | Get stories, arg types, default args, and Storybook URLs for a component |
| `storybook_create_component` | Scaffold a component + Storybook story from a plain-English description |
| `storybook_compose_view` | Compose existing components into a higher-order page/view with layout, state, and wiring |

## Quick Start

### Prerequisites

- Python ≥ 3.10
- A running Storybook instance (v7+)
- [`uv`](https://docs.astral.sh/uv/) installed

### Install & run with `uvx`

```bash
# Run directly (no install needed)
uvx storybook-mcp

# Or install globally first
uv tool install storybook-mcp
storybook-mcp
```

### Install from source (development)

```bash
git clone https://github.com/yourname/storybook-mcp.git
cd storybook-mcp
uv sync
uv run storybook-mcp
```

---

## Configuration for AI Coding Tools

### Roo Code / Kilo Code (`mcp.json`)

Add this to your `~/.config/roo-code/mcp.json` (or the equivalent Kilo Code path):

```json
{
  "mcpServers": {
    "storybook": {
      "command": "uvx",
      "args": ["storybook-mcp"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006",
        "STORYBOOK_COMPONENTS_DIR": "src/components",
        "STORYBOOK_FRAMEWORK": "react",
        "STORYBOOK_STYLE_TECH": "tailwind",
        "STORYBOOK_TYPESCRIPT": "true"
      }
    }
  }
}
```

### Claude Desktop (`claude_desktop_config.json`)

```json
{
  "mcpServers": {
    "storybook": {
      "command": "uvx",
      "args": ["storybook-mcp"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006",
        "STORYBOOK_COMPONENTS_DIR": "src/components",
        "STORYBOOK_FRAMEWORK": "react",
        "STORYBOOK_STYLE_TECH": "css-modules",
        "STORYBOOK_TYPESCRIPT": "true"
      }
    }
  }
}
```

### Cursor / Windsurf

These editors read an `mcp.json` in your project root. Create `.cursor/mcp.json` or `.windsurf/mcp.json`:

```json
{
  "mcpServers": {
    "storybook": {
      "command": "uvx",
      "args": ["storybook-mcp"],
      "env": {
        "STORYBOOK_URL": "http://localhost:6006",
        "STORYBOOK_COMPONENTS_DIR": "src/components",
        "STORYBOOK_FRAMEWORK": "react",
        "STORYBOOK_STYLE_TECH": "tailwind",
        "STORYBOOK_TYPESCRIPT": "true"
      }
    }
  }
}
```

---

## Environment Variables

| Variable | Default | Description |
|---|---|---|
| `STORYBOOK_URL` | `http://localhost:6006` | URL of your running Storybook dev server |
| `STORYBOOK_COMPONENTS_DIR` | `src/components` | Where new components are scaffolded |
| `STORYBOOK_FRAMEWORK` | `react` | `react` · `vue` · `svelte` · `angular` |
| `STORYBOOK_STYLE_TECH` | `css-modules` | `css-modules` · `tailwind` · `styled-components` · `scss` · `css` |
| `STORYBOOK_TYPESCRIPT` | `true` | Generate TypeScript (`true`) or JavaScript (`false`) |

---

## Tool Details

### `storybook_list_components`

Lists every component registered in the running Storybook, grouped by title hierarchy. Supports optional search filtering.

**Parameters:**
- `search` (optional) — case-insensitive substring filter
- `response_format` — `"markdown"` (default) or `"json"`

### `storybook_get_component`

Returns detailed info for a single component: all its stories, arg types, initial args, tags, and direct Storybook URLs.

**Parameters:**
- `component_title` (required) — exact title path, e.g. `"Components/Button"`
- `response_format` — `"markdown"` (default) or `"json"`

### `storybook_create_component`

Scaffolds a new component file + Storybook CSF3 story from a natural-language description. Adapts to the configured framework, language, and styling approach.

**Parameters:**
- `name` (required) — PascalCase component name
- `description` (required) — natural-language description of the component
- `category` (optional) — Storybook hierarchy path, defaults to `"Components"`
- `props` (optional) — explicit prop definitions; auto-inferred from description if omitted

### `storybook_compose_view`

Composes existing Storybook components into a higher-order page or view. Fetches the live component catalog, resolves each child component's args/props, then generates a page file that imports and wires them together with layout, local state, and event handlers.

**Parameters:**
- `name` (required) — PascalCase page/view name, e.g. `"DashboardPage"`
- `description` (required) — natural-language description of the page: layout, data flow, user interactions
- `components` (optional) — explicit list of `ComponentPlacement` objects specifying which Storybook components to include, with optional prop overrides and wrapper elements. When omitted, components are auto-discovered from the description.
- `layout` (optional) — layout hint: `"grid"`, `"flex-row"`, `"flex-col"`, `"sidebar-main"`, `"stack"`, `"dashboard"`. Defaults to `"flex-col"`.
- `include_state` (optional) — generate `useState`/`useCallback` hooks and sample handlers (default `true`)
- `include_story` (optional) — also generate a Storybook story for the composed page (default `true`)
- `category` (optional) — Storybook category, defaults to `"Pages"`

**ComponentPlacement fields:**
- `component_title` — Storybook title path, e.g. `"Components/Button"`
- `instance_name` (optional) — alias when the same component appears multiple times
- `props_override` (optional) — key/value prop overrides as JS expression strings
- `wrapper` (optional) — wrapper element for layout control, e.g. `'<div className="col-span-6">'`

---

## Example Prompts

Once connected, try asking your AI tool:

> "List all the button components in Storybook"

> "Show me the details and args for the Components/Card component"

> "Create a new AlertBanner component with variants for info, warning, and error. It should have a title, message, and optional dismiss button. Use tailwind for styling."

> "Compose a SettingsPage using the Sidebar, Tabs, TextInput, Toggle, and Button components. Use a sidebar-main layout. The sidebar should have navigation links and the main area should have a tabbed form for profile, notifications, and security settings."

> "Build a DashboardView using the Card, Chart, DataTable, and Badge components in a dashboard grid layout. Each card should wrap a chart or table."

---

## License

MIT
