Reftrixmcp

ReftrixMCP

Web 设计知识库平台——通过 MCP 工具进行布局分析、动效检测和质量评估。

面向前端工程师、设计师和 AI Agent 构建者，帮助他们通过 Claude 或任意 MCP 客户端分析真实网站并获取可复用的 UI 模式。

日语 / 日本語の概要

ReftrixMCP 是一个平台，使用向量搜索（pgvector HNSW）和 RAG 将 Web 设计模式整合到可搜索的知识库中，并通过 MCP 工具与 Claude 等 AI Agent 集成。

主要功能：布局分析 / 动效检测 / 质量评估 / 语义搜索 / 跨域搜索 / 图像相似度搜索 / 响应式分析 / 偏好画像 / 部件分析 / 速率限制 / 搜索缓存 / BullMQ UI / SBOM

提供 40 个 MCP 工具：Layout（5）/ Motion（2）/ Quality（1）/ Page（4）/ Narrative（1）/ Background（1）/ Responsive（2）/ Preference（3）/ Part（3）/ Style（1）/ Brief（1）/ System（1）/ Search（2）/ Design（5）/ Data（2）/ Audit（1）/ Embedding（1）/ Accessibility（1）/ Performance（1）/ Report（1）

详细的日语文档：docs/README.ja.md

功能介绍

• 布局分析——自动检测区块（主视觉区、功能区、CTA 等），提取网格和排版信息，并生成 React/Vue/HTML 代码
• 动效检测——发现 CSS/JS 动画并捕获帧（视频模式下每帧 15 px），通过 Pixelmatch 检测 CLS
• 质量评估——从三个维度（原创性、工艺水平、情境适配性）评估设计，并检测 AI 陈词滥调
• 语义搜索——通过 pgvector HNSW 混合搜索查找布局、动效、叙事、背景和响应式模式
• 偏好画像——通过反馈会话学习用户的设计偏好，并通过重排个性化搜索结果（符合 GDPR）
• 部件级分析——提取 16 种 UI 部件类型（按钮、图标、标题等），使用 DINOv2 视觉嵌入进行视觉相似度搜索
• 视觉模型集成——使用 Ollama llama3.2-vision，深入理解布局、动效和叙事
• 区块后处理——按类型、标题和高度自动合并/拆分区块（规则 1-4），以获得最佳结构
• 多瓦片捕获——将大型区块（高度超过视口）拆分为瓦片，实现完整的 DINOv2 视觉覆盖
• 空白图像检测——检测因延迟加载而未渲染的区块，并通过 Playwright 重新捕获以实现完整覆盖
• 代码生成——将分析后的区块转换为 React、Vue 或纯 HTML，并匹配动效模式
• 统一搜索——通过单次查询跨服务搜索布局、部件、动效、背景和叙事模式
• 图像相似度搜索——通过 DINOv2 嵌入，使用 Base64/URL 输入查找视觉上相似的设计（RRF 三源）
• 速率限制——Token Bucket + Redis Lua（防止 CWE-770 DoS），分为 3 档（分析 10 RPM / 搜索 120 RPM / 默认 60 RPM）
• 搜索缓存——LRU 内存缓存（lru-cache v11），基于 TTL 自然过期（5 分钟）
• BullMQ UI——Bull Board 仪表板，用于监控异步的 page.analyze 作业（端口 21080）
• SBOM——自动生成 CycloneDX 1.6，用于符合欧盟 CRA 漏洞报告要求

为什么选择 ReftrixMCP

布局感知	将区块、网格和排版提取为结构化数据，而不只是截图
动效感知	CSS 静态分析 + 逐帧视频采集，真实呈现动画行为
质量感知	三轴评分，并提供可执行的改进建议
可搜索	768 维多语言嵌入（e5-base），搭配 HNSW 索引和混合 RRF 排名
偏好感知	根据用户偏好建立画像，并通过反馈驱动所有搜索工具的重排
部件感知	提取 16 种 UI 部件类型，并通过 DINOv2 视觉嵌入进行跨站点组件比较
原生支持 MCP	40 个专为 Claude Desktop 和 MCP Client CLI 打造的工具

