mcp copilot-instructions.md

Copilot Instructions for Storybook MCP Addon

Architecture Overview

This is a pnpm monorepo with two MCP implementations:

• packages/addon-mcp: Storybook addon using tmcp, exposes MCP server at /mcp via Vite middleware
  • Provides addon-specific tools (story URLs, UI building instructions)
  • Imports and reuses tools from @storybook/mcp package for component manifest features
  • Extends StorybookContext with addon-specific configuration (AddonContext)
• packages/mcp: Standalone MCP library using tmcp, reusable outside Storybook
  • Provides reusable component manifest tools (list components, get documentation)
  • Exports tools and types for consumption by addon-mcp
• apps/internal-storybook: Test environment for addon integration

Both packages use tmcp with HTTP transport and Valibot schema validation for consistent APIs.

Addon Architecture

The addon uses a Vite plugin workaround to inject middleware (see packages/addon-mcp/src/preset.ts):

• Storybook doesn't expose an API for addons to register server middleware
• Solution: Inject a Vite plugin via viteFinal that adds /mcp endpoint
• Handler in mcp-handler.ts creates MCP servers using tmcp with HTTP transport

Toolset Configuration:

The addon supports configuring which toolsets are enabled:

• Addon Options: Configure default toolsets in .storybook/main.js:

  {
    name: '@storybook/addon-mcp',
    options: {
      toolsets: {
        dev: true,
        docs: true,
      }
    }
  }
  

• Per-Request Override: MCP clients can override toolsets per-request using the X-MCP-Toolsets header:
  • Header format: comma-separated list (e.g., dev,docs)
  • When header is present, only specified toolsets are enabled (others are disabled)
  • When header is absent, addon options are used
• Tool Enablement: Tools use the enabled callback to check if their toolset is active:

  server.tool(
  	{
  		name: 'my-tool',
  		enabled: () => server.ctx.custom?.toolsets?.dev ?? true,
  	},
  	handler,
  );
  

• Context-Aware: The getToolsets() function in mcp-handler.ts parses the header and returns enabled toolsets, which are passed to tools via AddonContext.toolsets