list_components

Instructions

Implementation Reference

• src/tools/components/list-components.ts:1-23 (handler)

  The main handler function 'handleListComponents' that executes the tool logic. It fetches available components via axios (which calls GitHub API), sorts them, and returns the list as JSON text.

  import { getAxiosImplementation } from '../../utils/framework.js';
  import { logError } from '../../utils/logger.js';
  
  export async function handleListComponents() {
    try {
      const axios = await getAxiosImplementation();
      const components = await axios.getAvailableComponents();
      return {
        content: [{ 
          type: "text", 
          text: JSON.stringify({ 
            components: components.sort(),
            total: components.length 
          }, null, 2) 
        }]
      };
    } catch (error) {
      logError('Failed to list components', error);
      throw new Error(`Failed to list components: ${error instanceof Error ? error.message : String(error)}`);
    }
  }
  
  export const schema = {}; 

• src/tools/components/list-components.ts:23-23 (schema)

  The schema for list_components is an empty object (no input parameters required).

  export const schema = {}; 

• src/tools/index.ts:3-3 (registration)

  Import of the handleListComponents function into the central tools registry.

  import { handleListComponents } from './components/list-components.js';

• src/tools/index.ts:14-14 (registration)

  Import of the listComponentsSchema (empty object) into the central tools registry.

  import { schema as listComponentsSchema } from './components/list-components.js';

• src/tools/index.ts:23-23 (registration)

  Registration of list_components tool handler in the toolHandlers map.

  list_components: handleListComponents,

• src/tools/index.ts:36-36 (registration)

  Registration of listComponentsSchema in the toolSchemas map.

  list_components: listComponentsSchema,

• src/tools/index.ts:65-72 (registration)

  Full tool definition for 'list_components' including name, description, and inputSchema (no required params).

  'list_components': {
    name: 'list_components',
    description: 'Get all available shadcn/ui v4 components',
    inputSchema: {
      type: 'object',
      properties: {}
    }
  },

• src/utils/framework.ts:120-136 (helper)

  The getAxiosImplementation helper that selects the right axios module based on the configured framework (react, svelte, vue, or react-native). Used by the handler to get the correct axios instance.

  export async function getAxiosImplementation() {
    const framework = getFramework();
  
    if (framework === "svelte") {
      // Dynamic import for Svelte implementation
      return import("./axios-svelte.js").then((module) => module.axios);
    } else if (framework === "vue") {
      // Dynamic import for Vue implementation
      return import("./axios-vue.js").then((module) => module.axios);
    } else if (framework === "react-native") {
      // Dynamic import for React Native implementation
      return import("./axios-react-native.js").then((module) => module.axios);
    } else {
      // Dynamic import for React implementation (default)
      return import("./axios.js").then((module) => module.axios);
    }
  }

• src/utils/axios.ts:92-139 (helper)

  The getAvailableComponents function that actually fetches the component list from the GitHub API (or falls back to a hardcoded list of known shadcn/ui v4 components).

  async function getAvailableComponents(): Promise<string[]> {
      const basePath = getRegistryBasePath();
      try {
          // First try the GitHub API
          const response = await githubApi.get(`/repos/${REPO_OWNER}/${REPO_NAME}/contents/${basePath}/ui`);
          
          if (!response.data || !Array.isArray(response.data)) {
              throw new Error('Invalid response from GitHub API');
          }
          
          const components = response.data
              .filter((item: any) => item.type === 'file' && item.name.endsWith('.tsx'))
              .map((item: any) => item.name.replace('.tsx', ''));
              
          if (components.length === 0) {
              throw new Error('No components found in the registry');
          }
          
          return components;
      } catch (error: any) {
          logError('Error fetching components from GitHub API', error);
          
          // Check for specific error types
          if (error.response) {
              const status = error.response.status;
              const message = error.response.data?.message || 'Unknown error';
              
              if (status === 403 && message.includes('rate limit')) {
                  throw new Error(`GitHub API rate limit exceeded. Please set GITHUB_PERSONAL_ACCESS_TOKEN environment variable for higher limits. Error: ${message}`);
              } else if (status === 404) {
                  throw new Error(`Components directory not found. The path ${basePath}/ui may not exist in the repository.`);
              } else if (status === 401) {
                  throw new Error(`Authentication failed. Please check your GITHUB_PERSONAL_ACCESS_TOKEN if provided.`);
              } else {
                  throw new Error(`GitHub API error (${status}): ${message}`);
              }
          }
          
          // If it's a network error or other issue, provide a fallback
          if (error.code === 'ECONNREFUSED' || error.code === 'ENOTFOUND' || error.code === 'ETIMEDOUT') {
              throw new Error(`Network error: ${error.message}. Please check your internet connection.`);
          }
          
          // If all else fails, provide a fallback list of known components
          logWarning('Using fallback component list due to API issues');
          return getUiLibrary() === 'base' ? getFallbackComponentsBase() : getFallbackComponents();
      }
  }

• src/server/capabilities.ts:108-114 (registration)

  Tool definition in capabilities.ts, declaring list_components with description and inputSchema.

  list_components: {
    description: "Get all available shadcn/ui v4 components",
    inputSchema: {
      type: "object",
      properties: {},
    },
  },

• src/server/handler.ts:138-148 (registration)

  Tool definition in the ListToolsRequestSchema handler in server/handler.ts, registering list_components with name, description, inputSchema, and annotations.

    name: 'list_components',
    description: 'Get all available shadcn/ui v4 components',
    inputSchema: {
      type: 'object',
      properties: {},
    },
    annotations: {
      title: "List Components",
      readOnlyHint: true,
    },
  },