HeroUI Migration MCP

Instructions

Implementation Reference

• src/core/migration.ts:224-280 (handler)

  The main handler function for the `analyze_file` MCP tool. It orchestrates compatibility checks, Tailwind analysis, and AST traversal.

  export async function analyzeFile(code: string, filename?: string): Promise<AnalyzeFileResult> {
    const findings: any[] = [];
    const manualSteps: string[] = [];
  
    // run compatibility helpers first (imports/hooks/props that weren't captured by AST)
    const issues = checkV3Compatibility(code);
    for (const msg of issues) {
      findings.push({ type: "doc", severity: "warning", message: msg, autoFixable: false, confidence: 0.5 });
    }
  
    // tailwind plugin check
    const tw = analyzeTailwindConfig(code);
    for (const iss of tw.issues) {
      findings.push({ type: "tailwind", severity: "warning", message: iss, autoFixable: false, confidence: 0.6 });
    }
  
    // AST-based scanning for more precise locations and types
    try {
      const ast = parse(code, { sourceType: "module", plugins: ["jsx", "typescript"], locations: true });
      traverse(ast, {
        ImportDeclaration(path: any) {
          const src = path.node.source.value;
          if (src.includes("@nextui-org/react")) {
            const loc = path.node.loc?.start;
            findings.push({
              type: "import",
              severity: "warning",
              message: `Legacy import source ${src}`,
              autoFixable: true,
              confidence: 0.8,
              location: loc ? { line: loc.line, column: loc.column } : undefined,
            });
          }
          path.node.specifiers.forEach((spec: any) => {
            if (t.isImportSpecifier(spec)) {
              const name = spec.imported.name;
              if (KNOWN_V2_IMPORTS[name]) {
                const loc = spec.loc?.start;
                findings.push({
                  type: "import",
                  severity: "info",
                  message: `Legacy component import ${name}`,
                  component: name,
                  autoFixable: true,
                  confidence: 0.7,
                  location: loc ? { line: loc.line, column: loc.column } : undefined,
                });
              }
            }
          });
        },
        JSXOpeningElement(path: any) {
          const nameNode = path.node.name;
          if (t.isJSXIdentifier(nameNode)) {
            const name = nameNode.name;
            if (KNOWN_V2_IMPORTS[name]) {
              const loc = nameNode.loc?.start;

• src/server.ts:419-432 (registration)

  Tool registration for `analyze_file` in the MCP server setup. It handles input parsing and invokes the core migration logic.

  server.registerTool(
    "analyze_file",
    {
      title: "Analyze file",
      description: "Analyze code and return detailed findings about legacy imports, components, props, hooks and Tailwind patterns.",
      inputSchema: { code: z.string(), filename: z.string().optional() }
    },
    async ({ code, filename }) => {
      const { analyzeFile } = await import("./core/migration.js");
      const result = await analyzeFile(code, filename);
      AnalyzeFileResultSchema.parse(result);
      return { content: [], structuredContent: result as any };
    }
  );