ReftrixMCP

Web design knowledge base platform -- layout analysis, motion detection, and quality evaluation via MCP tools.

For frontend engineers, designers, and AI-agent builders who want to analyze real websites and retrieve reusable UI patterns via Claude or any MCP client.

What it does

• Layout analysis -- auto-detect sections (hero, feature, CTA, etc.), extract grid/typography, and generate React/Vue/HTML code
• Motion detection -- discover CSS/JS animations with frame capture (15 px/frame video mode), CLS detection via Pixelmatch
• Quality evaluation -- score designs on three axes (originality, craftsmanship, contextuality) with anti-AI-cliche detection
• Semantic search -- find layout, motion, narrative, background, and responsive patterns via pgvector HNSW hybrid search
• Preference profiling -- learn user design preferences through feedback sessions and personalize search results via reranking (GDPR-compliant)
• Part-level analysis -- extract 16 UI part types (button, icon, heading, etc.) with DINOv2 visual embeddings for visual similarity search
• Vision integration -- Ollama llama3.2-vision for richer layout, motion, and narrative understanding
• Section post-processing -- auto merge/split sections by type, heading, and height (Rule 1-4) for optimal structure
• Multi-tile capture -- split large sections (>viewport height) into tiles for complete DINOv2 visual coverage
• Blank image detection -- detect lazy-loading unrendered sections and re-capture via Playwright for full coverage
• Code generation -- convert analyzed sections to React, Vue, or plain HTML with matched motion patterns
• Unified search -- cross-service search across layout, part, motion, background, and narrative patterns in a single query
• Image similarity search -- find visually similar designs via DINOv2 embeddings from Base64/URL input (RRF 3-source)
• Rate limiting -- Token Bucket + Redis Lua (CWE-770 DoS prevention), 3-tier (analysis 10 RPM / search 120 RPM / default 60 RPM)
• Search cache -- LRU in-memory cache (lru-cache v11) with TTL-based natural expiry (5 min)
• BullMQ UI -- Bull Board dashboard for monitoring async page.analyze jobs (port 21080)
• SBOM -- CycloneDX 1.6 auto-generation for EU CRA vulnerability reporting compliance

Why ReftrixMCP

Quickstart

Run page.analyze on any URL in under 5 minutes.

Prerequisites

Node.js 20+, pnpm 10+, Docker & Docker Compose, Ollama

Setup

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

Note: If you change .env.local, also update packages/database/.env. page.analyze workers are auto-forked by WorkerSupervisor when the MCP server starts (v0.4.0 PR7d-2+). Manual start via pnpm --filter @reftrixmcp/mcp-server worker:start:page is developer-only and requires REFTRIX_ALLOW_MANUAL_WORKER=true to bypass the Redis-based dual-run guard if the MCP server is also running. See Getting Started for GPU configuration and details.

GPU / CUDA: CUDA binary download is skipped by default (CPU fallback). For GPU acceleration setup, see Troubleshooting: CUDA Detection.

pnpm "Ignored build scripts": On pnpm install, pnpm 10 prints Ignored build scripts: @prisma/client, esbuild, sharp, ... and suggests Run "pnpm approve-builds". This is expected, not an error — pnpm 10 blocks dependency build/lifecycle scripts by default as a supply-chain safeguard. Setup still completes because sharp and esbuild ship prebuilt binaries, and the Prisma client is generated by the @reftrixmcp/database workspace package's own postinstall (prisma generate) during pnpm install — a workspace lifecycle script, which pnpm does not gate behind the dependency build-script allowlist. Only run pnpm approve-builds if you have a specific reason to let one of these blocked dependencies run its own native build step (onnxruntime-node is already allow-listed via pnpm.onlyBuiltDependencies, so it never appears in the ignored list; and CUDA acceleration is a separate opt-in — see the GPU / CUDA note above — not pnpm approve-builds).

Connect to Claude

Add to your MCP config:

• Claude Desktop: ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
• MCP Client CLI: .mcp.json in the project root or ~/.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"
      }
    }
  }
}