@supericons/mcp 0.4.6

package/server.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+  "name": "io.github.curlymolelabs/supericons",
+  "title": "Supericons",
+  "description": "Multilingual semantic SVG icon search and recommendations for AI coding agents. Search 20,000+ curated icons by meaning, use case, UI slot, or library.",
+  "repository": {
+    "url": "https://github.com/curlymolelabs/supericons",
+    "source": "github"
+  },
+  "version": "0.4.4",
+  "remotes": [
+    {
+      "type": "streamable-http",
+      "url": "https://mcp.supericons.dev/mcp"
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "supericons-mcp",
+      "version": "0.4.4",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}

package/telemetry.js

@@ -0,0 +1,85 @@
+import { createHash, randomUUID } from 'crypto';
+import { SUPABASE_ANON, SUPABASE_URL } from './auth.js';
+
+const PROCESS_SESSION_TOKEN = randomUUID();
+
+function getSessionHash() {
+  const today = new Date().toISOString().slice(0, 10);
+  return createHash('sha256')
+    .update(`${PROCESS_SESSION_TOKEN}|${today}`)
+    .digest('hex');
+}
+
+async function callRpc(name, payload) {
+  const response = await fetch(`${SUPABASE_URL}/rest/v1/rpc/${name}`, {
+    method: 'POST',
+    headers: {
+      'Content-Type': 'application/json',
+      apikey: SUPABASE_ANON,
+      Authorization: `Bearer ${SUPABASE_ANON}`,
+      Prefer: 'return=minimal',
+    },
+    body: JSON.stringify(payload),
+  });
+
+  if (!response.ok) {
+    throw new Error(`RPC ${name} failed (${response.status})`);
+  }
+}
+
+export async function logMcpSearchBatch({
+  query,
+  results,
+  locale = null,
+}) {
+  if (!Array.isArray(results) || results.length === 0) return;
+
+  const sessionHash = getSessionHash();
+  const batchId = randomUUID();
+
+  try {
+    await callRpc('si_mark_superseded_mcp_batches', {
+      p_session_hash: sessionHash,
+    });
+
+    await Promise.allSettled(results.map((result, index) => callRpc('si_log_icon_evidence', {
+      p_signal_type: 'mcp_call',
+      p_icon_id: `${result.library}:${result.id}`,
+      p_batch_id: batchId,
+      p_search_query: query || null,
+        p_result_position: index + 1,
+        p_ui_surface: 'mcp',
+      p_evidence_text: locale ? `search_icons locale=${locale}` : 'search_icons',
+      p_session_hash: sessionHash,
+      p_created_at: new Date().toISOString(),
+    })));
+  } catch (error) {
+    console.error('[SuperIcons] MCP telemetry failed:', error.message);
+  }
+}
+
+export async function logMcpSearchAttempt({
+  query,
+  resultCount,
+  libraryFilter = null,
+  locale = null,
+}) {
+  const normalizedQuery = String(query || '').trim().toLowerCase().replace(/\s+/g, ' ');
+  const safeResultCount = Number.isFinite(resultCount) ? Math.max(0, Math.round(resultCount)) : null;
+  if (!normalizedQuery || safeResultCount === null) return;
+
+  try {
+    await callRpc('si_log_icon_evidence', {
+      p_signal_type: 'search_attempt',
+      p_search_query: normalizedQuery,
+      p_result_count: safeResultCount,
+      p_library_filter: libraryFilter || 'all',
+      p_ui_surface: 'mcp',
+      p_evidence_text: locale ? `search_icons locale=${locale}` : 'search_icons',
+      p_session_hash: getSessionHash(),
+      p_created_at: new Date().toISOString(),
+    });
+  } catch (error) {
+    console.error('[SuperIcons] MCP search-attempt telemetry failed:', error.message);
+  }
+}

package/variant-support.js

@@ -0,0 +1,236 @@
+export const VARIANT_STYLES = Object.freeze({
+  ANY: 'any',
+  OUTLINE: 'outline',
+  SOLID: 'solid',
+});
+
+const DEFAULT_STRATEGY = Object.freeze({
+  kind: 'none',
+  supportsSolid: false,
+});
+
+const VARIANT_STRATEGIES = Object.freeze({
+  material: Object.freeze({
+    kind: 'material-fill-axis',
+    supportsSolid: true,
+  }),
+  tabler: Object.freeze({
+    kind: 'same-id-style-pair',
+    supportsSolid: true,
+    assetSeparator: 'hyphen',
+  }),
+  phosphor: Object.freeze({
+    kind: 'fill-suffix-pair',
+    supportsSolid: true,
+    solidSuffix: '-fill',
+    assetSeparator: 'hyphen',
+  }),
+  heroicons: Object.freeze({
+    kind: 'same-id-style-pair',
+    supportsSolid: true,
+    assetSeparator: 'hyphen',
+  }),
+  bootstrap: Object.freeze({
+    kind: 'fill-suffix-pair',
+    supportsSolid: true,
+    solidSuffix: '-fill',
+    assetSeparator: 'hyphen',
+  }),
+  ionicons: Object.freeze({
+    kind: 'outline-suffix-pair',
+    supportsSolid: true,
+    outlineSuffix: '-outline',
+    assetSeparator: 'hyphen',
+  }),
+  iconoir: Object.freeze({
+    kind: 'same-id-style-pair',
+    supportsSolid: true,
+    assetSeparator: 'hyphen',
+  }),
+  mingcute: Object.freeze({
+    kind: 'line-fill-suffix-pair',
+    supportsSolid: true,
+    outlineSuffix: '_line',
+    solidSuffix: '_fill',
+  }),
+});
+
+export const MCP_VARIANT_CAPABLE_LIBRARIES = Object.freeze(
+  Object.fromEntries(
+    Object.entries(VARIANT_STRATEGIES)
+      .filter(([, strategy]) => strategy.supportsSolid)
+      .map(([library, strategy]) => [library, strategy])
+  )
+);
+
+function dedupe(values) {
+  return [...new Set(values.filter(Boolean))];
+}
+
+export function normalizeRequestedStyle(style) {
+  const normalized = String(style || VARIANT_STYLES.ANY).trim().toLowerCase();
+  if (normalized === VARIANT_STYLES.OUTLINE || normalized === VARIANT_STYLES.SOLID) {
+    return normalized;
+  }
+  return VARIANT_STYLES.ANY;
+}
+
+export function getVariantStrategyForLibrary(library) {
+  return VARIANT_STRATEGIES[library] || DEFAULT_STRATEGY;
+}
+
+export function librarySupportsSolid(library) {
+  return Boolean(getVariantStrategyForLibrary(library).supportsSolid);
+}
+
+export function getVariantConceptId(library, id) {
+  const normalizedId = String(id || '').trim();
+  const strategy = getVariantStrategyForLibrary(library);
+
+  if (!normalizedId) return normalizedId;
+
+  if (strategy.kind === 'fill-suffix-pair') {
+    return normalizedId.replace(new RegExp(`${strategy.solidSuffix}$`, 'i'), '');
+  }
+
+  if (strategy.kind === 'outline-suffix-pair') {
+    return normalizedId.replace(new RegExp(`${strategy.outlineSuffix}$`, 'i'), '');
+  }
+
+  if (strategy.kind === 'line-fill-suffix-pair') {
+    return normalizedId
+      .replace(new RegExp(`${strategy.outlineSuffix}$`, 'i'), '')
+      .replace(new RegExp(`${strategy.solidSuffix}$`, 'i'), '');
+  }
+
+  return normalizedId;
+}
+
+export function buildVariantLookupCandidates({ library, id, style = VARIANT_STYLES.ANY }) {
+  const normalizedStyle = normalizeRequestedStyle(style);
+  const rawId = String(id || '').trim();
+  const strategy = getVariantStrategyForLibrary(library);
+  const normalizedId = strategy.assetSeparator === 'hyphen' ? rawId.replace(/_/g, '-') : rawId;
+
+  if (!normalizedId) return [];
+
+  const candidates = [normalizedId];
+
+  if (strategy.kind === 'fill-suffix-pair') {
+    const baseId = getVariantConceptId(library, normalizedId);
+    const solidId = `${baseId}${strategy.solidSuffix}`;
+
+    if (normalizedStyle === VARIANT_STYLES.OUTLINE) {
+      candidates.push(baseId);
+    } else if (normalizedStyle === VARIANT_STYLES.SOLID) {
+      candidates.push(solidId);
+    } else if (!normalizedId.endsWith(strategy.solidSuffix)) {
+      candidates.push(solidId);
+    } else {
+      candidates.push(baseId);
+    }
+  }
+
+  if (strategy.kind === 'outline-suffix-pair') {
+    const baseId = getVariantConceptId(library, normalizedId);
+    const outlineId = `${baseId}${strategy.outlineSuffix}`;
+
+    if (normalizedStyle === VARIANT_STYLES.OUTLINE) {
+      candidates.push(outlineId);
+    } else if (normalizedStyle === VARIANT_STYLES.SOLID) {
+      candidates.push(baseId);
+    } else if (!normalizedId.endsWith(strategy.outlineSuffix)) {
+      candidates.push(outlineId);
+    } else {
+      candidates.push(baseId);
+    }
+  }
+
+  if (strategy.kind === 'line-fill-suffix-pair') {
+    const baseId = getVariantConceptId(library, normalizedId);
+    const outlineId = `${baseId}${strategy.outlineSuffix}`;
+    const solidId = `${baseId}${strategy.solidSuffix}`;
+
+    if (normalizedStyle === VARIANT_STYLES.OUTLINE) {
+      candidates.push(outlineId);
+    } else if (normalizedStyle === VARIANT_STYLES.SOLID) {
+      candidates.push(solidId);
+    } else if (normalizedId.endsWith(strategy.outlineSuffix)) {
+      candidates.push(solidId);
+    } else if (normalizedId.endsWith(strategy.solidSuffix)) {
+      candidates.push(outlineId);
+    } else {
+      candidates.push(outlineId, solidId);
+    }
+  }
+
+  return dedupe(candidates);
+}
+
+export function getBaseSemanticIdsForVariant({ library, id }) {
+  const normalizedId = String(id || '').trim();
+  const conceptId = getVariantConceptId(library, normalizedId);
+  const strategy = getVariantStrategyForLibrary(library);
+  const normalizedIdUnderscore = normalizedId.replace(/-/g, '_');
+  const conceptIdUnderscore = conceptId.replace(/-/g, '_');
+
+  const ids = [`${library}:${normalizedId}`];
+
+  if (conceptId && conceptId !== normalizedId) {
+    ids.push(`${library}:${conceptId}`);
+  }
+
+  if (normalizedIdUnderscore && normalizedIdUnderscore !== normalizedId) {
+    ids.push(`${library}:${normalizedIdUnderscore}`);
+  }
+
+  if (conceptIdUnderscore && conceptIdUnderscore !== conceptId) {
+    ids.push(`${library}:${conceptIdUnderscore}`);
+  }
+
+  if (strategy.kind === 'outline-suffix-pair' && conceptId) {
+    ids.push(`${library}:${conceptId}${strategy.outlineSuffix}`);
+    ids.push(`${library}:${conceptIdUnderscore}${strategy.outlineSuffix.replace(/-/g, '_')}`);
+  }
+
+  return dedupe(ids);
+}
+
+export function iconMatchesRequestedStyle(icon, requestedStyle) {
+  const normalizedStyle = normalizeRequestedStyle(requestedStyle);
+  if (normalizedStyle === VARIANT_STYLES.ANY) return true;
+
+  if (icon?.lib === 'material') {
+    return true;
+  }
+
+  return icon?.style === normalizedStyle;
+}
+
+export function getConceptKeyForIcon(icon) {
+  if (!icon) return null;
+  const library = icon.lib || icon.library;
+  const id = icon.id || icon.source_name;
+  if (!library || !id) return null;
+  return `${library}:${getVariantConceptId(library, id)}`;
+}
+
+export function compareVariantPreference(left, right, requestedStyle = VARIANT_STYLES.ANY) {
+  const style = normalizeRequestedStyle(requestedStyle);
+
+  if (style === VARIANT_STYLES.OUTLINE) {
+    const leftScore = left?.style === VARIANT_STYLES.OUTLINE || left?.lib === 'material' ? 1 : 0;
+    const rightScore = right?.style === VARIANT_STYLES.OUTLINE || right?.lib === 'material' ? 1 : 0;
+    return rightScore - leftScore;
+  }
+
+  if (style === VARIANT_STYLES.SOLID) {
+    const leftScore = left?.style === VARIANT_STYLES.SOLID || left?.lib === 'material' ? 1 : 0;
+    const rightScore = right?.style === VARIANT_STYLES.SOLID || right?.lib === 'material' ? 1 : 0;
+    return rightScore - leftScore;
+  }
+
+  const leftScore = left?.style === VARIANT_STYLES.OUTLINE || left?.lib === 'material' ? 1 : 0;
+  const rightScore = right?.style === VARIANT_STYLES.OUTLINE || right?.lib === 'material' ? 1 : 0;
+  return rightScore - leftScore;
+}

package/workflow-access.js

@@ -0,0 +1,65 @@
+import { getConfiguredApiKey } from './auth.js';
+
+export function hasPremiumLibraryAccess(authState, library) {
+  if (authState?.isPro) return true;
+  return Array.isArray(authState?.purchasedSlugs) && authState.purchasedSlugs.includes(library);
+}
+
+export function hasProWorkflowAccess(authState) {
+  return Boolean(authState?.isPro);
+}
+
+export function buildPremiumLibraryAccessError(
+  libraryName,
+  hint = 'Set SUPERICONS_API_KEY in your MCP config with an API key that includes access to this premium pack.'
+) {
+  return {
+    error: 'Premium access required',
+    code: 'premium_library_access_required',
+    message: `The "${libraryName}" pack requires a purchase or Pro subscription. Visit https://supericons.dev`,
+    hint,
+    retryable: false,
+  };
+}
+
+export function buildProWorkflowAccessError(authState, featureName) {
+  const configuredApiKey = getConfiguredApiKey();
+
+  if (!configuredApiKey) {
+    return {
+      error: 'API key required',
+      code: 'workflow_api_key_required',
+      message: `${featureName} requires a Pro-linked SUPERICONS_API_KEY.`,
+      hint: 'Add SUPERICONS_API_KEY to your MCP config, then restart the MCP client.',
+      retryable: false,
+    };
+  }
+
+  if (authState?.authenticated && !authState?.isPro) {
+    return {
+      error: 'Pro workflow access required',
+      code: 'workflow_pro_required',
+      message: `${featureName} is available through Supericons Pro workflow access. Your current API key is valid, but it is not linked to a Pro subscription.`,
+      hint: 'Upgrade the account linked to this API key to Pro, or switch to a different Pro-linked SUPERICONS_API_KEY.',
+      retryable: false,
+    };
+  }
+
+  if (authState?.error) {
+    return {
+      error: 'Workflow access validation failed',
+      code: 'workflow_access_validation_failed',
+      message: `${featureName} could not confirm your workflow access right now.`,
+      hint: `Current auth validation error: ${authState.error}`,
+      retryable: true,
+    };
+  }
+
+  return {
+    error: 'Pro workflow access required',
+    code: 'workflow_pro_required',
+    message: `${featureName} is available through Supericons Pro workflow access. Visit https://supericons.dev/pricing and connect a Pro-linked SUPERICONS_API_KEY.`,
+    hint: 'Generate or manage your API key from Dashboard > API Keys after subscribing to Pro.',
+    retryable: false,
+  };
+}