HeroUI Migration MCP Server

HeroUI Migration MCP

Version: 0.3.0

A Model Context Protocol (MCP) server to help migrate HeroUI v2 / NextUI projects toward HeroUI v3 beta with a practical workflow based on project scanning, file analysis, guided rewrites, component comparison, and documentation lookup.

🚀 Overview

HeroUI v3 introduces important changes compared with v2:

• more compound component APIs
• package and import changes
• updated overlay and hook patterns
• Tailwind/CSS workflow changes
• some components that still require manual migration decisions

This server is designed to support a controlled, review-first migration workflow:

1. Scan a project.
2. Analyze impacted files.
3. Rewrite safe patterns.
4. Review manual changes.
5. Cross-check components against the generated documentation corpus.

Public API

By default, the server exposes the main public tools below:

• corpus_status — check whether generated documentation artifacts are present and usable
• scan_project — scan a codebase and identify files using legacy HeroUI/NextUI patterns
• analyze_file — inspect a file and return findings about imports, components, props, hooks, and Tailwind usage
• rewrite_file — apply heuristic rewrites and return the rewritten code plus diagnostics
• compare_component — compare a component across v2 and v3 and summarize migration status
• audit_tailwind — inspect a Tailwind config for legacy HeroUI patterns

Legacy tools

Some older compatibility/debugging tools still exist, but they are not enabled by default.

To enable them:

{
  "mcpServers": {
    "heroui-migration": {
      "command": "node",
      "args": ["/absolute/path/to/heroui-migration-mcp/dist/src/index.js"],
      "env": {
        "LEGACY_TOOLS_ENABLED": "true"
      }
    }
  }
}

✨ Features

Project scanning

• Detects legacy HeroUI/NextUI usage across a project
• Highlights affected files
• Assigns priority levels to help sequence the migration work

File analysis

• Detects legacy imports
• Detects component usage that changed in v3
• Flags hook migrations and prop migrations
• Returns structured findings with severity, confidence, and manual steps

Code rewriting

• Rewrites a subset of safe patterns automatically
• Returns:
  • rewritten code
  • edits
  • warnings
  • manual review flag
  • confidence score

Component comparison

• Looks up component presence and migration status between v2 and v3
• Helps distinguish:
  • same component
  • renamed component
  • compound API migration
  • removed/unknown component

Documentation corpus

• Uses generated v2/v3 docs optimized for migration lookup
• Supports component-only and full documentation outputs
• Exposes generated documentation as MCP resources

Tailwind audit

• Detects outdated HeroUI/Tailwind patterns
• Helps prepare CSS and config changes before component rewrites

📦 Installation

1. Prerequisites

• Node.js (v18+) installed.
• A HeroUI v2 project you want to migrate.

2. Setup the MCP Server

Clone this repository and install dependencies:

git clone https://github.com/sctg-development/heroui-migration-mcp.git
cd heroui-migration-mcp
npm install
npm run build

3. Build the documentation corpus

Before using the server seriously, generate the migration corpus and indexes:

npm run build-corpus -- --version all
npm run build-index -- --version all
npm run doctor

What these commands do:

• build-corpus generates v2/v3 documentation artifacts in data/generated
• build-index builds component indexes for faster and more reliable lookups
• doctor checks that the generated artifacts are present and healthy

4. Configure in Your MCP Client

Configure the server in your MCP client (e.g., Claude Desktop, Cursor, or other MCP-compatible editors):

{
  "mcpServers": {
    "heroui-migration": {
      "command": "node",
      "args": ["/absolute/path/to/heroui-migration-mcp/dist/src/index.js"]
    }
  }
}

Optional: Enable Legacy Tools (for backward compatibility)

{
  "mcpServers": {
    "heroui-migration": {
      "command": "node",
      "args": ["/absolute/path/to/heroui-migration-mcp/dist/src/index.js"],
      "env": {
        "LEGACY_TOOLS_ENABLED": "true"
      }
    }
  }
}

🎯 Recommended workflow

Recommended Migration Process

1. Verify the corpus

Call corpus_status to confirm the generated documentation artifacts are ready.

2. Scan the target project

Call scan_project on the app directory you want to migrate, for example apps/client.

Expected outcome:

• list of affected files
• priority classification
• first overview of the migration scope

3. Analyze representative fi