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:

Scan a project.
Analyze impacted files.
Rewrite safe patterns.
Review manual changes.
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:

Format	Files	Purpose
Full Text	`heroui-{v2,v3}-llms-full.txt`	Complete paginated documentation for LLMs
Components Only	`heroui-{v2,v3}-llms-components.txt`	Component reference only
JSON Index	`heroui-{v2,v3}-index.json`	Component metadata index
Web Variant	`heroui-v3-web-llms-full.txt`	v3 Web-specific documentation
Native Variant	`heroui-v3-native-llms-full.txt`	v3 React Native documentation

⚠️ 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

📄 License

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

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.

Name		Name	Last commit message	Last commit date
Latest commit History 7 Commits
.cursor		.cursor
.vscode		.vscode
data/index		data/index
scripts		scripts
src		src
tests/fixtures		tests/fixtures
.gitignore		.gitignore
LICENSE.md		LICENSE.md
README.md		README.md
eslint.config.ts		eslint.config.ts
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

HeroUI Migration MCP

🚀 Overview

Public API

Legacy tools

✨ Features

Project scanning

File analysis

Code rewriting

Component comparison

Documentation corpus

Tailwind audit

📦 Installation

1. Prerequisites

2. Setup the MCP Server

3. Build the documentation corpus

4. Configure in Your MCP Client

🎯 Recommended workflow

Recommended Migration Process

1. Verify the corpus

2. Scan the target project

3. Analyze representative files

4. Rewrite safe patterns

5. Audit Tailwind

6. Validate uncertain components

7. Test incrementally

Command Line Interface

💻 Development

Running the Server

Building & Testing

📁 Project Architecture

🔗 File Formats

⚠️ Migration guidance & Known Limitations

What works well

What still needs review

Known limitations

Best practices

📖 Official References

📄 License

What this means:

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Packages