stackzero-labs/mcp

Instructions

Implementation Reference

• src/server.ts:272-309 (registration)

  Dynamic registration of category-specific tools, including 'getProducts' for the 'Products' category in componentCategories.

  for (const [category, categoryComponents] of Object.entries(
    componentCategories
  )) {
    const componentNamesString = categoryComponents.join(", ");
  
    server.tool(
      `get${category}`,
      `Provides implementation details for ${componentNamesString} components.`,
      {},
      async () => {
        try {
          const categoryResults = await fetchComponentsByCategory(
            categoryComponents,
            components,
            exampleNamesByComponent
          );
  
          return {
            content: [
              {
                type: "text",
                text: JSON.stringify(categoryResults, null, 2),
              },
            ],
          };
        } catch (error) {
          let errorMessage = `Error processing ${category} components`;
          if (error instanceof Error) {
            errorMessage += `: ${error.message}`;
          }
          return {
            content: [{ type: "text", text: errorMessage }],
            isError: true,
          };
        }
      }
    );
  }

• src/server.ts:136-200 (handler)

  Core handler logic for fetching and processing components in a category (used by getProducts tool). Fetches details, generates install instructions, gathers examples, and validates with schema.

  async function fetchComponentsByCategory(
    categoryComponents: string[],
    allComponents: any[],
    exampleNamesByComponent: Map<string, string[]>
  ) {
    const componentResults = [];
  
    for (const componentName of categoryComponents) {
      const component = allComponents.find((c) => c.name === componentName);
      if (!component) continue;
  
      try {
        const componentDetails = await fetchComponentDetails(componentName);
        const componentContent = componentDetails.files[0]?.content;
  
        const relevantExampleNames =
          exampleNamesByComponent.get(componentName) || [];
  
        // Generate installation instructions
        const installInstructions = `You can install the component/blocks using  \
        shadcn/ui CLI. For example, with npx: npx shadcn@latest add \
        "https://ui.stackzero.co/r/${componentName}.json" (Rules: make sure the URL is wrapped in \
        double quotes. Once installed, \
        you can import the component like this: import { ${formatComponentName(
          component.name
        )} } from \
        "@/components/ui/${componentName}";`;
  
        const disclaimerText = `The code below is for context only. It helps you understand
        the component's props, types, and behavior. After installing, the component
        will be available for import via: import { ${formatComponentName(
          component.name
        )} } \
        from "@/components/ui/${componentName}";`;
  
        const exampleDetailsList = await Promise.all(
          relevantExampleNames.map((name) => fetchExampleDetails(name))
        );
  
        const formattedExamples = exampleDetailsList
          .filter((details) => details !== null)
          .map((details) => ({
            name: details.name,
            type: details.type,
            description: details.description,
            content: details.files[0]?.content,
          }));
  
        const validatedComponent = IndividualComponentSchema.parse({
          name: component.name,
          type: component.type,
          description: component.description,
          install: installInstructions,
          content: componentContent && disclaimerText + componentContent,
          examples: formattedExamples,
        });
  
        componentResults.push(validatedComponent);
      } catch (error) {
        console.error(`Error processing component ${componentName}:`, error);
      }
    }
  
    return componentResults;
  }

• src/utils/schemas.ts:23-27 (schema)

  Zod schema used to validate individual component details in the getProducts response.

  export const IndividualComponentSchema = ComponentSchema.extend({
    install: z.string(),
    content: z.string(),
    examples: z.array(ExampleSchema),
  });

• src/lib/categories.ts:12-20 (helper)

  Definition of the 'Products' category listing the specific components fetched by the getProducts tool.

  Products: [
    "price-format-basic",
    "price-format-sale",
    "quantity-input-basic",
    "variant-color-selector-basic",
    "variant-selector-basic",
    "variant-selector-images",
    "variant-selector-multiple",
  ],

• src/utils/api.ts:80-96 (helper)

  Helper function to fetch individual component details from the registry, called within the handler for each product.

  export async function fetchComponentDetails(componentName: string) {
    try {
      const response = await fetch(
        `${mcpConfig.registryUrl}/${componentName}.json`
      );
      if (!response.ok) {
        throw new Error(
          `Failed to fetch component ${componentName}: ${response.statusText}`
        );
      }
      const data = await response.json();
      return ComponentDetailSchema.parse(data);
    } catch (error) {
      console.error(`Error fetching component ${componentName}:`, error);
      throw error;
    }
  }