Mode d’emploi
- Copiez la commande et examinez le paquet avant de l’installer dans votre environnement agent.
- Consultez le document original pour les outils, identifiants et environnements requis.
- Décrivez les entrées et le livrable souhaité ; comparez la sortie aux sources.
npx skills add https://github.com/insane0777/awwwards-skills --skill awwwards-doctorAvant de commencer
- L’installation n’inclut ni abonnement au modèle, ni quota API, ni accès aux fichiers.
- Étoiles et installations reflètent l’activité, pas un test indépendant de qualité ou de sécurité.
Rendu depuis le dépôt source en conservant titres, exemples, code, tableaux, liens et images.
Awwwards MCP Doctor
You are repairing the awwwards-mcp toolchain or working around it mid-task. Work in this order: diagnose → fix mechanically → fix parsers (if drift) → recover the user's task. Never delete user data; the only destructive step (cache DB moved aside) keeps the old file — in the OS temp dir for --fix, beside the cache after a full backup for the manual reset.
Profile note: this skill's tools aresearch_sites,get_site_details,capture_live_site,analyze_page_structure,capture_component,export_design_tokensandanalyze_images. The examples below use those 1.x names (the defaultfullprofile). OnAWWWARDS_MCP_PROFILE=v2, usesearch_references {request:{kind:"sites", ...}},get_reference {request:{kind:"site_details", slug}},capture_page {request:{kind:"screenshot", url}},inspect_page {request:{kind:"structure", url}},capture_page {request:{kind:"component", url}},inspect_page {request:{kind:"tokens", url}}andaudit_page {request:{kind:"images", url}}instead. Full mapping: v2-routing.md.
1. Run the doctor (awwwards-mcp source checkout)
Run these from the root of the awwwards-mcp source checkout (github.com/INSANE0777/Awwwards-mcp), the repository whose package.json is awwwards-mcp — not from an awwwards-skills checkout. The npm package does not ship these scripts; if you installed the server, use section 3 instead.
npm run doctor # diagnose only
npm run doctor -- --fix # diagnose AND apply available fixes
npm run doctor -- --json # machine-readable reportThe doctor checks five things and knows how to fix the mechanical ones:
| Check | Failure meaning | What --fix does |
|---|---|---|
| network | awwwards.com blocked/challenged the request | nothing to fix locally — wait, retry later; never retry in a loop |
| parser-drift | awwwards.com markup changed under the parsers | captures the raw live page into docs/drift-<timestamp>/ (gitignored) as the fixture for the fix |
| playwright-chromium / ffmpeg-static | optional capture deps missing or broken | installs them (dev deps + npx playwright install chromium) |
| cache | SQLite DB corrupt/locked, or index older than 30 days | moves an unreadable DB aside (kept in temp) and rebuilds via npm run index |
| boot | dist/cli.js doesn't start | npm run build |
Re-run the doctor after fixing; the verdict must be HEALTHY before you claim the MCP is repaired.
2. Fixing real parser drift (the only code-level failure)
If the doctor reports parser-drift, the anchor probes say which parser broke. Repair sequence — keep it mechanical, verify at each step:
- Capture the evidence: the
--fixsnapshot indocs/drift-*/IS the
new truth. (The daily GitHub Action also opens/updates a parser-drift tracking issue with the drifted anchor names.)
- Locate the new anchors: open the captured HTML and find the markup
that replaced the old anchor (search the old anchor's purpose, e.g. the card JSON blob, the Elements section heading, the og:image meta).
- Re-anchor the parsers in
src/parsers.ts— change the minimum needed
(one split/indexOf/regex literal), not the surrounding logic.
- Update the probe list in
scripts/parser-drift-probe.mjs(in the same
awwwards-mcp checkout; PROBE_GROUPS) so the same failure is detectable next time.
- Refresh the fixture: download the live page with the same UA the
client uses and replace test/fixtures/listing.html (or the detail fixture). The offline tests run against fixtures only — a refreshed fixture proves the re-anchor against reality.
npm run typecheck && npm test— all tests must pass.- Commit as
fix: re-anchor <parser> after awwwards.com markup change,
reference the tracking issue.
Note: the annual-award tools (get_annual_*) come from the official JSON API (src/annual.ts), not the parsers, and the expanded award-cut listings (sites_of_the_month/year, nominees, winner_category_*) have their own trimmed fixtures under test/fixtures/awards/ — refresh those when their anchors drift, alongside the daily listing's.
3. End users (installed via npm, not a repo checkout)
The doctor scripts live in the repo, so for an npm-installed server:
- Check the version notice: stderr at startup prints when a newer
awwwards-mcp exists. Update with npm install -g awwwards-mcp@latest (or clear the npx cache) and restart the agent — a surprising share of "broken" reports are old parsers fixed in a newer release. AWWWARDS_AUTO_UPDATE=1 in the MCP server env opts into background self-update on startup.
- Back up, then reset only the database. Stop the agent/MCP server first
so the DB is not mid-write. Resolve the cache root with CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}" (the server reads the same variable). Copy it aside first, then move only the SQLite files; the next index/run rebuilds them:
CACHE="${AWWWARDS_CACHE_DIR:-$HOME/.awwwards-mcp}"
STAMP="$(date +%Y%m%d-%H%M%S)"
cp -R "$CACHE" "$CACHE.backup-$STAMP"
mkdir -p "$CACHE.moved-$STAMP"
for f in "$CACHE"/cache.db*; do [ -e "$f" ] && mv "$f" "$CACHE.moved-$STAMP/"; doneA blanket delete of the cache root would also destroy preferences.json (setup choices), skill-memory/findings.jsonl (learned findings), winner watches (rows inside cache.db), and captures in images/ and scene-captures/. The targeted reset loses only the search index and watch rows — the index rebuilds, watches must be re-added — while preferences, learned findings and captures are kept. Never rm -rf the cache root.
- If it still fails, it's upstream (block or drift): open an issue at the
awwwards-mcp repo attaching the raw HTML of the failing URL.
4. Recovering the in-flight task (the reason you noticed)
The user's build/research doesn't wait for the repair. Degrade gracefully:
- Stale cache is your friend:
search_sites/get_site_detailsserve
cached data when live fetches fail — say so in the reply ("7-day-old cached data").
- BlockedError means stop, not retry: the client never retries through
blocks; tell the user and continue with cached/alternate data.
- Capture tools down (playwright missing): fall back to
get_site_details screenshots (CDN-served, no browser needed) until npm run doctor -- --fix restores chromium.
- Token/image tools down:
export_design_tokensreuses the
capture_component pack (same playwright/chromium requirement), and analyze_images needs the same browser. Without playwright both return the raw browser/module error (e.g. Cannot find package 'playwright'), not the friendly install hint — capture_live_site / analyze_page_structure are the tools that return the hint. Cached get_site_details screenshots are the fallback. analyze_images never downloads assets — zero images means the page has no <img> elements (canvas/CSS-background content) or the scan found none, not a broken audit.
- One band, a preloader, or `mode:"anchors"`: 1.14 detects inner scroll
roots (scrollRoot) and waits out full-screen loaders; 1.15 returns mode:"anchors" for inner-scroll pages — six ordered viewport shots down the scroller as JSON paths (anchors[].scrollTop/file) with no inline image. That is the honest success payload, not a broken capture; use scrollCapture:"viewport" when you want one explicit viewport shot. A scrollRoot re-query error (0 or >1 matches) means the DOM changed between scan and shot — re-run or report the label and match count. If a page still returns a single band, its content may be in shadow DOM or canvas; inspect and report the limitation instead of treating it as a full band map.
- Parser drift mid-task: results may be partially empty (e.g. details
without palette). Surface which part is missing; don't silently present degraded data as complete.
- After the MCP is healthy again, re-run the failed calls and reconcile
with whatever the fallback produced.
Close the flywheel
Repairs are the highest-value lessons - they were expensive to learn. In a checkout of the awwwards-skills repository (the installed skill copy does not include this dev script), after a successful diagnosis + fix: node scripts/skill-memory.mjs record --skill awwwards-doctor --phase repair --symptom "..." --rule "..." [--evidence <report path>]. Distill folds recurring failure signatures into this installed copy so the next repair starts knowing them. When a rule proves out, promote --skill awwwards-doctor outputs it cleaned (no machine-local evidence paths) for the shipped-copy PR.
Anti-patterns
- Retrying blocked requests in a loop — politeness rules and block
detection exist precisely so this doesn't hammer awwwards.com.
- Diffing raw HTML to detect drift — cosmetic page changes would false-alarm
daily; only parser-anchor probes matter.
- "Fixing" parsers by loosening them to return empty results quietly — a
parse that can't find its anchors must error loudly (that is the drift signal).
- Blanket-deleting the cache root to "reset" — it destroys preferences,
learned findings, winner watches and captures. Back it up, then move only cache.db*.
- Treating the doctor's UNHEALTHY verdict as done because one check passed.
<!-- skill-memory:start --> <!-- skill-memory:end -->