heroui-mcp

T-hash06/heroui-mcp

3.2

If you are the rightful owner of heroui-mcp and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

HeroUI MCP Server is an open-source Model Context Protocol server designed to provide AI agents with comprehensive context and tooling for the HeroUI component library.

Tools

  1. list_components

    List all available HeroUI components.

  2. get_component_docs

    Get comprehensive documentation for a component.

  3. get_component_api

    Get API reference (props, methods, events).

  4. get_component_slots

    Get slot information for a component.

  5. get_component_data_attributes

    Get data attributes for a component.

  6. get_component_accessibility

    Get accessibility information and guidelines.

  7. get_component_usage

    Get usage examples and patterns.

HeroUI MCP Server

npm version TypeScript License: MIT

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

  1. Clone the repository:

    git clone https://github.com/your-username/heroui-mcp.git
cd heroui-mcp

  2. Install dependencies:

    pnpm install

  3. Build the project:

    pnpm build

  4. Start 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.

  1. Install the MCP Inspector:

    npx @modelcontextprotocol/inspector

  2. Connect 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:

ToolDescription
list_componentsList all available HeroUI components
get_component_docsGet comprehensive documentation for a component
get_component_apiGet API reference (props, methods, events)
get_component_slotsGet slot information for a component
get_component_data_attributesGet data attributes for a component
get_component_accessibilityGet accessibility information and guidelines
get_component_usageGet usage examples and patterns

Example: Exploring Components

Using the MCP Inspector, you can:

  1. Browse available tools - See all component-related tools in a visual interface
  2. Test tools interactively - Run tools like list_components or get_component_docs with real-time results
  3. Explore component data - Get detailed information about any HeroUI component
  4. 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

  1. Install dependencies:

    pnpm install

  2. Start 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 dev

    Option 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.ts

  3. For production deployment:

    # Build the project
pnpm build

# Start production server
pnpm start

  4. Run tests:

    pnpm test

  5. Format code:

    pnpm format

  6. Check code quality:

    pnpm check

Project Structure

src/
├── app.ts                 # Main application setup
├── index.ts              # Entry point
├── cache/                # Git caching system
├── config/               # Configuration management
├── http/                 # HTTP server and routes
├── resources/            # MCP resources
├── server/               # MCP server factory
├── tools/                # MCP tools implementation
│   └── components/       # HeroUI component tools
├── transport/            # Session management
├── types/                # TypeScript type definitions
└── utils/                # Utility functions

Available Scripts

ScriptDescription
pnpm devStart development server with Bun (fast TypeScript execution)
pnpm buildBuild the project for production (TypeScript compilation)
pnpm startStart the production server (requires build first)
pnpm testRun tests in watch mode
pnpm test:runRun tests once
pnpm test:coverageRun tests with coverage report
pnpm checkRun all quality checks (lint, type-check, test)
pnpm formatFormat code with Biome
pnpm lintLint code with Biome

Development vs Production

  • Development: Use pnpm dev (Bun) or npx tsx src/index.ts for fast TypeScript execution
  • Production: Use pnpm build then pnpm start for optimized compiled JavaScript

🔧 Configuration

The server can be configured through environment variables or configuration files:

Environment Variables

# Server configuration
PORT=3000
HOST=localhost

# Cache configuration
CACHE_DIR=./cache
REPO_URL=https://github.com/heroui-inc/heroui.git
BRANCH=main

Configuration Files

  • src/config/server.config.ts - Server configuration
  • src/config/cache.config.ts - Cache configuration

🧪 Testing

The project uses Vitest for testing:

# Run all tests
pnpm test

# Run tests once
pnpm test:run

# Run tests with coverage
pnpm test:coverage

# Run specific test file
pnpm test src/tools/components/list-components.test.ts

🤝 Contributing

We welcome contributions! Please see our for details.

Quick Contribution Guide

  1. Fork the repository
  2. Create a feature branch: git checkout -b feature/amazing-feature
  3. Make your changes
  4. Run quality checks: pnpm check
  5. Commit your changes: git commit -m 'Add amazing feature'
  6. Push to the branch: git push origin feature/amazing-feature
  7. 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:

NODE_ENV=development pnpm dev

📄 License

This project is licensed under the MIT License - see the file for details.

🙏 Acknowledgments

🔗 Links

Made with ❤️ for the HeroUI community

HeroUI • MCP • GitHub