search_components

Instructions

Implementation Reference

• src/tools/search-components.ts:39-99 (handler)

  Main handler function executing the tool logic: input validation, Storybook stories fetching, filtering by query/searchIn (name/title/category/all), pagination, and formatted response.

  export async function handleSearchComponents(input: any) {
    try {
      const validatedInput = validateSearchComponentsInput(input);
      const client = new StorybookClient();
      const searchIn = validatedInput.searchIn || 'all';
      const query = validatedInput.query.toLowerCase();
  
      // Handle wildcard queries - if query is just "*" or empty, match everything
      const isWildcard = query === '*' || query === '' || query === '.*';
  
      const storiesIndex = await client.fetchStoriesIndex();
      const stories = storiesIndex.stories || storiesIndex.entries || {};
  
      const filterFn = (story: any, componentName: string, _category?: string) => {
        const storyTitle = story.title || '';
        const categoryParts = storyTitle.split('/').slice(0, -1);
        const storyCategory = categoryParts.length > 0 ? categoryParts.join('/') : undefined;
  
        if (isWildcard) {
          return true;
        }
  
        switch (searchIn) {
          case 'name':
            return componentName.toLowerCase().includes(query);
          case 'title':
            return storyTitle.toLowerCase().includes(query);
          case 'category':
            return storyCategory ? storyCategory.toLowerCase().includes(query) : false;
          case 'all':
          default:
            return (
              componentName.toLowerCase().includes(query) ||
              storyTitle.toLowerCase().includes(query) ||
              Boolean(storyCategory?.toLowerCase().includes(query))
            );
        }
      };
  
      const componentMap = mapStoriesToComponents(stories, { filterFn });
      const allResults = getComponentsArray(componentMap);
  
      // Apply pagination
      const paginationResult = applyPagination(allResults, {
        page: validatedInput.page,
        pageSize: validatedInput.pageSize,
      });
  
      const message = formatPaginationMessage(
        paginationResult,
        'Found',
        `matching "${validatedInput.query}", searched in: ${searchIn}`
      );
  
      return formatSuccessResponse(paginationResult.items, message);
    } catch (error) {
      return handleErrorWithContext(error, 'search components', {
        resource: 'component search results',
      });
    }
  }

• src/tools/search-components.ts:8-37 (schema)

  Tool object definition for 'search_components' including name, description, and inputSchema specifying parameters: query (required), searchIn, page, pageSize.

  export const searchComponentsTool: Tool = {
    name: 'search_components',
    description:
      'Search design system components by name, title, or category. Find UI components like modals, dialogs, popups, overlays, buttons, forms, cards, etc. Name is the component name only (e.g., "Modal", "Dialog"), title is the full story path (e.g., "Components/Overlays/Modal"), category is the grouping (e.g., "Components/Overlays"). Use "*" as query to list all components. Supports pagination for large result sets.',
    inputSchema: {
      type: 'object',
      properties: {
        query: {
          type: 'string',
          description:
            'The search query to match (e.g., "button", "form", "nav"). Use "*" to list all components. Case-insensitive partial matching.',
        },
        searchIn: {
          type: 'string',
          enum: ['name', 'title', 'category', 'all'],
          description:
            'Where to search: "name" (component name only), "title" (full path), "category" (grouping), or "all" (search everywhere, default)',
        },
        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: ['query'],
    },
  };

• src/index.ts:15-35 (registration)

  Registration in MCP server: 'search_components' handler mapped in toolHandlers Map and Tool object included in allTools array for listing.

  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],
  ]);
  
  const allTools = [
    tools.listComponentsTool,
    tools.getComponentHTMLTool,
    tools.getComponentVariantsTool,
    tools.searchComponentsTool,
    tools.getComponentDependenciesTool,
    tools.getThemeInfoTool,
    tools.getComponentByPurposeTool,
    tools.getExternalCSSTool,
  ];

• src/utils/validators.ts:30-35 (schema)

  Zod validation schema for SearchComponentsInput used in the tool handler validation.

  const SearchComponentsInputSchema = z.object({
    query: z.string(),
    searchIn: z.enum(['name', 'title', 'category', 'all']).optional(),
    page: z.number().int().positive().optional(),
    pageSize: z.number().int().min(1).max(100).optional(),
  });

• src/utils/validators.ts:94-108 (helper)

  Validation helper function that parses input using Zod schema and constructs typed SearchComponentsInput object.

  export function validateSearchComponentsInput(input: any): SearchComponentsInput {
    const parsed = SearchComponentsInputSchema.parse(input);
    const result: SearchComponentsInput = {
      query: parsed.query,
    };
    if (parsed.searchIn !== undefined) {
      result.searchIn = parsed.searchIn;
    }
    if (parsed.page !== undefined) {
      result.page = parsed.page;
    }
    if (parsed.pageSize !== undefined) {
      result.pageSize = parsed.pageSize;
    }
    return result;