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 files

Use analyze_file on the files reported by the scan.

Focus first on:

• app providers
• layout and navbar files
• modal/dropdown/table usage
• auth and shell components
• shared UI primitives

4. Rewrite safe patterns

Use rewrite_file on files where the analysis indicates mostly safe changes.

Always review:

• imports
• compound component nesting
• modal structure
• hooks and overlay logic
• navbar-related code

5. Audit Tailwind

Use audit_tailwind on your Tailwind configuration before or during the migration.

6. Validate uncertain components

Use compare_component whenever a component mapping is unclear or looks suspicious.

7. Test incrementally

After each batch of changes:

• run TypeScript checks
• run lint
• run unit tests
• smoke-test critical UI flows

Command Line Interface

The project also provides standalone CLI utilities:

# Build documentation corpus
npm run build-corpus -- --version all

# Build component indexes
npm run build-index -- --version all

# Check corpus health
npm run doctor

# Scan a target project
npm run scan-project -- --directory ./apps/client --force

# Audit Tailwind config
npm run audit-tailwind -- --file ./tailwind.config.ts

# Run the test suite
npm run test

# Run tests once
npm run test:run

💻 Development

Running the Server

# Production mode
npm run start

# Development mode with auto-reload
npm run dev

# Using the MCP Inspector (test interface)
npm run inspect

# Inspector in watch mode
npm run inspect:dev

Building & Testing

# Compile TypeScript
npm run build

# Run tests
npm run test

# Run tests (non-watch)
npm run test:run

📁 Project Architecture

src/ ├── cli/ # command-line utilities ├── core/ # analysis, rewriting, migration logic, AST helpers ├── indexers/ # component/document indexing helpers ├── knowledge/ # mappings, aliases, migration knowledge ├── types/ # contracts and schemas ├── server.ts # MCP server registration └── index.ts # stdio entry point

data/ ├── generated/ # generated v2/v3 documentation corpus └── index/ # generated component indexes

🔗 File Formats

Generated documentation is available in multiple formats:

⚠️ Migration guidance & Known Limitations

What works well

This server is especially useful for:

• identifying migration hotspots quickly
• detecting common v2 imports and patterns
• converting many compound component cases
• generating structured rewrite diagnostics
• helping teams migrate incrementally

What still needs review

Manual review is still recommended for:

• navbar-related code
• overlay logic and hook migration
• modal composition changes
• advanced Tailwind/theming patterns
• any rewrite with warnings or low confidence

Known limitations

• Some migrations are heuristic and cannot be guaranteed correct automatically.
• HeroUI v3 beta may still evolve.
• Certain components or patterns require manual refactoring rather than direct renaming.
• Generated corpus health and project migration progress are related but not identical concerns.

Best practices

• Start with scan_project, not rewrite_file
• Use analyze_file before rewriting complex files
• Review all warnings before committing changes
• Migrate in small batches
• Keep the original v2 branch available for comparison
• Re-run scans after each migration batch

📖 Official References

• HeroUI Documentation
• HeroUI GitHub
• Model Context Protocol (MCP)

📄 License

This project is released under the GNU Affero General Public License v3.0 or later (AGPL-3.0-or-later).

Copyright © 2026 Ronan LE MEILLAT - SCTG Development

All source files include a header comment block with copyright information. The full license text is available in LICENSE.md.

What this means:

• ✅ You can use, modify, and distribute this software
• ✅ You must include the original license and copyright notice
• ✅ You must disclose modifications to the source code
• ⚠️ You must distribute any derivative work under the same AGPL-3.0+ license
• ⚠️ Network usage counts as distribution (if you modify and run this server, you must provide access to the source)

For more details, see the full AGPL-3.0 License.