awwwards-mcp 1.7.0 → 1.7.2

package/dist/capture.js

@@ -8,8 +8,8 @@ import { join } from "node:path";
 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.";
+    "Install it where this server runs (globally works for a global install):  npm install -g playwright && npx playwright install chromium\n" +
+    "Then retry the capture or structure tool (or restart your agent afterward).";
 export async function captureLiveSite(url, imagesDir, 
 // "as string" keeps Playwright an unresolved optional dependency at compile time;
 // Node resolves it (and may throw) at runtime, which the try/catch below handles.

package/dist/cli.js

@@ -13,6 +13,7 @@ import { createHandlers } from "./server.js";
 import { captureLiveSite } from "./capture.js";
 import { runIndexer, shouldAutoIndex } from "./indexer.js";
 import { checkForUpdate } from "./version-check.js";
+import { checkEnvironment } from "./env-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
@@ -155,4 +156,8 @@ if (shouldAutoIndex(cache)) {
 // 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);
+// Environment notice: once a day, verify playwright/ffmpeg are usable from
+// the server's own install (a real chromium launch, not just an import);
+// stderr-only, never blocks serving.
+checkEnvironment();
 await server.connect(new StdioServerTransport());

package/dist/env-check.js

@@ -0,0 +1,108 @@
+// Environment probe: at startup (once per day), report whether the optional
+// heavy deps the live-capture and motion tools need are actually usable, so
+// the agent learns about a missing playwright/ffmpeg BEFORE a capture fails
+// mid-task instead of after. Companion to version-check.ts; same constraints
+// of a stdio MCP server:
+//   - stdout is the JSON-RPC channel → notices go to stderr only
+//   - serving must never wait on this → fire-and-forget, per-step timeouts,
+//     every failure swallowed (missing module, crashed spawn, dead FS)
+//   - at most one probe per day per machine (state in the cache dir)
+// A real chromium launch is mandatory — import("playwright") succeeding does
+// NOT mean the browser binary is present (the browsers are a separate
+// download into the user's cache; the exact failure class this catches).
+//
+// cwd note: the probe spawns `node -e` from THIS package's root, because
+// `node -e` resolves modules from cwd — walking up from a random MCP-client
+// cwd would miss a globally-installed playwright/ffmpeg, which the package
+// itself resolves fine from dist/../node_modules up to the global root.
+import { spawn } from "node:child_process";
+import { existsSync, readFileSync, writeFileSync, mkdirSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { homedir } from "node:os";
+import { fileURLToPath } from "node:url";
+const CHECK_INTERVAL_MS = 24 * 60 * 60 * 1000;
+// dist/env-check.js → one level up is the package root (the repo root in dev).
+const pkgRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+export function envStateFile() {
+    const cacheRoot = process.env.AWWWARDS_CACHE_DIR ?? join(homedir(), ".awwwards-mcp");
+    return join(cacheRoot, "env-check.json");
+}
+function readState() {
+    try {
+        if (!existsSync(envStateFile()))
+            return null;
+        return JSON.parse(readFileSync(envStateFile(), "utf8"));
+    }
+    catch {
+        return null;
+    }
+}
+function writeState() {
+    try {
+        mkdirSync(dirname(envStateFile()), { recursive: true });
+        writeFileSync(envStateFile(), JSON.stringify({ checkedAt: Date.now() }));
+    }
+    catch {
+        /* state is an optimization; unwritable state just means we probe again */
+    }
+}
+export const ENV_FIX_HINTS = {
+    playwright: "awwwards-mcp: live capture/analyze/motion tools need Playwright — run:  npm install -g playwright && npx playwright install chromium  (restart your agent afterward)\n",
+    ffmpeg: "awwwards-mcp: motion recording needs ffmpeg-static — run:  npm install -g ffmpeg-static  (restart your agent afterward)\n",
+};
+function run(cmd, args, timeoutMs) {
+    return new Promise((res) => {
+        try {
+            const child = spawn(cmd, args, { stdio: ["ignore", "pipe", "pipe"], cwd: pkgRoot });
+            let out = "";
+            const timer = setTimeout(() => child.kill(), timeoutMs);
+            child.stdout.on("data", (d) => (out += String(d)));
+            child.stderr.on("data", (d) => (out += String(d)));
+            child.on("close", (code) => {
+                clearTimeout(timer);
+                res({ code, out: out.slice(0, 300) });
+            });
+            child.on("error", () => {
+                clearTimeout(timer);
+                res({ code: null, out: "" });
+            });
+        }
+        catch {
+            res({ code: null, out: "" });
+        }
+    });
+}
+const LAUNCH_SCRIPT = 'import("playwright").then(m=>m.chromium.launch()).then(b=>b.close()).then(()=>console.log("ok"))' +
+    '.catch(e=>{console.error(e.message);process.exit(1)})';
+const FFMPEG_SCRIPT = 'import("ffmpeg-static").then(m=>console.log(m.default??m)).catch(()=>process.exit(1))';
+async function defaultProbe() {
+    const pw = await run(process.execPath, ["-e", LAUNCH_SCRIPT], 30_000);
+    if (pw.code !== 0)
+        console.error(ENV_FIX_HINTS.playwright + (pw.out ? `  last error: ${pw.out}` : ""));
+    const ff = await run(process.execPath, ["-e", FFMPEG_SCRIPT], 10_000);
+    if (ff.code !== 0)
+        console.error(ENV_FIX_HINTS.ffmpeg);
+    // A flaky chromium launch (first-run policy, AV scan) must not crash the
+    // probe — it just counts as a failure, so tomorrow still re-checks.
+    return pw.code === 0 && ff.code === 0;
+}
+/**
+ * Once a day, probe playwright + ffmpeg from the server's own install
+ * location. Fire-and-forget; stdout untouched; every failure swallowed.
+ * `probe` is injectable for tests; resolves with true on a healthy env,
+ * false/throw when unusable — the scheduler records state on true only.
+ */
+export function checkEnvironment(opts) {
+    const state = readState();
+    if (state && Date.now() - state.checkedAt < CHECK_INTERVAL_MS)
+        return;
+    // Fire-and-forget AND swallow-everything: a rejected probe must not surface
+    // as an unhandled rejection or break server startup.
+    const probe = opts?.probe ?? defaultProbe;
+    void probe()
+        .then((healthy) => {
+        if (healthy === true)
+            writeState();
+    })
+        .catch(() => { });
+}

package/dist/motion.js

@@ -6,7 +6,7 @@ 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" +
+    "Install it where this server runs (globally works for a global install):  npm install -g ffmpeg-static\n" +
     "Then retry record_site_motion.";
 // Recording-pass timings, tuned against the 30s MCP tool ceiling. The
 // validated script (scripts/record-scrollthrough.mjs) spends well past 45s

package/dist/server.js

@@ -83,6 +83,7 @@ function errorResponse(err) {
 export const MOTION_DNA_TTL_MS = 90 * 24 * 60 * 60 * 1000;
 export function createHandlers(deps) {
     const { client, cache } = deps;
+    const nowMs = deps.now ?? Date.now;
     // Which filter wins the URL (combined filter URLs 404 on awwwards.com).
     const urlSource = (f) => f.color ? "color" : f.award ? "award" : f.technology ? "technology" : f.tags?.length ? "tag" : "none";
     // Two modes:
@@ -793,7 +794,7 @@ export function createHandlers(deps) {
     // ---- longitudinal monitoring ----
     async function new_winners(args) {
         try {
-            const res = await fetchNewWinners(client, cache, { award: args.award ?? "sotd" });
+            const res = await fetchNewWinners(client, cache, { award: args.award ?? "sotd", now: nowMs });
             // Seed the sites cache too — next search_sites serves these rows
             // without re-fetching the same listing.
             if (res.newWinners.length > 0)
@@ -808,7 +809,7 @@ export function createHandlers(deps) {
                 for (const site of res.newWinners) {
                     try {
                         const html = await client.getHtml(site.detailPath);
-                        records.push(...recordsFromSiteHtml(html, site, Math.floor(Date.now() / 1000)));
+                        records.push(...recordsFromSiteHtml(html, site, Math.floor(nowMs() / 1000)));
                         backfilled++;
                     }
                     catch {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "awwwards-mcp",
-  "version": "1.7.0",
+  "version": "1.7.2",
   "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",
@@ -50,10 +50,11 @@
   },
   "devDependencies": {
     "@types/node": "^24.0.0",
+    "@vitest/mocker": "^4.1.11",
     "ffmpeg-static": "^5.3.0",
     "playwright": "^1.63.0",
     "tsx": "^4.19.0",
     "typescript": "^5.6.0",
-    "vitest": "^3.0.0"
+    "vitest": "^4.1.11"
   }
 }