快速开始

5 分钟内即可对任意 URL 运行 page.analyze。

前置条件

Node.js 20+、pnpm 10+、Docker 和 Docker Compose、Ollama

设置

git clone https://github.com/TKMD/ReftrixMCP.git && cd ReftrixMCP
pnpm install                                     # CUDA skip is default; see GPU note below
cp .env.example .env.local                       # edit DATABASE_URL / REDIS_URL as needed
cp .env.local packages/database/.env             # Prisma CLI requires this copy
pnpm docker:up                                   # PostgreSQL 18 + pgvector + Redis
pnpm db:migrate && pnpm db:seed
pnpm build
pnpm exec playwright install chromium            # browser for page crawling
pnpm --filter @reftrixmcp/ml download:dinov2        # DINOv2 visual embedding model (~330 MB)
pnpm --filter @reftrixmcp/ml repair:e5-cache --check # (optional) verify multilingual-e5-base ONNX cache (~1.1 GB) integrity
curl -fsSL https://ollama.com/install.sh | sh    # install Ollama
ollama pull llama3.2-vision                      # vision model (~7.9 GB)
ollama serve                                     # keep running in a separate terminal

注意：如果更改 .env.local，也请更新 packages/database/.env。 MCP 服务启动时，page.analyze 工作进程会由 WorkerSupervisor 自动派生（v0.4.0 PR7d-2+）。通过 pnpm --filter @reftrixmcp/mcp-server worker:start:page 手动启动仅供开发者使用；如果 MCP 服务也在运行，则需要设置 REFTRIX_ALLOW_MANUAL_WORKER=true，以绕过基于 Redis 的双重运行保护。 GPU 配置及详情请参阅入门指南。

GPU / CUDA：默认跳过 CUDA 二进制文件下载（回退到 CPU）。如需设置 GPU 加速，请参阅故障排除：CUDA 检测。

pnpm“已忽略构建脚本”：运行 pnpm install 时，pnpm 10 会显示 Ignored build scripts: @prisma/client, esbuild, sharp, ...，并建议运行 Run "pnpm approve-builds"。这是预期行为，并非错误——pnpm 10 默认会阻止依赖项构建和生命周期脚本，以保障供应链安全。设置仍会完成，因为 sharp 和 esbuild 提供预构建二进制文件，而 Prisma 客户端则由 @reftrixmcp/database 工作区软件包自己的 postinstall（prisma generate）在 pnpm install 期间生成——这是工作区生命周期脚本，pnpm 不会将其纳入依赖项构建脚本许可列表的管控范围。只有在有特定理由要让某个被阻止的依赖项运行其自身的原生构建步骤时，才运行 pnpm approve-builds（onnxruntime-node 已通过 pnpm.onlyBuiltDependencies 加入许可名单，因此不会出现在忽略列表中；CUDA 加速则是单独选择启用的功能——请参阅上文的 GPU / CUDA 说明——与 pnpm approve-builds 无关）。

连接到 Claude

添加到 MCP 配置中：

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• MCP Client CLI：项目根目录中的 .mcp.json 或 ~/.claude/.mcp.json

{
  "mcpServers": {
    "reftrix": {
      "command": "node",
      "args": ["/absolute/path/to/ReftrixMCP/apps/mcp-server/dist/index.js"],
      "env": {
        "NODE_ENV": "development",
        "DATABASE_URL": "postgresql://reftrix:change_me@localhost:26432/reftrix?schema=public",
        "REDIS_URL": "redis://localhost:27379",
        "OLLAMA_BASE_URL": "http://localhost:11434",
        "OLLAMA_HOST": "http://localhost:11434",
        "ENABLE_SECTION_SCREENSHOT_FALLBACK": "true"
      }
    }
  }
}

将 change_me 替换为安全密码。端口 26432 = 标准端口 5432 + 偏移量 21000。

