better-icons 1.0.1 → 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,6 +11,46 @@ 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!).
 
+## 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`
+
+## 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'
+```
+
+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
@@ -93,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
 ```
 
@@ -100,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`
 
@@ -133,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 |