内容
<div align="center">
<img src="dna.gif" width="200" />
**提取任何网站的设计DNA — 一个可搜索的、由Claude构建的可重复使用的UI模式库。**
[](https://github.com/olartgabo/design-dna-mcp/actions/workflows/ci.yml)
[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)
[](https://github.com/MCPJam/inspector)
<br>
<img src="docs/assets/capture-readout.png" alt="A crawl of linear.app: full-page capture alongside the extracted palette, typefaces, spacing scale, and component candidates" width="100%">
<sub>对 <code>linear.app</code> 进行一次 `crawl_website` 调用 — 全页捕获、8色调色板、字体、间距比例和167个运动规则，以及由此产生的组件候选项。</sub>
</div>
---
设计画廊（Godly、Awwwards、Minimal Gallery……）是优秀的创意来源，但却是糟糕的数据库。你会因为喜欢某个网站的某个方面而将其加入书签 — 导航处理、间距系统、悬停动画 — 但之后却再也找不到它。
这个MCP服务器解决了这个问题。指向任何网站，它都会：
1. **捕获** 设计证据与Playwright — 截图、DOM、计算样式、字体层次、颜色调色板、间距比例和声明的CSS运动
2. **分解** 它与Claude成为可重用的设计组件（“编号章节索引（x.x标签）”、“图像显示悬停”、“药丸形主要CTA”）具有类别、描述、样式标签和元数据
3. **存储** 您选择保留的组件在本地SQLite库中，带有向量嵌入
4. **回答** 来自任何MCP客户端的自然语言查询：*“查找粘性编辑导航”*、*“单间距技术标签”*、*“类似技术产品页面的网站”*
> 知识的单位是 **组件**，而不是网站。网站只是证据。
## 示例
```
> crawl_website("https://linear.app")
capture 1 · 9 screenshots · palette #f7f8f8/#0f1011/… · Inter Variable + Berkeley Mono · 167 motion rules
> extract_components(captureId: 1)
[navigation] 暗色极简顶部导航 — minimal, dark, swiss, saas
[typography] 单间距内联代码标签 — monospace, technical, terminal
[diagram] 编号技术图表 — technical, blueprint, isometric
[number-treatment] 编号章节索引（x.x标签） — technical, monospace, editorial
[motion] 动画网格点背景图案 — technical, ambient, blueprint
… 18 candidates
> save_component(captureId: 1, saveAll: true)
> find_components("monospace technical labels")
0.62 [typography] 单间距内联代码标签 https://linear.app/
0.61 [number-treatment] 编号章节索引（x.x标签） https://linear.app/
```
## 工具
| 工具 | 功能 |
|---|---|
| `crawl_website(url)` | Playwright捕获：全页 + 分段截图、DOM、样式、字体、调色板、间距比例、CSS运动。每次捕获版本控制。无API成本。 |
| `extract_components(url \| captureId, focus?)` | 一个Claude视觉调用将捕获结果分解为组件候选项。候选项被缓存，**不**自动保存 — 您来策划。 |
| `save_component(candidateId \| captureId+saveAll \| component)` | 将组件保存到库中，带有航程嵌入。在（sourceUrl，name）上更新。 |
| `find_components(query, filters?)` | 语义搜索，带有可选类别/标签/主题/源URL过滤器。 |
| `search_designs(query)` | 按源网站分组的相同索引 — “类似站点”视图。 |
| `ping` | 健康检查 + 库大小。 |
## 设置
需要 **Node 20+** 和 [Anthropic](https://console.anthropic.com) （分析）和 [Voyage AI](https://dash.voyageai.com) （嵌入）的API密钥。
```sh
git clone https://github.com/olartgabo/design-dna-mcp.git
cd design-dna-mcp
npm install
npx playwright install chromium # 一次性浏览器下载
npm run build
```
如果npm阻止安装脚本，请先批准原生构建：
```sh
npm install-scripts approve better-sqlite3
npm install-scripts approve esbuild
npm rebuild better-sqlite3 esbuild
```
### 在Claude Code中注册
在任何平台上最可靠的方式（使用 `-s user` 在所有项目中启用）：
```sh
claude mcp add-json design-dna -s user '{"command":"node","args":["/absolute/path/to/design-dna-mcp/dist/index.js"],"env":{"ANTHROPIC_API_KEY":"sk-ant-...","VOYAGE_API_KEY":"pa-..."}}'
```
### 在Claude Desktop中注册
添加到 `claude_desktop_config.json`:
```json
{
"mcpServers": {
"design-dna": {
"command": "node",
"args": ["/absolute/path/to/design-dna-mcp/dist/index.js"],
"env": {
"ANTHROPIC_API_KEY": "sk-ant-...",
"VOYAGE_API_KEY": "pa-..."
}
}
}
}
```
### 环境变量
| 变量 | 必需 | 默认值 | 目的 |
|---|---|---|---|
| `ANTHROPIC_API_KEY` | for `extract_components` | — | Claude视觉分析 |
| `VOYAGE_API_KEY` | for save/search | — | 嵌入 |
| `DESIGN_DNA_DATA_DIR` | no | `~/.design-dna-mcp` | SQLite数据库 + 截图 |
| `DESIGN_DNA_MODEL` | no | `claude-sonnet-5` | 分析模型 |
| `DESIGN_DNA_EMBEDDING_MODEL` | no | `voyage-3.5` | 嵌入模型 |
服务器在没有密钥的情况下可以正常启动 — 需要缺少的密钥的工具会在调用时出现清晰的错误，指出变量名。库在所有项目中共享（它位于数据目录中，而不是存储库中）。
<sub>该项目以前名为 `design-research-mcp`。旧的 `DESIGN_RESEARCH_*` 变量仍然有效，现有库 `~/.design-research-mcp` 将在原地被采用 — 无需迁移。</sub>
## 工作原理
```
网站 ─→ Playwright ─→ 捕获（截图 · DOM · 样式.json · css/）
│
▼
蒸馏器（大小上限的JSON + ≤6张图片）
│
▼
Claude（一次视觉调用，强制工具使用模式）
│
▼
候选项（缓存，人类策划）
│ save_component
▼
SQLite + sqlite-vec（余弦）+ 航程嵌入
│
▼
find_components / search_designs（MCP）
```
值得注意的设计决策：
- **有边界的AI成本** — 提取是 *一个* Claude调用每个站点（蒸馏数据 + 一些图片），而不是每个元素的调用。
- **精选而非囤积** — 提取产生候选项；只有您保存的内容才可搜索。`saveAll`存在于您想要所有内容时。
- **一切本地** — SQLite + sqlite-vec在一个文件中，截图在磁盘上。没有Postgres，没有S3，没有服务。
- **大载荷保留在磁盘上** — 工具结果携带路径和紧凑摘要，从不base64大块数据。
## 成本和速率限制
- `crawl_website` 免费（本地Playwright）。
- `extract_components` ≈ 一个 `claude-sonnet-5` 调用，约5-10K输入令牌 + 每个站点最多6张图片。
- 嵌入是每次保存/搜索的微小航程调用 — 实际上可忽略不计。
- 航程的 **免费层允许 ~3 请求/分钟**；客户端重试带有长回退（最多 ~70s），因此快速连续的搜索感觉很慢，直到您向航程帐户添加计费。
## 通过MCPJam验证
该服务器中的每个工具都通过带有 [**MCPJam**](https://github.com/MCPJam/inspector) 的真实stdio传输进行了测试 — 模式验证、握手和实时工具调用 — 而不仅仅是单元测试。自己重现：
```sh
npx @mcpjam/cli tools list --transport stdio --command node --args dist/index.js
npx @mcpjam/cli server doctor --transport stdio --command node --args dist/index.js
npx @mcpjam/cli tools call --transport stdio --command node --args dist/index.js \
--tool-name crawl_website --tool-args '{"url": "https://example.com"}'
```
## 开发
```sh
npm test # 51个离线测试（vitest）— 本地固定站点，无需API密钥
npm run dev # 通过tsx从源代码运行
node scripts/try-crawl.mjs https://linear.app # 抓取真实站点（无需密钥）
node scripts/e2e.mjs https://linear.app # 完整的实时循环（需要两个密钥）
node scripts/mcp-smoke.mjs # stdio往返冒烟测试
```
按规格优先构建。完整的轨迹 — 需求 → 设计 → 任务，带有验证扫描 — 位于 [`.claude/specs/design-dna-mcp/`](.claude/specs/design-dna-mcp/)，原始产品愿景位于 [`docs/VISION.md`](docs/VISION.md)。
## 路线图（v2）
- `classify_design(url)` — 样式置信度分数（编辑 92%，瑞士 85%，…）
- `compare_designs(url1, url2)` — 共享与独特模式
- `recommend_components(project_description)` — “我正在构建一个黑暗编辑投资组合” → 精选组件集
- 交互记录 — 带有测量缓动、持续时间、交错的悬停/滚动捕获
- FTS5混合搜索、画廊站点摄入助手
## 许可证
[MIT](LICENSE)
