awwwards-setup

Awwwards MCP 设置

首次配置 awwwards MCP 服务。目标是在首次正式搜索前，了解用户希望如何呈现结果，并且只在会用到时才安装可选的重型依赖项。每项选择都会保存，不会重复询问。

**配置说明：**此技能的工具包括 search_sites、list_categories、get_annual_categories（以及 get_annual_nominees / get_annual_nominee）、new_winners、watch_site、capture_live_site、analyze_page_structure、record_site_motion、export_design_tokens、analyze_images 和 analyze_bundle。以下示例使用 1.x 名称（默认 full）。在 AWWWARDS_MCP_PROFILE=v2 下，使用 search_references {request:{kind:"sites", ...}}、 browse_awards {request:{kind:"filters"}}、 browse_awards {request:{kind:"annual_categories"}}（也包括 kind:"annual_nominees" 和 kind:"annual_nominee"）、 monitor_awards {request:{action:"poll_winners"}}、 monitor_awards {request:{action:"add_watch", kind, pattern}}、 monitor_awards {request:{action:"list_watches"}}、 monitor_awards {request:{action:"remove_watch", kind, pattern}}、 capture_page {request:{kind:"screenshot", url}}、 inspect_page {request:{kind:"structure", url}}、 capture_page {request:{kind:"recording", url}}、 inspect_page {request:{kind:"tokens", url}}、 audit_page {request:{kind:"images", url}} 和 audit_page {request:{kind:"bundle", url}}。 设置 AWWWARDS_MCP_ATLAS=1 后，完整配置会添加 search_atlas、 get_atlas、capture_atlas 和 export_evidence_pack；v2 还会添加 export_evidence_pack 及 Atlas 分支。请参阅 awwwards-atlas 技能。 完整映射： v2-routing.md。

0. 检查是否已有偏好设置

读取 ~/.awwwards-mcp/preferences.json（可通过 AWWWARDS_CACHE_DIR 更改缓存目录——如果已设置，请遵循该设置）。如果文件存在且包含下方列出的字段，请静默应用并停止操作——不要重新引导配置。如果缺少某个字段，只询问该字段。如果文件不存在，则继续。

0b. 尚未连接 MCP？先完成配置

不区分配置文件的检测方式：只有在完全没有可用的 awwwards 工具时，才表示服务尚未注册。已连接的 v2 会话有意不提供 search_sites 或 list_categories；可通过 search_references 和/或 get_index 识别。已连接的 core 会话会注册 13 个工具，但不包含 list_categories，因此不要将其设为必需项。如果任何 awwwards 工具有响应，请跳到步骤 1。

如果没有可用工具，说明服务尚未向 Agent 注册——请先完成配置。检测 Agent，并使用对应的添加命令（在步骤 1 中再安装一次性可选依赖；无需 API 密钥或账号；Node ≥ 22.13）：

Agent	命令
Claude Code	claude mcp add awwwards -- npx -y awwwards-mcp
Codex CLI	codex mcp add awwwards -- npx -y awwwards-mcp
OpenCode (opencode.json)	"mcp": { "awwwards": { "type": "local", "command": ["npx", "-y", "awwwards-mcp"] } }
mcpServers-standard 客户端（Claude Desktop、Cursor、Windsurf、Gemini CLI、Cline、Continue）	"mcpServers": { "awwwards": { "command": "npx", "args": ["-y", "awwwards-mcp"] } }

pi（设计上不支持 MCP）：将此技能安装到 Agent 的技能目录中——pi 可以使用工作流；如需实时数据，则需要使用其他 Agent 或支持 MCP 的扩展。注册后，必须重启 Agent，工具才会显示——请告知用户并停止；现在可以收集偏好（步骤 1）并保存，以便重启后的会话直接进入运行状态。 可选的环境变量：AWWWARDS_CACHE_DIR（自定义缓存位置）、AWWWARDS_AUTO_UPDATE=1（有新版本时在后台自动更新）、AWWWARDS_MCP_PROFILE=core|full|v2（core 仅注册 13 个构建循环工具，包括 get_annual_categories；full 提供全部 41 个工具（设置 AWWWARDS_MCP_ATLAS=1 时为 45 个）； v2 注册 10 个整合工具，以及 5 个保留工具（保留原有名称和平铺输入：create_design_brief、build_project、verify_build、verify_flow、analyze_network_capture），启用 Atlas 时为 16 个；只有 34 个被替换的 1.x 名称会消失；默认值为 full； 更改此设置需要重启服务）。AWWWARDS_MCP_ATLAS=1 是启用实验性 Atlas 工具和 CLI 的独立选择性标志；它不会更改 core；请参阅 awwwards-atlas 技能。旧名称 → 新名称的 v2 映射见 v2-routing.md——不要在 v2 会话中混用 1.x 名称。 AWWWARDS_MCP_MAX_RESPONSE_BYTES（默认值为 32 MB；超出大小限制的结果会转换为截断 JSON）、AWWWARDS_MCP_DEBUG_MEMORY=1（每次工具调用在 stderr 中输出一行指标），以及 AWWWARDS_MCP_ATTACH=1（允许对已登录页面进行只读 CDP 附加）。 兼容一个版本周期内使用的旧版 AWARDS_MCP_* 拼写；规范名称为 AWWWARDS_MCP_*。

1. 一次性询问用户（批量提问）

