better-icons 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Better Auth Inc. 
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,191 @@
+# Better Icons
+
+An MCP (Model Context Protocol) server for searching and retrieving icons from 200+ icon libraries powered by [Iconify](https://iconify.design/) - the same data source behind [icones.js.org](https://icones.js.org).
+
+## Why?
+
+When doing AI-assisted coding, icons are often a pain point. AI models struggle to:
+- Know what icons are available
+- Provide correct SVG code
+- Suggest appropriate icons for UI elements
+
+This MCP server solves that by giving AI models direct access to search and retrieve icons from the massive Iconify collection (200,000+ icons!).
+
+## Quick Setup
+
+### 1. Install the MCP Server
+
+```bash
+npx better-icons setup
+```
+
+This will interactively configure the MCP server for:
+- **Cursor**
+- **Claude Desktop**
+- **VS Code (Copilot)**
+- **Windsurf**
+
+### 2. Add AI Rules to Your Project
+
+Teach your AI assistant how to properly use better-icons:
+
+```bash
+npx skills add better-auth/better-icons
+```
+
+Or install rules directly (supports multiple editors):
+
+```bash
+npx better-icons rules
+```
+
+This opens an interactive selector for:
+- **Cursor**
+- **Claude Code**
+- **Windsurf**
+- **OpenCode**
+- **GitHub Copilot**
+- **Cline / Roo**
+- **Aider**
+
+The rules ensure AI assistants will:
+- ✅ Use the `better-icons` MCP instead of installing icon packages
+- ✅ Create a single `icons.tsx` file with all icons
+- ✅ Reuse existing icons before adding new ones
+- ✅ Follow consistent naming conventions
+- ❌ Never install `lucide-react`, `react-icons`, `@heroicons/react`, etc.
+
+## Manual Installation
+
+### Cursor
+
+Add to `~/.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "better-icons": {
+      "command": "npx",
+      "args": ["-y", "better-icons"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+
+```json
+{
+  "mcpServers": {
+    "better-icons": {
+      "command": "npx",
+      "args": ["-y", "better-icons"]
+    }
+  }
+}
+```
+
+## Tools
+
+### `search_icons`
+
+Search for icons across 200+ icon libraries.
+
+```
+Search for "arrow" icons
+Search for "home" icons in the lucide collection
+```
+
+**Parameters:**
+- `query` (required): Search query (e.g., 'arrow', 'home', 'user')
+- `limit` (optional): Maximum results (1-999, default: 32)
+- `prefix` (optional): Filter by collection (e.g., 'mdi', 'lucide')
+- `category` (optional): Filter by category
+
+### `get_icon`
+
+Get the SVG code for a specific icon with multiple usage formats.
+
+```
+Get the SVG for mdi:home
+Get lucide:arrow-right with size 24
+```
+
+**Parameters:**
+- `icon_id` (required): Icon ID in format 'prefix:name' (e.g., 'mdi:home')
+- `color` (optional): Icon color (e.g., '#ff0000', 'currentColor')
+- `size` (optional): Icon size in pixels
+
+**Returns:**
+- Raw SVG code
+- React/JSX component code
+- Iconify component usage
+
+### `list_collections`
+
+List available icon collections/libraries.
+
+```
+List all icon collections
+Search for "material" collections
+```
+
+**Parameters:**
+- `category` (optional): Filter by category
+- `search` (optional): Search collections by name
+
+### `recommend_icons`
+
+Get icon recommendations for a specific use case.
+
+```
+What icon should I use for a settings button?
+Recommend icons for user authentication
+```
+
+**Parameters:**
+- `use_case` (required): Describe what you need
+- `style` (optional): 'solid', 'outline', or 'any'
+- `limit` (optional): Number of recommendations (1-20)
+
+## Popular Icon Collections
+
+| Prefix | Name | Style | Icons |
+|--------|------|-------|-------|
+| `mdi` | Material Design Icons | Solid | 7,000+ |
+| `lucide` | Lucide Icons | Outline | 1,500+ |
+| `heroicons` | Heroicons | Both | 300+ |
+| `tabler` | Tabler Icons | Outline | 5,000+ |
+| `ph` | Phosphor Icons | Multiple | 9,000+ |
+| `ri` | Remix Icons | Both | 2,800+ |
+| `fa6-solid` | Font Awesome 6 | Solid | 2,000+ |
+| `simple-icons` | Simple Icons | Logos | 3,000+ |
+
+## CLI Commands
+
+```bash
+npx better-icons          # Run the MCP server
+npx better-icons setup    # Interactive setup wizard
+npx better-icons rules    # Install AI rules to your project
+npx better-icons config   # Show manual config instructions
+npx better-icons help     # Show help
+```
+
+## Development
+
+```bash
+# Install dependencies
+bun install
+
+# Run locally
+bun run index.ts
+
+# Build for publishing
+bun run build
+```
+
+## License
+
+MIT

package/better-icons/best-practices/SKILLS.md

@@ -0,0 +1,149 @@
+---
+name: better-icons-best-practices
+description: Skill for integrating Better Icons
+---
+## Overview
+
+Use the `better-icons` MCP server for all icon needs. Do NOT use `lucide-react`, `@heroicons/react`, `react-icons`, or any other icon library.
+
+## How to Get Icons
+
+1. **Search for icons** using the `search_icons` tool
+2. **Get the SVG** using the `get_icon` tool
+3. **Add to the project's `icons.tsx` file** (create if it doesn't exist)
+
+## React Projects - Icon Pattern
+
+### File Structure
+
+All icons should be in a single `icons.tsx` file (typically at `src/components/icons.tsx` or `components/icons.tsx`).
+
+### Icons File Format
+
+```tsx
+import { SVGProps } from "react";
+
+type IconProps = SVGProps<SVGSVGElement>;
+
+export const Icons = {
+  // Example icons - add more as needed
+  home: (props: IconProps) => (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" {...props}>
+      <path fill="currentColor" d="M10 20v-6h4v6h5v-8h3L12 3L2 12h3v8z"/>
+    </svg>
+  ),
+  
+  arrowRight: (props: IconProps) => (
+    <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" {...props}>
+      <path fill="currentColor" d="M12 4l-1.41 1.41L16.17 11H4v2h12.17l-5.58 5.59L12 20l8-8z"/>
+    </svg>
+  ),
+  
+  // Add more icons here...
+} as const;
+
+export type IconName = keyof typeof Icons;
+```
+
+### Usage in Components
+
+```tsx
+import { Icons } from "@/components/icons";
+
+// Basic usage
+<Icons.home />
+
+// With props
+<Icons.arrowRight className="w-5 h-5 text-blue-500" />
+
+// With click handler
+<button onClick={handleClick}>
+  <Icons.settings className="w-4 h-4" />
+  Settings
+</button>
+```
+
+## Workflow for Adding Icons
+
+### Step 1: Check if icon exists
+
+Before adding a new icon, check the existing `icons.tsx` file. If an icon with the same purpose exists, use it.
+
+### Step 2: Search for the icon
+
+Use the `search_icons` tool:
+```
+search_icons({ query: "settings", prefix: "lucide", limit: 5 })
+```
+
+Prefer these collections (in order):
+1. `lucide` - Clean, consistent outline icons
+2. `tabler` - Similar style to lucide
+3. `mdi` - Comprehensive, good for filled icons
+4. `heroicons` - Tailwind-style icons
+
+### Step 3: Get the SVG
+
+Use the `get_icon` tool:
+```
+get_icon({ icon_id: "lucide:settings" })
+```
+
+### Step 4: Add to icons.tsx
+
+Convert the SVG to the Icons pattern:
+
+```tsx
+// From get_icon response:
+// <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24">...</svg>
+
+// Add to Icons object:
+settings: (props: IconProps) => (
+  <svg xmlns="http://www.w3.org/2000/svg" width="1em" height="1em" viewBox="0 0 24 24" {...props}>
+    {/* SVG content */}
+  </svg>
+),
+```
+
+### Step 5: Use in component
+
+```tsx
+<Icons.settings className="w-5 h-5" />
+```
+
+## Icon Naming Conventions
+
+- Use camelCase: `arrowRight`, `chevronDown`, `userPlus`
+- Be descriptive: `checkCircle` not `check2`
+- Match purpose: `close` for X icons, `menu` for hamburger
+- Avoid prefixes: `settings` not `iconSettings`
+
+## Common Icons Reference
+
+| Purpose | Icon Name | Search Term |
+|---------|-----------|-------------|
+| Navigation | `menu`, `close`, `arrowLeft`, `arrowRight` | menu, x, arrow |
+| Actions | `plus`, `minus`, `edit`, `trash`, `save` | plus, edit, trash |
+| Status | `check`, `x`, `alertCircle`, `info` | check, alert, info |
+| User | `user`, `users`, `userPlus` | user |
+| Media | `play`, `pause`, `volume`, `image` | play, volume |
+| Files | `file`, `folder`, `download`, `upload` | file, download |
+| Communication | `mail`, `message`, `phone`, `bell` | mail, message |
+| UI | `search`, `filter`, `settings`, `more` | search, settings |
+
+## DO NOT
+
+- ❌ Install `lucide-react`, `react-icons`, `@heroicons/react`, etc.
+- ❌ Import icons from external packages
+- ❌ Create separate files for each icon
+- ❌ Use icon fonts (Font Awesome CDN, etc.)
+- ❌ Inline SVGs directly in components (put them in icons.tsx)
+
+## DO
+
+- ✅ Use the `better-icons` MCP tools to find icons
+- ✅ Maintain a single `icons.tsx` file
+- ✅ Reuse existing icons when possible
+- ✅ Use consistent naming conventions
+- ✅ Pass className for sizing/coloring
+- ✅ Use `currentColor` for fill/stroke (inherits text color)