list_components
Discover available UI components in your design system or Storybook. View component names, categories, and stories to identify elements for building interfaces. Filter by category or use pagination for large libraries.
Instructions
List all UI components available in your design system/Storybook. Returns components like modals, dialogs, buttons, forms, cards, etc. with their names, categories, and stories. Use this to explore what components are available for building UI features. Use category="all" or omit category parameter to list all components. Supports pagination to handle large component libraries.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| category | No | Filter components by category path (e.g., "Components/Buttons", "Layout"). Use "all" or omit to list all components. | |
| page | No | Page number (1-based). Default is 1. | |
| pageSize | No | Number of components per page (1-100). Default is 50. |
Implementation Reference
- src/tools/list-components.ts:33-93 (handler)The main handler function that executes the list_components tool: validates input, fetches Storybook stories index, maps stories to components with optional category filter, applies pagination, and formats the response.export async function handleListComponents(input: any) { let validatedInput: any; try { validatedInput = validateListComponentsInput(input); const client = new StorybookClient(); const storiesIndex = await client.fetchStoriesIndex(); if (!storiesIndex) { throw new Error( 'Failed to fetch stories index - received null or undefined. Ensure Storybook is running and accessible at: ' + client.getStorybookUrl() ); } // Support both v3 (stories) and v4 (entries) format const storiesData = storiesIndex.stories || storiesIndex.entries; if (!storiesData || typeof storiesData !== 'object') { throw new Error( `Invalid stories index structure. Expected object with 'stories' or 'entries' property, got: ${JSON.stringify(storiesIndex).substring(0, 200)}... Check if your Storybook instance is properly configured.` ); } const stories = Object.values(storiesData); if (stories.length === 0) { return formatSuccessResponse( [], `No components found in Storybook at ${client.getStorybookUrl()}. Ensure your Storybook has stories configured and is accessible. Debug info: storiesData keys: ${Object.keys(storiesData).slice(0, 5).join(', ')}` ); } const filterFn = validatedInput.category && validatedInput.category !== 'all' ? (_story: any, _componentName: string, category?: string) => category === validatedInput.category : undefined; const componentMap = mapStoriesToComponents(storiesData, filterFn ? { filterFn } : {}); const allComponents = getComponentsArray(componentMap); // Apply pagination const paginationResult = applyPagination(allComponents, { page: validatedInput.page, pageSize: validatedInput.pageSize, }); const message = formatPaginationMessage( paginationResult, 'Found', `filter: ${validatedInput.category || 'none'}` ); return formatSuccessResponse(paginationResult.items, message); } catch (error) { return handleErrorWithContext(error, 'list components', { resource: 'components list', }); } }
- src/tools/list-components.ts:12-30 (schema)JSON schema for tool inputs: category (optional filter), page, pageSize.inputSchema: { type: 'object', properties: { category: { type: 'string', description: 'Filter components by category path (e.g., "Components/Buttons", "Layout"). Use "all" or omit to list all components.', }, page: { type: 'number', description: 'Page number (1-based). Default is 1.', }, pageSize: { type: 'number', description: 'Number of components per page (1-100). Default is 50.', }, }, required: [], },
- src/index.ts:15-24 (registration)Registers 'list_components' tool name to its handler function in the MCP server's toolHandlers Map.const toolHandlers = new Map<string, (input: any) => Promise<any>>([ ['list_components', tools.handleListComponents], ['get_component_html', tools.handleGetComponentHTML], ['get_component_variants', tools.handleGetComponentVariants], ['search_components', tools.handleSearchComponents], ['get_component_dependencies', tools.handleGetComponentDependencies], ['get_theme_info', tools.handleGetThemeInfo], ['get_component_by_purpose', tools.handleGetComponentByPurpose], ['get_external_css', tools.handleGetExternalCSS], ]);
- src/index.ts:26-35 (registration)Includes listComponentsTool in the allTools array for ListToolsRequest response.const allTools = [ tools.listComponentsTool, tools.getComponentHTMLTool, tools.getComponentVariantsTool, tools.searchComponentsTool, tools.getComponentDependenciesTool, tools.getThemeInfoTool, tools.getComponentByPurposeTool, tools.getExternalCSSTool, ];
- src/types/tools.ts:9-13 (schema)TypeScript type definition for ListComponentsInput, matching the tool's input schema.export interface ListComponentsInput { category?: string; page?: number; pageSize?: number; }