feat: MCP icon and stock-image tools (zero-config + key fallback) (#48)

* feat: shared HTTP + three-tier cache for MCP asset fetchers

Introduces `mcp-server/src/asset-fetchers/` with two reusable primitives
that upcoming icon and stock-photo tools share:

- `http.js` — `fetchWithTimeout` / `fetchText` / `fetchJson` / `fetchBinary`
  built on native fetch + AbortSignal.timeout. No new runtime deps.
- `cache.js` — generic three-tier cache (in-flight Map → in-memory → disk)
  cloned from the emoji-loader pattern, parameterised so icons, search
  results, and image bytes can all reuse it. TTL support for search caches.

Caches live under `~/.cache/drawd-mcp/` to match the existing convention.

* feat: Iconify provider for the MCP server

Adds `asset-fetchers/iconify.js` wrapping the public Iconify HTTP API:

- `fetchIcon(collection, name, {size, color})` returns the SVG body.
- `searchIcons(query, {prefix, limit})` returns ranked candidate icon IDs.

Slug components are validated against `/^[a-z0-9][a-z0-9-]*$/` to prevent
path-traversal via crafted names. Iconify's stub-empty `<svg></svg>`
"not found" responses are normalised to a clear error.

SVGs are cached forever (immutable per id); search results have a 7-day TTL.
Both share the new three-tier `Cache` class.

* feat: stock-photo providers (Unsplash, Pexels, Picsum) with fallback chain

Adds three photo providers behind a uniform `searchPhotos(query, {limit})`
interface plus an orchestrator that picks among them based on configured
API keys.

- `picsum.js` — keyless deterministic seeded URLs. Always available.
- `unsplash.js` — reads `UNSPLASH_ACCESS_KEY` per call. Throws a typed
  `MissingApiKeyError` when unset so the orchestrator can fall through.
- `pexels.js` — same pattern, reads `PEXELS_API_KEY`.
- `index.js` — `findStockImage(query, {source, limit})` implements the
  `unsplash → pexels → picsum` chain. Includes a `warning` field in the
  result envelope when a keyed source was skipped silently.

API keys are read from env on every call — never logged, never written
to disk, never stashed on module state.

* feat: MCP asset tools — generate_icon, search_icons, find_stock_image

Adds three new MCP tools (net +3 → 32 tools total) backed by the new
asset-fetchers infrastructure:

- `generate_icon(collection, name, {size, color})` — Iconify SVG fetch.
- `search_icons(query, {collection, limit})` — Iconify search.
- `find_stock_image(query, {source, limit})` — orchestrated photo search
  (Unsplash → Pexels → Picsum) with `warning` on key-fallback.

Per the implementation plan, `search_stock_images` was merged into
`find_stock_image` — one tool, returns N results.

Asset tools are stateless (no flow context required) so they bypass
the `withFilePath` injection used by all other tool groups.

* feat: renderer pre-pass to inline remote <img src> URLs

Satori cannot fetch image URLs itself, so screens that reference
stock photos via `<img src="https://...">` would otherwise render
with broken images. This pre-pass downloads each unique image URL
and rewrites `src` to a base64 data URI before Satori parses the HTML.

Concurrency is capped at 4 in-flight downloads. The image-bytes cache
is the same three-tier cache used by the other asset fetchers, so
re-renders are fast.

SECURITY: an explicit hostname allowlist is enforced — only the
provider hosts the asset tools emit (api.iconify.design,
images.unsplash.com, api.unsplash.com, api.pexels.com, images.pexels.com,
picsum.photos, fastly.picsum.photos) are fetched. Any other host
(or a failed/timed-out fetch) is replaced with a transparent 1×1 PNG
so prompt-injected `<img src="https://attacker.example/...">` cannot
turn the MCP into an SSRF gadget and a single bad URL never breaks
the whole render.

* feat: document MCP icon and stock-image tools

- userGuide.md gains an "Icons and stock photos" section under MCP usage,
  describing the 3 new tools, the zero-config / key-upgrade paths, and
  the renderer's image-inlining + hostname allowlist behaviour.
- Tool count bumped from 29 to 32. New "Assets" category added.
- mcp-server/index.js gains a header comment listing the new
  UNSPLASH_ACCESS_KEY / PEXELS_API_KEY env vars alongside existing args
  with an explicit "never logged, never persisted" reminder.

---------

Co-authored-by: Quang Tran <16215255+trmquang93@users.noreply.github.com>

Author: trmquang93

mcp-server/index.js

@@ -1,3 +1,22 @@
+// Drawd MCP server entry point.
+//
+// CLI args:
+//   --file <path.drawd>   Pre-load a flow file at startup. Equivalent to the
+//                         agent calling open_flow as its first tool.
+//
+// Environment variables (all optional):
+//   UNSPLASH_ACCESS_KEY   Enables query-relevant Unsplash photos in
+//                         find_stock_image. Without it, the tool falls back
+//                         to Pexels (if PEXELS_API_KEY is set) or Picsum.
+//   PEXELS_API_KEY        Enables Pexels as the secondary photo source.
+//   DRAWD_SELECTION_PORT  Override the localhost port the selection bridge
+//                         binds to. Defaults to 3337.
+//   CHROME_PATH           Path to Chrome/Chromium for the legacy html-to-png
+//                         renderer. Not used by the default Satori path.
+//
+// API keys are read from env on every call, never logged, never written
+// to disk. Outbound asset fetches are restricted to a hostname allowlist —
+// see src/renderer/satori-renderer.js (inlineRemoteImages).
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { FlowState } from "./src/state.js";
 import { SatoriRenderer } from "./src/renderer/satori-renderer.js";

mcp-server/src/asset-fetchers/__tests__/cache.test.js

@@ -0,0 +1,85 @@
+// @vitest-environment node
+//
+// Cache uses real fs/promises, so use the node env (avoid jsdom intercepting node: imports).
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { Cache, hashKey } from "../cache.js";
+
+const uniqueSubdir = () =>
+  `test-cache-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+
+describe("hashKey", () => {
+  it("produces a stable hex string", () => {
+    expect(hashKey("foo")).toMatch(/^[0-9a-f]{40}$/);
+    expect(hashKey("foo")).toBe(hashKey("foo"));
+    expect(hashKey("foo")).not.toBe(hashKey("bar"));
+  });
+});
+
+describe("Cache", () => {
+  let cache;
+  beforeEach(() => {
+    cache = new Cache({ subdir: uniqueSubdir(), encoding: "text" });
+  });
+
+  it("caches the fetcher result in memory after first call", async () => {
+    const fetcher = vi.fn(async () => "value-1");
+    const r1 = await cache.getOrFetch("k", fetcher);
+    const r2 = await cache.getOrFetch("k", fetcher);
+    expect(r1).toBe("value-1");
+    expect(r2).toBe("value-1");
+    expect(fetcher).toHaveBeenCalledTimes(1);
+  });
+
+  it("dedupes concurrent in-flight requests", async () => {
+    let resolveOuter;
+    const fetcher = vi.fn(
+      () =>
+        new Promise((resolve) => {
+          resolveOuter = resolve;
+        })
+    );
+    // disable disk reads so the in-flight slot is set synchronously enough
+    cache.readDisk = async () => null;
+    const p1 = cache.getOrFetch("dup", fetcher);
+    const p2 = cache.getOrFetch("dup", fetcher);
+    // Yield microtasks so the readDisk(null) await resolves and the fetcher fires.
+    await Promise.resolve();
+    await Promise.resolve();
+    expect(fetcher).toHaveBeenCalledTimes(1);
+    resolveOuter("dup-value");
+    const [v1, v2] = await Promise.all([p1, p2]);
+    expect(v1).toBe("dup-value");
+    expect(v2).toBe("dup-value");
+  });
+
+  it("falls back to fetcher again after clearMemory", async () => {
+    const fetcher = vi
+      .fn()
+      .mockResolvedValueOnce("v1")
+      .mockResolvedValueOnce("v2");
+
+    const r1 = await cache.getOrFetch("k", fetcher);
+    cache.clearMemory();
+    // disk write is fire-and-forget; it may or may not have landed before
+    // the next call. To make this test deterministic, override readDisk.
+    cache.readDisk = async () => null;
+    const r2 = await cache.getOrFetch("k", fetcher);
+    expect(r1).toBe("v1");
+    expect(r2).toBe("v2");
+    expect(fetcher).toHaveBeenCalledTimes(2);
+  });
+
+  it("propagates fetcher errors and removes the in-flight slot", async () => {
+    const err = new Error("boom");
+    const fetcher = vi
+      .fn()
+      .mockRejectedValueOnce(err)
+      .mockResolvedValueOnce("recovered");
+
+    await expect(cache.getOrFetch("err", fetcher)).rejects.toThrow("boom");
+    cache.readDisk = async () => null;
+    const r2 = await cache.getOrFetch("err", fetcher);
+    expect(r2).toBe("recovered");
+  });
+});

mcp-server/src/asset-fetchers/__tests__/iconify.test.js

@@ -0,0 +1,95 @@
+// @vitest-environment node
+
+import { describe, it, expect, beforeEach, vi } from "vitest";
+import { fetchIcon, searchIcons, _internal } from "../iconify.js";
+
+function mockFetchOnce(body, { ok = true, status = 200 } = {}) {
+  const res = {
+    ok,
+    status,
+    text: async () => (typeof body === "string" ? body : JSON.stringify(body)),
+    json: async () => (typeof body === "string" ? JSON.parse(body) : body),
+    headers: new Map(),
+  };
+  global.fetch = vi.fn(async () => res);
+}
+
+describe("iconify.fetchIcon", () => {
+  beforeEach(() => {
+    _internal.svgCache.clearMemory();
+    // disable disk reads so tests don't depend on fs state
+    _internal.svgCache.readDisk = async () => null;
+  });
+
+  it("constructs the iconify URL with size and color params", async () => {
+    mockFetchOnce("<svg xmlns=\"http://www.w3.org/2000/svg\"><path/></svg>");
+    await fetchIcon("mdi", "home", { size: 32, color: "#ff0000" });
+    const calledUrl = global.fetch.mock.calls[0][0];
+    expect(calledUrl).toContain("https://api.iconify.design/mdi/home.svg");
+    expect(calledUrl).toContain("height=32");
+    expect(calledUrl).toContain("color=%23ff0000");
+  });
+
+  it("rejects unsafe collection slugs", async () => {
+    await expect(fetchIcon("../etc", "home")).rejects.toThrow(/Invalid iconify collection/);
+  });
+
+  it("rejects unsafe icon names", async () => {
+    await expect(fetchIcon("mdi", "home/passwd")).rejects.toThrow(/Invalid iconify icon/);
+  });
+
+  it("rejects empty SVG bodies as not-found", async () => {
+    mockFetchOnce("<svg></svg>");
+    await expect(fetchIcon("mdi", "missing")).rejects.toThrow(/Icon not found/);
+  });
+
+  it("returns the SVG body verbatim on success", async () => {
+    const body = "<svg xmlns=\"http://www.w3.org/2000/svg\"><circle r=\"4\"/></svg>";
+    mockFetchOnce(body);
+    const out = await fetchIcon("mdi", "home");
+    expect(out).toBe(body);
+  });
+
+  it("uses cache on second lookup", async () => {
+    const body = "<svg xmlns=\"http://www.w3.org/2000/svg\"><path/></svg>";
+    mockFetchOnce(body);
+    await fetchIcon("mdi", "home");
+    await fetchIcon("mdi", "home");
+    expect(global.fetch).toHaveBeenCalledTimes(1);
+  });
+});
+
+describe("iconify.searchIcons", () => {
+  beforeEach(() => {
+    _internal.searchCache.clearMemory();
+    _internal.searchCache.readDisk = async () => null;
+  });
+
+  it("returns normalized {results,total} from iconify response", async () => {
+    mockFetchOnce({ icons: ["mdi:home", "ph:house"] });
+    const out = await searchIcons("home");
+    expect(out.total).toBe(2);
+    expect(out.results).toEqual([
+      { id: "mdi:home", collection: "mdi", name: "home" },
+      { id: "ph:house", collection: "ph", name: "house" },
+    ]);
+  });
+
+  it("clamps limit between 1 and 64", async () => {
+    mockFetchOnce({ icons: [] });
+    await searchIcons("home", { limit: 9999 });
+    const calledUrl = global.fetch.mock.calls[0][0];
+    expect(calledUrl).toContain("limit=64");
+  });
+
+  it("requires a non-empty query", async () => {
+    await expect(searchIcons("")).rejects.toThrow(/query is required/);
+  });
+
+  it("passes prefix when provided", async () => {
+    mockFetchOnce({ icons: [] });
+    await searchIcons("home", { prefix: "mdi" });
+    const calledUrl = global.fetch.mock.calls[0][0];
+    expect(calledUrl).toContain("prefix=mdi");
+  });
+});

mcp-server/src/asset-fetchers/__tests__/orchestrator.test.js

@@ -0,0 +1,94 @@
+// @vitest-environment node
+
+import { describe, it, expect, beforeEach, afterEach, vi } from "vitest";
+import { findStockImage } from "../index.js";
+import { _internal as unsplashInternal } from "../unsplash.js";
+import { _internal as pexelsInternal } from "../pexels.js";
+
+const ORIG_UNSPLASH = process.env.UNSPLASH_ACCESS_KEY;
+const ORIG_PEXELS = process.env.PEXELS_API_KEY;
+
+function mockFetchJson(body) {
+  const res = {
+    ok: true,
+    status: 200,
+    json: async () => body,
+    text: async () => JSON.stringify(body),
+    headers: new Map(),
+  };
+  global.fetch = vi.fn(async () => res);
+}
+
+beforeEach(() => {
+  delete process.env.UNSPLASH_ACCESS_KEY;
+  delete process.env.PEXELS_API_KEY;
+  unsplashInternal.searchCache.clearMemory();
+  unsplashInternal.searchCache.readDisk = async () => null;
+  unsplashInternal.searchCache.writeDisk = async () => {};
+  pexelsInternal.searchCache.clearMemory();
+  pexelsInternal.searchCache.readDisk = async () => null;
+  pexelsInternal.searchCache.writeDisk = async () => {};
+});
+
+afterEach(() => {
+  if (ORIG_UNSPLASH != null) process.env.UNSPLASH_ACCESS_KEY = ORIG_UNSPLASH;
+  if (ORIG_PEXELS != null) process.env.PEXELS_API_KEY = ORIG_PEXELS;
+});
+
+describe("findStockImage — fallback chain", () => {
+  it("falls all the way through to Picsum when no keys are set", async () => {
+    const out = await findStockImage("kitchen", { limit: 3 });
+    expect(out.source).toBe("picsum");
+    expect(out.results.length).toBe(3);
+    expect(out.warning).toMatch(/UNSPLASH_ACCESS_KEY/);
+    expect(out.warning).toMatch(/PEXELS_API_KEY/);
+  });
+
+  it("uses unsplash when UNSPLASH_ACCESS_KEY is set", async () => {
+    process.env.UNSPLASH_ACCESS_KEY = "test-key";
+    mockFetchJson({
+      results: [
+        {
+          urls: { regular: "https://images.unsplash.com/abc", small: "https://images.unsplash.com/abc-sm" },
+          alt_description: "kitchen",
+          user: { name: "Alice" },
+          width: 1200,
+          height: 800,
+        },
+      ],
+    });
+    const out = await findStockImage("kitchen", { limit: 1 });
+    expect(out.source).toBe("unsplash");
+    expect(out.results[0].url).toBe("https://images.unsplash.com/abc");
+    expect(out.results[0].attribution).toContain("Alice");
+    expect(out.warning).toBeUndefined();
+  });
+
+  it("respects explicit source override", async () => {
+    const out = await findStockImage("kitchen", { source: "picsum", limit: 1 });
+    expect(out.source).toBe("picsum");
+    expect(out.warning).toBeUndefined();
+  });
+
+  it("falls through when explicit source has no key", async () => {
+    const out = await findStockImage("kitchen", { source: "unsplash", limit: 1 });
+    expect(out.source).toBe("picsum");
+    expect(out.warning).toMatch(/UNSPLASH_ACCESS_KEY/);
+  });
+
+  it("sends Authorization header for unsplash", async () => {
+    process.env.UNSPLASH_ACCESS_KEY = "k1";
+    mockFetchJson({ results: [] });
+    await findStockImage("a", { source: "unsplash" });
+    const headers = global.fetch.mock.calls[0][1].headers;
+    expect(headers.Authorization).toBe("Client-ID k1");
+  });
+
+  it("sends Authorization header for pexels", async () => {
+    process.env.PEXELS_API_KEY = "k2";
+    mockFetchJson({ photos: [] });
+    await findStockImage("a", { source: "pexels" });
+    const headers = global.fetch.mock.calls[0][1].headers;
+    expect(headers.Authorization).toBe("k2");
+  });
+});

mcp-server/src/asset-fetchers/__tests__/picsum.test.js

@@ -0,0 +1,36 @@
+// @vitest-environment node
+
+import { describe, it, expect } from "vitest";
+import { searchPhotos } from "../picsum.js";
+
+describe("picsum.searchPhotos", () => {
+  it("returns the requested number of results (default 5)", () => {
+    const r = searchPhotos("kitchen");
+    expect(r.results).toHaveLength(5);
+  });
+
+  it("clamps limit between 1 and 20", () => {
+    expect(searchPhotos("a", { limit: 9999 }).results).toHaveLength(20);
+    expect(searchPhotos("a", { limit: 0 }).results).toHaveLength(1);
+  });
+
+  it("produces deterministic URLs for the same query", () => {
+    const a = searchPhotos("kitchen", { limit: 3 });
+    const b = searchPhotos("kitchen", { limit: 3 });
+    expect(a.results.map((r) => r.url)).toEqual(b.results.map((r) => r.url));
+  });
+
+  it("differs across queries", () => {
+    const a = searchPhotos("kitchen", { limit: 3 });
+    const b = searchPhotos("forest", { limit: 3 });
+    expect(a.results[0].url).not.toBe(b.results[0].url);
+  });
+
+  it("uses picsum.photos host", () => {
+    const r = searchPhotos("home");
+    for (const item of r.results) {
+      expect(item.url.startsWith("https://picsum.photos/")).toBe(true);
+      expect(item.source).toBe("picsum");
+    }
+  });
+});