io.github.asr-aditya/iconserve

IconServe

A free, agent-readable service that aggregates 10,000+ open-source icons — Lucide, Heroicons, Tabler, and Simple Icons — and serves them as SVG or PNG at predictable URLs, with keyword + semantic search, an llms.txt, and an MCP server.

Runs entirely within the Cloudflare free tier (Workers + R2 + Workers AI).

How an agent uses it

Discoverability surfaces (for crawling/browsing agents)

• GET /icon/{set}/{name} — crawlable HTML page per icon (preview, usage, JSON-LD ImageObject + breadcrumb). /icon/{name} 302-redirects to the best match.
• GET /sitemap.xml — every icon page (~10k URLs).
• GET /robots.txt — explicitly allows AI crawlers (GPTBot, OAI-SearchBot, ClaudeBot, PerplexityBot, Google-Extended, …) and points to the sitemap.
• Landing page carries WebSite+SearchAction and WebAPI JSON-LD and Open Graph tags.
• IndexNow: key file served at /{INDEXNOW_KEY}.txt; npm run indexnow pings Bing/Yandex to crawl new or changed URLs instantly (pass paths to submit a subset, e.g. npm run indexnow /icon/lucide/house).

Transforms (query params on any icon URL)

• color= hex / CSS color / currentColor — e.g. ?color=%23e11d48
• size= 1..2048 px
• stroke= 0..20 (line icons)
• style= e.g. solid (Heroicons), filled (Tabler)
• format= svg | png

Example: /i/shopping-cart.svg?color=crimson&size=48&stroke=1.5

Architecture

Build (offline, on your machine — no Cloudflare cost)
  scripts/ingest.mjs  → data/pack/icons.json  (id → normalized SVG, currentColor-driven)
                        data/pack/catalog.json (names, tags, aliases, license, styles)
                        data/pack/corpus.json  (search text per icon)
  scripts/embed.mjs   → data/pack/embeddings.bin  (10k × 384, bge-small-en-v1.5)
                        data/pack/embed-index.json

Cloudflare
  R2 (ICONS)   holds the 4 packed artifacts; loaded once per isolate into memory
  Workers AI   embeds ONLY the query string at search time (same 384-dim model)
  Worker       routing, color/size/stroke transforms, PNG (resvg-wasm), search, MCP, docs
  Assets       public/index.html landing page

Semantic search = keyword ranking fused (reciprocal-rank fusion) with cosine similarity over the in-memory embeddings. No Vectorize, no per-vector billing, no dimension cap. If embeddings.bin is absent, search gracefully falls back to keyword-only.

Local development

npm install
npm run build:data     # ingest + embed  (embed downloads a ~40MB model once)
npm run upload:r2      # push artifacts into the LOCAL R2 store
npm run dev            # http://localhost:8787

In wrangler dev --local the Workers AI binding is offline, so search runs keyword-only locally. Semantic search activates once deployed (or when running against the remote AI binding).

Deploy (Cloudflare free tier)

wrangler login         # one-time, opens a browser
npm run deploy         # creates the R2 bucket, uploads artifacts, deploys the Worker

npm run deploy runs scripts/deploy.mjs: it creates the iconserve-icons bucket (idempotent), uploads the four artifacts to remote R2, then wrangler deploy.

Adding / updating icon sets

Edit scripts/lib/sets.mjs, then re-run npm run build:data && npm run upload:r2 (local) or npm run deploy (remote). Set priority for /i/{name} best-match is DEFAULT_SET_ORDER in wrangler.toml.

Licensing

Icons are redistributed under their original permissive licenses: Lucide (ISC), Heroicons (MIT), Tabler (MIT), Simple Icons (CC0). Brand marks from Simple Icons are trademarks of their respective owners — use them per each brand's guidelines.