MCP Magic UI

An MCP (Model Context Protocol) server for accessing and exploring Magic UI components from the magicuidesign/magicui repository.

What is MCP Magic UI?

MCP Magic UI is a server that implements the Model Context Protocol (MCP) to provide access to Magic UI components. It fetches component data from the Magic UI GitHub repository, categorizes them, and makes them available through an MCP API. This allows AI assistants and other MCP clients to easily discover and use Magic UI components in their applications.

Features

• Component Discovery: Access all Magic UI components through MCP tools
• Component Categorization: Components are automatically categorized based on their names and dependencies
• Caching System: Local caching of component data to reduce GitHub API calls and work offline
• Multiple Transport Options: Support for both stdio and HTTP transport methods
• Fallback Mechanism: Mock data is provided when GitHub API is unavailable

Installation

# Clone the repository
git clone https://github.com/idcdev/mcp-magic-ui.git
cd mcp-magic-ui

# Install dependencies
npm install

# Build the project
npm run build

Configuration

To avoid GitHub API rate limits, it's recommended to set up a GitHub personal access token:

1. Create a token at https://github.com/settings/tokens

2. Create a `.env` file in the project root (or copy from `.env.example`)

3. Add your token to the `.env` file:

GITHUB_TOKEN=your_github_token_here

Usage

Starting the server

You can start the server using either stdio or HTTP transport:

# Using stdio transport (default)
npm start

# Using HTTP transport
TRANSPORT_TYPE=http npm start

Connecting to the server

You can connect to the server using any MCP client. For example, using the MCP Inspector:

npx @modelcontextprotocol/inspector mcp-magic-ui

Or, if using HTTP transport:

npx @modelcontextprotocol/inspector http://localhost:3000

Available Tools

The server provides the following MCP tools:

• `get_all_components` - Get a list of all available Magic UI components with their metadata
• `get_component_by_path` - Get the source code of a specific component by its file path

Project Structure

• `src/` - Source code
  • `index.ts` - Main entry point for the server
  • `cli.ts` - Command-line interface
  • `server.ts` - MCP server configuration and tool definitions
  • `services/` - Service modules
    • `github.ts` - GitHub API interaction and caching
    • `component-parser.ts` - Component categorization and processing

• `cache/` - Local cache for component data
• `dist/` - Compiled JavaScript code

How It Works

1. The server fetches component data from the Magic UI GitHub repository

2. Component data is cached locally to reduce API calls and enable offline usage

3. Components are categorized based on their names and dependencies

4. The server exposes MCP tools to access and search for components

5. Clients can connect to the server using stdio or HTTP transport

Contributing

Contributions are welcome! Here are some ways you can contribute:

• Report bugs and suggest features by creating issues
• Improve documentation
• Submit pull requests with bug fixes or new features

License

MIT