better-icons 1.0.0 → 1.0.2

package/README.md

@@ -1,6 +1,6 @@
 # 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).
+An MCP (Model Context Protocol) server for searching and retrieving 200,000 icons from 150+ icon sets, powered by [Iconify](https://iconify.design/) - the same data source behind [icones.js.org](https://icones.js.org).
 
 ## Why?
 
@@ -11,49 +11,72 @@ When doing AI-assisted coding, icons are often a pain point. AI models struggle
 
 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
+## Auto-Learning Preferences
 
-### 1. Install the MCP Server
+Better Icons automatically learns which icon collections you prefer based on your usage. When you retrieve icons using `get_icon`, the server tracks which collections you use most frequently and prioritizes them in future searches and recommendations.
 
-```bash
-npx better-icons setup
-```
+- **Consistent style**: Icons from your preferred collections appear first in search results
+- **Zero configuration**: Just use the server normally and it learns your preferences
+- **Global memory**: Preferences are stored in `~/.better-icons/preferences.json` and apply across all projects
+- **Full control**: View preferences with `get_icon_preferences` or reset with `clear_icon_preferences`
 
-This will interactively configure the MCP server for:
-- **Cursor**
-- **Claude Desktop**
-- **VS Code (Copilot)**
-- **Windsurf**
+## Project Icon Sync
 
-### 2. Add AI Rules to Your Project
+Automatically sync icons to your project's icon file - no configuration needed.
 
-Teach your AI assistant how to properly use better-icons:
+```
+You: "I need a settings icon"
 
-```bash
-npx skills add better-auth/better-icons
+AI: Uses sync_icon → automatically:
+  ✓ Fetches the icon from Iconify
+  ✓ Adds SettingsIcon to your icons.tsx
+  ✓ Returns: import { SettingsIcon } from './icons'
 ```
 
-Or install rules directly (supports multiple editors):
+The AI knows your project structure and passes the icons file path directly:
+
+```
+sync_icon(
+  icons_file: "/Users/me/myapp/src/components/icons.tsx",
+  framework: "react",
+  icon_id: "lucide:settings"
+)
+```
+
+### Supported frameworks
+
+- **React** - TSX components with proper props typing
+- **Vue** - Template-based components
+- **Svelte** - Svelte components with className prop
+- **Solid** - SolidJS components
+- **SVG** - Raw SVG string exports
+
+## Quick Setup
 
 ```bash
-npx better-icons rules
+npx better-icons setup
 ```
 
-This opens an interactive selector for:
+This will interactively configure the MCP server for:
 - **Cursor**
 - **Claude Code**
-- **Windsurf**
 - **OpenCode**
-- **GitHub Copilot**
-- **Cline / Roo**
-- **Aider**
+- **Windsurf**
+- **VS Code (Copilot)**
+
+## Add AI Skills (Optional)
+
+Teach your AI assistant best practices for using better-icons:
+
+```bash
+npx skills add better-auth/better-icons
+```
 
-The rules ensure AI assistants will:
+This ensures AI assistants will:
 - ✅ Use the `better-icons` MCP instead of installing icon packages
-- ✅ Create a single `icons.tsx` file with all icons
+- ✅ For React, 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
 
@@ -72,9 +95,9 @@ Add to `~/.cursor/mcp.json`:
 }
 ```
 
-### Claude Desktop
+### Claude Code (CLI)
 
-Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):
+Add to `~/.claude/settings.json`:
 
 ```json
 {
@@ -110,6 +133,7 @@ Get the SVG code for a specific icon with multiple usage formats.
 
 ```
 Get the SVG for mdi:home
+Get a URL for mdi:home
 Get lucide:arrow-right with size 24
 ```
 
@@ -117,11 +141,13 @@ Get lucide:arrow-right with size 24
 - `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
+- `format` (optional): 'svg' (default) or 'url'
 
 **Returns:**
 - Raw SVG code
 - React/JSX component code
 - Iconify component usage
