shadcn-vue-mcp

Instructions

Implementation Reference

• src/core/tools.ts:123-149 (handler)

  Handler function that creates component documentation using ComponentServices.createComponentDoc and opens it in the browser using WebViewService.openMarkdownInBrowser, then returns the documentation content.

  execute: async (params) => {
    try {
      const processedDoc = await services.ComponentServices.createComponentDoc(
        params.name,
        params.type
      );
  
      // 在浏览器中打开markdown文档
      const componentTitle = `${params.name} - shadcn/vue Component Documentation`;
      await services.WebViewService.openMarkdownInBrowser(
        processedDoc || "No documentation found for this component",
        componentTitle
      );
  
      return {
        content: [
          {
            type: "text",
            text: `${processedDoc}`,
          },
        ],
      };
    } catch (error) {
      console.error("Error executing tool:", error);
      throw error;
    }
  },

• src/core/tools.ts:113-122 (schema)

  Zod input schema validating type as 'components' or 'charts' and name as valid shadcn-vue component using ComponentServices.isValidComponent.

  parameters: z.object({
    // components | charts
    type: z.enum(["components", "charts"]).describe("type of the component"),
    name: z
      .string()
      .describe("name of the component in lowercase")
      .refine((name) => services.ComponentServices.isValidComponent(name), {
        message: "Component must be a valid shadcn/vue component",
      }),
  }),

• src/core/tools.ts:110-150 (registration)

  Registration of the 'component-usage-doc' tool using server.addTool, including name, description, parameters schema, and execute handler.

  server.addTool({
    name: "component-usage-doc",
    description: "read usage doc of a component， Use this tool when mentions /doc.",
    parameters: z.object({
      // components | charts
      type: z.enum(["components", "charts"]).describe("type of the component"),
      name: z
        .string()
        .describe("name of the component in lowercase")
        .refine((name) => services.ComponentServices.isValidComponent(name), {
          message: "Component must be a valid shadcn/vue component",
        }),
    }),
    execute: async (params) => {
      try {
        const processedDoc = await services.ComponentServices.createComponentDoc(
          params.name,
          params.type
        );
  
        // 在浏览器中打开markdown文档
        const componentTitle = `${params.name} - shadcn/vue Component Documentation`;
        await services.WebViewService.openMarkdownInBrowser(
          processedDoc || "No documentation found for this component",
          componentTitle
        );
  
        return {
          content: [
            {
              type: "text",
              text: `${processedDoc}`,
            },
          ],
        };
      } catch (error) {
        console.error("Error executing tool:", error);
        throw error;
      }
    },
  });

• src/core/services/componentServices.ts:361-373 (helper)

  Core helper function that fetches the full component documentation, retrieves usage demos, replaces ComponentPreview tags with demo code, and returns processed markdown.

  static async createComponentDoc(name: string, type: string) {
    const doc = await this.readFullComponentDoc({
      type: type,
      name: name,
    });
    const demos = await this.fetchUsageDemo(name);
  
    // 将文档中的 <ComponentPreview name="组件名" /> 替换为对应的 demo 代码
    // 确保demos是数组类型
    const demosArray = Array.isArray(demos) ? demos : [];
    const processedDoc = this.replaceComponentPreviewsWithCode(doc, demosArray);
    return processedDoc;
  }

• src/core/services/webViewService.ts:13-39 (helper)

  Helper function that converts markdown to HTML, creates a styled webpage, saves to temp file, and opens it in the browser.

  static async openMarkdownInBrowser(
    markdownContent: string,
    title: string = "Component Documentation"
  ): Promise<void> {
    try {
      // 将markdown转换为HTML
      const htmlContent = await marked(markdownContent);
  
      // 创建完整的HTML页面
      const fullHtml = this.createHtmlPage(htmlContent, title);
  
      // 创建临时文件
      const tempDir = os.tmpdir();
      const tempFilePath = path.join(tempDir, `component-doc-${Date.now()}.html`);
  
      // 写入HTML文件
      fs.writeFileSync(tempFilePath, fullHtml, "utf8");
  
      // 在浏览器中打开
      await open(tempFilePath);
  
      console.log(`Documentation opened in browser: ${tempFilePath}`);
    } catch (error) {
      console.error("Error opening markdown in browser:", error);
      throw error;
    }
  }