awwwards-mcp 1.2.0 → 1.3.0

package/README.md

@@ -18,9 +18,9 @@ of any site: color palette, tech stack, design elements, award history.
 | `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
 

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

@@ -23,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 {
@@ -77,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"),
@@ -93,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.

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/server.js

@@ -419,7 +419,12 @@ export function createHandlers(deps) {
             // the injectable playwright loader — opts must land in fourth place.
             const capture = deps.captureFn ??
                 ((url, imagesDir, opts) => import("./capture.js").then((m) => m.captureLiveSite(url, imagesDir, undefined, opts)));
-            const result = await capture(args.url, cache.imagesDir, { waitStrategy: args.waitStrategy });
+            // The tool schema defaults viewport to "desktop" (zod); the ?? keeps
+            // direct handler calls on the same explicit path.
+            const result = await capture(args.url, cache.imagesDir, {
+                waitStrategy: args.waitStrategy,
+                viewport: args.viewport ?? "desktop",
+            });
             if ("error" in result)
                 return { content: [text(result.error)], isError: true };
             return {
@@ -442,6 +447,7 @@ export function createHandlers(deps) {
                 ((url, maxBands, opts) => import("./structure.js").then((m) => m.analyzePageStructure(url, undefined, maxBands, opts)));
             const structure = await analyze(args.url, args.maxBands, {
                 waitStrategy: args.waitStrategy,
+                viewport: args.viewport ?? "desktop",
             });
             if ("error" in structure)
                 return { content: [text(structure.error)], isError: true };
@@ -454,14 +460,15 @@ export function createHandlers(deps) {
     async function record_site_motion(args) {
         try {
             // Lazy default: playwright/ffmpeg are only touched when the tool runs.
-            // The default forwards motionOpts wholesale, so waitStrategy flows into
-            // recordSiteMotion's MotionOpts (which already accepts it).
+            // The default forwards motionOpts wholesale, so waitStrategy and viewport
+            // flow into recordSiteMotion's MotionOpts (which already accepts both).
             const motion = deps.motionFn ??
                 ((url, motionOpts) => import("./motion.js").then((m) => m.recordSiteMotion(url, motionOpts)));
             const result = await motion(args.url, {
                 cacheImagesDir: cache.imagesDir,
                 frames: args.frames,
                 waitStrategy: args.waitStrategy,
+                viewport: args.viewport ?? "desktop",
             });
             if ("error" in result)
                 return { content: [text(result.error)], isError: true };

package/dist/structure.js

@@ -1,4 +1,5 @@
 import { CAPTURE_INSTALL_HINT } from "./capture.js";
+import { resolveViewport } from "./viewport.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
@@ -182,7 +183,12 @@ export async function analyzePageStructure(url, loader = () => import("playwrigh
     }
     try {
         const waitStrategy = opts?.waitStrategy ?? "load";
-        const page = await browser.newPage({ viewport: { width: 1440, height: 900 } });
+        // Viewport profile split: width/height fill playwright's `viewport` key;
+        // the mobile-profile flags (deviceScaleFactor/isMobile/hasTouch) are
+        // sibling context options. The desktop profile 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/viewport.js

@@ -0,0 +1,7 @@
+export const VIEWPORT_PROFILES = {
+    desktop: { width: 1440, height: 900 },
+    mobile: { width: 390, height: 844, deviceScaleFactor: 3, isMobile: true, hasTouch: true },
+};
+export function resolveViewport(name) {
+    return VIEWPORT_PROFILES[name ?? "desktop"];
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awwwards-mcp",
-  "version": "1.2.0",
+  "version": "1.3.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",

package/skills/awwwards-inspiration/SKILL.md

@@ -38,7 +38,9 @@ Run this loop before building anything visual:
    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.
+   layouts, contrast breaks, footer) were never visible in them. For
+   mobile-excellence references pass `viewport: "mobile"` — and capture BOTH
+   viewports when the desktop and mobile designs diverge.
 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
@@ -68,8 +70,10 @@ Run this loop before building anything visual:
 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
+   maps section by section (count, order, backgrounds, heights). Match the
+   reference's viewport when comparing: for mobile-excellence references pass
+   `viewport: "mobile"`, and capture BOTH viewports when the design diverges.
+   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.
 

package/skills/awwwards-motion-study/SKILL.md

@@ -68,6 +68,9 @@ Capture rules that prevent re-shoots:
 - **Capture BEFORE building** — the doctrine step. Review first, code second.
 - Use a **consistent viewport** (1440×900 matches the QA scripts) so your
   reference tiles and build tiles are comparable.
+- For phone-class references pass `record_site_motion` a `viewport: "mobile"`
+  (390×844 @3x with isMobile + hasTouch) — and capture BOTH viewports when
+  the desktop and mobile designs diverge.
 - **Pre-scroll** to fire lazy content, scroll back to top, then record —
   otherwise reveal-on-scroll sections record as blank boxes.
 - For multi-page sites, record **each page** you'll rebuild (home, projects,