+- Direct SVG URL (when `format: "url"`)
 
 ### `list_collections`
 
@@ -150,6 +176,96 @@ Recommend icons for user authentication
 - `style` (optional): 'solid', 'outline', or 'any'
 - `limit` (optional): Number of recommendations (1-20)
 
+### `get_icon_preferences`
+
+View your learned icon collection preferences with usage statistics.
+
+```
+Show my icon preferences
+What icon collections do I use most?
+```
+
+### `clear_icon_preferences`
+
+Reset all learned icon preferences to start fresh.
+
+```
+Clear my icon preferences
+Reset icon preferences
+```
+
+### `find_similar_icons`
+
+Find similar icons or variations of a given icon across different collections and styles.
+
+```
+Find icons similar to lucide:home
+What other arrow icons are there like mdi:arrow-right?
+```
+
+**Parameters:**
+- `icon_id` (required): Icon ID to find variations of
+- `limit` (optional): Maximum number of similar icons (1-50, default: 10)
+
+### `get_icons`
+
+Get multiple icons at once (batch retrieval). More efficient than multiple `get_icon` calls.
+
+```
+Get these icons: lucide:home, lucide:settings, lucide:user
+```
+
+**Parameters:**
+- `icon_ids` (required): Array of icon IDs (max 20)
+- `color` (optional): Color for all icons
+- `size` (optional): Size in pixels for all icons
+
+### `get_recent_icons`
+
+View your recently used icons for quick reuse.
+
+```
+Show my recent icons
+What icons have I used recently?
+```
+
+**Parameters:**
+- `limit` (optional): Number of recent icons to show (1-50, default: 20)
+
+### `sync_icon`
+
+Get an icon AND automatically add it to your project's icons file. The recommended way to add icons.
+
+```
+Sync the lucide:home icon to my project
+Add a settings icon to my icons file
+```
+
+**Parameters:**
+- `icons_file` (required): Absolute path to the icons file
+- `framework` (required): 'react', 'vue', 'svelte', 'solid', or 'svg'
+- `icon_id` (required): Icon ID in format 'prefix:name'
+- `component_name` (optional): Custom component name
+- `color` (optional): Icon color
+- `size` (optional): Icon size in pixels
+
+**Returns:**
+- Confirmation that icon was added (or already exists)
+- Import statement to use
+- Usage example
+
+### `scan_project_icons`
+
+Scan an icons file to see what icons are already available.
+
+```
+What icons are already in my project?
+Scan my icons file
+```
+
+**Parameters:**
+- `icons_file` (required): Absolute path to the icons file
+
 ## Popular Icon Collections
 
 | Prefix | Name | Style | Icons |
@@ -166,13 +282,27 @@ Recommend icons for user authentication
 ## 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
+npx better-icons              # Run the MCP server (for tool configs)
+npx better-icons setup        # Interactive setup wizard
+npx better-icons setup -y     # Setup with auto-confirm (global)
+npx better-icons setup -s project  # Setup for current project only
+npx better-icons config       # Show manual config instructions
+npx better-icons --help       # Show help
 ```
 
+### Options
+
+| Option | Description |
+|--------|-------------|
+| `-y, --yes` | Skip confirmation prompts |
+| `-a, --agent <agents...>` | Specify agents (cursor, claude-code, opencode, windsurf, vscode) |
+| `-s, --scope <scope>` | Config scope: `global` (default) or `project` |
+
+### Scope
+
+- **Global**: Configures MCP server for all projects (stored in home directory)
+- **Project**: Configures MCP server for current project only (stored in project root)
+
 ## Development
 
 ```bash
@@ -180,9 +310,9 @@ npx better-icons help     # Show help
 bun install
 
 # Run locally
-bun run index.ts
+bun run dev
 
-# Build for publishing
+# Build
 bun run build
 ```