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.

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";

src/pages/docs/userGuide.md

@@ -832,7 +832,7 @@ Open Claude Desktop settings, go to the MCP section, and add a new server with:
 
 ### Available tools
 
-The MCP server exposes 29 tools organized by category:
+The MCP server exposes 32 tools organized by category:
 
 - **File** — `create_flow`, `open_flow`, `save_flow`, `get_flow_info`
 - **Screen** — `create_screen` (from HTML), `create_blank_screen`, `update_screen`, `delete_screen`, `list_screens`, `get_screen`, `update_screen_image`, `batch_create_screens`, `compose_chrome`, `get_chrome_info`
@@ -844,6 +844,7 @@ The MCP server exposes 29 tools organized by category:
 - **Comments** — `list_comments`, `create_comment`, `update_comment`, `resolve_comment`, `delete_comment`
 - **Generation** — `validate_flow`, `generate_instructions`, `analyze_navigation`
 - **Selection** — `get_current_selection`
+- **Assets** — `generate_icon`, `search_icons`, `find_stock_image`
 
 ### Creating screens from HTML
 
@@ -894,6 +895,33 @@ A typical agent interaction looks like this:
 
 You can then open the saved `.drawd` file in Drawd to visually inspect the flow, adjust screen positions, refine hotspots, and regenerate instructions.
 
+### Icons and stock photos
+
+Three asset tools let agents enrich screens with real imagery instead of hand-drawn shapes or emoji substitutes.
+
+- `generate_icon` — Fetch one icon by `collection` + `name` from Iconify (275k+ icons across `mdi`, `ph`, `lucide`, `tabler`, `heroicons`, `solar`, `carbon`, and more). Returns an inline SVG string the agent embeds verbatim in the screen HTML. Use `color: "currentColor"` to inherit the surrounding text color.
+- `search_icons` — Search Iconify across all (or one) collections. Returns ranked candidate icon IDs the agent can preview and pick from before calling `generate_icon`.
+- `find_stock_image` — Search royalty-free photos and get back URLs with attribution. Embed via `<img src="...">` in the screen HTML; the renderer fetches and inlines the bytes at PNG-render time. Sources: Unsplash, Pexels, Picsum.
+
+#### Zero-config and key-upgrade paths
+
+The tools work on a fresh install with no API keys — Iconify and Picsum are keyless. Setting environment variables upgrades the photo source without code changes:
+
+- `UNSPLASH_ACCESS_KEY` — enables query-relevant Unsplash results.
+- `PEXELS_API_KEY` — enables Pexels as the secondary photo source.
+
+`find_stock_image` tries `unsplash` → `pexels` → `picsum` in order based on which keys are configured. When a keyed source is requested but the key is missing, the tool transparently falls back to the next provider and includes a `warning` field describing what happened, so the agent can surface it to the user.
+
+> [!NOTE]
+> Picsum does not actually search by query — it returns deterministic seeded photos for a given query string. Set `UNSPLASH_ACCESS_KEY` for query-relevant results.
+
+#### Renderer image inlining
+
+When `create_screen` HTML contains `<img src="https://...">`, the renderer downloads each image and bakes the bytes into the rendered PNG so the screen looks complete. Only an allowlist of provider hosts (`api.iconify.design`, `images.unsplash.com`, `api.unsplash.com`, `api.pexels.com`, `images.pexels.com`, `picsum.photos`, `fastly.picsum.photos`) is fetched. Any other host (or a failed fetch) is replaced with a transparent 1×1 placeholder so a single bad URL never breaks the whole render.
+
+> [!TIP]
+> Cached image bytes live under `~/.cache/drawd-mcp/` and persist across runs. The first render of a screen with photos is the slow one; re-renders use the disk cache.
+
 ### Reading the user's current selection
 
 The `get_current_selection` tool lets an AI agent know which element(s) you currently have selected in the Drawd browser app — so you can say "update this screen" or "add a hotspot here" without pasting IDs.