# 🎨 Aicon - AI Icon Search & Generation

> **MCP Server + API** for intelligent icon management with AI-powered generation and web-based authentication.

## 🚀 Quick Start

### For Users
```bash
# 1. Install the MCP server
npm install -g aicon-mcp

# 2. Add to Claude Desktop (claude_desktop_config.json)
{
  "mcpServers": {
    "aicon": {
      "command": "aicon",
      "args": []
    }
  }
}

# 3. Authenticate in Claude Desktop
# Use: login({action: "login"}) to start web authentication
```

### For Developers/Admins
See **[DEPLOY.md](DEPLOY.md)** for complete deployment instructions.

---

## 📋 What This Does

- **🔍 Search Icons**: Find from 275,000+ existing icons (Material, Heroicons, Lucide, etc.)
- **🎨 Generate Icons**: Create custom icons using AI (powered by Runware.ai)
- **📥 Download Icons**: Save as SVG or PNG with background removal
- **🔐 Web Authentication**: Claude Code-style login flow with subscription plans
- **📊 Usage Tracking**: Monitor API usage and rate limits
- **🔑 Secure**: API key authentication with permission controls

---

## 🔐 Authentication System

### **Web-Based Login Flow**
1. Run `login({action: "login"})` in Claude Desktop
2. Browser opens automatically for authentication
3. Login/register with credentials  
4. Select subscription plan (Free/Pro/Enterprise)
5. API key generated and saved automatically
6. All icon tools now available!

### **Subscription Plans**
- **🆓 FREE**: 100 searches/month, SVG downloads
- **🚀 PRO**: Unlimited searches + AI generation ($9/month)
- **🏢 ENTERPRISE**: Everything unlimited + API access ($29/month)

---

## 🏗️ Architecture

```
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│   MCP Server    │───▶│   Backend API   │───▶│   External APIs │
│   (Local)       │    │   (Vercel)      │    │ Iconify+Runware │
└─────────────────┘    └─────────────────┘    └─────────────────┘
        │                        │                        │
        ▼                        ▼                        ▼
┌─────────────────┐    ┌─────────────────┐    ┌─────────────────┐
│ Claude Desktop  │    │   Supabase DB   │    │  Generated SVGs │
│   (AI Client)   │    │ (Usage & Keys)  │    │   (./Aicon/)    │
└─────────────────┘    └─────────────────┘    └─────────────────┘
```

---

## 📦 Components

### 1. **MCP Server** (`/src/`)
- **Tools**: 6 MCP tools including web authentication
- **Config**: Multi-level configuration (env, user, project)
- **Storage**: Local file management for downloaded icons
- **Client**: HTTP client with request tracking

### 2. **Backend API** (Deployed to Vercel)
- **Endpoints**: REST API for icon search, generation, usage
- **Auth**: Production API key system with permissions
- **Database**: Supabase integration for usage tracking
- **Processing**: Image manipulation (Sharp, Potrace)

---

## 🛠️ Development

### MCP Server
```bash
npm install
npm run dev        # Development mode
npm run build      # Build TypeScript
npm run typecheck  # Type checking
```

---

## 🎯 Usage Examples

### Authenticate First
```javascript
// Start web authentication in Claude Desktop
login({action: "login"})

// Check authentication status
login({action: "status"})

// View subscription plans
login({action: "plans"})
```

### Search for Icons
```javascript
// Search icons after authentication
search_icons({
  query: "home",
  library: "heroicons", 
  style: "outline"
})
```

### Generate Custom Icons
```javascript
// Generate AI icons (Pro/Enterprise plans)
generate_icons({
  subject: "rocket ship",
  context: "space app",
  style: "filled",
  colors: "blue gradient"
})
```

### Download Icons
```javascript
// Download icons in various formats
fetch_icons({
  id: "heroicons:home",
  type: "iconify",
  format: "svg"
})
```

---

## 📊 Features

- ✅ **275,000+ Icons** from 200+ open source icon libraries
- ✅ **AI Generation** with background removal
- ✅ **Web Authentication** Claude Code-style login flow
- ✅ **Subscription Plans** Free/Pro/Enterprise tiers
- ✅ **Format Support** (SVG, PNG)
- ✅ **Rate Limiting** with usage tracking  
- ✅ **Production Ready** with comprehensive tests
- ✅ **Claude Integration** via MCP protocol

---

## 📄 License

MIT License - see LICENSE file for details.