OLLAMA_BASE_URL 供 MCP 服务进程使用；OLLAMA_HOST 供工作进程使用。如果 Ollama 运行在非默认端口，两者必须保持一致。

ENABLE_SECTION_SCREENSHOT_FALLBACK 为初始截图范围之外的版块启用基于 Playwright 的单独截图（适用于 WebGL/延迟渲染页面）。这能显著提高 DINOv2 视觉嵌入的覆盖率。设为 "false" 可禁用此功能。

可选环境变量（默认值开箱即用）： MAX_TILES_PER_SECTION（默认值 20，最大值 100）——每个版块多图块捕获的最大图块数。 BLANK_IMAGE_STDDEV_THRESHOLD（默认值 5.0）——空白图像检测的标准差阈值。 DUPLICATE_VECTOR_THRESHOLD（默认值 0.995）——视觉嵌入去重的余弦相似度阈值。 EMBEDDING_IDLE_TIMEOUT_MS（默认值 30000）——ONNX Worker 显存自动释放计时器（设为 0 可禁用）。 DINOV2_MODEL_PATH——自定义 DINOv2 ViT-B/14 ONNX 模型路径。 EMBEDDING_CACHE_ENABLED（默认值 true）——启用/禁用 Layout Embedding 磁盘缓存（仅附加退出标记；设为 "false" 可不写入缓存文件）。 REFTRIX_EMBEDDING_CACHE_ROOT（默认值 /tmp/reftrix-embedding-cache）——嵌入缓存根目录；默认情况下，解析到 os.tmpdir() 之外的根目录会被拒绝（故障安全）。设置 REFTRIX_EMBEDDING_CACHE_ROOT_ALLOW_FALLBACK=true 可改为回退到默认根目录，并显示警告。

工具示例

ReftrixMCP 提供 40 个 MCP 工具。主要示例：

• layout.ingest——获取网页、截取屏幕截图并提取版块模式
• layout.search——通过自然语言查询对版块布局进行语义搜索
• motion.detect——通过视频模式帧捕获检测 CSS/JS 动画
• quality.evaluate——从原创性、工艺水平和上下文契合度方面评估设计质量
• page.analyze——统一分析：在一次调用中分析布局、动效、质量和响应式设计（通过 BullMQ 异步运行）；可选择启用 Phase 7.5：无障碍审计、性能评估和自动快照
• responsive.search——按视口和断点搜索响应式分析结果
• preference.hear——交互式偏好倾听会话，包含示例展示和反馈收集
• preference.get——检索偏好配置文件（支持 GDPR 数据可携带性）
• preference.reset——重置或永久删除偏好配置文件（GDPR 删除权）
• part.search——通过视觉（DINOv2）或文本嵌入对 UI 部件进行语义搜索
• part.inspect——获取部件详细信息，包括计算样式、边界框和无障碍信息
• part.compare——并排比较 2–5 个部件的样式、布局和交互

完整工具参考：MCP Tools Guide

架构

MCP Client (Claude Desktop / Code)  --stdio-->  MCP Server (40 tools, Zod)
  +-- Service Layer: Playwright, Sharp+Pixelmatch, DOMPurify
  +-- ML Layer: ONNX Runtime (multilingual-e5-base + DINOv2 ViT-B/14, 768-dim)
  +-- BullMQ Workers: page.analyze, quality.evaluate
  +-- PostgreSQL 18 + pgvector 0.8 (HNSW, tsvector)  +  Redis 7

文档

指南	描述
入门指南	安装、设置和首次分析
MCP 工具指南	全部 40 个工具及其使用示例
page.analyze 深入解析	异步分析流程和数据结构
故障排除	常见问题及解决方案

已知限制

