Storybook MCP Server

offiziell

Hilft Agenten, automatisch Stories für Ihre UI-Komponenten zu schreiben und zu testen.

Dokumentation

Storybook MCP – Leitfaden für Mitwirkende

Willkommen im Monorepo des Storybook MCP Addons! Dieses Projekt ermöglicht KI-Agenten ein effizienteres Arbeiten mit Storybook, indem es einen MCP-Server (Model Context Protocol) bereitstellt, der Informationen zu UI-Komponenten und Entwicklungsworkflows zugänglich macht.

📦 Pakete

Dieses Monorepo enthält vier Hauptpakete:

@storybook/mcp – Eigenständige MCP-Bibliothek zur Bereitstellung von Storybook-Komponentenwissen (kann unabhängig verwendet werden)
@storybook/addon-mcp – Storybook-Addon, das einen MCP-Server innerhalb Ihres Storybook-Entwicklungsservers ausführt und die Funktionalität von @storybook/mcp aus Ihrem lokalen Storybook einbindet
@storybook/claude-code-plugin – Claude-Code-Plugin mit Storybook-Einrichtungsfähigkeiten und MCP-Konfiguration
@storybook/codex-plugin – Codex-Plugin mit Storybook-Einrichtungsfähigkeiten und MCP-Konfiguration

Jedes Paket verfügt über eine eigene README mit benutzerorientierter Dokumentation. Dieses Dokument richtet sich an Mitwirkende, die diese Pakete entwickeln, testen oder zu ihnen beitragen möchten.

🚀 Schnellstart

Testen der Claude- und Codex-Plugins von GitHub

Externe Tester können den Plugin-Marktplatz direkt aus dem main-Branch dieses Repositorys installieren. Ein lokaler Klon ist nicht erforderlich.

Codex

codex plugin marketplace add storybookjs/mcp --ref main
codex plugin add storybook@storybook

Überprüfen Sie den Marktplatz und das Plugin:

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code

claude plugin marketplace add storybookjs/mcp@main --scope user
claude plugin install storybook@storybook --scope user

Überprüfen Sie das Plugin und den MCP-Server:

claude plugin list --json
claude mcp list

Das Repository bewahrt Marktplatz-Kataloge bewusst an zwei Orten auf. Die Stammkataloge unterstützen GitHub-Installationen von storybookjs/mcp; die paketlokalen Kataloge unterstützen lokale Paketentwicklungsskripte. Sie sollten identisch sein, mit Ausnahme des relativen Plugin-Quellpfads, und die Paketvalidierung prüft dies.

Voraussetzungen

Node.js 24+ – Das Projekt erfordert Node.js 24 oder höher (siehe .nvmrc)
pnpm 10.19.0+ – Strikte Paketmanager-Anforderung (erzwungen in package.json)

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g [email protected]

Installation

# Clone the repository
git clone https://github.com/storybookjs/mcp.git
cd addon-mcp

# Install all dependencies (for all packages in the monorepo)
pnpm install

Entwicklungsworkflow

# Build all packages
pnpm build

# Start development mode (watches for changes in all packages)
pnpm dev

# Run unit tests in watch mode
pnpm test

# Run unit tests once
pnpm test:run

# Run Storybook with the addon for testing
pnpm --filter internal-storybook storybook

Der Storybook-Befehl startet:

Die interne Test-Storybook-Instanz auf http://localhost:6006
Das Addon im Watch-Modus, sodass Änderungen automatisch übernommen werden
MCP-Server verfügbar unter http://localhost:6006/mcp

🛠️ Häufige Aufgaben

Entwicklung

Der Befehl turbo watch build führt alle Pakete im Watch-Modus aus und baut sie bei Änderungen automatisch neu:

# Start development mode for all packages
pnpm turbo watch build

# This is usually all you need - starts Storybook AND watches addon for changes
pnpm storybook

Bauen

# Build all packages
pnpm build

Testen

Das Monorepo verwendet eine zentrale Vitest-Konfiguration auf Stammebene mit für jedes Paket konfigurierten Projekten:

# Watch tests across all packages
pnpm test

# Run tests once across all packages
pnpm test:run

# Run tests with coverage and CI reporters
pnpm test:ci

Debugging von MCP-Servern

Verwenden Sie den MCP Inspector, um die MCP-Serverfunktionalität zu debuggen und zu testen:

# Launches the MCP inspector (requires Storybook to be running)
pnpm inspect

Dies verwendet die Konfiguration in .mcp.inspect.json, um eine Verbindung zu Ihren lokalen MCP-Servern herzustellen.

Alternativ können Sie auch diese curl-Befehle verwenden, um zu prüfen, ob alles funktioniert:

