mcp addon-mcp.instructions.md

Copilot Instructions for @storybook/addon-mcp

Project Overview

This is a Storybook addon that runs an MCP (Model Context Protocol) server within Storybook's dev server to help AI agents develop UI components more efficiently. The addon exposes MCP tools via an HTTP endpoint at /mcp when Storybook is running.

Architecture

Key Components

• MCP Server: Built using tmcp library with HTTP transport
• Vite Plugin Middleware: Workaround to inject /mcp endpoint into Storybook's dev server
• Tools System: Extensible tool registration using server.tool() method
• Toolsets Configuration: Configurable tool groups that can be toggled via addon options or per-request headers
• Context-Based Architecture: AddonContext passed through to all tools containing Storybook options and runtime info
• Schema Validation: Uses Valibot for JSON schema validation via @tmcp/adapter-valibot
• Telemetry: Usage tracking with opt-out via Storybook's disableTelemetry config

Toolsets

The addon supports two toolsets that can be enabled/disabled:

1. dev (default: true)

   • preview-stories: Retrieve story preview URLs from Storybook
   • get-storybook-story-instructions: Provide UI development guidelines

2. docs (default: true)

   • list-all-documentation: List all available components from manifest
   • get-documentation: Get detailed component documentation

Configuration Methods:

1. Addon Options (.storybook/main.js):

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

1. Per-Request Header (X-MCP-Toolsets):
   • Comma-separated list of toolset names
   • Example: X-MCP-Toolsets: dev,docs
   • When present, overrides addon options (all toolsets default to disabled except those in header)
   • When absent, uses addon options

Implementation:

• getToolsets() function in mcp-handler.ts parses the header and merges with addon options
• Tools use enabled callback to check if their toolset is active:

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

• AddonContext.toolsets contains the resolved toolset configuration