reicon-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Dev Chauhan
+
+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,69 @@
+# reicon-mcp
+
+MCP server and CLI for searching, previewing, and applying Reicon icons. Works fully offline with a prebuilt search index.
+
+## MCP Server
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "reicon": {
+      "command": "npx",
+      "args": ["reicon-mcp"]
+    }
+  }
+}
+```
+
+Or point directly at the local binary after building:
+
+```json
+{
+  "mcpServers": {
+    "reicon": {
+      "command": "node",
+      "args": ["/path/to/reicon/packages/reicon-mcp/bin/run.cjs"]
+    }
+  }
+}
+```
+
+### Tools
+
+| Tool | Description |
+| :--- | :--- |
+| `search_icons` | Rank icons by keyword |
+| `view_icon` | Return raw SVG markup and metadata |
+| `apply_icon` | Generate framework-specific import and usage snippets |
+| `list_categories` | List all icon categories |
+
+## CLI
+
+```bash
+npx reicon-mcp search "shopping cart"
+npx reicon-mcp view heart --weight Filled
+npx reicon-mcp apply heart --framework react --size 32 --color "#ef4444"
+npx reicon-mcp categories
+```
+
+### File write mode
+
+For scripted insertion, replace a marker string in a target file:
+
+```bash
+npx reicon-mcp apply heart --framework react --file src/App.tsx --marker "{/* ICON */}"
+```
+
+The marker must exist exactly once. The command exits non-zero if the marker is not found.
+
+## Build
+
+From the monorepo root:
+
+```bash
+npm run build:mcp
+```
+
+MIT © [Dev Chauhan](https://devchauhan.in)

package/bin/run.cjs

@@ -0,0 +1,20 @@
+#!/usr/bin/env node
+
+const { existsSync } = require('fs');
+const { join } = require('path');
+const { pathToFileURL } = require('url');
+
+const args = process.argv.slice(2);
+const root = join(__dirname, '..');
+const base = existsSync(join(root, 'server', 'index.js')) ? root : join(root, 'dist');
+
+if (args.length === 0) {
+  import(pathToFileURL(join(base, 'server/index.js')).href);
+} else {
+  import(pathToFileURL(join(base, 'cli/index.js')).href).then((mod) => {
+    mod.run(args).catch((err) => {
+      console.error(err);
+      process.exit(1);
+    });
+  });
+}

package/cli/index.d.ts

@@ -0,0 +1 @@
+export declare function run(argv: string[]): Promise<void>;

package/cli/index.js

@@ -0,0 +1,130 @@
+import { readFileSync, writeFileSync } from 'fs';
+import { handleApplyIcon } from '../server/tools/apply-icon.js';
+import { handleListCategories } from '../server/tools/list-categories.js';
+import { handleSearchIcons } from '../server/tools/search-icons.js';
+import { handleViewIcon } from '../server/tools/view-icon.js';
+function parseArgs(argv) {
+    const result = {};
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        if (arg.startsWith('--')) {
+            const key = arg.slice(2);
+            const next = argv[i + 1];
+            if (next && !next.startsWith('--')) {
+                result[key] = next;
+                i++;
+            }
+            else {
+                result[key] = 'true';
+            }
+        }
+        else {
+            positional.push(arg);
+        }
+    }
+    return { positional, flags: result };
+}
+function print(data) {
+    console.log(JSON.stringify(data, null, 2));
+}
+function applyToFile(filePath, marker, importStatement, usageSnippet) {
+    const content = readFileSync(filePath, 'utf-8');
+    if (!content.includes(marker)) {
+        console.error(`Marker not found in ${filePath}: ${marker}`);
+        process.exit(1);
+    }
+    let updated = content.replace(marker, usageSnippet);
+    if (importStatement && !updated.includes(importStatement)) {
+        const lines = updated.split('\n');
+        let insertAt = 0;
+        for (let i = 0; i < lines.length; i++) {
+            if (lines[i].startsWith('import ') || lines[i].startsWith('<script')) {
+                insertAt = i + 1;
+            }
+        }
+        if (insertAt === 0) {
+            lines.unshift(importStatement);
+        }
+        else {
+            lines.splice(insertAt, 0, importStatement);
+        }
+        updated = lines.join('\n');
+    }
+    writeFileSync(filePath, updated, 'utf-8');
+    print({ ok: true, file: filePath });
+}
+export async function run(argv) {
+    const { positional, flags } = parseArgs(argv);
+    const command = positional[0];
+    if (!command) {
+        console.error('Usage: reicon-mcp <search|view|apply|categories> [args]');
+        process.exit(1);
+    }
+    switch (command) {
+        case 'search': {
+            const query = positional.slice(1).join(' ');
+            if (!query) {
+                console.error('Usage: reicon-mcp search <query>');
+                process.exit(1);
+            }
+            const result = handleSearchIcons({
+                query,
+                weight: flags.weight,
+                limit: flags.limit ? Number(flags.limit) : undefined,
+            });
+            print(result);
+            if ('error' in result)
+                process.exit(1);
+            break;
+        }
+        case 'view': {
+            const name = positional[1];
+            if (!name) {
+                console.error('Usage: reicon-mcp view <name> --weight Outline|Filled');
+                process.exit(1);
+            }
+            const weight = flags.weight || 'Outline';
+            const result = handleViewIcon({ name, weight });
+            print(result);
+            if ('error' in result)
+                process.exit(1);
+            break;
+        }
+        case 'apply': {
+            const name = positional[1];
+            if (!name) {
+                console.error('Usage: reicon-mcp apply <name> --framework react|vue|svelte|html|svg');
+                process.exit(1);
+            }
+            const framework = flags.framework || 'react';
+            const weight = flags.weight || 'Outline';
+            const result = handleApplyIcon({
+                name,
+                weight,
+                framework,
+                size: flags.size ? Number(flags.size) : undefined,
+                color: flags.color,
+                componentName: flags.componentName,
+            });
+            if ('error' in result) {
+                print(result);
+                process.exit(1);
+            }
+            if (flags.file && flags.marker) {
+                applyToFile(flags.file, flags.marker, result.importStatement, result.usageSnippet);
+            }
+            else {
+                print(result);
+            }
+            break;
+        }
+        case 'categories': {
+            print(handleListCategories());
+            break;
+        }
+        default:
+            console.error(`Unknown command: ${command}`);
+            process.exit(1);
+    }
+}

package/core/codegen.d.ts

@@ -0,0 +1,7 @@
+import type { ApplyIconInput, ApplyIconOutput, IconEntry, IconWeight } from './types.js';
+export declare function generateCode(icon: IconEntry, input: ApplyIconInput): ApplyIconOutput | {
+    error: string;
+};
+export declare function buildSvgMarkup(icon: IconEntry, weight: IconWeight): string | {
+    error: string;
+};

package/core/codegen.js

@@ -0,0 +1,96 @@
+function weightProp(weight, framework) {
+    if (weight === 'Outline')
+        return '';
+    if (framework === 'html')
+        return ' weight="filled"';
+    return ` weight="${weight}"`;
+}
+function sizeProp(size, framework) {
+    if (framework === 'vue')
+        return ` :size="${size}"`;
+    if (framework === 'html')
+        return ` size="${size}"`;
+    if (framework === 'svelte' || framework === 'react')
+        return ` size={${size}}`;
+    return ` width="${size}" height="${size}"`;
+}
+function colorProp(color, framework) {
+    if (framework === 'vue')
+        return ` color="${color}"`;
+    if (framework === 'html')
+        return ` color="${color}"`;
+    if (framework === 'svelte' || framework === 'react') {
+        const val = color === 'currentColor' ? 'currentColor' : `"${color}"`;
+        return ` color={${val}}`;
+    }
+    return ` color="${color}"`;
+}
+export function generateCode(icon, input) {
+    const size = input.size ?? 24;
+    const color = input.color ?? 'currentColor';
+    const component = input.componentName ?? icon.pascal;
+    const weight = input.weight;
+    const weightData = icon.weights[weight];
+    const hasColor = input.color !== undefined;
+    if (!weightData) {
+        return { error: `Icon "${icon.name}" does not have a ${weight} weight.` };
+    }
+    const colorAttr = (framework) => hasColor ? colorProp(color, framework) : '';
+    switch (input.framework) {
+        case 'react': {
+            const importStatement = `import { ${component} } from 'reicon-react';`;
+            const props = [
+                sizeProp(size, 'react'),
+                colorAttr('react'),
+                weightProp(weight, 'react'),
+            ].join('');
+            const usageSnippet = `<${component}${props} />`;
+            return { importStatement, usageSnippet };
+        }
+        case 'vue': {
+            const importStatement = `import { ${component} } from 'reicon-vue';`;
+            const props = [
+                sizeProp(size, 'vue'),
+                colorAttr('vue'),
+                weightProp(weight, 'vue'),
+            ].join('');
+            const usageSnippet = `<${component}${props} />`;
+            return { importStatement, usageSnippet };
+        }
+        case 'svelte': {
+            const importStatement = `import { ${component} } from 'reicon-svelte';`;
+            const props = [
+                sizeProp(size, 'svelte'),
+                colorAttr('svelte'),
+                weightProp(weight, 'svelte'),
+            ].join('');
+            const usageSnippet = `<${component}${props} />`;
+            return { importStatement, usageSnippet };
+        }
+        case 'html': {
+            const importStatement = '<script src="https://unpkg.com/reicon/cdn/reicon.min.js"></script>';
+            const props = [
+                ` icon="${icon.name}"`,
+                sizeProp(size, 'html'),
+                colorAttr('html'),
+                weightProp(weight, 'html'),
+            ].join('');
+            const usageSnippet = `<re-icon${props}></re-icon>`;
+            return { importStatement, usageSnippet };
+        }
+        case 'svg': {
+            const importStatement = '';
+            const usageSnippet = `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}" viewBox="${weightData.viewBox}" fill="none">${weightData.code}</svg>`;
+            return { importStatement, usageSnippet };
+        }
+        default:
+            return { error: `Unknown framework: ${input.framework}` };
+    }
+}
+export function buildSvgMarkup(icon, weight) {
+    const weightData = icon.weights[weight];
+    if (!weightData) {
+        return { error: `Icon "${icon.name}" does not have a ${weight} weight.` };
+    }
+    return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="${weightData.viewBox}" fill="none">${weightData.code}</svg>`;
+}

package/core/index-builder.d.ts

@@ -0,0 +1,11 @@
+import type { IconIndex } from './types.js';
+export declare function buildIconIndex(data: {
+    categories?: Record<string, {
+        icons?: Record<string, {
+            description?: string[];
+            weights?: Record<string, {
+                code?: string;
+            }>;
+        }>;
+    }>;
+}): IconIndex;

package/core/index-builder.js

@@ -0,0 +1,63 @@
+const W_KEYS = ['Outline', 'Filled'];
+const SEARCH_ALIASES = {
+    x: ['close', 'dismiss', 'cancel'],
+    cart: ['shopping cart', 'shopping'],
+    trash: ['delete', 'remove', 'bin'],
+    settings: ['gear', 'cog'],
+    search: ['magnifier', 'find'],
+    user: ['profile', 'account', 'avatar'],
+    heart: ['love', 'favorite', 'like'],
+};
+function toPascalCase(str) {
+    return str
+        .split('-')
+        .map((s) => s.charAt(0).toUpperCase() + s.slice(1))
+        .join('');
+}
+function stripSvgWrapper(code) {
+    if (!code)
+        return '';
+    return code.replace(/^<svg[^>]*>/, '').replace(/<\/svg>\s*$/, '').trim();
+}
+function rewriteColors(svg) {
+    return svg.replace(/fill="white"/g, 'fill="currentColor"');
+}
+export function buildIconIndex(data) {
+    const icons = [];
+    const categorySet = new Set();
+    const pascalLowerSet = new Set();
+    for (const [catKey, catData] of Object.entries(data.categories || {})) {
+        categorySet.add(catKey);
+        for (const [iconKey, icon] of Object.entries(catData.icons || {})) {
+            let pascal = toPascalCase(iconKey);
+            if (pascalLowerSet.has(pascal.toLowerCase())) {
+                pascal += toPascalCase(catKey);
+            }
+            pascalLowerSet.add(pascal.toLowerCase());
+            const weights = {};
+            for (const wName of W_KEYS) {
+                const wData = icon.weights?.[wName];
+                if (wData?.code) {
+                    weights[wName] = {
+                        code: rewriteColors(stripSvgWrapper(wData.code)),
+                        viewBox: '0 0 24 24',
+                    };
+                }
+            }
+            if (Object.keys(weights).length > 0) {
+                icons.push({
+                    name: iconKey,
+                    pascal,
+                    category: catKey,
+                    tags: [...(icon.description || []), ...(SEARCH_ALIASES[iconKey] || [])],
+                    weights,
+                });
+            }
+        }
+    }
+    icons.sort((a, b) => a.name.localeCompare(b.name));
+    return {
+        icons,
+        categories: [...categorySet].sort(),
+    };
+}

package/core/load-index.d.ts

@@ -0,0 +1,2 @@
+import type { IconIndex } from './types.js';
+export declare function loadIndex(): IconIndex;

package/core/load-index.js

@@ -0,0 +1,28 @@
+import { readFileSync } from 'fs';
+import { dirname, join } from 'path';
+import { fileURLToPath } from 'url';
+let cached = null;
+function resolveIndexPath() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    const candidates = [
+        join(here, '..', 'data', 'icon-index.json'),
+        join(here, '..', '..', 'src', 'data', 'icon-index.json'),
+    ];
+    for (const p of candidates) {
+        try {
+            readFileSync(p, 'utf-8');
+            return p;
+        }
+        catch {
+            continue;
+        }
+    }
+    throw new Error('icon-index.json not found. Run npm run build:mcp first.');
+}
+export function loadIndex() {
+    if (cached)
+        return cached;
+    const path = resolveIndexPath();
+    cached = JSON.parse(readFileSync(path, 'utf-8'));
+    return cached;
+}

package/core/search.d.ts

@@ -0,0 +1,13 @@
+import type { IconEntry, IconIndex, IconWeight, SearchResult } from './types.js';
+export declare function isSentenceQuery(query: string): boolean;
+export declare function searchIcons(index: IconIndex, query: string, options?: {
+    weight?: IconWeight;
+    limit?: number;
+}): {
+    results: SearchResult[];
+    instruction: string;
+} | {
+    error: string;
+};
+export declare function findIcon(index: IconIndex, name: string): IconEntry | undefined;
+export declare function listCategories(index: IconIndex): string[];

package/core/search.js

@@ -0,0 +1,134 @@
+const SENTENCE_MARKERS = /\?|!|\.{2,}/;
+const SENTENCE_WORDS = /\b(please|could|would|want|need|show|find|give|get|me|my|the|a|an|icon for|looking for|i am|i'm|can you|help me)\b/i;
+const SYNONYMS = {
+    close: ['x'],
+    cart: ['cart', 'cart-large', 'shopping-cart2'],
+    'shopping cart': ['cart', 'cart3', 'shopping-cart2', 'cart-large'],
+    delete: ['trash', 'trash-bin-trash'],
+    remove: ['trash', 'x'],
+    settings: ['settings', 'settings-minimalistic'],
+    arrow: ['arrow-right', 'arrow-down', 'arrow-up', 'arrow-left'],
+    search: ['search', 'minimalistic-magnifer'],
+    heart: ['heart', 'heart-angle'],
+    trash: ['trash', 'trash-bin-trash'],
+    user: ['user', 'user-circle'],
+};
+function normalize(text) {
+    return text.toLowerCase().trim().replace(/\s+/g, ' ');
+}
+function tokenize(text) {
+    return normalize(text).split(' ').filter(Boolean);
+}
+export function isSentenceQuery(query) {
+    const trimmed = query.trim();
+    if (!trimmed)
+        return true;
+    if (SENTENCE_MARKERS.test(trimmed))
+        return true;
+    const words = tokenize(trimmed);
+    if (words.length > 6)
+        return true;
+    if (words.length >= 4 && SENTENCE_WORDS.test(trimmed))
+        return true;
+    if (/^(how|what|where|which|why|when)\b/i.test(trimmed))
+        return true;
+    return false;
+}
+function synonymBoost(query, name) {
+    const key = normalize(query);
+    const list = SYNONYMS[key];
+    if (!list)
+        return 0;
+    const idx = list.indexOf(name);
+    if (idx === -1)
+        return 0;
+    return 3000 - idx * 100;
+}
+function scoreIcon(icon, query, tokens, weight) {
+    const q = normalize(query);
+    const name = icon.name;
+    const nameNorm = name.replace(/-/g, ' ');
+    const tagsNorm = icon.tags.map((t) => normalize(t));
+    let score = 0;
+    score += synonymBoost(query, name);
+    if (name === q || name === q.replace(/ /g, '-')) {
+        score += 10000;
+    }
+    if (tokens.length === 1 && name === tokens[0]) {
+        score += 5000;
+    }
+    if (tokens.every((t) => name.includes(t) || nameNorm.includes(t))) {
+        score += 2000;
+    }
+    if (tagsNorm.some((t) => t === q)) {
+        score += 1500;
+    }
+    for (const token of tokens) {
+        if (tagsNorm.some((t) => t === token))
+            score += 800;
+        if (name.includes(token))
+            score += 600;
+        if (tagsNorm.some((t) => t.includes(token)))
+            score += 300;
+    }
+    if (tokens.length === 1 && name.startsWith(tokens[0])) {
+        score += 400;
+    }
+    score += Math.max(0, 50 - name.length);
+    if (weight) {
+        if (icon.weights[weight])
+            score += 10;
+        else
+            score -= 1000;
+    }
+    return score;
+}
+export function searchIcons(index, query, options = {}) {
+    if (isSentenceQuery(query)) {
+        return {
+            error: 'Query looks like a full sentence. Use concise keywords instead, such as "cart", "user", or "settings".',
+        };
+    }
+    const limit = options.limit ?? 5;
+    const tokens = tokenize(query);
+    const weights = options.weight ? [options.weight] : ['Outline', 'Filled'];
+    const results = [];
+    for (const icon of index.icons) {
+        for (const weight of weights) {
+            if (!icon.weights[weight])
+                continue;
+            const score = scoreIcon(icon, query, tokens, weight);
+            if (score > 0) {
+                results.push({
+                    name: icon.name,
+                    weight,
+                    category: icon.category,
+                    tags: icon.tags,
+                    score,
+                });
+            }
+        }
+    }
+    results.sort((a, b) => b.score - a.score || a.name.length - b.name.length);
+    const seen = new Set();
+    const deduped = [];
+    for (const r of results) {
+        const key = `${r.name}:${r.weight}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        deduped.push(r);
+        if (deduped.length >= limit)
+            break;
+    }
+    return {
+        results: deduped,
+        instruction: 'Pick exactly one result from the list above and proceed with view_icon or apply_icon. Do not ask a person to choose.',
+    };
+}
+export function findIcon(index, name) {
+    return index.icons.find((i) => i.name === name);
+}
+export function listCategories(index) {
+    return index.categories;
+}

package/core/types.d.ts

@@ -0,0 +1,36 @@
+export type IconWeight = 'Outline' | 'Filled';
+export type Framework = 'react' | 'vue' | 'svelte' | 'html' | 'svg';
+export interface IconWeightData {
+    code: string;
+    viewBox: string;
+}
+export interface IconEntry {
+    name: string;
+    pascal: string;
+    category: string;
+    tags: string[];
+    weights: Partial<Record<IconWeight, IconWeightData>>;
+}
+export interface IconIndex {
+    icons: IconEntry[];
+    categories: string[];
+}
+export interface SearchResult {
+    name: string;
+    weight: IconWeight;
+    category: string;
+    tags: string[];
+    score: number;
+}
+export interface ApplyIconInput {
+    name: string;
+    weight: IconWeight;
+    framework: Framework;
+    size?: number;
+    color?: string;
+    componentName?: string;
+}
+export interface ApplyIconOutput {
+    importStatement: string;
+    usageSnippet: string;
+}

package/core/types.js

@@ -0,0 +1 @@
+export {};