将以下内容整理成一份简短问卷一次性呈现——用户只需回答一次， 无需经受四轮追问。为每项提供合理的默认值，让“全部使用默认值”成为有效回答：

1. 结果密度——使用 search_sites 时，结果应如何呈现？

   • 完整（默认）：每条结果都附带内嵌截图。便于一眼判断设计；但会占用更多上下文。
   • 精简：简洁的文本卡片，仅为所请求页面的前两条结果提供内嵌预览。适合广泛探索和长时间运行的 Agent。 此设置对应 responseMode 参数：除非请求另有说明，否则每次搜索都会使用所选默认值（需要评估屏幕效果的任务仍应使用完整模式）。存储为 "responseMode": "full" | "compact"。

2. 默认视口，用于实时捕获、结构分析和动效记录——"desktop"（1440×900，默认）或 "mobile"（390×844）；如果用户表示移动端对设计工作很重要，也可选 "both"。存储为 "defaultViewport": "desktop" | "mobile" | "both"。

3. 实时捕获——是否需要最新的截图／结构带状图／动效录制／设计令牌导出／图像审计（capture_live_site、analyze_page_structure、record_site_motion、export_design_tokens、analyze_images）？这些功能需要安装可选的 playwright + chromium（约 120 MB）： npm install -g awwwards-mcp playwright ffmpeg-static && npm exec --global -- playwright install chromium 然后在相同作用域内，将此 Agent 的 awwwards 注册项从 npx -y awwwards-mcp 切换为已安装的命令（awwwards-mcp），并重启，以便服务和 Playwright 从同一个全局安装位置解析。如果需要，现在就运行安装（只需安装一次，重复运行也安全）。如果不需要，则跳过并说明：安装完成前，捕获工具会报错。存储为 "capturesEnabled": true | false。 捆绑包取证的可选扩展：npm install -g webcrack 可为 analyze_bundle 启用反混淆／解包模式；未安装时，该工具仍会获取、保存原始代码块并按关键词搜索。

4. 本地索引——search_sites 可立即使用，但要通过礼貌抓取实时网站来逐步扩充数据（每页约 31 个网站）。本地索引（约 4 分钟，可恢复，之后会自动在后台刷新）可让你立即搜索数千个网站： npx -y -p awwwards-mcp awwwards-index（或在 awwwards-mcp 源码目录中运行 npm run index）。向用户提供此选项；如果用户接受，就在后台运行并继续后续操作——不要因此阻塞引导流程。存储为 "autoIndex": true | false。

5. 获奖作品监控——是否要跨会话跟踪工作室、标签或特定网站？如果用户说出任何名称，就为每项分别注册（watch_site，action: "add"，kind: studio|tag|url，可选 award 和 note），并提醒用户：首次运行 watch_site list 只会建立基线。这里不要存储任何内容（监控项保存在服务自己的缓存中）。

6. 保持最新（可选，无需存储，仅作为操作建议）：如果用户会研究趋势，请说明，在会话开始时使用 new_winners 可保持获奖作品基线最新，并为任何监控项提供数据。

在引导过程中说明：年度奖项相关问题由三个 get_annual_* 工具处理；search_sites 的奖项筛选器除了每日获奖作品外，还覆盖 sotm／soty／nominees 以及获奖类别细分（ecommerce、portfolio、product、typography、businessServices、noCode）。

将答案作为一个 JSON 对象写入偏好设置文件；如有需要，创建 ~/.awwwards-mcp/：

{
  "responseMode": "full",
  "defaultViewport": "desktop",
  "capturesEnabled": true,
  "autoIndex": true,
  "onboardedAt": "2026-09-28T00:00:00.000Z"
}

2. 验证工具链（不提问）

回答偏好设置后，一次性检查配置：

• 版本偏差：如果服务启动时输出了更新通知（stderr），告知用户新版本号以及如何使用该版本（npx -y awwwards-mcp@latest，或在服务的 env 中设置 AWWWARDS_AUTO_UPDATE=1）。
• 如果 capturesEnabled：用一行确认 playwright 已解析成功。 如果失败，说明在 npm exec --global -- playwright install chromium 成功之前，捕获工具都处于禁用状态——不要循环重试。
• 如果缓存目录看起来有问题（工具报错提示 SQLite 或锁相关问题）： 引导用户使用 awwwards-doctor skill；不要删除任何内容。
• 如果 AWWWARDS_MCP_PROFILE=v2：使用 get_index {request:{kind:"status"}}（无需网络）或在本地索引已有记录后使用 search_references {request:{kind:"sites", query:"portfolio"}}，探测整合后的工具集。如果在 v2 会话中使用了 1.x 工具名称，这是路由错误，并非安装损坏——请查看 v2-routing.md，并在更改配置文件后重启。

3. 汇报并交接

最后用 2–3 行总结：已保存的偏好设置、后台已安装／启动的内容，以及用户工作流要运行的唯一下一条命令（通常是 search_sites——使用已保存的 responseMode）。 简明收尾；此 skill 用于设置，而非教程。具体操作方法见 awwwards-inspiration（研究循环、获奖作品动态、索引操作）、awwwards-motion-study（视频参考研究）和 awwwards-doctor（修复）。

后续更改设置

如果用户要求更改这些设置（例如“改成精简模式”“在移动设备上捕获”），更新偏好文件并用一行确认。若偏好设置已存在，再次运行此 skill 时只询问尚未填写的字段。