list_blocks

Instructions

Implementation Reference

• src/tools/blocks/list-blocks.ts:4-47 (handler)

  The main handler function for the 'list_blocks' tool. It checks if the framework is react-native (returns empty), then calls axios.getAvailableBlocks(category) to fetch categorized blocks from the shadcn/ui GitHub repository.

  export async function handleListBlocks({ category }: { category?: string }) {
    const framework = getFramework();
  
    if (framework === "react-native") {
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(
              {
                categories: {},
                totalBlocks: 0,
                availableCategories: [],
                message:
                  "Blocks are not available for React Native framework. The react-native-reusables repository does not provide block templates.",
              },
              null,
              2
            ),
          },
        ],
      };
    }
  
    try {
      const axios = await getAxiosImplementation();
      const blocks = await axios.getAvailableBlocks(category);
      return {
        content: [
          {
            type: "text",
            text: JSON.stringify(blocks, null, 2),
          },
        ],
      };
    } catch (error) {
      logError("Failed to list blocks", error);
      throw new Error(
        `Failed to list blocks: ${
          error instanceof Error ? error.message : String(error)
        }`
      );
    }
  }

• src/utils/axios.ts:777-896 (helper)

  The getAvailableBlocks function that actually fetches available blocks from the GitHub API. It lists the blocks directory, categorizes blocks (calendar, dashboard, login, sidebar, products, etc.), and optionally filters by category.

  async function getAvailableBlocks(category?: string): Promise<any> {
      const blocksPath = `${getRegistryBasePath()}/blocks`;
      
      try {
          const response = await githubApi.get(`/repos/${REPO_OWNER}/${REPO_NAME}/contents/${blocksPath}?ref=${REPO_BRANCH}`);
          
          if (!Array.isArray(response.data)) {
              throw new Error('Unexpected response from GitHub API');
          }
          
          const blocks: any = {
              calendar: [],
              dashboard: [],
              login: [],
              sidebar: [],
              products: [],
              authentication: [],
              charts: [],
              mail: [],
              music: [],
              other: []
          };
          
          for (const item of response.data) {
              const blockInfo: any = {
                  name: item.name.replace('.tsx', ''),
                  type: item.type === 'file' ? 'simple' : 'complex',
                  path: item.path,
                  size: item.size || 0,
                  lastModified: item.download_url ? 'Available' : 'Directory'
              };
              
              // Add description based on name patterns
              if (item.name.includes('calendar')) {
                  blockInfo.description = 'Calendar component for date selection and scheduling';
                  blocks.calendar.push(blockInfo);
              } else if (item.name.includes('dashboard')) {
                  blockInfo.description = 'Dashboard layout with charts, metrics, and data display';
                  blocks.dashboard.push(blockInfo);
              } else if (item.name.includes('login') || item.name.includes('signin')) {
                  blockInfo.description = 'Authentication and login interface';
                  blocks.login.push(blockInfo);
              } else if (item.name.includes('sidebar')) {
                  blockInfo.description = 'Navigation sidebar component';
                  blocks.sidebar.push(blockInfo);
              } else if (item.name.includes('products') || item.name.includes('ecommerce')) {
                  blockInfo.description = 'Product listing and e-commerce components';
                  blocks.products.push(blockInfo);
              } else if (item.name.includes('auth')) {
                  blockInfo.description = 'Authentication related components';
                  blocks.authentication.push(blockInfo);
              } else if (item.name.includes('chart') || item.name.includes('graph')) {
                  blockInfo.description = 'Data visualization and chart components';
                  blocks.charts.push(blockInfo);
              } else if (item.name.includes('mail') || item.name.includes('email')) {
                  blockInfo.description = 'Email and mail interface components';
                  blocks.mail.push(blockInfo);
              } else if (item.name.includes('music') || item.name.includes('player')) {
                  blockInfo.description = 'Music player and media components';
                  blocks.music.push(blockInfo);
              } else {
                  blockInfo.description = `${item.name} - Custom UI block`;
                  blocks.other.push(blockInfo);
              }
          }
          
          // Sort blocks within each category
          Object.keys(blocks).forEach(key => {
              blocks[key].sort((a: any, b: any) => a.name.localeCompare(b.name));
          });
          
          // Filter by category if specified
          if (category) {
              const categoryLower = category.toLowerCase();
              if (blocks[categoryLower]) {
                  return {
                      category,
                      blocks: blocks[categoryLower],
                      total: blocks[categoryLower].length,
                      description: `${category.charAt(0).toUpperCase() + category.slice(1)} blocks available in shadcn/ui v4`,
                      usage: `Use 'get_block' tool with the block name to get the full source code and implementation details.`
                  };
              } else {
                  return {
                      category,
                      blocks: [],
                      total: 0,
                      availableCategories: Object.keys(blocks).filter(key => blocks[key].length > 0),
                      suggestion: `Category '${category}' not found. Available categories: ${Object.keys(blocks).filter(key => blocks[key].length > 0).join(', ')}`
                  };
              }
          }
          
          // Calculate totals
          const totalBlocks = Object.values(blocks).flat().length;
          const nonEmptyCategories = Object.keys(blocks).filter(key => blocks[key].length > 0);
          
          return {
              categories: blocks,
              totalBlocks,
              availableCategories: nonEmptyCategories,
              summary: Object.keys(blocks).reduce((acc: any, key) => {
                  if (blocks[key].length > 0) {
                      acc[key] = blocks[key].length;
                  }
                  return acc;
              }, {}),
              usage: "Use 'get_block' tool with a specific block name to get full source code and implementation details.",
              examples: nonEmptyCategories.slice(0, 3).map(cat => 
                  blocks[cat][0] ? `${cat}: ${blocks[cat][0].name}` : ''
              ).filter(Boolean)
          };
          
      } catch (error: any) {
          if (error.response?.status === 404) {
              throw new Error('Blocks directory not found in the v4 registry');
          }
          throw error;
      }
  }

• src/tools/blocks/list-blocks.ts:49-55 (schema)

  Input schema for the list_blocks tool, defining an optional 'category' string parameter to filter by block category.

  export const schema = {
    category: {
      type: "string",
      description:
        "Filter by category (calendar, dashboard, login, sidebar, products)",
    },
  };

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

  Registration of the 'list_blocks' tool, mapping name, description, and inputSchema with the listBlocksSchema.

  'list_blocks': {
    name: 'list_blocks',
    description: 'Get all available shadcn/ui v4 blocks with categorization',
    inputSchema: {
      type: 'object',
      properties: listBlocksSchema
    }
  },

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

  Mapping the handler function handleListBlocks to the tool name 'list_blocks' in the toolHandlers export object.

    list_blocks: handleListBlocks,
    apply_theme: handleApplyTheme,
    list_themes: handleListThemes,
    get_theme: handleGetTheme
  };
  
  export const toolSchemas = {
    get_component: getComponentSchema,
    get_component_demo: getComponentDemoSchema,
    list_components: listComponentsSchema,
    get_component_metadata: getComponentMetadataSchema,
    get_directory_structure: getDirectoryStructureSchema,
    get_block: getBlockSchema,
    list_blocks: listBlocksSchema,
    apply_theme: applyThemeSchema,
    list_themes: listThemesSchema,
    get_theme: getThemeSchema
  };