<div align="center">

# Aceternity MCP

**A Model Context Protocol server for Aceternity UI components**

Discover, explore, and install 100+ Aceternity UI components directly from your AI assistant. Get intelligent recommendations, detailed metadata, and one-command installations.

[![PyPI - Version](https://img.shields.io/pypi/v/aceternity-mcp.svg)](https://pypi.org/project/aceternity-mcp/)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/aceternity-mcp.svg)](https://www.python.org/downloads/)
[![MCP](https://img.shields.io/badge/MCP-Compliant-1f6feb)](https://modelcontextprotocol.io/)
[![License](https://img.shields.io/github/license/devinoldenburg/aceternity-mcp)](./LICENSE)

</div>

---

## What is Aceternity MCP?

Aceternity MCP is a Model Context Protocol server that brings the entire Aceternity UI component library to your AI assistant. Instead of just knowing component names, your AI gets rich metadata including:

- **Detailed descriptions** (60+ words per component)
- **Visual characteristics** and behavior patterns
- **Use case recommendations** and compatibility info
- **Installation commands** and dependencies
- **Scoring metrics** for animation, customization, performance impact

This helps your AI make informed decisions about which components fit your design needs.

## Features

- **Complete Registry**: Access to 100+ Aceternity UI components with full metadata
- **Intelligent Search**: Filter by category, visual intensity, animation level, use case
- **Smart Recommendations**: Get component suggestions based on your project type
- **Combination Planning**: Recommend complementary components (navbar + hero + CTA)
- **One-Command Install**: Install components directly through your AI assistant
- **Cross-Platform**: Works on macOS, Linux, and Windows
- **Universal Support**: Configures Cursor, Claude Desktop, Claude Code, Cline, Windsurf, OpenCode

## Quick Start

### Install from PyPI (Recommended)

```bash
# Install the package
pip install aceternity-mcp

# Run the interactive setup wizard (recommended for first-time users)
aceternity-mcp install

# Or use the legacy installer
aceternity-mcp-install

# Or configure all tools automatically
aceternity-mcp install --non-interactive
```

**What the installer does:**
1. Syncs 100+ components from Aceternity UI (or uses bundled registry)
2. Configures your AI tools automatically
3. Verifies the installation
4. Shows you next steps

## CLI Commands

The `aceternity-mcp` command provides a powerful CLI for managing your installation:

| Command | Description |
|---------|-------------|
| `aceternity-mcp install` | Run interactive setup wizard |
| `aceternity-mcp update` | Check for and install updates |
| `aceternity-mcp repair` | Fix common installation issues |
| `aceternity-mcp status` | Show installation health and status |
| `aceternity-mcp diagnose` | Run diagnostics (JSON output) |
| `aceternity-mcp --version` | Show version information |
| `aceternity-mcp --help` | Show help message |

**Examples:**

```bash
# Check for updates
aceternity-mcp update

# Fix installation issues
aceternity-mcp repair

# Repair only registry
aceternity-mcp repair --registry

# Check installation status
aceternity-mcp status

# Detailed status with client configs
aceternity-mcp status --verbose

# Run diagnostics
aceternity-mcp diagnose
```

### Development Installation

```bash
# Clone the repository
git clone https://github.com/devinoldenburg/aceternity-mcp.git
cd aceternity-mcp

# Install in development mode
pip install -e .

# Sync the component registry (optional - registry is included in package)
python scripts/sync_registry.py

# Configure your AI tools
python -m aceternity_mcp.install
```

### Running the MCP Server

To run the MCP server directly (for manual configuration):

```bash
# Using the server command
aceternity-mcp-server

# Or using the legacy command
aceternity-mcp-server
```

### Manual Configuration

Add to your AI tool's MCP configuration:

**Cursor** (`~/.cursor/mcp.json`):
```json
{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}
```

**Claude Code** (`~/.claude/mcp.json`):
```json
{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}
```

**Cline** (VS Code extension settings):
```json
{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}
```

**Windsurf** (`~/.codeium/windsurf/mcp_config.json`):
```json
{
  "mcp_servers": {
    "aceternity_ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}
```

**OpenCode** (`~/.opencode/mcp.json`):
```json
{
  "mcpServers": {
    "aceternity-ui": {
      "command": "aceternity-mcp",
      "args": []
    }
  }
}
```

> **Note**: When installed via pipx (recommended), the `aceternity-mcp` command is available in your PATH and no `cwd` is needed. The registry is bundled with the package.

## Available Tools

Once configured, your AI assistant can use these tools:

| Tool | Description |
|------|-------------|
| `list_components` | List all available components |
| `list_categories` | Show component categories |
| `search_components` | Search by name, description, or tags |
| `get_component` | Get detailed component information |
| `get_category` | Get all components in a category |
| `recommend_components` | Get recommendations for your use case |
| `recommend_combination` | Suggest complementary components |
| `match_components_to_project` | Match components to your project type |
| `install_component` | Install a component with dependencies |
| `filter_by_scores` | Filter by visual/animation intensity |

## Example Prompts

Try these with your AI assistant:

```
"Show me subtle dark background effects with low performance impact"
"Recommend a navbar + hero + CTA combination for a SaaS landing page"
"Find highly customizable card components for testimonials"
"Give me low-motion components suitable for a dashboard"
"Install Spotlight and show me what dependencies are needed"
"What components work well for dark mode dashboards?"
"Show me animated text effects that aren't too distracting"
```

## Architecture

```
aceternity-mcp/
├── registry/              # Component metadata registry (bundled with package)
│   ├── index.json        # Master index
│   ├── raw/              # Raw data from Aceternity UI
│   ├── components/       # Enriched component metadata
│   └── categories/       # Category definitions
├── scripts/              # Utility scripts
│   ├── sync_registry.py  # Sync from Aceternity UI (optional)
│   └── validate_registry.py
├── src/aceternity_mcp/   # MCP server source
│   ├── server.py         # MCP server implementation
│   ├── install.py        # Universal installer
│   ├── models.py         # Data models
│   ├── registry.py       # Registry loader (finds registry in pipx share/)
│   ├── search.py         # Search functionality
│   └── recommender.py    # Recommendation engine
└── pyproject.toml        # Package configuration (includes registry in shared-data)
```

When installed via pipx, the registry is automatically available at:
```
~/.local/pipx/venvs/aceternity-mcp/share/aceternity-mcp/registry/
```

## Development

### Validate Registry Quality

```bash
# Compile check
python -m compileall src scripts

# Validate registry schema
python scripts/validate_registry.py
```

### Update Component Registry

```bash
# Sync latest components from Aceternity UI (optional)
python scripts/sync_registry.py

# With API key (optional)
python scripts/sync_registry.py --api-key "$ACETERNITY_API_KEY"

# Reinstall to bundle updated registry
pipx reinstall aceternity-mcp
```

> **Note**: The registry is bundled with the package, so running `sync_registry.py` is only needed if you want to update to the latest components from Aceternity UI.

### CLI Development

The CLI provides management commands for end users:

```bash
# Test CLI commands
aceternity-mcp --help
aceternity-mcp status
aceternity-mcp diagnose

# Test update check
aceternity-mcp update --non-interactive

# Test repair functionality
aceternity-mcp repair --non-interactive
```

## Supported AI Tools

| Tool | Config File | Status |
|------|-------------|--------|
| Cursor | `~/.cursor/mcp.json` | ✅ Supported |
| Claude Desktop | Platform-specific | ✅ Supported |
| Claude Code | `~/.claude/mcp.json` | ✅ Supported |
| Cline | VS Code extension | ✅ Supported |
| Windsurf | `~/.codeium/windsurf/mcp_config.json` | ✅ Supported |
| OpenCode | `~/.opencode/mcp.json` | ✅ Supported |

## Requirements

- **Python**: 3.10 or higher
- **Node.js**: Required for registry sync (npx command)
- **MCP Client**: One of the supported AI tools listed above

## Security

- No secrets are committed to the repository
- API keys are optional and used only during sync operations
- Keys are not stored on disk
- The repository stores metadata descriptions, not component source files

## Contributing

Contributions are welcome! Please see:
- [Contributing Guide](./CONTRIBUTING.md)
- [Code of Conduct](./CODE_OF_CONDUCT.md)
- [Security Policy](./SECURITY.md)

## License

MIT License - see [LICENSE](./LICENSE) for details.

## Links

- [PyPI Package](https://pypi.org/project/aceternity-mcp/)
- [GitHub Repository](https://github.com/devinoldenburg/aceternity-mcp)
- [Issue Tracker](https://github.com/devinoldenburg/aceternity-mcp/issues)
- [Model Context Protocol](https://modelcontextprotocol.io/)
