awwwards-mcp 1.0.0

package/dist/structure.js

@@ -0,0 +1,208 @@
+import { CAPTURE_INSTALL_HINT } from "./capture.js";
+// Runs IN THE PAGE via page.evaluate. Collects full-width, tall, opaque
+// elements as band candidates; body is always the base candidate. Gradient
+// shorthand backgrounds leave backgroundColor transparent — such sections
+// fall through to the nearest opaque ancestor (usually body).
+//
+// page.evaluate serializes plain data only, so this is a single
+// self-contained function returning { title, totalHeight, candidates }
+// (no closures over module scope). The Node tsconfig has no DOM lib, so
+// browser globals are reached through globalThis.
+//
+// The backgroundColor alpha parsing in the visit loop (including the
+// modern-color-function fallback) is mirrored in test/structure.test.ts
+// ("SCAN_SNIPPET alpha parsing handles space syntax and percentage alphas")
+// and must stay in sync.
+export const SCAN_SNIPPET = () => {
+    const g = globalThis;
+    const doc = g.document;
+    const totalHeight = Math.round(doc.documentElement.scrollHeight);
+    const bodyW = doc.body.getBoundingClientRect().width || 1;
+    const bodyBg = g.getComputedStyle(doc.body).backgroundColor;
+    const candidates = [
+        {
+            tag: "body",
+            label: "body",
+            bg: bodyBg,
+            top: 0,
+            height: totalHeight,
+            textStart: "",
+        },
+    ];
+    const seen = new Set();
+    const visit = (el, depth) => {
+        if (depth > 6 || candidates.length >= 300 || seen.has(el))
+            return;
+        seen.add(el);
+        const r = el.getBoundingClientRect();
+        if (el !== doc.body && r.width >= 0.6 * bodyW && r.height >= 120) {
+            const s = g.getComputedStyle(el);
+            const color = s.backgroundColor;
+            // Alpha parse tolerant of legacy comma syntax and CSS Color 4
+            // space syntax: rgb(r g b / a), rgb(r, g, b, a), and percentage alphas.
+            // A rgba?() miss falls back by color function: modern opaque functions
+            // (oklch/oklab/lab/lch/hwb/color) count as opaque (alpha 1); anything
+            // else (gradients, keywords) stays conservative at alpha 0.
+            const m = /rgba?\(([^)]+)\)/.exec(color);
+            let alpha = 0;
+            if (m) {
+                const parts = m[1].replace(/\//g, " ").trim().split(/[\s,]+/).filter(Boolean);
+                const aRaw = parts.length >= 4 ? parts[3] : "1";
+                alpha = aRaw.endsWith("%") ? parseFloat(aRaw) / 100 : parseFloat(aRaw);
+                if (Number.isNaN(alpha))
+                    alpha = 0;
+            }
+            else if (/^(oklch|oklab|lab|lch|hwb|color)\(/.test(color.trim())) {
+                alpha = 1;
+            }
+            if (alpha > 0) {
+                candidates.push({
+                    tag: el.tagName.toLowerCase(),
+                    label: (el.id ? "#" + el.id : "") + (el.classList.length ? "." + String(el.classList[0]) : ""),
+                    bg: s.backgroundColor,
+                    top: Math.round(r.top + g.scrollY),
+                    height: Math.round(r.height),
+                    textStart: (el.textContent ?? "").trim().slice(0, 60),
+                });
+            }
+        }
+        for (const child of el.children)
+            visit(child, depth + 1);
+    };
+    visit(doc.body, 0);
+    return { title: doc.title, totalHeight, candidates };
+};
+// PURE: reduces raw candidates to the page's visible horizontal band map.
+// Sweeps y in 8px steps; at each y the effective background is the covering
+// candidate with the SMALLEST height (most specific wins). Consecutive
+// same-background runs merge (first label wins); bands < 40px are absorbed
+// into the previous band; the count is capped by merging the smallest band
+// into its previous neighbor. Uncovered y (gaps) never emit a band.
+export function collapseBands(cands, totalHeight, maxBands = 40) {
+    // Round candidate geometry up front: the sweep samples integer y and the
+    // emitted coordinates must be rounded (top 0.4 must yield a band at 0).
+    const usable = cands
+        .map((c) => ({ ...c, top: Math.round(c.top), height: Math.round(c.height) }))
+        .filter((c) => c.height > 0);
+    const STEP = 8;
+    const bgAt = (y) => {
+        let best = null;
+        for (const c of usable) {
+            if (c.top <= y && y < c.top + c.height) {
+                if (!best || c.height < best.height)
+                    best = c;
+            }
+        }
+        return best;
+    };
+    const runs = [];
+    let y = 0;
+    let current = null;
+    while (y < totalHeight) {
+        const c = bgAt(y);
+        if (current && c && c.bg === current.cand.bg) {
+            // same run continues
+        }
+        else {
+            if (current)
+                runs.push({ cand: current.cand, top: current.top, height: y - current.top });
+            current = c ? { cand: c, top: y } : null;
+            if (!c) {
+                // no candidate covers y (gap): nothing is emitted; when coverage
+                // resumes the merge pass below re-joins same-bg neighbors.
+            }
+        }
+        y += STEP;
+    }
+    if (current)
+        runs.push({ cand: current.cand, top: current.top, height: totalHeight - current.top });
+    // Merge adjacent same-bg runs (first label wins), absorb tiny slivers.
+    // Absorbing a sliver seals the seam so a same-bg run after the sliver
+    // stays its own band instead of bleeding across it.
+    const merged = [];
+    for (const r of runs) {
+        const prev = merged[merged.length - 1];
+        if (prev && !prev.sealed && prev.cand.bg === r.cand.bg)
+            prev.height = r.top + r.height - prev.top;
+        else if (r.height < 40 && prev) {
+            prev.height = r.top + r.height - prev.top;
+            prev.sealed = true;
+        }
+        else
+            merged.push({ ...r });
+    }
+    // Cap: merge the smallest band into its previous neighbor until <= maxBands.
+    while (merged.length > maxBands && merged.length > 1) {
+        let idx = 1;
+        for (let i = 1; i < merged.length; i++)
+            if (merged[i].height < merged[idx].height)
+                idx = i;
+        merged[idx - 1].height = merged[idx - 1].height + merged[idx].height;
+        merged.splice(idx, 1);
+    }
+    return merged.map((r, i) => ({
+        index: i,
+        tag: r.cand.tag,
+        label: r.cand.label,
+        background: r.cand.bg,
+        offsetTop: Math.round(r.top),
+        height: Math.round(r.height),
+        textStart: r.cand.textStart,
+    }));
+}
+// Scroll through the page so lazy-rendered sections have layout before a
+// screenshot or band scan (spec requirement; 450px steps, brief settle, back
+// to top). Shared by captureLiveSite and analyzePageStructure — this is the
+// ONE implementation; capture.ts imports it.
+export async function preScroll(page) {
+    await page.evaluate(async () => {
+        const step = 450;
+        for (let y = 0; y < document.documentElement.scrollHeight; y += step) {
+            window.scrollTo(0, y);
+            await new Promise((r) => setTimeout(r, 40));
+        }
+        window.scrollTo(0, 0);
+        await new Promise((r) => setTimeout(r, 150));
+    });
+}
+export async function analyzePageStructure(url, loader = () => import("playwright"), maxBands, opts) {
+    let chromium;
+    try {
+        ({ chromium } = await loader());
+    }
+    catch {
+        return { error: CAPTURE_INSTALL_HINT };
+    }
+    let browser;
+    try {
+        browser = await chromium.launch();
+    }
+    catch {
+        return { error: CAPTURE_INSTALL_HINT };
+    }
+    try {
+        const waitStrategy = opts?.waitStrategy ?? "load";
+        const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+        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.
+        if (waitStrategy === "load")
+            await page.waitForTimeout(3000);
+        await preScroll(page);
+        const raw = (await page.evaluate(SCAN_SNIPPET));
+        return {
+            url,
+            title: raw.title,
+            totalHeight: raw.totalHeight,
+            bands: collapseBands(raw.candidates, raw.totalHeight, maxBands ?? 40),
+        };
+    }
+    finally {
+        try {
+            await browser.close();
+        }
+        catch {
+            /* keep the primary error */
+        }
+    }
+}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "awwwards-mcp",
+  "version": "1.0.0",
+  "description": "Free MCP server giving AI agents design inspiration from Awwwards: search award-winning sites with inline screenshots and extract design DNA.",
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "awwwards-mcp": "dist/cli.js",
+    "awwwards-index": "dist/index-cli.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "skills"
+  ],
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "scripts": {
+    "build": "tsc",
+    "index": "node dist/index-cli.js",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "smoke": "tsx test/live-smoke.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^24.0.0",
+    "ffmpeg-static": "^5.3.0",
+    "playwright": "^1.63.0",
+    "tsx": "^4.19.0",
+    "typescript": "^5.6.0",
+    "vitest": "^3.0.0"
+  }
+}

