get_component_by_purpose
Search and retrieve design system components based on their specific purpose, such as form inputs, navigation, or feedback. Use this tool to quickly locate UI elements for building features.
Instructions
Find design system components by their purpose or use case. Available purposes: "form inputs" (input fields, selects, checkboxes), "navigation" (menus, breadcrumbs, tabs), "feedback" (alerts, toasts, modals, dialogs, popups), "data display" (tables, cards, lists), "layout" (grids, containers, dividers), "buttons" (all button types), "progress" (loaders, spinners), "media" (images, videos, carousels). Use this when looking for components to build specific UI features. Supports pagination for large result sets.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number (1-based). Default is 1. | |
| pageSize | No | Number of components per page (1-100). Default is 50. | |
| purpose | Yes | The purpose to search for (e.g., "form inputs", "navigation", "feedback", "data display") |
Input Schema (JSON Schema)
{
"properties": {
"page": {
"description": "Page number (1-based). Default is 1.",
"type": "number"
},
"pageSize": {
"description": "Number of components per page (1-100). Default is 50.",
"type": "number"
},
"purpose": {
"description": "The purpose to search for (e.g., \"form inputs\", \"navigation\", \"feedback\", \"data display\")",
"type": "string"
}
},
"required": [
"purpose"
],
"type": "object"
}
Implementation Reference
- The main execution handler for the 'get_component_by_purpose' tool. Validates input, fetches Storybook stories, matches components using purpose-specific regex patterns or dynamic patterns, maps stories to components, applies pagination, and returns a formatted response.export async function handleGetComponentByPurpose(input: any) { let validatedInput: any; try { validatedInput = validateGetComponentByPurposeInput(input); const purposeLower = validatedInput.purpose.toLowerCase(); const client = new StorybookClient(); // Fetch all components const index = await client.fetchStoriesIndex(); const stories = index.stories || index.entries; if (!stories) { throw new Error('No stories found in Storybook index'); } // Find matching purpose patterns let patterns: RegExp[] = []; let description = ''; // Check predefined purposes if (PURPOSE_PATTERNS[purposeLower]) { patterns = PURPOSE_PATTERNS[purposeLower].patterns; description = PURPOSE_PATTERNS[purposeLower].description; } else { // Create patterns from the purpose string const words = purposeLower.split(/\s+/); patterns = words.map((word: string) => new RegExp(word, 'i')); description = `Components related to ${validatedInput.purpose}`; } // Create filter function for purpose matching const filterFn = (story: any, componentName: string) => { const componentTitle = story.title || ''; const storyName = story.name || story.story || ''; return patterns.some( pattern => pattern.test(componentTitle) || pattern.test(storyName) || pattern.test(componentName) ); }; const componentMap = mapStoriesToComponents(stories, { filterFn, useComponentKey: 'title', }); const allComponents = getComponentsArray(componentMap); // Apply pagination const paginationResult = applyPagination(allComponents, { page: validatedInput.page, pageSize: validatedInput.pageSize, }); const result: ComponentByPurpose = { purpose: validatedInput.purpose, components: paginationResult.items, description, }; const message = formatPaginationMessage( paginationResult, 'Found', `for purpose: ${validatedInput.purpose}` ); return formatSuccessResponse(result, message); } catch (error) { return handleErrorWithContext(error, 'get components by purpose', { resource: 'components by purpose', }); } }
- src/utils/validators.ts:53-57 (schema)Zod schema for validating the input to get_component_by_purpose tool, used in the validateGetComponentByPurposeInput function.const GetComponentByPurposeInputSchema = z.object({ purpose: z.string(), page: z.number().int().positive().optional(), pageSize: z.number().int().min(1).max(100).optional(), });
- src/index.ts:15-24 (registration)Registers the handleGetComponentByPurpose handler in the toolHandlers Map used by the MCP server for tool calls.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:27-35 (registration)Registers the getComponentByPurposeTool (including schema) in the allTools array returned by ListTools.tools.listComponentsTool, tools.getComponentHTMLTool, tools.getComponentVariantsTool, tools.searchComponentsTool, tools.getComponentDependenciesTool, tools.getThemeInfoTool, tools.getComponentByPurposeTool, tools.getExternalCSSTool, ];
- src/tools/index.ts:10-13 (registration)Exports the tool definition and handler for use in src/index.ts registration.export { getComponentByPurposeTool, handleGetComponentByPurpose, } from './get-component-by-purpose.js';
- Defines predefined regex patterns and descriptions for common component purposes used in matching logic.const PURPOSE_PATTERNS: Record<string, { patterns: RegExp[]; description: string }> = { 'form inputs': { patterns: [ /input/i, /textfield/i, /textarea/i, /select/i, /dropdown/i, /checkbox/i, /radio/i, /switch/i, /toggle/i, /slider/i, /datepicker/i, /timepicker/i, /form/i, /field/i, ], description: 'Components for collecting user input in forms', }, navigation: { patterns: [ /nav/i, /menu/i, /breadcrumb/i, /tabs?/i, /stepper/i, /pagination/i, /link/i, /sidebar/i, /drawer/i, /appbar/i, /toolbar/i, /header/i, ], description: 'Components for navigating through the application', }, feedback: { patterns: [ /alert/i, /snackbar/i, /toast/i, /notification/i, /message/i, /error/i, /warning/i, /success/i, /info/i, /banner/i, /dialog/i, /modal/i, /popup/i, /tooltip/i, /popover/i, ], description: 'Components for providing feedback to users', }, 'data display': { patterns: [ /table/i, /datagrid/i, /list/i, /card/i, /chip/i, /badge/i, /avatar/i, /image/i, /icon/i, /typography/i, /text/i, /label/i, /tag/i, ], description: 'Components for displaying data and content', }, layout: { patterns: [ /grid/i, /container/i, /box/i, /stack/i, /flex/i, /spacer/i, /divider/i, /layout/i, /panel/i, /section/i, /wrapper/i, /column/i, /row/i, ], description: 'Components for structuring and laying out content', }, buttons: { patterns: [/button/i, /fab/i, /icon.*button/i, /action/i, /cta/i], description: 'Interactive button components', }, progress: { patterns: [ /progress/i, /loading/i, /spinner/i, /skeleton/i, /loader/i, /circular.*progress/i, /linear.*progress/i, ], description: 'Components for showing loading and progress states', }, media: { patterns: [ /image/i, /video/i, /audio/i, /media/i, /gallery/i, /carousel/i, /slider/i, /player/i, ], description: 'Components for displaying media content', }, };