# test that the mcp server is running
# use port 6006 to test the addon-mcp server instead
curl -X POST \
  http://localhost:13316/mcp      \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

# test a specific tool call
curl -X POST http://localhost:13316/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/call",
    "params": {
      "name": "list-all-documentation",
      "arguments": {}
    }
  }'

Debugging mit Storybook

Sie können Storybook starten mit:

pnpm storybook

Dies baut alles und startet Storybook mit addon-mcp. Sie können dann Ihren Coding-Agenten unter http://localhost:6006/mcp (oder Ihrem konfigurierten Addon-Endpunkt) damit verbinden und es ausprobieren.

Arbeiten mit der MCP-App

Um mit der MCP-App zu arbeiten und sie zu debuggen, die als Teil des Preview-Stories-Tools gerendert wird, können Sie:

Den Insiders-Build von VSCode verwenden
Sicherstellen, dass die Einstellung chat.mcp.apps.enabled aktiviert ist
Das Storybook des Repos im Watch-Modus starten, indem Sie pnpm storybook im Stammverzeichnis ausführen
VSCode neu starten und die Datei .vscode/mcp.json öffnen und sicherstellen, dass das Storybook MCP als „Wird ausgeführt“ markiert ist, andernfalls auf „Starten“ klicken.
Einen Chat in VSCode öffnen und eine Eingabeaufforderung wie diese schreiben:

Zeige mir, wie alle Button-Stories aussehen, unter Verwendung des Storybook MCP

Nach dieser ersten Eingabeaufforderung startet Storybook bei Änderungen automatisch neu. Warten Sie, bis es vollständig bereit ist, dann können Sie die Aufforderung "Das Tool erneut ausführen" eingeben.

Sie können auch den Inspector von MCPJam verwenden, um eine detailliertere Kontrolle über die Tool-Aufrufe zu haben.

Formatierung & Linting

# Format all files with Prettier
pnpm format

# Check formatting without changing files
pnpm format:check

# Lint code with oxlint
pnpm lint

# Lint with GitHub Actions format (for CI)
pnpm lint:ci

# Check package exports with publint
pnpm publint

🔍 Qualitätsprüfungen

Das Monorepo umfasst mehrere Qualitätsprüfungen, die in der CI ausgeführt werden:

# Run all checks (build, test, lint, format, typecheck, publint)
pnpm check

# Run checks in watch mode (experimental)
pnpm check:watch

# Type checking (uses tsc directly, not turbo)
pnpm typecheck

# Type checking with turbo (for individual packages)
pnpm turbo:typecheck

# Testing with turbo (for individual packages)
pnpm turbo:test

📝 Code-Konventionen

TypeScript & Imports

Immer Dateierweiterungen in relativen Imports einschließen:

// ✅ Correct
import { foo } from './bar.ts';

// ❌ Wrong
import { foo } from './bar';

JSON-Imports verwenden die Import-Attribut-Syntax:

import pkg from '../package.json' with { type: 'json' };

🚢 Release-Prozess

Dieses Projekt verwendet Changesets für die Versionsverwaltung:

# 1. Create a changeset describing your changes
pnpm changeset

Wenn Sie einen PR erstellen, fügen Sie ein Changeset hinzu, falls Ihre Änderungen einen Release auslösen sollen:

Patch: Fehlerbehebungen, Dokumentationsaktualisierungen
Minor: Neue Funktionen, rückwärtskompatible Änderungen
Major: Breaking Changes

🤝 Mitwirken

Wir freuen uns über Beiträge! So können Sie beginnen:

Repository forken und einen Feature-Branch erstellen
Ihre Änderungen vornehmen und dabei die obigen Code-Konventionen befolgen
Ihre Änderungen testen mit der internen Storybook-Instanz
Ein Changeset erstellen, falls Ihre Änderungen einen Release rechtfertigen
Einen Pull Request einreichen mit einer klaren Beschreibung

Vor dem Einreichen

Code baut ohne Fehler (pnpm build)
Tests bestehen (pnpm test:run)
Code ist formatiert (pnpm format)
Code ist gelintet (pnpm lint)
Typüberprüfung besteht (pnpm typecheck)
Änderungen mit MCP Inspector oder internem Storybook getestet
Changeset erstellt, falls erforderlich (pnpm changeset)

Hilfe erhalten

Ideen & Funktionswünsche: Eine Diskussion starten
Fehlerberichte: Ein Issue eröffnen
Fragen: In den GitHub Discussions stellen

📄 Lizenz

MIT – Siehe LICENSE für Details

Hinweis: Dieses Projekt ist experimentell und befindet sich in aktiver Entwicklung. APIs und Architektur können sich ändern, während wir die besten Wege zur Integration von KI-Agenten mit Storybook erkunden.