Storybook MCP

Storybook MCP - Guide du contributeur

Bienvenue dans le monorepo de l'addon Storybook MCP ! Ce projet permet aux agents IA de travailler plus efficacement avec Storybook en fournissant un serveur MCP (Model Context Protocol) qui expose les informations des composants UI et les flux de développement.

📦 Packages

Ce monorepo contient quatre packages principaux :

• @storybook/mcp - Bibliothèque MCP autonome pour servir la connaissance des composants Storybook (peut être utilisée indépendamment)
• @storybook/addon-mcp - Addon Storybook qui exécute un serveur MCP au sein de votre serveur de développement Storybook, et inclut les fonctionnalités de @storybook/mcp depuis votre Storybook local
• @storybook/claude-code-plugin - Plugin Claude Code avec des compétences de configuration Storybook et la configuration MCP
• @storybook/codex-plugin - Plugin Codex avec des compétences de configuration Storybook et la configuration MCP

Chaque package possède son propre README avec une documentation destinée aux utilisateurs. Ce document est destiné aux contributeurs qui souhaitent développer, tester ou contribuer à ces packages.

🚀 Démarrage rapide

Tester les plugins Claude et Codex depuis GitHub

Les testeurs externes peuvent installer le marketplace de plugins directement depuis la branche main de ce dépôt. Aucun clone local n'est requis.

Codex (plus de détails)

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

Vérifier le marketplace et le plugin :

codex plugin marketplace list
codex plugin list --marketplace storybook

Claude Code (plus de détails)

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

Vérifier le plugin et le serveur MCP :

claude plugin list --json
claude mcp list

Le dépôt conserve intentionnellement les catalogues du marketplace à deux endroits. Les catalogues racine prennent en charge les installations GitHub depuis storybookjs/mcp ; les catalogues locaux aux packages prennent en charge les scripts de développement locaux des packages. Ils doivent rester identiques à l'exception du chemin relatif de la source du plugin, et la validation du package vérifie qu'ils le sont.

Prérequis

• Node.js 24+ - Le projet nécessite Node.js 24 ou supérieur (voir .nvmrc)
• pnpm 10.19.0+ - Exigence stricte de gestionnaire de packages (appliquée dans package.json)

# Use the correct Node version
nvm use

# Install pnpm if you don't have it
npm install -g pnpm@10.19.0

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

Flux de développement

# 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

La commande Storybook démarre :

• L'instance Storybook de test interne sur http://localhost:6006
• L'addon en mode surveillance, afin que les modifications soient reflétées automatiquement
• Le serveur MCP disponible à l'adresse http://localhost:6006/mcp

🛠️ Tâches courantes

Développement

La commande turbo watch build exécute tous les packages en mode surveillance, reconstruisant automatiquement lorsque vous apportez des modifications :

# 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

Construction

# Build all packages
pnpm build

Tests

Le monorepo utilise une configuration Vitest centralisée au niveau racine avec des projets configurés pour chaque package :

# 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

Débogage des serveurs MCP

Utilisez l'inspecteur MCP pour déboguer et tester les fonctionnalités du serveur MCP :

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

Cela utilise la configuration dans .mcp.inspect.json pour se connecter à vos serveurs MCP locaux.

Alternativement, vous pouvez également utiliser ces commandes curl pour vérifier que tout fonctionne :

# 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": {}
    }
  }'

Débogage avec Storybook

Vous pouvez démarrer Storybook avec :

pnpm storybook

Cela construira tout et démarrera Storybook avec addon-mcp, et vous pourrez alors connecter votre agent de codage à l'adresse http://localhost:6006/mcp (ou votre point de terminaison d'addon configuré) et l'essayer.

Travailler avec l'application MCP

Pour travailler avec et déboguer l'application MCP qui est rendue dans le cadre de l'outil preview-stories, vous pouvez :

1. Utiliser la version Insiders de VSCode
2. S'assurer que le paramètre chat.mcp.apps.enabled est activé
3. Démarrer le Storybook du dépôt en mode surveillance en exécutant pnpm storybook à la racine
4. Redémarrer VSCode et, ouvrir le fichier .vscode/mcp.json et s'assurer que le Storybook MCP est marqué comme En cours d'exécution, sinon cliquer sur Démarrer.
5. Ouvrir un chat dans VSCode et écrire une invite comme celle-ci :

Montre-moi à quoi ressemblent toutes les stories de boutons, en utilisant le Storybook MCP

6. Après cette première invite, chaque fois que vous apportez des modifications, Storybook redémarre automatiquement. Attendez qu'il soit complètement prêt, puis vous pouvez demander "Exécute à nouveau l'outil".

Vous pouvez également utiliser l'inspecteur de MCPJam pour avoir un contrôle de plus bas niveau sur les appels d'outils.

Formatage & 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

🔍 Contrôles qualité

Le monorepo inclut plusieurs contrôles qualité qui s'exécutent dans la CI :

# 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

📝 Conventions de code

TypeScript & Imports

Toujours inclure les extensions de fichier dans les imports relatifs :

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

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

• Les imports JSON utilisent la syntaxe des attributs d'import :

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

🚢 Processus de publication

Ce projet utilise Changesets pour la gestion des versions :

# 1. Create a changeset describing your changes
pnpm changeset

Lorsque vous créez une PR, ajoutez un changeset si vos modifications doivent déclencher une publication :

• Patch : Corrections de bugs, mises à jour de la documentation
• Mineur : Nouvelles fonctionnalités, modifications rétrocompatibles
• Majeur : Modifications incompatibles

🤝 Contribuer

Nous accueillons les contributions avec plaisir ! Voici comment commencer :

1. Forker le dépôt et créer une branche de fonctionnalité
2. Apporter vos modifications en suivant les conventions de code ci-dessus
3. Tester vos modifications en utilisant l'instance Storybook interne
4. Créer un changeset si vos modifications justifient une publication
5. Soumettre une pull request avec une description claire

Avant de soumettre

• Le code se construit sans erreurs (pnpm build)
• Les tests passent (pnpm test:run)
• Le code est formaté (pnpm format)
• Le code est linté (pnpm lint)
• La vérification de type passe (pnpm typecheck)
• Modifications testées avec l'inspecteur MCP ou le Storybook interne
• Changeset créé si nécessaire (pnpm changeset)

Obtenir de l'aide

• Idées & Demandes de fonctionnalités : Lancer une discussion
• Rapports de bugs : Ouvrir un ticket
• Questions : Demander dans GitHub Discussions

📄 Licence

MIT - Voir LICENSE pour plus de détails

---

Note : Ce projet est expérimental et en développement actif. Les API et l'architecture peuvent changer à mesure que nous explorons les meilleures façons d'intégrer les agents IA avec Storybook.