• onnxruntime-node 是可选依赖，pnpm install 默认会安装它（它为机器学习功能提供支持，包括嵌入和视觉搜索）。如果该依赖在不受支持的平台上安装失败，或你使用 pnpm install --no-optional 跳过安装，非机器学习工具（布局分析、质量评估、代码生成）仍可正常使用
• CPU 模式下的嵌入处理每段文本约需 2-5 秒；批量处理建议使用 GPU
• 最低需要 16 GB RAM；使用 Ollama Vision 并发分析时建议配备 32 GB
• 首次调用嵌入功能时，会将约 1.1 GB 的 ONNX 模型（multilingual-e5-base，FP32）下载到 transformers.js 缓存中。可随时使用 pnpm --filter @reftrixmcp/ml repair:e5-cache --check 验证完整性；如果大小或 SHA-256 不匹配，可传入 --repair 重新下载，或传入 --force 始终重新下载
• MCP 服务启动时，page.analyze 工作进程会由 WorkerSupervisor 自动派生（v0.4.0 PR7d-2+）；手动启动仅供开发者使用（MCP 服务运行时需要设置 REFTRIX_ALLOW_MANUAL_WORKER=true）
• 视觉分析（布局、动效、叙事）需要在本地运行 Ollama 和 llama3.2-vision
• DINOv2 视觉嵌入模型需要下载约 330 MB

发布说明 / リリースノート

• npm 发布自动化 — Trusted Publishing / OIDC（2026-07-12）：现在由 CI 驱动 npm 发布。创建针对 v* 标签的 GitHub Release 会触发 .github/workflows/publish.yml，按依赖顺序通过 npm Trusted Publishing (OIDC) 发布 5 个包（@reftrixmcp/core、@reftrixmcp/database、@reftrixmcp/ml、@reftrixmcp/webdesign-core、@reftrixmcp/mcp-server）——不使用 NPM_TOKEN 密钥，且每个包都会带有 --provenance 发布。verify 作业会先构建并验证所有 tarball；只有在 npm-publish GitHub Environment 的必需审核者批准后，publish 作业才会运行。 / npm 公開自動化 — Trusted Publishing / OIDC（2026-07-12）: npm 公開は CI 駆動になりました。v* タグの GitHub Release を作成すると .github/workflows/publish.yml が起動し、5 パッケージ（@reftrixmcp/core・@reftrixmcp/database・@reftrixmcp/ml・@reftrixmcp/webdesign-core・@reftrixmcp/mcp-server）を依存順に npm Trusted Publishing (OIDC) で公開します — NPM_TOKEN シークレットは使用せず、各パッケージは --provenance 付きで公開されます。verify job が先に全 tarball を build・検証し、publish job は npm-publish GitHub Environment の required-reviewer 承認の後にのみ実行されます。
• 计划 v4.4 PR-N（2026-05-17）：根据 ADR-0035 Amendment 1 §Decision 5，正式移除 WorkerSupervisorOptions.restartDelayMs 字段，并统一为仅使用环境变量的规范 SSOT。现在，WORKER_RESTART_DELAY_MS 和 EMBEDDING_BACKFILL_RESTART_DELAY_MS 环境变量是各类型重启冷却时间值的唯一事实来源；通过 getRestartDelayMsForType(workerType) 进行解析。服务器版本升级至 0.6.0。 / WorkerSupervisorOptions.restartDelayMs フィールドを正式削除し、ADR-0035 Amendment 1 §Decision 5 に従い env-only canonical SSOT へ一元化。WORKER_RESTART_DELAY_MS と EMBEDDING_BACKFILL_RESTART_DELAY_MS 環境変数が per-type restart cooldown 値の唯一の真実源となり、getRestartDelayMsForType(workerType) 経由で解決される。サーバーバージョンを 0.6.0 に bump。

许可证

AGPL-3.0-only —— 参见 LICENSE。

网络使用须根据第 13 条披露源代码。 源代码：github.com/TKMD/ReftrixMCP 商业许可证：[email protected]

贡献

请参阅 CONTRIBUTING.md。

安全

请按照 SECURITY.md 报告漏洞。 隐私：docs/legal/PRIVACY_POLICY.md | 分析隐私：apps/mcp-server/PRIVACY.md | 数据保留：apps/mcp-server/DATA_RETENTION.md | 第三方许可证：THIRDPARTY_LICENSES.md