Storybook MCP Server

Node CI npm license

Ein Model Context Protocol (MCP) Server, der Tools zur Interaktion mit Storybook-Dokumentationen und Komponenteninformationen bereitstellt.

Funktionen

getComponentList: Ruft eine Liste aller Komponenten aus einem konfigurierten Storybook ab
getComponentsProps: Ruft detaillierte Informationen zu Props für mehrere Komponenten mithilfe von Headless-Browser-Automatisierung ab
Custom Tools: Erstellen Sie benutzerdefinierte Tools, die mithilfe von JavaScript beliebige Informationen aus Ihren Storybook-Seiten extrahieren können

Related MCP server: MCP Server

Installation und Konfiguration

MCP-Einstellungen

Fügen Sie die folgende Konfiguration zu den MCP-Einstellungen hinzu:

{
  "mcpServers": {
    "storybook": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "<your_storybook_url>/index.json"
      }
    }
  }
}

storybook-mcp startet sofort und installiert beim ersten Ausführen Chromium im Hintergrund. Wenn Sie den Browser vorab installieren möchten, führen Sie npx -y storybook-mcp@latest install-browser aus. Bis dieser Download abgeschlossen ist, kann der erste Aufruf eines browserbasierten Tools länger dauern.

Umgebungsvariablen

STORYBOOK_URL (erforderlich): Die URL zu der index.json-Datei Ihres Storybooks
CUSTOM_TOOLS (optional): JSON-Array mit Definitionen für benutzerdefinierte Tools zum Extrahieren spezifischer Informationen aus Ihrem Storybook

Verwendung

Der Server bietet integrierte Tools und unterstützt benutzerdefinierte Tools:

Integrierte Tools

1. getComponentList

Ruft eine Liste aller verfügbaren Komponenten aus dem konfigurierten Storybook ab.

Beispiel:

Available components:
Accordion
Avatar
Badge
Button
...

2. getComponentsProps

Ruft detaillierte Informationen zu Props für mehrere Komponenten ab, einschließlich:

Eigenschaftsnamen
Typen
Standardwerte
Beschreibungen
Status (erforderlich/optional)

Parameter:

componentNames (Array von Strings): Array der Komponentennamen, für die Informationen zu den Props abgerufen werden sollen

Beispiel für die Verwendung:

Tool: getComponentsProps
Parameters: { "componentNames": ["Button", "Input", "Avatar"] }

Benutzerdefinierte Tools

Sie können benutzerdefinierte Tools definieren, um spezifische Informationen aus Ihren Storybook-Seiten zu extrahieren. Jedes benutzerdefinierte Tool kann:

Zu einer beliebigen Seite in Ihrem Storybook navigieren
Benutzerdefiniertes JavaScript ausführen, um Daten zu extrahieren
Strukturierte Daten an den KI-Assistenten zurückgeben

Struktur benutzerdefinierter Tools:

interface CustomTool {
  name: string; // Unique tool name
  description: string; // Tool description for the AI
  parameters: object; // Input parameters schema (optional)
  page: string; // URL to navigate to
  handler: string; // JavaScript code to execute on the page
}

Beispiel für benutzerdefinierte Tools:

[
  {
    "name": "getIconList",
    "description": "Get All Icons from the Icon page",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/icon--docs",
    "handler": "Array.from(document.querySelectorAll('.icon-name')).map(i => i.textContent)"
  },
  {
    "name": "getColorPalette",
    "description": "Extract color palette from design tokens",
    "parameters": {},
    "page": "https://your-storybook.com/?path=/docs/design-tokens--colors",
    "handler": "Array.from(document.querySelectorAll('.color-swatch')).map(el => ({ name: el.getAttribute('data-color-name'), value: el.style.backgroundColor }))"
  }
]

Weitere Beispiele und eine detaillierte Dokumentation finden Sie unter examples/custom-tools-example.md.

Beispiel

Konfigurieren Sie Spectrum storybook-mcp mit den Umgebungsvariablen STORYBOOK_URL und CUSTOM_TOOLS.

{
  "mcpServers": {
    "storybook-mcp": {
      "command": "npx",
      "args": ["-y", "storybook-mcp@latest"],
      "env": {
        "STORYBOOK_URL": "https://opensource.adobe.com/spectrum-web-components/storybook/index.json",
        "CUSTOM_TOOLS": "[{\"name\":\"getIconList\",\"description\":\"Get All Icons from the Icon page\",\"parameters\":{},\"page\":\"https://opensource.adobe.com/spectrum-web-components/storybook/iframe.html?viewMode=docs&id=icons--docs&globals=\",\"handler\":\"Array.from(document.querySelector('icons-demo').shadowRoot.querySelectorAll('.icon')).map(i => i.textContent)\"}]"
      }
    }
  }
}

Funktionsweise

Komponentenliste: Der Server ruft die index.json-Datei des Storybooks ab (v3 ist stories.json) und extrahiert alle Komponenten, die als Typ "docs" markiert sind
Props-Informationen: Für Komponenten-Props führt der Server folgende Schritte aus:
- Findet die Dokumentations-ID der Komponente aus der index.json
- Erstellt die iframe-URL für die Dokumentationsseite der Komponente
- Verwendet Playwright, um die Seite in einem Headless-Browser zu laden
- Extrahiert das HTML der Props-Tabelle aus der Dokumentation

Unterstützte Storybook-URLs

Der Server funktioniert mit jedem Storybook, das eine index.json-Datei bereitstellt (v3 ist stories.json). Gängige Muster:

https://your-storybook-domain.com/index.json
https://your-storybook-domain.com/storybook/index.json

Entwicklung

Lokale Entwicklung

Repository klonen
Abhängigkeiten installieren: yarn install
Playwright-Browser installieren: yarn install:browser
Umgebungsvariable setzen: export STORYBOOK_URL="your-storybook-url"
Im Entwicklungsmodus ausführen: yarn dev

Hinweis: Sie können alternativ auch npx @modelcontextprotocol/inspector tsx src/index.ts anstelle von yarn dev verwenden, falls Sie dies bevorzugen.

Build

yarn build

Testen

yarn test

Anforderungen

Node.js 18.0.0 oder höher
Chromium-Browser, installiert durch Playwright

Fehlerbehandlung

Der Server enthält eine umfassende Fehlerbehandlung für:

Fehlende oder ungültige Storybook-URLs
Netzwerkverbindungsprobleme
Szenarien, in denen Komponenten nicht gefunden werden
Fehler bei der Playwright-Browser-Automatisierung

Lizenz

Storybook MCP ist MIT-lizenziert.

storybook-mcp