Merge pull request #32 from storybookjs/copilot/add-manifest-provider-option

JReinhold · web-flow · commit 0196ae10219b · 2025-10-23T17:01:49.000+02:00
Add manifestProvider option to allow custom manifest retrieval
diff --git a/.changeset/beige-eagles-live.md b/.changeset/beige-eagles-live.md
@@ -0,0 +1,5 @@
+---
+'@storybook/mcp': patch
+---
+
+Support passing in a custom manifestProvider option to the MCP server, falling back to fetch() as the default
diff --git a/.github/instructions/mcp.instructions.md b/.github/instructions/mcp.instructions.md
@@ -88,6 +88,8 @@ Or with coverage enabled:
 pnpm test run --coverage
 ```
 
+**Important**: Vitest automatically clears all mocks between tests, so you should never need to call `vi.clearAllMocks()` in a `beforeEach` hook.
+
 ### Inspector Tool
 
 ```bash
diff --git a/.gitignore b/.gitignore
@@ -4,6 +4,7 @@ storybook-static/
 build-storybook.log
 .DS_Store
 .env
+coverage/
 
 # Turborepo
 .turbo
diff --git a/.prettierignore b/.prettierignore
@@ -1,2 +1,3 @@
 dist
 pnpm-lock.yaml
+coverage
diff --git a/packages/mcp/serve.ts b/packages/mcp/serve.ts
@@ -3,8 +3,12 @@ import { serve } from 'srvx';
 import fs from 'node:fs/promises';
 
 const storybookMcpHandler = await createStorybookMcpHandler({
-	// fetch the manifest from this local server, itself
-	source: 'http://localhost:13316/fixtures/full-manifest.fixture.json',
+	// Use the local path directly via manifestProvider
+	source: './fixtures/full-manifest.fixture.json',
+	manifestProvider: async (source) => {
+		// Read the manifest from the local file system
+		return await fs.readFile(source, 'utf-8');
+	},
 });
 
 serve({
@@ -15,15 +19,6 @@ serve({
 			return await storybookMcpHandler(req);
 		}
 
-		// Serve local manifests for the tools to use
-		if (pathname.startsWith('/fixtures')) {
-			try {
-				const fixture = await fs.readFile(`.${pathname}`, 'utf-8');
-				return new Response(fixture, {
-					headers: { 'Content-Type': 'application/json' },
-				});
-			} catch {}
-		}
 		return new Response('Not found', { status: 404 });
 	},
 	port: 13316,
diff --git a/packages/mcp/src/index.ts b/packages/mcp/src/index.ts
@@ -21,16 +21,8 @@ export type { StorybookContext } from './types.ts';
 
 type Handler = (req: Request, context?: StorybookContext) => Promise<Response>;
 
-type StorybookMcpHandlerOptions = {
-	/**
-	 * The default source URL for fetching component manifests.
-	 * Can be overridden per-request via context parameter.
-	 */
-	source?: string;
-};
-
 export const createStorybookMcpHandler = async (
-	options: StorybookMcpHandlerOptions = {},
+	options: StorybookContext = {},
 ): Promise<Handler> => {
 	const adapter = new ValibotJsonSchemaAdapter();
 	const server = new McpServer(
@@ -56,7 +48,9 @@ export const createStorybookMcpHandler = async (
 
 	return (async (req, context) => {
 		const source = context?.source ?? options.source;
+		const manifestProvider =
+			context?.manifestProvider ?? options.manifestProvider;
 
-		return await transport.respond(req, { source });
+		return await transport.respond(req, { source, manifestProvider });
 	}) as Handler;
 };
diff --git a/packages/mcp/src/tools/get-component-documentation.test.ts b/packages/mcp/src/tools/get-component-documentation.test.ts
@@ -7,11 +7,11 @@ import {
 } from './get-component-documentation.ts';
 import type { StorybookContext } from '../types.ts';
 import smallManifestFixture from '../../fixtures/small-manifest.fixture.json' with { type: 'json' };
-import * as fetchManifest from '../utils/fetch-manifest.ts';
+import * as getManifest from '../utils/get-manifest.ts';
 
 describe('getComponentDocumentationTool', () => {
 	let server: McpServer<any, StorybookContext>;
-	let fetchManifestSpy: any;
+	let getManifestSpy: any;
 
 	beforeEach(async () => {
 		const adapter = new ValibotJsonSchemaAdapter();
@@ -45,9 +45,9 @@ describe('getComponentDocumentationTool', () => {
 		);
 		await addGetComponentDocumentationTool(server);
 
-		// Mock fetchManifest to return the fixture
-		fetchManifestSpy = vi.spyOn(fetchManifest, 'fetchManifest');
-		fetchManifestSpy.mockResolvedValue(smallManifestFixture);
+		// Mock getManifest to return the fixture
+		getManifestSpy = vi.spyOn(getManifest, 'getManifest');
+		getManifestSpy.mockResolvedValue(smallManifestFixture);
 	});
 
 	it('should return formatted documentation for a single component', async () => {
@@ -266,8 +266,8 @@ describe('getComponentDocumentationTool', () => {
 	});
 
 	it('should handle fetch errors gracefully', async () => {
-		fetchManifestSpy.mockRejectedValue(
-			new fetchManifest.ManifestFetchError(
+		getManifestSpy.mockRejectedValue(
+			new getManifest.ManifestGetError(
 				'Failed to fetch manifest: 404 Not Found',
 				'https://example.com/manifest.json',
 			),
@@ -291,7 +291,7 @@ describe('getComponentDocumentationTool', () => {
 			{
 			  "content": [
 			    {
-			      "text": "Error fetching manifest: Failed to fetch manifest: 404 Not Found",
+			      "text": "Error getting manifest: Failed to fetch manifest: 404 Not Found",
 			      "type": "text",
 			    },
 			  ],
diff --git a/packages/mcp/src/tools/get-component-documentation.ts b/packages/mcp/src/tools/get-component-documentation.ts
@@ -1,7 +1,7 @@
 import * as v from 'valibot';
 import type { McpServer } from 'tmcp';
 import type { StorybookContext } from '../types.ts';
-import { fetchManifest, errorToMCPContent } from '../utils/fetch-manifest.ts';
+import { getManifest, errorToMCPContent } from '../utils/get-manifest.ts';
 import { formatComponentManifest } from '../utils/format-manifest.ts';
 
 export const GET_TOOL_NAME = 'get-component-documentation';
@@ -29,7 +29,10 @@ export async function addGetComponentDocumentationTool(
 		},
 		async (input: GetComponentDocumentationInput) => {
 			try {
-				const manifest = await fetchManifest(server.ctx.custom?.source);
+				const manifest = await getManifest(
+					server.ctx.custom?.source,
+					server.ctx.custom?.manifestProvider,
+				);
 
 				const content = [];
 				const notFoundIds: string[] = [];
diff --git a/packages/mcp/src/tools/list-all-components.test.ts b/packages/mcp/src/tools/list-all-components.test.ts
@@ -7,11 +7,11 @@ import {
 } from './list-all-components.ts';
 import type { StorybookContext } from '../types.ts';
 import smallManifestFixture from '../../fixtures/small-manifest.fixture.json' with { type: 'json' };
-import * as fetchManifest from '../utils/fetch-manifest.ts';
+import * as getManifest from '../utils/get-manifest.ts';
 
 describe('listAllComponentsTool', () => {
 	let server: McpServer<any, StorybookContext>;
-	let fetchManifestSpy: any;
+	let getManifestSpy: any;
 
 	beforeEach(async () => {
 		const adapter = new ValibotJsonSchemaAdapter();
@@ -45,9 +45,9 @@ describe('listAllComponentsTool', () => {
 		);
 		await addListAllComponentsTool(server);
 
-		// Mock fetchManifest to return the fixture
-		fetchManifestSpy = vi.spyOn(fetchManifest, 'fetchManifest');
-		fetchManifestSpy.mockResolvedValue(smallManifestFixture);
+		// Mock getManifest to return the fixture
+		getManifestSpy = vi.spyOn(getManifest, 'getManifest');
+		getManifestSpy.mockResolvedValue(smallManifestFixture);
 	});
 
 	it('should return a list of all components', async () => {
@@ -98,8 +98,8 @@ describe('listAllComponentsTool', () => {
 	});
 
 	it('should handle fetch errors gracefully', async () => {
-		fetchManifestSpy.mockRejectedValue(
-			new fetchManifest.ManifestFetchError(
+		getManifestSpy.mockRejectedValue(
+			new getManifest.ManifestGetError(
 				'Failed to fetch manifest: 404 Not Found',
 				'https://example.com/manifest.json',
 			),
@@ -121,7 +121,7 @@ describe('listAllComponentsTool', () => {
 			{
 			  "content": [
 			    {
-			      "text": "Error fetching manifest: Failed to fetch manifest: 404 Not Found",
+			      "text": "Error getting manifest: Failed to fetch manifest: 404 Not Found",
 			      "type": "text",
 			    },
 			  ],
@@ -131,7 +131,7 @@ describe('listAllComponentsTool', () => {
 	});
 
 	it('should handle unexpected errors gracefully', async () => {
-		fetchManifestSpy.mockRejectedValue(new Error('Network timeout'));
+		getManifestSpy.mockRejectedValue(new Error('Network timeout'));
 
 		const request = {
 			jsonrpc: '2.0' as const,
diff --git a/packages/mcp/src/tools/list-all-components.ts b/packages/mcp/src/tools/list-all-components.ts
@@ -1,6 +1,6 @@
 import type { McpServer } from 'tmcp';
 import type { StorybookContext } from '../types.ts';
-import { fetchManifest, errorToMCPContent } from '../utils/fetch-manifest.ts';
+import { getManifest, errorToMCPContent } from '../utils/get-manifest.ts';
 import { formatComponentManifestMapToList } from '../utils/format-manifest.ts';
 
 export const LIST_TOOL_NAME = 'list-all-components';
@@ -17,7 +17,10 @@ export async function addListAllComponentsTool(
 		},
 		async () => {
 			try {
-				const manifest = await fetchManifest(server.ctx.custom?.source);
+				const manifest = await getManifest(
+					server.ctx.custom?.source,
+					server.ctx.custom?.manifestProvider,
+				);
 
 				const componentList = formatComponentManifestMapToList(manifest);
 				return {
diff --git a/packages/mcp/src/types.ts b/packages/mcp/src/types.ts
@@ -2,13 +2,19 @@ import * as v from 'valibot';
 
 /**
  * Custom context passed to MCP server and tools.
- * Contains the source URL for fetching component manifests.
+ * Contains the source URL for getting component manifests.
  */
 export interface StorybookContext extends Record<string, unknown> {
 	/**
-	 * The URL of the remote manifest to fetch component data from.
+	 * The URL of the remote manifest to get component data from.
 	 */
 	source?: string;
+	/**
+	 * Optional function to provide custom manifest retrieval logic.
+	 * If provided, this function will be called instead of using fetch.
+	 * The function receives the source URL and should return the manifest as a string.
+	 */
+	manifestProvider?: (source: string) => Promise<string>;
 }
 
 const JSDocTag = v.record(v.string(), v.array(v.string()));
diff --git a/packages/mcp/src/utils/error-to-mcp-content.test.ts b/packages/mcp/src/utils/error-to-mcp-content.test.ts
@@ -1,10 +1,10 @@
 import { describe, it, expect } from 'vitest';
-import { errorToMCPContent, ManifestFetchError } from './fetch-manifest.ts';
+import { errorToMCPContent, ManifestGetError } from './get-manifest.ts';
 
 describe('errorToMCPContent', () => {
-	it('should convert ManifestFetchError to MCP error content', () => {
-		const error = new ManifestFetchError(
-			'Failed to fetch',
+	it('should convert ManifestGetError to MCP error content', () => {
+		const error = new ManifestGetError(
+			'Failed to get',
 			'https://example.com',
 		);
 
@@ -14,7 +14,7 @@ describe('errorToMCPContent', () => {
 			content: [
 				{
 					type: 'text',
-					text: 'Error fetching manifest: Failed to fetch',
+					text: 'Error getting manifest: Failed to get',
 				},
 			],
 			isError: true,
@@ -37,10 +37,10 @@ describe('errorToMCPContent', () => {
 		});
 	});
 
-	it('should handle ManifestFetchError with cause', () => {
+	it('should handle ManifestGetError with cause', () => {
 		const cause = new Error('Network error');
-		const error = new ManifestFetchError(
-			'Failed to fetch manifest',
+		const error = new ManifestGetError(
+			'Failed to get manifest',
 			'https://example.com',
 			cause,
 		);
@@ -51,23 +51,23 @@ describe('errorToMCPContent', () => {
 			content: [
 				{
 					type: 'text',
-					text: 'Error fetching manifest: Failed to fetch manifest\nCaused by: Network error',
+					text: 'Error getting manifest: Failed to get manifest\nCaused by: Network error',
 				},
 			],
 			isError: true,
 		});
 	});
 
-	it('should handle ManifestFetchError without URL', () => {
-		const error = new ManifestFetchError('Failed to fetch');
+	it('should handle ManifestGetError without URL', () => {
+		const error = new ManifestGetError('Failed to get');
 
 		const result = errorToMCPContent(error);
 
 		expect(result).toEqual({
 			content: [
 				{
 					type: 'text',
-					text: 'Error fetching manifest: Failed to fetch',
+					text: 'Error getting manifest: Failed to get',
 				},
 			],
 			isError: true,
diff --git a/packages/mcp/src/utils/fetch-manifest.test.ts b/packages/mcp/src/utils/fetch-manifest.test.ts
diff --git a/packages/mcp/src/utils/fetch-manifest.ts b/packages/mcp/src/utils/fetch-manifest.ts
diff --git a/packages/mcp/src/utils/get-manifest.test.ts b/packages/mcp/src/utils/get-manifest.test.ts
diff --git a/packages/mcp/src/utils/get-manifest.ts b/packages/mcp/src/utils/get-manifest.ts

-Original file line number
+Diff line change
@@ @@ -0,0 +1,5 @@ @@
 +---
 +'@storybook/mcp': patch
 +---
++
 +Support passing in a custom manifestProvider option to the MCP server, falling back to fetch() as the default
Original file line number	Diff line number	Diff line change
`@@ -1,2 +1,3 @@`
`1`	`1`	`dist`
`2`	`2`	`pnpm-lock.yaml`
	`3`	`+coverage`