iconserve

IconServe

一项免费且可供 Agent 读取的服务，汇集了 10,000+ 个开源图标——Lucide、 Heroicons、Tabler 和 Simple Icons—— 并通过固定格式的 URL 提供 SVG 或 PNG，支持关键词与语义搜索，提供 llms.txt 和 MCP 服务。

完全运行在 Cloudflare 免费套餐（Workers + R2 + Workers AI）中。

Agent 如何使用

需求	操作
嵌入一个知道名称的图标	GET /i/{name}.svg（最佳匹配）或 /icons/{set}/{name}.svg
查找合适的图标	GET /api/search?q=shopping+cart → 名称 + 可直接使用的 URL
一次性读取完整 API	GET /llms.txt（或 /llms-full.txt）
原生工具调用	/mcp 上的 MCP 服务（search_icons、get_icon、list_sets）
OpenAPI	GET /openapi.json

可发现性入口（供爬取／浏览的 Agent 使用）

• GET /icon/{set}/{name} — 每个图标都有可爬取的 HTML 页面（预览、用法、JSON-LD ImageObject + 面包屑）。/icon/{name} 会 302 重定向到最佳匹配项。
• GET /sitemap.xml — 包含所有图标页面（约 10k 个 URL）。
• GET /robots.txt — 明确允许 AI 爬虫（GPTBot、OAI-SearchBot、ClaudeBot、PerplexityBot、Google-Extended 等）访问，并指向站点地图。
• 落地页包含 WebSite+SearchAction 和 WebAPI JSON-LD，以及 Open Graph 标签。
• IndexNow：密钥文件通过 /{INDEXNOW_KEY}.txt 提供；npm run indexnow 会通知 Bing/Yandex 立即爬取新增或变更的 URL（可传入路径以仅提交部分内容，例如 npm run indexnow /icon/lucide/house）。

转换（适用于任意图标 URL 的查询参数）

• color= 十六进制值 / CSS 颜色 / currentColor — 例如 ?color=%23e11d48
• size= 1..2048 像素
• stroke= 0..20（线条图标）
• style= 例如 solid（Heroicons）、filled（Tabler）
• format= svg | png

示例：/i/shopping-cart.svg?color=crimson&size=48&stroke=1.5

架构

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

语义搜索 = 关键词排名与内存嵌入的余弦相似度进行融合（倒数排名融合）。无需 Vectorize，无需按向量计费，也没有维度上限。如果缺少 embeddings.bin，搜索会自动退化为仅关键词搜索。

本地开发

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

在 wrangler dev --local 中，Workers AI 绑定处于离线状态，因此本地搜索仅使用关键词。 部署后（或连接远程 AI 绑定运行时）即可启用语义搜索。

部署（Cloudflare 免费套餐）

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

npm run deploy 会运行 scripts/deploy.mjs：创建 iconserve-icons 存储桶（可重复执行），将四个构件上传到远程 R2，然后运行 wrangler deploy。

添加／更新图标集

编辑 scripts/lib/sets.mjs，然后重新运行 npm run build:data && npm run upload:r2 （本地）或 npm run deploy（远程）。/i/{name} 最佳匹配的集合优先级在 wrangler.toml 的 DEFAULT_SET_ORDER 中设置。

许可

图标按照各自原有的宽松许可重新分发：Lucide（ISC）、Heroicons（MIT）、 Tabler（MIT）、Simple Icons（CC0）。Simple Icons 中的品牌标志是其各自所有者的商标，请遵循各品牌的使用规范。