Purpose
ReftrixMCP is a web design knowledge base platform for front-end engineers, designers, and AI agent developers, used to analyze real websites and retrieve reusable UI patterns. It runs as an MCP server and can be integrated with Claude or any MCP client, turning web pages into structured, vector-retrievable design knowledge.
Main Capabilities
- Layout Analysis (Layout): Automatically detects section types (hero, feature, CTA, etc.), extracts grid/typography information, and can generate React, Vue, or plain HTML code.
- Motion Detection (Motion): Discovers CSS/JS animations, supports frame capture (15 px/frame video mode), and performs CLS detection via Pixelmatch.
- Quality Assessment (Quality): Scores designs across three dimensions—originality, craft, and contextuality—and includes anti-AI cliché detection.
- Semantic Search: Based on pgvector HNSW hybrid search, finds layout, motion, narrative, background, and responsive patterns.
- Preference Profiling: Learns user design preferences through feedback sessions and personalizes search results through reranking (GDPR-compliant).
- Component-Level Analysis: Extracts 16 UI component types (buttons, icons, headings, etc.), using DINOv2 visual embeddings to support visual similarity search.
- Responsive Analysis: Retrieves responsive analysis results by viewport and breakpoint.
- Optional Phases: page.analyze supports an optional Phase 7.5, including accessibility auditing, performance assessment, and automatic snapshots.
Usage
Connect through an MCP client (such as Claude Desktop). Add the server in the MCP configuration, for example under macOS for Claude Desktop ~/Library/Application Support/Claude/claude_desktop_config.json, or in the project root use .mcp.json. The password placeholder must be replaced in the configuration, and the documentation notes that port 26432 is standard 5432 plus a 21000 offset. Environment variables such as OLLAMA_BASE_URL and OLLAMA_HOST need to be consistent; ENABLE_SECTION_SCREENSHOT_FALLBACK can enable section screenshot fallback. Multiple optional environment variables have default values (such as MAX_TILES_PER_SECTION, BLANK_IMAGE_STDDEV_THRESHOLD, DINOV2_MODEL_PATH, etc.).
Tool Examples
A total of 40 MCP tools are provided, with key examples including:layout.ingest(crawls web pages, takes screenshots, and extracts section patterns),layout.search(natural language semantic search for layout sections),motion.detect(motion detection),quality.evaluate(design quality scoring),page.analyze(unified analysis, asynchronous BullMQ),responsive.search、preference.hear/preference.get/preference.reset、part.search/part.inspect/part.compare , etc. For the complete tool reference, see the MCP Tools Guide.
Applicable Scenarios
Front-end engineers reusing UI patterns, designers analyzing competitor designs, and AI agent developers building automated workflows based on a design knowledge base.
Limitations
- Requires Node.js 20+, pnpm 10+, Docker & Docker Compose, and Ollama.
- onnxruntime-node is an optional dependency; if installation fails or --no-optional is used, non-ML tools remain available.
- In CPU mode, embedding takes about 2-5 seconds per text segment; GPU is recommended for batch work.
- Minimum 16 GB RAM, 32 GB recommended to support concurrent analysis with Ollama Vision.
- The first embedding call downloads an approximately 1.1 GB ONNX model (multilingual-e5-base); the DINOv2 visual embedding model requires an additional approximately 330 MB (ViT-B/14 ONNX).
- Visual analysis (layout, motion, narrative) requires Ollama + llama3.2-vision running locally.
- The page.analyze worker is automatically forked by WorkerSupervisor when the MCP server starts; manual startup is limited to developers (requires REFTRIX_ALLOW_MANUAL_WORKER=true).
- Licensed under AGPL-3.0-only; network use requires source code disclosure under Section 13; for commercial licensing, contact licence@reftrix.io.
