Provides code formatting for the project through the 'format' script, ensuring consistent code style
Offers faster development server startup and TypeScript execution as an alternative runtime environment
Powers the Git-based caching system for efficient documentation retrieval from the HeroUI repository
Provides repository hosting for both the MCP server and the HeroUI component library it documents
Serves as the primary runtime environment for the MCP server with version 18.0+ required
Offers package management as an alternative to pnpm for dependency installation
Recommended as the primary package manager for installing dependencies and running scripts
Provides type safety and improved developer experience with comprehensive type definitions
Powers the testing framework for unit and integration tests with coverage reporting
HeroUI MCP Server
A high-quality, open-source Model Context Protocol (MCP) server that provides AI agents with comprehensive context and tooling for the HeroUI component library. This server bridges AI systems and HeroUI, enabling intelligent assistance for developers working with HeroUI components.
🚀 Features
Component Discovery: List and explore all available HeroUI components
Documentation Access: Retrieve comprehensive component documentation and usage examples
API Reference: Access detailed component props, slots, and data attributes
Accessibility Information: Get accessibility guidelines and best practices for each component
Usage Patterns: Learn common implementation patterns and best practices
TypeScript Support: Full TypeScript support with comprehensive type definitions
Caching System: Efficient Git-based caching for fast documentation retrieval
RESTful API: Clean HTTP endpoints for easy integration
📋 Prerequisites
Node.js 18.0 or higher
pnpm (recommended) or npm
Git (for repository caching)
Bun (optional, recommended for faster development) or tsx for TypeScript execution
🛠️ Installation
From Source
Clone the repository:
git clone https://github.com/T-Hash06/heroui-mcp.git cd heroui-mcpInstall dependencies:
pnpm installBuild the project:
pnpm buildStart the server:
pnpm start
The server will start on http://localhost:3000
by default.
🎯 Quick Start
Basic Usage
Once the server is running, the best way to interact with it is through the MCP Inspector tool, which provides a user-friendly interface for exploring and testing MCP servers.
Install the MCP Inspector:
npx @modelcontextprotocol/inspectorConnect to your server:
Open the MCP Inspector in your browser
Add your server URL:
http://localhost:3000
Explore the available tools and resources interactively
Available Tools
The server provides the following MCP tools:
Tool | Description |
| List all available HeroUI components |
| Get comprehensive documentation for a component |
| Get API reference (props, methods, events) |
| Get slot information for a component |
| Get data attributes for a component |
| Get accessibility information and guidelines |
| Get usage examples and patterns |
Example: Exploring Components
Using the MCP Inspector, you can:
Browse available tools - See all component-related tools in a visual interface
Test tools interactively - Run tools like
list_components
orget_component_docs
with real-time resultsExplore component data - Get detailed information about any HeroUI component
View formatted output - See documentation and API information in a readable format
The MCP Inspector provides the best experience for exploring the server's capabilities without needing to write code or use command-line tools.
🏗️ Development
Development Setup
Install dependencies:
pnpm installStart development server (choose one option):
Option A: Using Bun (recommended for faster startup)
# Install Bun if you don't have it curl -fsSL https://bun.sh/install | bash # Start development server pnpm devOption B: Using tsx (if you prefer Node.js)
# Install tsx globally or use npx npm install -g tsx # Run directly with tsx npx tsx src/index.tsFor production deployment:
# Build the project pnpm build # Start production server pnpm startRun tests:
pnpm testFormat code:
pnpm formatCheck code quality:
pnpm check
Project Structure
Available Scripts
Script | Description |
| Start development server with Bun (fast TypeScript execution) |
| Build the project for production (TypeScript compilation) |
| Start the production server (requires build first) |
| Run tests in watch mode |
| Run tests once |
| Run tests with coverage report |
| Run all quality checks (lint, type-check, test) |
| Format code with Biome |
| Lint code with Biome |
Development vs Production
Development: Use
pnpm dev
(Bun) ornpx tsx src/index.ts
for fast TypeScript executionProduction: Use
pnpm build
thenpnpm start
for optimized compiled JavaScript
🔧 Configuration
The server can be configured through environment variables or configuration files:
Environment Variables
Configuration Files
src/config/server.config.ts
- Server configurationsrc/config/cache.config.ts
- Cache configuration
🧪 Testing
The project uses Vitest for testing:
🤝 Contributing
Quick Contribution Guide
Fork the repository
Create a feature branch:
git checkout -b feature/amazing-feature
Make your changes
Run quality checks:
pnpm check
Commit your changes:
git commit -m 'Add amazing feature'
Push to the branch:
git push origin feature/amazing-feature
Open a Pull Request
Development Standards
Follow Conventional Commits
Maintain TypeScript strict mode compliance
Write tests for new functionality
Ensure all quality checks pass (
pnpm check
)Document new features and APIs
🐞 Troubleshooting
Common Issues
Server won't start
Check if the port is already in use
Verify Node.js version (18.0+ required)
Ensure all dependencies are installed
Cache initialization fails
Check internet connection for Git repository access
Verify Git is installed and accessible
Check repository URL and branch configuration
Tool execution errors
Ensure the HeroUI repository cache is initialized
Check component name spelling and case sensitivity
Verify the requested component exists in the documentation
Debug Mode
Enable debug logging:
📄 License
This project is licensed under the MIT License - see the LICENSE file for details.
🙏 Acknowledgments
HeroUI - The amazing component library this server supports
Model Context Protocol - The protocol specification
🔗 Links
This server cannot be installed
A high-quality, open-source Model Context Protocol (MCP) server that bridges AI systems and HeroUI, enabling intelligent assistance for developers working with HeroUI components.
Related MCP Servers
- -securityFlicense-qualityA Model Context Protocol server implementation that enables connection between OpenAI APIs and MCP clients for coding assistance with features like CLI interaction, web API integration, and tool-based architecture.Last updated -34
- AsecurityFlicenseAqualityAn all-in-one Model Context Protocol (MCP) server that connects your coding AI to numerous databases, data warehouses, data pipelines, and cloud services, streamlining development workflow through seamless integrations.Last updated -3
- -securityAlicense-qualityModel Context Protocol (MCP) server that provides AI assistants with advanced web research capabilities, including Google search integration, intelligent content extraction, and multi-source synthesis.Last updated -144MIT License
- AsecurityFlicenseAqualityA Model Context Protocol (MCP) server that connects AI assistants directly with Freepik's APIs, allowing users to search, generate, and manage visual content without leaving their AI workflow.Last updated -917