list_components

Instructions

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;
  }