awwwards-mcp 1.5.0 → 1.6.0

package/README.md

@@ -4,31 +4,89 @@ Free, open-source MCP server that gives AI agents design inspiration from
 [Awwwards](https://www.awwwards.com/) — the Mobbin-style visual reference loop,
 sourced from the web's best award-winning websites.
 
+<a href="https://github.com/INSANE0777/Awwwards-mcp"><img src="assets/demo.gif" alt="awwwards-mcp in action: search results, design DNA, motion filmstrip, band map — real tool output" width="480"></a>
+
 Your agent searches in natural language ("dark 3D portfolio sites", "soft pastel
 e-commerce"), sees **real screenshots inline**, and can pull the **design DNA**
 of any site: color palette, tech stack, design elements, award history.
+Free-text queries run on a porter-stemmed, prefix-matching FTS5 index with BM25
+ranking — "magazines" now finds Magazine-tagged sites (68 on the live index),
+best matches first, where the old substring path returned zero. Multi-word
+queries keep AND semantics: every token must hit the same site.
 
 ## Tools
 
 | Tool | What it does |
 |------|--------------|
-| `search_sites` | Search by color, tags, technology or award type. Returns site cards with inline screenshots. |
+| `search_sites` | Search by color, tags, technology, award type or free-text query. Multi-word queries match against the local FTS5 index and rank BM25 (title hits lead); zero results come with loose-match and taxonomy-tag hints. Returns site cards with inline screenshots. |
 | `get_site_details` | Full design DNA for one site: palette, technologies, elements, awards, description. |
 | `get_site_elements` | Component-level visuals for one site: each element's poster image inline (3D models, video content, mobile layouts, microcopy…) + video URLs. |
 | `list_categories` | Every filter the agent can search by (200+ tags, 27 colors). |
-| `capture_live_site` | Optional: fresh full-page screenshot of any live URL. Waits for `load` + a settle window with a bounded pre-scroll, so heavy sites work (`waitStrategy: "networkidle"` available). (needs [playwright](https://playwright.dev)). |
-| `analyze_page_structure` | Section band map of any page (live URL or local file:// build): tag, background, offset, height per band. Compare a reference site's structure against your build. Same heavy-site-friendly wait (`waitStrategy: "networkidle"` available). (needs [playwright](https://playwright.dev)). |
-| `record_site_motion` | Optional: short motion-through video of a live URL — preloader, scroll-triggered and hover/cursor animations. Returns an inline filmstrip JPEG plus the saved .webm path. (needs [playwright](https://playwright.dev) + ffmpeg-static). |
+| `capture_live_site` | Optional: fresh full-page screenshot of any live URL. Waits for `load` + a settle window with a bounded pre-scroll, so heavy sites work (`waitStrategy: "networkidle"` available). Pass `viewport: "mobile"` for the 390×844 iPhone-class render (`"desktop"` 1440×900 default). (needs [playwright](https://playwright.dev)). |
+| `analyze_page_structure` | Section band map of any page (live URL or local file:// build): tag, background, offset, height per band. Compare a reference site's structure against your build. Same heavy-site-friendly wait (`waitStrategy: "networkidle"` available); `viewport: "mobile"` analyzes the phone-class layout (`"desktop"` default). (needs [playwright](https://playwright.dev)). |
+| `record_site_motion` | Optional: short motion-through video of a live URL — preloader, scroll-triggered and hover/cursor animations. Returns an inline filmstrip JPEG plus the saved .webm path. `viewport: "mobile"` records at phone size — the filmstrip renders at the selected viewport, no pillarboxing (`"desktop"` default). (needs [playwright](https://playwright.dev) + ffmpeg-static). |
 
 ## Setup
 
+Any MCP-compatible coding agent can use awwwards-mcp — no API key, no account.
+Requires Node ≥ 22.13 (`node -v` to check). Pick your agent:
+
+**Updates**: the server checks the npm registry once a day and prints an
+stderr notice when a newer `awwwards-mcp` exists (stdout stays clean for the
+JSON-RPC channel — your agent sees the notice as a log line). Set
+`AWWWARDS_AUTO_UPDATE=1` in the server's `env` to opt into background
+self-update; restart your agent afterwards to load it. Nothing is fetched
+more than once a day and serving never waits on the check.
+
 **Claude Code**
 
 ```bash
 claude mcp add awwwards -- npx -y awwwards-mcp
 ```
 
-**Claude Desktop / Cursor / Windsurf** (`mcpServers` in the config):
+**Codex CLI** (ChatGPT desktop app and the IDE extension share this config)
+
+```bash
+codex mcp add awwwards -- npx -y awwwards-mcp
+```
+
+or in `~/.codex/config.toml` (project-scoped: `.codex/config.toml`):
+
+```toml
+[mcp_servers.awwwards]
+command = "npx"
+args = ["-y", "awwwards-mcp"]
+```
+
+**OpenCode** (`opencode.json` — note the command is an array)
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "mcp": {
+    "awwwards": {
+      "type": "local",
+      "command": ["npx", "-y", "awwwards-mcp"]
+    }
+  }
+}
+```
+
+**ZCode** (`~/.zcode/cli/config.json` — note servers nest under `"mcp": { "servers": ... }`)
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"], "env": {} }
+    }
+  }
+}
+```
+
+**Claude Desktop / Cursor / Windsurf / Gemini CLI / Cline / Continue** — anything
+reading the common `mcpServers` JSON shape (e.g. `~/.claude/claude_desktop_config.json`
+or `~/.gemini/settings.json`):
 
 ```json
 {
@@ -38,25 +96,58 @@ claude mcp add awwwards -- npx -y awwwards-mcp
 }
 ```
 
-Optional full-page captures:
+**Anything else** — awwwards-mcp is a plain stdio MCP server: point your client
+at `npx -y awwwards-mcp` and it works. To pin a version, use
+`npx -y awwwards-mcp@1.0.0`.
+
+**pi coding agent** has no built-in MCP by design — it uses skills and
+extensions instead. Two options:
+
+1. Install the awwwards-inspiration skill (below). pi reads skills from
+   `~/.pi/agent/skills/` or `~/.agents/skills/` (the latter is shared across
+   agents following the Agent Skills standard). The skill teaches the workflow;
+   for it to reach the live data, add an MCP-supporting pi extension, or run
+   the queries in another agent and paste results.
+2. Skip MCP entirely: ask pi to build you a small CLI wrapper around
+   awwwards.com, or use a shared skills directory (`~/.agents/skills/`) so the
+   same skill file serves pi and every other agent.
+
+Optional full-page captures (needed by `capture_live_site`,
+`analyze_page_structure`, `record_site_motion`):
 
 ```bash
 npm install -g playwright && npx playwright install chromium
 ```
 
+`record_site_motion` additionally uses ffmpeg; it resolves the `ffmpeg-static`
+package automatically if present.
+
 ## Skills
 
-This package ships an agent skill that teaches the inspiration workflow —
-search, judge from screenshots, pull design DNA, state a design direction —
-using the awwwards MCP tools. Copy it into your agent's skills directory:
+This package ships three agent skills. Any agent that follows the
+[Agent Skills standard](https://agentskills.io) can load them; copy them into
+your agent's skills directory:
 
 ```bash
 npm install awwwards-mcp
-mkdir -p ~/.claude/skills && cp -r node_modules/awwwards-mcp/skills/awwwards-inspiration ~/.claude/skills/
+mkdir -p ~/.agents/skills && cp -r node_modules/awwwards-mcp/skills/awwwards-inspiration node_modules/awwwards-mcp/skills/awwwards-doctor node_modules/awwwards-mcp/skills/awwwards-motion-study ~/.agents/skills/
 ```
 
-For ZCode, copy to `~/.zcode/skills/` instead of `~/.claude/skills/`.
-Windows: run this from Git Bash, or copy `node_modules\awwwards-mcp\skills\awwwards-inspiration` manually.
+| Skill | What it teaches |
+|-------|-----------------|
+| `awwwards-inspiration` | The inspiration loop: search, judge from screenshots, pull design DNA, state a design direction, capture/motion-first builds. |
+| `awwwards-motion-study` | The full video chain: what to record from a live site (and what to skip), frame-by-frame review (video input or tile-per-element), the motion inventory, and build verification by re-recording. |
+| `awwwards-doctor` | Repair: run `npm run doctor`, apply its fixes, re-anchor parsers after real awwwards.com drift, recover the in-flight task that surfaced the failure. |
+
+| Agent | Skills directory |
+|-------|------------------|
+| Claude Code | `~/.claude/skills/` |
+| pi | `~/.pi/agent/skills/` (also reads `~/.agents/skills/`) |
+| ZCode | `~/.zcode/skills/` |
+| Agent Skills-standard agents | `~/.agents/skills/` |
+
+Windows: run this from Git Bash, or copy
+`node_modules\awwwards-mcp\skills\awwwards-inspiration` manually.
 
 ## Indexing (recommended)
 
@@ -94,6 +185,171 @@ and content remain the property of Awwwards and the credited creators — don't
 bulk-scrape, redistribute, or republish them. If you use this commercially,
 review awwwards.com's terms yourself.
 
+## Built with awwwards-mcp: four real sites
+
+Four complete sites were built through the full inspiration loop this MCP
+enables, using nothing but the server's tools plus the shipped
+`awwwards-inspiration` skill. Each one exercised a different corner of the
+loop — and every correction the loop caught on the way became doctrine in the
+skill.
+
+> **Built in one shot, by a model that can't watch video.** All three sites
+> were built in a single prompt run on **GLM 5.3-flash** — which does not
+> support video input. The loop's motion study worked entirely from
+> frame-tiled filmstrips (ffmpeg, 1–2 fps per element) instead of watching
+> the recordings. With a video-native model, those same `get_site_elements`
+> videos and `record_site_motion` .webm files could be watched directly —
+> timing, easing and overlap read at full fidelity — and the motion-true
+> results would be better still. The skill's frame-tile doctrine is what
+> closes that gap today.
+
+**1. [Ridge](showcase/ridge/index.html)**
+([source](showcase/ridge/)) — a Swiss-minimal single-page showcase for a fictional engineering-talent studio, direction **Aspen Search** (SOTD + Developer Award, jury 7.48): monochrome `#FAFAF8`/`#1A1A1A` + mint, giant grotesque section markers, halftone grain, asymmetric panel grid, dark discipline panels in an interior **horizontal pin passage**, count-up stats, client rows, theme toggle, cursor-follower. Built with the v1.4.0 toolkit: FTS5-ranked direction search, **both-viewports** reference captures and QA (desktop 7,849px + mobile 390×844), overflow audit (0px both), pin-center shots, film verification — and the skill-memory flywheel recorded the findings. QA evidence: `showcase/ridge/_qa/`.
+
+| Panel grid (desktop) | Horizontal discipline passage | Mobile 390×844 |
+|---|---|---|
+| ![Ridge desktop — Swiss panel grid with mint and grain](assets/ridge-home.jpg) | ![Ridge disciplines — pinned horizontal passage mid-slide](assets/ridge-disciplines.jpg) | ![Ridge mobile — stacked grid, zero overflow](assets/ridge-mobile.jpg) |
+
+**2. [Fallow Press](fallow-press/index.html)**
+([source](fallow-press/)) — a flat-2D editorial journal, direction
+**Emergence Magazine** (SOTD): pink `#FF9398` on cream and black, torn-paper
+masthead (pure CSS `clip-path`, zero WebGL), giant grotesque display over
+grayscale photography, serif-italic brand, three pages with **separate
+horizontal** projects/about pages (GSAP ScrollTrigger pin +
+`containerAnimation`).
+
+| Torn-paper masthead (home) | Horizontal gallery (Fields) | Horizontal chapters (Practices) |
+|---|---|---|
+| ![Fallow Press home — torn-paper masthead over grayscale photography](assets/fallow-home.jpg) | ![Fallow Press Fields — pinned horizontal gallery panel](assets/fallow-fields.jpg) | ![Fallow Press Practices — pink quote chapter](assets/fallow-practices.jpg) |
+
+The loop as it ran:
+
+1. `search_sites` (magazine filters) → shortlist judged from inline
+   screenshots → `get_site_details` on Emergence Magazine.
+2. **Capture before building**: `capture_live_site` + `record_site_motion`
+   on the live site *first*; full-page PNG and motion .webm kept in
+   [fallow-press/ref-motion/](fallow-press/ref-motion/) as the evidence trail.
+3. Build, then verify: full-page capture plus **panel-center pin shots** of
+   both horizontal pages (13 stops each, in
+   [fallow-press/_qa/](fallow-press/_qa/) — `capture-qa.mjs` is reusable).
+4. The pin shots caught a real bug: horizontal-panel entrances used
+   `toggleActions: "play none none reverse"`, and 100vw panels hide content
+   at midpoints on the way back — copy disappeared mid-view. Fix
+   (one-shot play entrances) is now doctrine: **full-viewport panels get
+   one-shot entrances**; QA pin shots land at panel **centers**, not uniform
+   fractions, or you photograph empty transition zones.
+
+**3. Cerebrium recreation** (`C:/Users/Afjal/cerebrium-recreation/`) — a
+fidelity-first recreation of cerebrium.ai, pixel-checked against the live
+reference: full-page captures of both sides, `analyze_page_structure` band
+compare, and SVG icon/legend fixes until the build matched the reference to
+within 1px of total page height (10,871px vs 10,870px). This is the
+**structure-before-pixels** doctrine at its strictest — band maps compared,
+never just totals.
+
+![Cerebrium recreation — full-page build capture](assets/cerebrium-build.jpg)
+
+**4. The Meridian** (`C:/Users/Afjal/editorial-site/`) — an editorial journal
+built from ORDR/Hearst references: the first build to run the whole loop
+end-to-end. `analyze_page_structure` caught a masthead band bug by comparing
+the build's band map against the reference's; the reference captures,
+motion film, and the reusable pre-scroll capture script live in
+`editorial-site/_qa/`.
+
+![The Meridian editorial journal — full-page build capture](assets/meridian-build.jpg)
+
+![The Meridian — motion filmstrip from record_site_motion](assets/meridian-filmstrip.jpg)
+
+## Skills used to build these
+
+| Skill | Role in the builds |
+|---|---|
+| `awwwards-inspiration` | The 8-step loop itself (ships with this package): search → judge from screenshots → design DNA → capture/motion study → state direction → build → band-map verify. |
+| `gsap-scrolltrigger` | The horizontal pin + `containerAnimation` pattern (ease `"none"`, one-shot entrances) driving both Fallow Press horizontal pages. |
+| `gsap-core` / `gsap-timeline` | Tween composition and sequenced hero entrances (torn-paper drop, panel copy rises). |
+| `frontend-design` | Typography, palette and layout judgment applied when translating reference DNA into original pages. |
+| `lenis` (library, via skill guidance) | smooth scrolling synced to ScrollTrigger on the Fallow Press home page. |
+| `tailwindcss` / plain CSS | All builds are plain hand-rolled CSS — flat 2D, no frameworks needed. |
+
+**The skills self-improve:** every loop pass records what verification caught (`scripts/skill-memory.mjs record`), and a deterministic distiller folds rules seen 2+ times into your installed skill copy — while the shipped copies only change via human PR. A techniques registry (`skills/_memory/techniques.json`) catalogs researched how-tos per domain (video understanding, motion detection, UI structure, micro-interactions, images).
+
+Reduced-motion, JS-less visits, and capture tools all get graceful fallbacks
+(vertical stacks; progressive-enhancement reveals).
+
+**What the verification loop caught** — proof the structure-before-pixels
+doctrine is load-bearing:
+
+- Element **posters lie**: the first showcase build was designed from poster
+  frames alone and rendered a spinning 3D ring as *floating static cards*.
+  Downloading the element videos (`get_site_elements`) and frame-tiling them
+  revealed the motion truth — now the skill mandates studying motion before
+  animating.
+- Full-page captures of reveal-on-scroll builds showed blank sections: `.reveal`
+  animation state vs capture's no-scroll reality. Builds ship
+  content-visible-without-JS progressive enhancement.
+- Horizontal-panel copy vanished **mid-view** on the Fallow Press pages:
+  `toggleActions` reverse reverts entrances while a 100vw panel is still
+  holding the viewport (see above).
+- Band-map compare kept the references' rhythm instead of drifting on
+  section heights (Cerebrium, The Meridian).
+
+Prompt counts: **3** for the original showcase build (the build ask, the
+motion correction that exposed the poster-lie, the structure pass) and
+**1** for Fallow Press ("create a new website using our MCP and skills… no
+3D websites") — its two follow-ups were caught by the QA loop, not by the
+user. Each correction became doctrine in the shipped `awwwards-inspiration`
+skill: frame-study element videos before animating; judge page architecture
+from the studied passages; tile per element, not one giant filmstrip;
+capture live sites and animation **before** building.
+
+## Can awwwards-mcp crawl the sitemap? (robots.txt notes)
+
+The awwwards.com `robots.txt` advertises
+`Sitemap: https://www.awwwards.com/sitemap.xml` and — verified live
+2026-09-18 — **that sitemap URL returns a soft-404 HTML page** (as do common
+child names like `/sitemap-websites.xml`). So sitemap discovery isn't
+currently a path to more data; the polite crawl surface is exactly what the
+indexer uses:
+
+- **Allowed and used**: `/websites/`, `/websites/<filter>/`, `/sites/<slug>`
+  (one filter per URL; deep pagination stays un-crawled).
+- **Disallowed and never fetched**: `/tag/`, `/search-websites`,
+  `/websites/?` (query-string pagination), `/elements/*`, `/vote/`,
+  favourites/likes/follows, and the rest of the 33 rules.
+- Our client (`src/awwwards.ts` `buildFilterUrl`) constructs **only**
+  `/websites/…` paths at 1 request/second — the loop stays inside the
+  published rules by construction, not by convention.
+
+## Contributing
+
+PRs welcome! The project especially needs **parser-drift fixes** — when live
+awwwards.com markup changes, a fresh HTML snapshot attached to an issue often
+becomes the new test fixture and the fastest merged PR. See
+[CONTRIBUTING.md](CONTRIBUTING.md) for the full guide:
+
+**Parser-drift is monitored automatically.** A probe script
+([scripts/parser-drift-probe.mjs](scripts/parser-drift-probe.mjs),
+`npm run drift`) checks every markup anchor the parsers depend on — the
+`split`/`indexOf`/regex literals in `src/parsers.ts` — against the live
+listing and detail pages (2 fetches, 1 request/second, same politeness as
+the client). A daily GitHub Action ([.github/workflows/parser-drift.yml](.github/workflows/parser-drift.yml))
+runs it and, on drift, opens/updates a single tracking issue with the exact
+anchors that changed (and auto-closes it when a later run is green). To run
+it yourself: `npm run drift` (live, exit code 0/1/2) or `npm run drift -- --fixture`
+(offline, checks the committed fixtures still feed every anchor). Raw HTML
+is never diffed or stored — anchors only fire when the parsers actually
+break, so there are no false alarms from cosmetic tweaks.
+
+- Development setup & project layout (offline fixture-tested, no network in tests)
+- How to create a PR: fork → `fix/`/`feat/`/`docs/` branch → typecheck + tests → PR template
+- The politeness constraints new code must keep (1 req/s, robots.txt paths, light runtime deps)
+
+Bugs and feature ideas start as
+[issues](https://github.com/INSANE0777/Awwwards-mcp/issues/new/choose) with
+templates. Security problems go privately — see
+[SECURITY.md](SECURITY.md). By participating you agree to the
+[Code of Conduct](CODE_OF_CONDUCT.md).
+
 ## Development
 
 ```bash

package/dist/cache.js

@@ -17,6 +17,28 @@ const SCHEMA = `
     key TEXT PRIMARY KEY, value TEXT, fetchedAt INTEGER
   );
 `;
+// FTS5 full-text layer over the sites table (derived — rebuildable at any
+// time). Probe-guarded: if this Node build ships without FTS5, every fts
+// statement is skipped and searchSites returns null (server keeps the legacy
+// substring path). Columns mirror sites; tags/awards stay JSON strings —
+// unicode61 tokenizes around brackets/quotes, so tokens extract cleanly.
+const FTS_SCHEMA = `
+  CREATE VIRTUAL TABLE IF NOT EXISTS sites_fts USING fts5(
+    slug UNINDEXED, title, tags, awards, tokenize='porter unicode61'
+  );
+  CREATE TRIGGER IF NOT EXISTS sites_fts_ai AFTER INSERT ON sites BEGIN
+    INSERT INTO sites_fts (slug, title, tags, awards)
+    VALUES (new.slug, new.title, new.tags, new.awards);
+  END;
+  CREATE TRIGGER IF NOT EXISTS sites_fts_au AFTER UPDATE OF title, tags, awards ON sites BEGIN
+    DELETE FROM sites_fts WHERE slug = new.slug;
+    INSERT INTO sites_fts (slug, title, tags, awards)
+    VALUES (new.slug, new.title, new.tags, new.awards);
+  END;
+  CREATE TRIGGER IF NOT EXISTS sites_fts_ad AFTER DELETE ON sites BEGIN
+    DELETE FROM sites_fts WHERE slug = old.slug;
+  END;
+`;
 function rowToSite(r) {
     return {
         slug: r.slug,
@@ -34,6 +56,12 @@ export class Cache {
     dbPath;
     now;
     imagesDir;
+    // FTS5 capability of this Node build, probed on the first DB open (the
+    // constructor's eager withDb). null = not yet probed; false = FTS5 compiled
+    // out → searchSites returns null and callers keep the legacy substring
+    // path. Instance-cached so searchSites never re-probes; public so the
+    // server layer and tests can branch on it.
+    ftsAvailable = null;
     constructor(rootDir, now = Date.now) {
         this.now = now;
         mkdirSync(rootDir, { recursive: true });
@@ -52,12 +80,40 @@ export class Cache {
         const db = new DatabaseSync(this.dbPath);
         try {
             db.exec(SCHEMA);
+            if (this.ftsAvailable === null) {
+                try {
+                    db.exec(FTS_SCHEMA);
+                    this.ftsAvailable = true;
+                }
+                catch {
+                    this.ftsAvailable = false; // FTS5 compiled out → legacy fallback
+                }
+            }
+            if (this.ftsAvailable) {
+                // The fts table is derived and must never gate correctness: if sites
+                // has rows but sites_fts is empty (pre-FTS database opened for the
+                // first time), rebuild the index. The guard lives inside the INSERT
+                // itself (slug NOT IN sites_fts), not only in the counts above: the
+                // counts are read non-atomically, so `npm run index` and a first open
+                // can both pass them and both run this statement — sites_fts.slug has
+                // no unique constraint, so an unguarded re-run would double-index.
+                // Afterwards triggers keep it synced.
+                const { s: sitesN } = db.prepare("SELECT COUNT(*) AS s FROM sites").get();
+                const { s: ftsN } = db.prepare("SELECT COUNT(*) AS s FROM sites_fts").get();
+                if (sitesN > 0 && ftsN === 0) {
+                    db.exec("INSERT INTO sites_fts (slug, title, tags, awards) SELECT slug, title, tags, awards FROM sites WHERE slug NOT IN (SELECT slug FROM sites_fts)");
+                }
+            }
             return fn(db);
         }
         finally {
             db.close();
         }
     }
+    /** @visibleForTesting */
+    withDbForTest(fn) {
+        this.withDb(fn);
+    }
     upsertSites(sites) {
         this.withDb((db) => {
             const stmt = db.prepare(`INSERT INTO sites (slug, id, title, createdAt, tags, thumbnailPath, liveUrl, detailPath, awards, fetchedAt)
@@ -99,6 +155,34 @@ export class Cache {
             return rowToSite(row);
         });
     }
+    // Full-text search over cached sites. matchMode "AND" (default) requires
+    // every token; "OR" matches rows containing any token (the server uses OR
+    // for its zero-result "loose matches" hint). Each token is a porter-stemmed
+    // prefix term, so multi-word queries match rows where the words are
+    // scattered across title/tags/awards. Results are bm25-ascending (best
+    // match first). Returns null when FTS5 is unavailable on this build or the
+    // query has no usable tokens — callers fall back to legacy search.
+    searchSites(query, maxAgeMs, limit = 200, matchMode = "AND") {
+        // Sanitization strips quotes/parens/operators, leaving [a-z0-9-] only —
+        // the quoted `"tok"*` MATCH string below cannot inject FTS syntax.
+        const tokens = query.toLowerCase().split(/\s+/)
+            .map((t) => t.replace(/[^a-z0-9-]/g, ""))
+            .filter((t) => t.length > 0);
+        if (!tokens.length)
+            return null;
+        return this.withDb((db) => {
+            if (!this.ftsAvailable)
+                return null;
+            const match = tokens.map((t) => `"${t}"*`).join(matchMode === "OR" ? " OR " : " AND ");
+            const min = this.now() - maxAgeMs;
+            const rows = db.prepare(`SELECT s.* FROM sites_fts
+         JOIN sites s ON s.slug = sites_fts.slug
+         WHERE sites_fts MATCH ? AND s.fetchedAt > ?
+         ORDER BY bm25(sites_fts) ASC
+         LIMIT ?`).all(match, min, limit);
+            return rows.map(rowToSite);
+        });
+    }
     setMeta(key, value) {
         this.withDb((db) => {
             db.prepare(`INSERT INTO meta (key, value, fetchedAt) VALUES (?, ?, ?)

package/dist/capture.js

@@ -6,6 +6,7 @@ import { join } from "node:path";
 // CAPTURE_INSTALL_HINT from here) — both sides only use the other's bindings
 // at call time, which ESM resolves fine.
 import { preScroll } from "./structure.js";
+import { resolveViewport } from "./viewport.js";
 export const CAPTURE_INSTALL_HINT = "Full-page capture needs Playwright, which is an optional dependency.\n" +
     "Install it with:  npm install -D playwright && npx playwright install chromium\n" +
     "Then retry the capture or structure tool.";
@@ -29,7 +30,12 @@ loader = () => import("playwright"), opts) {
     }
     try {
         const waitStrategy = opts?.waitStrategy ?? "load";
-        const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+        // Same viewport-profile split as analyzePageStructure (structure.ts):
+        // width/height fill the `viewport` key, mobile-profile flags spread in as
+        // sibling context options. Desktop resolves to no extra fields, so the
+        // default call shape is unchanged.
+        const { width, height, ...contextOpts } = resolveViewport(opts?.viewport);
+        const page = await browser.newPage({ viewport: { width, height }, ...contextOpts });
         await page.goto(url, { waitUntil: waitStrategy, timeout: 45_000 });
         // "load" can fire before late XHRs settle, so give the page a fixed
         // settle window; networkidle already means the network went quiet.

package/dist/cli.js

@@ -12,6 +12,7 @@ import { Cache } from "./cache.js";
 import { createHandlers } from "./server.js";
 import { captureLiveSite } from "./capture.js";
 import { runIndexer, shouldAutoIndex } from "./indexer.js";
+import { checkForUpdate } from "./version-check.js";
 // The handlers return ToolResponse, which is structurally identical to the
 // SDK's CallToolResult at runtime ({ content, isError? }). CallToolResult's
 // schema additionally carries a [k: string]: unknown index signature that a
@@ -22,6 +23,10 @@ const waitStrategySchema = z
     .enum(["load", "networkidle"])
     .default("load")
     .describe("'load' + settle works on heavy sites; 'networkidle' waits for total quiet");
+const viewportSchema = z
+    .enum(["desktop", "mobile"])
+    .default("desktop")
+    .describe("desktop = 1440x900 (default); mobile = 390x844 iPhone-class with deviceScaleFactor 3, isMobile + hasTouch");
 const cacheRoot = process.env.AWWWARDS_CACHE_DIR ?? join(homedir(), ".awwwards-mcp");
 let cache;
 try {
@@ -76,11 +81,13 @@ server.tool("list_categories", "List the filter taxonomy available on Awwwards:
 server.tool("capture_live_site", "Take a fresh full-page screenshot of a live website URL using a headless browser. Requires the optional playwright dependency.", {
     url: z.string().url().describe("Absolute URL of the site to capture"),
     waitStrategy: waitStrategySchema,
+    viewport: viewportSchema,
 }, (args) => asMcpResult(handlers.capture_live_site(args)));
 server.tool("analyze_page_structure", "Extract a page's section band map (tag, label, background color, offset, height per band) via a headless browser. Works on live URLs and file:// paths — use it to compare a reference site's structure against your local build.", {
     url: z.string().url().describe("Absolute URL (https:// or file://) of the page to analyze"),
     maxBands: z.number().int().min(5).max(60).default(40).describe("Cap on returned bands"),
     waitStrategy: waitStrategySchema,
+    viewport: viewportSchema,
 }, (args) => asMcpResult(handlers.analyze_page_structure(args)));
 server.tool("record_site_motion", "Record a short motion-through video of a live website — preloader, scroll-triggered and hover/cursor animations — and return an inline filmstrip JPEG plus the .webm path. Requires the optional playwright and ffmpeg-static dependencies.", {
     url: z.string().url().describe("Absolute URL of the site to record"),
@@ -92,6 +99,7 @@ server.tool("record_site_motion", "Record a short motion-through video of a live
         .default(16)
         .describe("Filmstrip tile count (default 16 → a 4x4 grid)"),
     waitStrategy: waitStrategySchema,
+    viewport: viewportSchema,
 }, (args) => asMcpResult(handlers.record_site_motion(args)));
 // Auto-refresh: if the index is stale (or absent) and no crawl is running,
 // re-index in the background. Serving is never blocked; errors are stderr-only.
@@ -100,4 +108,7 @@ if (shouldAutoIndex(cache)) {
         console.error(`awwwards-mcp: background index failed: ${err instanceof Error ? err.message : String(err)}`);
     });
 }
+// Update notice: once a day, compare against the npm registry; stderr-only,
+// never blocks serving. AWWWARDS_AUTO_UPDATE=1 opts into background install.
+checkForUpdate(pkgJson.version);
 await server.connect(new StdioServerTransport());

package/dist/motion.js

@@ -4,6 +4,7 @@ import { existsSync, mkdirSync, mkdtempSync, readdirSync, renameSync, rmSync, st
 import { readFile } from "node:fs/promises";
 import { join } from "node:path";
 import { CAPTURE_INSTALL_HINT } from "./capture.js";
+import { resolveViewport } from "./viewport.js";
 export const MOTION_FFMPEG_HINT = "Motion recording needs ffmpeg-static, which is an optional dependency.\n" +
     "Install it with:  npm install -D ffmpeg-static\n" +
     "Then retry record_site_motion.";
@@ -167,9 +168,17 @@ export async function recordSiteMotion(url, opts) {
     const videoTmp = mkdtempSync(join(opts.cacheImagesDir, ".video-tmp-"));
     const waitStrategy = opts.waitStrategy ?? "load";
     try {
+        // Viewport profile split (same as structure/capture): width/height fill
+        // the `viewport` key; the mobile-profile flags (deviceScaleFactor/
+        // isMobile/hasTouch) spread in as sibling context options AFTER the
+        // existing fields. recordVideo.size derives from the same profile so the
+        // video canvas matches the viewport (desktop keeps the 1440x900 canvas; a
+        // mobile recording gets a 390x844 canvas instead of a pillarboxed one).
+        const { width, height, ...contextOpts } = resolveViewport(opts.viewport);
         const context = await browser.newContext({
-            viewport: { width: 1440, height: 900 },
-            recordVideo: { dir: videoTmp, size: { width: 1440, height: 900 } },
+            viewport: { width, height },
+            recordVideo: { dir: videoTmp, size: { width, height } },
+            ...contextOpts,
         });
         try {
             const page = await context.newPage();

package/dist/parsers.js

@@ -148,9 +148,12 @@ export function parseElements(html) {
             continue;
         }
         const mediaPath = blob?.collectableImage;
-        // Only element media (videos/posters live under element/); other blobs
-        // (site card, collections) must not leak in if the end bound is missing.
-        if (typeof mediaPath === "string" && mediaPath.startsWith("element/")) {
+        // Only element media; other blobs (site card, collections) must not leak
+        // in if the end bound is missing. Media paths come in two schemes: modern
+        // sites store them under element/YYYY/MM/..., 2018-era sites under
+        // external/YYYY/MM/... (both verified live 2026-09-18 — the CDN serves
+        // both prefixes and their _static.jpeg posters).
+        if (typeof mediaPath === "string" && /^(element|external)\//.test(mediaPath)) {
             elements.push({
                 title: decodeEntities(String(blob.collectableTitle ?? "")),
                 mediaPath,