better-icons 1.0.2 → 1.0.3-beta.2

package/README.md

@@ -1,82 +1,65 @@
 # Better Icons
 
-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).
+Search and retrieve 200,000+ icons from 150+ icon collections. Works as an MCP server for AI agents or CLI tool.
 
-## 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!).
-
-## Auto-Learning Preferences
-
-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.
-
-- **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`
+## Quick Start
 
-## Project Icon Sync
-
-Automatically sync icons to your project's icon file - no configuration needed.
-
-```
-You: "I need a settings icon"
-
-AI: Uses sync_icon → automatically:
-  ✓ Fetches the icon from Iconify
-  ✓ Adds SettingsIcon to your icons.tsx
-  ✓ Returns: import { SettingsIcon } from './icons'
-```
+### Add SKills
 
-The AI knows your project structure and passes the icons file path directly:
+You can enable the underlying icons cli usage using skills
 
+```bash
+npx add-skill better-auth/better-icons
 ```
-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
+### MCP Server (AI Agents)
 
-## Quick Setup
+Configure the MCP server to enable icon tools in your AI coding agents.
 
 ```bash
 npx better-icons setup
 ```
 
-This will interactively configure the MCP server for:
+This interactively configures the MCP server for:
 - **Cursor**
 - **Claude Code**
 - **OpenCode**
 - **Windsurf**
 - **VS Code (Copilot)**
 
-## Add AI Skills (Optional)
+Or [configure manually](#manual-installation).
 
-Teach your AI assistant best practices for using better-icons:
+### CLI (Direct Usage)
+
+Use the CLI to search and retrieve icons directly from your terminal.
 
 ```bash
-npx skills add better-auth/better-icons
+# Search for icons
+npx better-icons search arrow
+npx better-icons search home --prefix lucide --limit 10
+
+# Get icon SVG (outputs to stdout)
+npx better-icons get lucide:home > icon.svg
+npx better-icons get mdi:account --color '#333' --size 24
+
+# JSON output for scripting
+npx better-icons search settings --json | jq '.icons[:5]'
+npx better-icons get heroicons:check --json
 ```
 
-This ensures AI assistants will:
-- ✅ Use the `better-icons` MCP instead of installing icon packages
-- ✅ For React, create a single `icons.tsx` file with all icons
-- ✅ Reuse existing icons before adding new ones
-- ✅ Follow consistent naming conventions
+## Why?
+
+Icons are a common pain point in AI-assisted coding. Models often struggle to know which icons are available, generate correct SVG code, maintain consistent styles, and organize icons properly. Inline SVGs also consume unnecessary tokens.
+
+## Features
+
+- **200,000+ Icons** - Search across 150+ icon collections (Lucide, Heroicons, Material Design, etc.)
+- **Auto-Learning** - Remembers which icon collections you use and prioritizes them in future searches
+- **Project Sync** - Icons are written directly to your icons file (`.tsx`, `.ts`, `.js`) instead of pasting SVG into chat (saves tokens!)
+- **Batch Retrieval** - Get multiple icons at once
+- **Similar Icons** - Find the same icon across different collections and styles
+- **Recent Icons** - Quick access to icons you've used before
+- **Multi-Framework** - React, Vue, Svelte, Solid, and raw SVG exports
 
 ## Manual Installation
 
@@ -110,11 +93,13 @@ Add to `~/.claude/settings.json`:
 }
 ```
 
-## Tools
+## MCP Tools
+
+The following tools are available when using the MCP server with AI agents.
 
 ### `search_icons`
 
-Search for icons across 200+ icon libraries.
+Search for icons across 150+ icon collections.
 
 ```
 Search for "arrow" icons
@@ -279,18 +264,46 @@ Scan my icons file
 | `fa6-solid` | Font Awesome 6 | Solid | 2,000+ |
 | `simple-icons` | Simple Icons | Logos | 3,000+ |
 
-## CLI Commands
+## CLI Reference
+
+### Search Icons
+
+Search across 150+ icon collections.
+
+```bash
+better-icons search <query> [options]
+```
+
+| Option | Description |
+|--------|-------------|
+| `-p, --prefix <prefix>` | Filter by collection (e.g., `lucide`, `mdi`) |
+| `-l, --limit <number>` | Maximum results (default: 32) |
+| `--json` | Output as JSON for scripting |
+
+### Get Icon
+
+Retrieve a single icon's SVG code.
 
 ```bash
-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
+better-icons get <icon-id> [options]
 ```
 
-### Options
+| Option | Description |
+|--------|-------------|
+| `-c, --color <color>` | Icon color (e.g., `#ff0000`, `currentColor`) |
+| `-s, --size <pixels>` | Icon size in pixels |
+| `--json` | Output as JSON with metadata |
+
+The icon ID format is `prefix:name` (e.g., `lucide:home`, `mdi:arrow-right`).
+
+### Setup Commands
+
+```bash
+better-icons setup              # Interactive setup wizard
+better-icons setup -y           # Auto-confirm (global scope)
+better-icons setup -s project   # Setup for current project only
+better-icons config             # Show manual config instructions
+```
 
 | Option | Description |
 |--------|-------------|
@@ -298,11 +311,6 @@ npx better-icons --help       # Show help
 | `-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