code/lib/mcp/README.md
Reusable MCP package for Storybook component and docs knowledge.
Learn more about Storybook at storybook.js.org.
@storybook/mcpThis package is a library: the tarball ships one module and no executable. It declares no bin,
starts no process, and has no CLI. You register its tools on an MCP server you own, using the
snippets below. If you want a running Storybook MCP server with no code at all, use the dev server
instead — storybook dev serves one at /mcp through @storybook/addon-mcp.
components.json (required)docs.json (optional)The Storybook repository has a local HTTP server built on this package,
serve.ts, that loads
manifests from a directory or URL. It is a development harness and is not part of the published
package.
The snippets below cover the common self-hosting patterns.
import { createStorybookMcpHandler } from '@storybook/mcp';
const storybookMcpHandler = await createStorybookMcpHandler();
export async function handleRequest(request: Request): Promise<Response> {
if (new URL(request.url).pathname === '/mcp') {
return storybookMcpHandler(request);
}
return new Response('Not found', { status: 404 });
}
Use manifestProvider when your manifests are not available from the same origin/path layout:
const storybookMcpHandler = await createStorybookMcpHandler({
manifestProvider: async (_request, path) => {
return asyncReadManifestFromSomewhere(path);
},
});
createStorybookMcpHandlerType:
(options?: StorybookMcpHandlerOptions) => Promise<Handler>;
type Handler = (req: Request, context?: StorybookContext) => Promise<Response>;
Creates and configures an MCP HTTP handler with all built-in docs tools registered.
optionsType: StorybookMcpHandlerOptions
Default: {}
Server-level configuration. The handler uses this at creation time and as a fallback for per-request context.
Type: Promise<Handler>
A fetch-compatible request handler for your /mcp endpoint.
@tmcp/transport-http.Request as context.request.context overrides handler-level options for:
Note:
onSessionInitializecan only be set at handler creation time (inoptions).
import { createStorybookMcpHandler } from '@storybook/mcp';
const mcp = await createStorybookMcpHandler({
manifestProvider: async (_request, path) => {
return await fetchManifest(path);
},
});
export async function handleRequest(request: Request) {
if (new URL(request.url).pathname !== '/mcp') {
return new Response('Not found', { status: 404 });
}
return mcp(request);
}
@storybook/mcp uses the same core fields in two places:
createStorybookMcpHandler(options))handler(request, context))Type:
type StorybookContext = {
request?: Request;
manifestProvider?: (
request: Request | undefined,
path: string,
source?: Source,
) => Promise<string>;
sources?: Source[];
onListAllDocumentation?: (params: {
context: StorybookContext;
manifests: AllManifests;
resultText: string;
sources?: SourceManifests[];
}) => void | Promise<void>;
onGetDocumentation?: (
params:
| {
context: StorybookContext;
input: { id: string; storybookId?: string };
foundDocumentation: ComponentManifest | Doc;
resultText: string;
}
| {
context: StorybookContext;
input: { id: string; storybookId?: string };
},
) => void | Promise<void>;
};
type StorybookMcpHandlerOptions = StorybookContext & {
onSessionInitialize?: (initializeRequestParams: InitializeRequestParams) => void | Promise<void>;
};
[!NOTE]
onSessionInitializeis only used when provided at handler creation time (createStorybookMcpHandler(options)). It is ignored in per-requestcontext.
InitializeRequestParamsis thetmcpinitialize payload type, and its exact structure may change in patch versions. Prefer treating it as an opaque protocol payload unless you need specific fields.
manifestProviderType:
(request: Request | undefined, path: string, source?: Source) => Promise<string>;
Primary extension point for production setups.
Use this when manifests are not available at the default same-origin paths. Your function returns the raw JSON string for each requested manifest path.
For a real customization example (switching between HTTP and filesystem-backed manifest loading), see the Example implementation section above.
Manifest paths requested by built-in tools:
./manifests/components.json (required)./manifests/docs.json (optional)requestType: Request
The incoming HTTP request for the current call, as a Web Fetch API (WHATWG) Request.
This is not a Node.js http.IncomingMessage. In Node runtimes, pass a fetch-compatible Request (for example, Node's global Request from Undici in modern Node versions), or convert your server's native request object before calling the handler.
createStorybookMcpHandler automatically sets this field when you invoke the returned handler with (request, context?).
onListAllDocumentationType:
(params: {
context: StorybookContext;
manifests: AllManifests;
resultText: string;
sources?: SourceManifests[];
}) => void | Promise<void>
Optional callback after docs-list resolves successfully.
onGetDocumentationType:
(
params:
| {
context: StorybookContext;
input: { id: string; storybookId?: string };
foundDocumentation: ComponentManifest | Doc;
resultText: string;
}
| {
context: StorybookContext;
input: { id: string; storybookId?: string };
},
) => void | Promise<void>
Optional callback after docs-show runs:
foundDocumentation and resultText.context and input.sourcesType: Source[]
Optional multi-source configuration for composing multiple Storybook MCP sources. This is supported but relatively uncommon for most user setups.
SourceType:
type Source = {
id: string;
title: string;
url?: string;
};
Represents one Storybook source in multi-source mode.
SourceManifestsType:
type SourceManifests = {
source: Source;
componentManifest: ComponentManifestMap;
docsManifest?: DocsManifestMap;
error?: string;
notice?: RequiresOwnMcpNotice;
};
Represents fetched manifests, an error, or non-error routing guidance for a single source.
RequiresOwnMcpNoticeType:
type RequiresOwnMcpNotice = {
kind: 'requires-own-mcp';
endpoint: string;
};
Indicates that a composed Storybook source cannot be read through the local MCP proxy and should be accessed through its own MCP endpoint instead.
Use these when you want to build your own tmcp server instead of using createStorybookMcpHandler, while still reusing Storybook's docs tools.
This approach is useful when you need to:
[!IMPORTANT] These composition helpers are built for
tmcp'sMcpServerand cannot be directly composed into a server built with the official MCP TypeScript SDK (@modelcontextprotocol/sdk).
Minimal composition example:
import { McpServer } from 'tmcp';
import { ValibotJsonSchemaAdapter } from '@tmcp/adapter-valibot';
import {
addGetStoryDocumentationTool,
addGetDocumentationTool,
addListAllDocumentationTool,
type StorybookContext,
} from '@storybook/mcp';
const adapter = new ValibotJsonSchemaAdapter();
const server = new McpServer(
{ name: 'custom-mcp', version: '1.0.0' },
{
adapter,
capabilities: {
tools: { listChanged: true },
},
},
).withContext<StorybookContext>();
await addListAllDocumentationTool(server);
await addGetDocumentationTool(server);
await addGetStoryDocumentationTool(server);
After registration, wire your own transport and pass StorybookContext per request so tools can resolve manifests (request, manifestProvider, and optional sources).
addListAllDocumentationToolType:
(server: McpServer<any, StorybookContext>, enabled?: () => boolean | Promise<boolean>) =>
Promise<void>;
Registers the list tool that returns all component/docs IDs from manifests.
addGetDocumentationToolType:
(
server: McpServer<any, StorybookContext>,
enabled?: () => boolean | Promise<boolean>,
options?: { multiSource?: boolean },
) => Promise<void>;
Registers documentation lookup by component/docs id.
When options.multiSource is true, the tool schema requires storybookId input.
addGetStoryDocumentationToolType:
(
server: McpServer<any, StorybookContext>,
enabled?: () => boolean | Promise<boolean>,
options?: { multiSource?: boolean },
) => Promise<void>;
Registers story-level documentation lookup for a specific story variant by componentId and storyName.