package/skills/awwwards-inspiration/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: awwwards-inspiration
+description: Use when building a site that needs design references (e.g. "make it feel premium", "dark 3D portfolio vibes"), when the user asks for standalone inspiration research ("show me award-winning e-commerce sites", "what's trending in brutalism"), or when setting up or maintaining the awwwards-mcp local index or live-capture tooling (awwwards-index, capture_live_site).
+---
+
+# Awwwards Inspiration
+
+You have access to the `awwwards` MCP server: a searchable library of
+award-winning websites with inline screenshots and per-site design DNA. Use
+it to ground design decisions in real, proven references instead of guessing.
+
+## When to use this skill
+
+1. **During site builds** — before writing any UI code, gather references and
+   state a design direction.
+2. **Standalone research** — the user wants inspiration, trends, or examples
+   ("show me dark 3D portfolio sites").
+3. **Index & capture ops** — building the local search index, or taking fresh
+   screenshots of live URLs.
+
+## The inspiration loop
+
+Run this loop before building anything visual:
+
+1. **Restate the goal as concrete attributes.** Turn the user's request into
+   mood, color, technology, and industry terms. "Make it feel premium" becomes
+   e.g. "dark, elegant, WebGL, agency portfolio".
+2. **Ground your vocabulary.** If unsure which filters exist, call
+   `list_categories` first — it returns every color hex and tag/technology
+   slug you can search by.
+3. **Search.** Call `search_sites` with 1–3 filters (e.g.
+   `{ color: "#404040", tags: ["3d", "portfolio"] }`). Judge the results from
+   the inline screenshots, not just titles. Shortlist 2–3 candidates.
+4. **Live reference URL named? Capture it full-page first.** (and later capture
+   your own build the same way — compare both against each other) If the user
+   points at a specific live site (e.g. "recreate cerebrium.ai"), call
+   `capture_live_site` on that URL before anything else and design from the
+   full-page PNG — every section, top to bottom. Cached Awwwards screenshots
+   are hero-only crops (~880×660) and hide everything below the fold: the
+   sections that make a site's structure distinctive (pricing, feature
+   layouts, contrast breaks, footer) were never visible in them.
+5. **Get the design DNA.** Call `get_site_details` on the top pick for its
+   palette, technologies, design elements, awards, and description. If it
+   reports a layout-drift error, fall back to judging the shortlisted
+   screenshots, `get_site_elements` (which uses a different parser), or a
+   `capture_live_site` of the site's URL for a first-hand full-page view.
+6. **Get component-level visuals (when building).** Call `get_site_elements`
+   on shortlisted sites to see individual design elements — 3D models, video
+   content, mobile layouts, microcopy — with poster images inline and video
+   URLs. Treat element posters as texture, not structure: they are video
+   frames (often mid-animation or near-black), not full-section layouts.
+7. **State the design direction before writing code.** In prose: palette
+   (hexes from the references), type mood, layout patterns, and tech choices,
+   each traceable to a reference. Then build.
+8. **Verify structure, then polish.** After building, capture your own build
+   full-page (`capture_live_site` on its `file://` or served URL) and run
+   `analyze_page_structure` on BOTH the reference and the build. Compare band
+   maps section by section (count, order, backgrounds, heights). Fix
+   distribution mismatches first — a section that is 3× the reference's height
+   is a structural bug no amount of pixel polish fixes. Match the reference's
+   band structure, never just its total height.
+
+### Anti-patterns
+
+- **Vague single-word searches** ("modern", "nice") — use concrete color/tag/
+  technology/award filters instead.
+- **Skipping to code** without stating a direction — the references are
+  worthless if nothing is derived from them.
+- **Dumping raw tool output at the user** — curate: show the shortlist, the
+  chosen direction, and why.
+- **Designing from a thumbnail or element poster** — thumbnails are hero-only
+  crops and posters are video frames; neither shows the page's real
+  structure. When the reference URL is known, capture it full-page (step 4).
+- **Padding empty bands to match total height** — if your build's total height
+  matches the reference but a spacer/background band is far taller than the
+  reference's equivalent, the height was stolen from real content sections.
+  Compare band maps, not totals. Spacer and decorative elements are measured
+  against the reference's equivalent band — never invented to absorb height.
+
+## Tool reference
+
+| Tool | Key params | Returns | Gotchas |
+|------|-----------|---------|---------|
+| `search_sites` | `query` (free text vs titles/tags), `color` (hex like `#404040`), `tags` (array of slugs), `technology` (slug), `award` (`sotd`\|`developer`\|`honorable`), `count` (1–12, default 6), `page` (default 1) | Text list of site cards (title, slug, live URL, awards, tags) + inline JPEG screenshots | Awwwards applies only one URL filter — priority color > award > technology > first tag; the rest are checked client-side. Color searches always scrape live (never cached). Deep pagination is unavailable by design (robots.txt). On live-request failure, stale cache is served when present. |
+| `get_site_details` | `slug` (from `search_sites`, e.g. `l-i-s-a`) | Title, live URL, awards, color palette, technologies, design elements, description, full-size screenshot URL; inline screenshot when available | Cached 7 days; a parse that comes back all-empty is an error, not a quiet empty result. |
+| `get_site_elements` | `slug` | Numbered element list (image or video, with video URLs) + up to 8 inline poster JPEGs | Videos are mp4 URLs (posters only are shown inline). Elements feed from the same fetch as `get_site_details`. |
+| `list_categories` | none | JSON: every color hex and filter/tag slug, plus usage guidance | Cached 30 days. Call this whenever filter vocabulary is uncertain. |
+| `capture_live_site` | `url` (absolute URL) | Full-page PNG saved to disk + inline image | Requires the optional playwright dependency (`npm install -g playwright && npx playwright install chromium`). |
+| `analyze_page_structure` | `url` (absolute URL or `file://` path), `maxBands` (cap on returned bands, default 40) | JSON: `title`, `totalHeight`, and an ordered band map (`index`, `tag`, `label`, `background`, `offsetTop`, `height`, `textStart` (first ~60 chars of the band's text) per band) | Requires playwright. Run it on BOTH the reference and your build (step 8) and compare band maps — count, order, backgrounds, heights — never just total height. |
+| `record_site_motion` | `url` (absolute URL), `frames` (filmstrip tile count, 4–36, default 16 → a 4x4 grid) | Inline filmstrip JPEG of a motion-through pass (preloader dwell, slow scroll, hover/cursor interactions) + the saved .webm path as text | Requires playwright + ffmpeg-static. Runs a ~30 s scripted pass — heavier than a capture, use when motion matters (step on from static captures). |
+
+All image results arrive as MCP image content blocks — look at them, don't
+just read the text blocks.
+
+## Index & capture ops
+
+**Local index.** `search_sites` works out of the box but unindexed depth is
+limited by polite live scraping (~31 sites per filter page). Build the index
+once for searches across thousands of sites:
+
+```bash
+npx -y -p awwwards-mcp awwwards-index      # from the published package
+npm run index                              # from a repo checkout
+```
+
+- Crawls all ~200 tag pages at 1 request/second (~4 minutes) into a SQLite
+  cache at `~/.awwwards-mcp/`.
+- Resumable: interrupt and re-run; completed pages are skipped.
+- The MCP server re-indexes automatically in the background whenever the
+  index is stale — you rarely need to run this by hand.
+
+**Live captures.** `capture_live_site` needs playwright installed once (see
+table above). Two uses: (1) the user wants a screenshot of a URL that is not
+an Awwwards site, or a fresher view than the cached thumbnails; and (2) —
+the more important one — the user names a live site as the design reference
+for a build: capture it full-page first and derive the structure from that
+image (see step 4 of the loop).
+
+**Motion capture.** Static images can't show preloaders, scroll-driven
+animation, or transitions — and most award-winning sites are built around
+exactly those. When the reference site has motion, record it: launch
+Playwright with `recordVideo`, wait out the preloader (~7 s), scroll slowly
+to the bottom in small steps so every scroll-triggered animation fires on
+camera, then extract a filmstrip of frames with ffmpeg (`npm i -D
+ffmpeg-static`, one frame every ~3 s) and Read the frames — or call
+`record_site_motion` directly: the filmstrip comes back inline and the .webm
+path as text.
+
+**Filmstrip is the fallback, not the default.** First try Reading the
+video file directly — if your model supports video input, watching the
+scroll-through gives you timing, easing, and transitions the frames can't.
+If the Read comes back with media omitted / "model does not support video
+input", extract the filmstrip and Read the frames instead. A ready-made
+recorder ships in this repo at
+`scripts/record-scrollthrough.mjs` (run it from the repo root; playwright
+and ffmpeg-static are devDependencies).