Provides tools to facilitate the migration of projects from NextUI v2 to HeroUI v3, including project scanning, file analysis for legacy patterns, automated code rewriting, and component API comparisons.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@HeroUI Migration MCP scan my project for legacy HeroUI patterns and list the affected files"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
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.
Related MCP server: @gapra/nuxt-migration-mcp
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
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"
}
}
}
}Detects legacy HeroUI/NextUI usage across a project
Highlights affected files
Assigns priority levels to help sequence the migration work
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
Rewrites a subset of safe patterns automatically
Returns:
rewritten code
edits
warnings
manual review flag
confidence score
Looks up component presence and migration status between v2 and v3
Helps distinguish:
same component
renamed component
compound API migration
removed/unknown component
Uses generated v2/v3 docs optimized for migration lookup
Supports component-only and full documentation outputs
Exposes generated documentation as MCP resources
Detects outdated HeroUI/Tailwind patterns
Helps prepare CSS and config changes before component rewrites
Node.js (v18+) installed.
A HeroUI v2 project you want to migrate.
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 buildBefore using the server seriously, generate the migration corpus and indexes:
npm run build-corpus -- --version all
npm run build-index -- --version all
npm run doctorWhat 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
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"
}
}
}
}Call corpus_status to confirm the generated documentation artifacts are ready.
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
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
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
Use audit_tailwind on your Tailwind configuration before or during the migration.
Use compare_component whenever a component mapping is unclear or looks suspicious.
After each batch of changes:
run TypeScript checks
run lint
run unit tests
smoke-test critical UI flows
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# 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# Compile TypeScript
npm run build
# Run tests
npm run test
# Run tests (non-watch)
npm run test:runsrc/ ├── 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
Generated documentation is available in multiple formats:
Format | Files | Purpose |
Full Text |
| Complete paginated documentation for LLMs |
Components Only |
| Component reference only |
JSON Index |
| Component metadata index |
Web Variant |
| v3 Web-specific documentation |
Native Variant |
| v3 React Native documentation |
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
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
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.
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
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.
✅ 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.
Analyze code and return detailed findings about legacy imports, components, props, hooks and Tailwind patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes | ||
| filename | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full disclosure burden. While 'return detailed findings' implies read-only behavior, it fails to explicitly confirm safety, side effects, output format, or what constitutes 'legacy' patterns.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence (12 words) that front-loads the action and target. No redundant or wasteful text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 2-parameter analysis tool with no output schema, the description adequately covers the analysis scope but leaves critical gaps regarding the optional filename parameter and return value structure. Minimum viable but incomplete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% with no parameter descriptions. Description mentions analyzing 'code' which maps to the required parameter, but offers no explanation for the optional 'filename' parameter (its purpose, format, or when to include it). Inadequate compensation for schema gaps.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States specific verb ('Analyze') and target resource ('code'), listing concrete analysis targets (legacy imports, components, props, hooks, Tailwind patterns). Implicitly distinguishes from sibling 'audit_tailwind' by breadth of analysis, though explicit comparison is absent.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides no explicit guidance on when to use this tool versus siblings like 'scan_project' (multi-file) or 'audit_tailwind' (narrow scope). No prerequisites or exclusions mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Analyze a Tailwind configuration file for legacy HeroUI patterns.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. While 'analyze' implies a read-only operation, the description does not disclose auth requirements, side effects, rate limits, or what the analysis output format/structure looks like.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence that is front-loaded and efficiently structured. Every word earns its place—no redundancy or boilerplate.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a single-parameter tool but incomplete given the lack of annotations and output schema. The description covers the core purpose but omits expected return values, error conditions, or behavioral constraints that would help an agent invoke the tool effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, requiring the description to compensate. It partially compensates by implying the 'code' parameter should contain Tailwind configuration content, but does not explicitly document the parameter semantics, format requirements, or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Specific verb (analyze), resource (Tailwind configuration file), and scope (legacy HeroUI patterns) are clearly stated. However, it does not explicitly differentiate from the sibling 'analyze_file' tool, which is more generic.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use this tool versus 'analyze_file' or other siblings. No mention of prerequisites or when not to use it. Usage is only implied by the specific domain mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Show presence/status of a component between v2 and v3, with alias lookup.
| Name | Required | Description | Default |
|---|---|---|---|
| component | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It successfully discloses the alias lookup behavior, but fails to mention safety characteristics (read-only vs destructive), return format, or error behavior when components are missing.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence efficiently packages the core functionality without repetition. Front-loaded with the action ('Show'), and every phrase earns its place by conveying unique operational scope (v2/v3, alias lookup).
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool, the description covers the primary function adequately, but lacks output specification (no output schema exists) and assumes domain knowledge of what v2 and v3 represent without clarifying the comparison context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema has 0% description coverage for the single 'component' parameter. The description implies the parameter accepts aliases via 'with alias lookup', adding some semantic meaning, but does not fully compensate for the lack of schema documentation (no format examples, constraints, or clear statement that component can be an alias).
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly identifies the resource (component) and action (show presence/status between v2 and v3), plus distinguishes from siblings via version-specific comparison and alias lookup capabilities that no other tools mention.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No explicit guidance on when to use versus alternatives, nor prerequisites for the v2/v3 comparison context. The alias lookup feature implies usage when exact component names are unknown, but this is not explicitly stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Checks the presence and metadata of generated documentation artifacts.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full disclosure burden. It indicates the read-only nature through 'checks' and mentions inspecting 'presence and metadata,' which hints at the return structure. However, it omits details about return format, caching behavior, or performance characteristics expected of a status endpoint.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single efficient sentence with zero redundancy. Information density is high with no filler words, and the scope (presence + metadata) is clearly stated upfront.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Adequate for a zero-parameter tool but incomplete regarding output contract. Since no output schema exists, the description should ideally specify the return structure (e.g., object with exists boolean and metadata fields) rather than just saying it 'checks' these things.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Input schema contains zero parameters. Per scoring rules, 0 parameters establishes a baseline score of 4. The description does not need to compensate for missing parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Provides specific verb 'checks' and clear resource 'generated documentation artifacts' (defining the 'corpus'). However, it does not explicitly differentiate from sibling tools like scan_project or analyze_file that might also inspect project state.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Contains no guidance on when to invoke this tool versus alternatives (e.g., when to check corpus status versus scanning the project or analyzing specific files). No prerequisites or contextual triggers are mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Apply heuristic migrations to code and return the rewritten source plus diagnostics.
| Name | Required | Description | Default |
|---|---|---|---|
| code | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden but omits critical safety information: whether the operation is destructive, if it requires specific file permissions, or what 'heuristic' implies regarding reliability. While it mentions returning 'rewritten source plus diagnostics,' it doesn't explain error conditions or side effects.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with minimal waste. Front-loaded with the action (apply migrations) followed by return value. 'Heuristic migrations' is slightly opaque but the structure is efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero annotation coverage, 0% schema descriptions, no output schema, and a mutation-oriented operation (rewrite), the description is insufficient. It lacks input constraints, error handling details, and behavioral guarantees needed for a code transformation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% (no descriptions in schema), yet the description fails to compensate by defining the 'code' parameter. It doesn't specify expected format, language constraints, or whether this accepts file paths, raw strings, or specific syntax.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verbs (apply, return) and identifies the resource (code/source). However, 'heuristic migrations' remains somewhat jargon-heavy and doesn't clearly differentiate from sibling tools like analyze_file or compare_component which might also process code.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance provided on when to use this tool versus siblings like analyze_file or compare_component. No mention of prerequisites or conditions where rewriting is preferable to other code analysis tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recursively scans a directory for files using legacy HeroUI/NextUI components.
| Name | Required | Description | Default |
|---|---|---|---|
| directory | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description carries full burden due to missing annotations. It discloses the recursive traversal behavior but omits critical safety information (read-only vs. destructive), output format/structure, and performance characteristics for large directories. It does not contradict any annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Single sentence with zero waste. 'Recursively' modifies the action, 'legacy HeroUI/NextUI components' specifies the target pattern, and 'directory' indicates the input scope. Perfectly front-loaded and appropriately sized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given zero schema descriptions, missing annotations, and no output schema, the description is minimally adequate but incomplete. It fails to describe what the tool returns (file list? count? locations?) or how results are structured, which is essential information for an agent to use the output effectively.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema coverage, the description must compensate. It mentions 'scans a directory' which semantically maps to the 'directory' parameter, but provides no explicit parameter documentation, path format guidance (absolute vs. relative), or examples. Baseline assistance provided.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description provides a specific verb ('recursively scans'), resource ('directory'), and scope ('files using legacy HeroUI/NextUI components'). The term 'legacy' and title's 'HeroUI v2' context effectively distinguish this as a migration detection tool versus siblings like analyze_file or rewrite_file, though it doesn't explicitly state these distinctions.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description lacks explicit guidance on when to use this tool versus alternatives. While 'recursively scans a directory' implicitly contrasts with analyze_file (likely single-file), there are no explicit when/when-not statements or prerequisites mentioned.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.3.0analyze_fileaudit_tailwindcompare_componentcorpus_statusrewrite_filescan_projectScored across 6 tools
Each tool has a clearly distinct purpose within the HeroUI migration domain: analyze_file focuses on code analysis, audit_tailwind targets configuration files, compare_component handles component comparisons, corpus_status checks documentation artifacts, rewrite_file performs code migrations, and scan_project scans directories. There is no overlap or ambiguity in their functions.
The tool names follow a consistent verb_noun pattern (e.g., analyze_file, audit_tailwind, compare_component) with clear, descriptive verbs. The only minor deviation is 'corpus_status', which uses a noun_verb structure, but overall the naming is highly predictable and readable.
With 6 tools, the server is well-scoped for its purpose of HeroUI migration. Each tool serves a specific role in the migration workflow, from scanning and analysis to comparison and rewriting, making the count appropriate and efficient for the domain.
The tool set covers key aspects of a migration workflow: scanning (scan_project), analysis (analyze_file, audit_tailwind), comparison (compare_component), documentation checks (corpus_status), and rewriting (rewrite_file). A minor gap might be tools for handling edge cases or rollback operations, but the core migration process is well-covered.
Build, version, review, and export websites, web apps, and games from a conversation.
UI design from prompts, screenshots, and URLs for AI coding agents and theme tokens.
AI website audit: security, SEO, performance, UX and accessibility checks with actionable fixes.
Find UI components and themes, retrieve code, and generate with hosted 21st AI when enabled.
