shadcn-ui MCP Server

Instructions

Implementation Reference

• src/index.ts:480-492 (handler)

  Main handler function for the get_component_examples tool. It validates the component name, fetches examples using fetchComponentExamples, and returns them in a standardized response format. Handles errors appropriately.

   * Handle the get_component_examples tool request
   */
  private async handleGetComponentExamples(args: any) {
    const componentName = this.validateComponentName(args);
  
    try {
      // Fetch component examples
      const examples = await this.fetchComponentExamples(componentName);
      return this.createSuccessResponse(examples);
    } catch (error) {
      this.handleAxiosError(error, `Component examples for "${componentName}"`);
    }
  }

• src/index.ts:494-516 (helper)

  Core helper function that orchestrates fetching examples by scraping the shadcn/ui docs page with cheerio, collecting code blocks, and fetching additional demo from GitHub.

  /**
   * Fetches component examples from documentation and GitHub
   * @param componentName Name of the component
   * @returns Array of component examples
   */
  private async fetchComponentExamples(
    componentName: string
  ): Promise<ComponentExample[]> {
    const response = await this.axiosInstance.get(
      `${this.SHADCN_DOCS_URL}/docs/components/${componentName}`
    );
    const $ = cheerio.load(response.data);
  
    const examples: ComponentExample[] = [];
  
    // Collect examples from different sources
    this.collectGeneralCodeExamples($, examples);
    this.collectSectionExamples($, 'Usage', 'Basic usage example', examples);
    this.collectSectionExamples($, 'Link', 'Link usage example', examples);
    await this.collectGitHubExamples(componentName, examples);
  
    return examples;
  }

• src/index.ts:518-558 (helper)

  Helper function to extract general code examples (pre blocks) from the documentation page, associating them with nearby headings for titles.

  /**
   * Collects general code examples from the page
   * @param $ Cheerio instance
   * @param examples Array to add examples to
   */
  private collectGeneralCodeExamples(
    $: cheerio.CheerioAPI,
    examples: ComponentExample[]
  ): void {
    const codeBlocks = $('pre');
    codeBlocks.each((i, el) => {
      const code = $(el).text().trim();
      if (code) {
        // Find heading before code block
        let title = 'Code Example ' + (i + 1);
        let description = 'Code example';
  
        // Look for headings
        let prevElement = $(el).prev();
        while (
          prevElement.length &&
          !prevElement.is('h1') &&
          !prevElement.is('h2') &&
          !prevElement.is('h3')
        ) {
          prevElement = prevElement.prev();
        }
  
        if (prevElement.is('h2') || prevElement.is('h3')) {
          title = prevElement.text().trim();
          description = `${title} example`;
        }
  
        examples.push({
          title,
          code,
          description,
        });
      }
    });
  }

• src/index.ts:596-618 (helper)

  Helper to fetch additional demo code example directly from the shadcn/ui GitHub repo raw file.

  private async collectGitHubExamples(
    componentName: string,
    examples: ComponentExample[]
  ): Promise<void> {
    try {
      const githubResponse = await this.axiosInstance.get(
        `${this.SHADCN_RAW_GITHUB_URL}/apps/www/registry/default/example/${componentName}-demo.tsx`
      );
  
      if (githubResponse.status === 200) {
        examples.push({
          title: 'GitHub Demo Example',
          code: githubResponse.data,
        });
      }
    } catch (error) {
      // Continue even if GitHub fetch fails
      console.error(
        `Failed to fetch GitHub example for ${componentName}:`,
        error
      );
    }
  }

• src/index.ts:133-147 (registration)

  Tool registration in the list_tools response, including name, description, and input schema.

  {
    name: 'get_component_examples',
    description: 'Get usage examples for a specific shadcn/ui component',
    inputSchema: {
      type: 'object',
      properties: {
        componentName: {
          type: 'string',
          description:
            'Name of the shadcn/ui component (e.g., "accordion", "button")',
        },
      },
      required: ['componentName'],
    },
  },

• src/index.ts:136-145 (schema)

  Input schema definition for the tool, specifying the required 'componentName' parameter.

  inputSchema: {
    type: 'object',
    properties: {
      componentName: {
        type: 'string',
        description:
          'Name of the shadcn/ui component (e.g., "accordion", "button")',
      },
    },
    required: ['componentName'],