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.

ReftrixMCPは、Webデザインパターンをベクトル検索(pgvector HNSW)と RAGで検索可能なナレッジベースに集約し、MCPツール経由でClaude等の AIエージェントと統合するプラットフォームです。

主要機能: レイアウト分析 / モーション検出 / 品質評価 / セマンティック検索 / 横断検索 / 画像類似検索 / レスポンシブ解析 / 嗜好プロファイリング / パーツ分析 / レート制限 / 検索キャッシュ / BullMQ UI / SBOM

28のMCPツールを提供: Layout(5) / Motion(2) / Quality(3) / Page(2) / Narrative(1) / Background(1) / Responsive(1) / Preference(3) / Part(3) / Style(1) / Brief(1) / Project(2) / System(1) / Search(1) / Design(1)

詳細な日本語ドキュメント: docs/README.ja.md

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
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 (~800 MB)
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 managed by WorkerSupervisor. Run pnpm --filter @reftrixmcp/mcp-server worker:start:page to start the worker process. See Getting Started for GPU configuration and details.

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"
      }
    }
  }
}

Replace change_me with a secure password. Port 26432 = standard 5432 + 21000 offset.

OLLAMA_BASE_URL is used by the MCP server process; OLLAMA_HOST is used by the worker process. Both must match if Ollama runs on a non-default port.

ENABLE_SECTION_SCREENSHOT_FALLBACK enables Playwright-based individual section screenshots for sections outside the initial screenshot range (WebGL/lazy-rendered pages). This significantly improves DINOv2 visual embedding coverage. Set to "false" to disable.

Optional environment variables (defaults work out of the box): MAX_TILES_PER_SECTION (default 20, max 100) -- max tiles per section for multi-tile capture. BLANK_IMAGE_STDDEV_THRESHOLD (default 5.0) -- stddev threshold for blank image detection. DUPLICATE_VECTOR_THRESHOLD (default 0.995) -- cosine similarity threshold for vision embedding dedup. EMBEDDING_IDLE_TIMEOUT_MS (default 30000) -- ONNX Worker VRAM auto-release timer (0 to disable). DINOV2_MODEL_PATH -- custom DINOv2 ViT-B/14 ONNX model path.

Example tools

ReftrixMCP provides 28 MCP tools. Key examples:

• layout.ingest -- fetch a web page, take a screenshot, and extract section patterns

• layout.search -- semantic search over layout sections by natural-language query

• motion.detect -- detect CSS/JS animations with video-mode frame capture

• quality.evaluate -- score design quality on originality, craftsmanship, and contextuality

• page.analyze -- unified analysis: layout + motion + quality in one call (async via BullMQ)

• responsive.search -- search responsive analysis results by viewport and breakpoint

• preference.hear -- interactive preference hearing sessions with sample presentation and feedback collection

• preference.get -- retrieve preference profiles (with GDPR data portability support)

• preference.reset -- reset or permanently delete preference profiles (GDPR Right to Erasure)

• part.search -- semantic search over UI parts with visual (DINOv2) or text embeddings

• part.inspect -- get detailed part info including computed styles, bounding box, and accessibility

• part.compare -- compare 2-5 parts side by side on styles, layout, and interaction

Full tool reference: MCP Tools Guide

Architecture

MCP Client (Claude Desktop / Code)  --stdio-->  MCP Server (28 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

Documentation

Known limitations

• CPU-mode embedding takes ~2-5 s per text; GPU recommended for batch workloads

• Minimum 16 GB RAM; 32 GB recommended for concurrent analysis with Ollama Vision

• First embedding call downloads ~400 MB model (multilingual-e5-base)

• page.analyze workers are managed by WorkerSupervisor; run pnpm --filter @reftrixmcp/mcp-server worker:start:page to start

• Vision analysis (layout, motion, narrative) requires Ollama + llama3.2-vision running locally

• DINOv2 visual embedding model requires ~800 MB download (ViT-B/14 ONNX)

License

AGPL-3.0-only -- see LICENSE.

Network use requires source disclosure per Section 13. Source: github.com/TKMD/ReftrixMCP Commercial license: licence@reftrix.io

Contributing

See CONTRIBUTING.md.

Security

Report vulnerabilities per SECURITY.md. Privacy: docs/legal/PRIVACY_POLICY.md | Profiling privacy: apps/mcp-server/PRIVACY.md | Data retention: apps/mcp-server/DATA_RETENTION.md | Third-party licenses: THIRDPARTY_LICENSES.md