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.

License: AGPL-3.0-only TypeScript PostgreSQL MCP pnpm

Japanese / 日本語の概要

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

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

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

Layout-aware	Sections, grids, and typography extracted as structured data -- not just screenshots
Motion-aware	CSS static analysis + frame-by-frame video capture for real animation behavior
Quality-aware	Three-axis scoring with actionable improvement suggestions
Searchable	768-dim multilingual embeddings (e5-base) with HNSW index and hybrid RRF ranking
Preference-aware	User preference profiling with feedback-driven reranking across all search tools
Part-aware	16 UI part types extracted with DINOv2 visual embeddings for cross-site component comparison
MCP-native	40 tools purpose-built for Claude Desktop and MCP Client CLI

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

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. EMBEDDING_CACHE_ENABLED (default true) -- enable/disable the Layout Embedding disk cache (additive opt-out flag; set "false" to write no cache files). REFTRIX_EMBEDDING_CACHE_ROOT (default /tmp/reftrix-embedding-cache) -- embedding cache root; a root resolving outside os.tmpdir() is rejected by default (fail-closed). Set REFTRIX_EMBEDDING_CACHE_ROOT_ALLOW_FALLBACK=true to instead degrade to the default root with a warning.

Example tools

ReftrixMCP provides 40 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 + responsive in one call (async via BullMQ), with opt-in Phase 7.5: accessibility audit, performance evaluation, and auto snapshot
• 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 (<!-- gen:tool-count -->40<!-- /gen:tool-count --> 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

Guide	Description
Getting Started	Installation, setup, and first analysis
MCP Tools Guide	All 40 tools with usage examples
page.analyze Deep Dive	Async analysis flow and data structures
Troubleshooting	Common issues and solutions

Known limitations

• onnxruntime-node is an optional dependency that pnpm install installs by default (it powers the ML features — embedding and visual search). If it fails to install on an unsupported platform, or you skip it with pnpm install --no-optional, the non-ML tools (layout analysis, quality evaluation, code generation) still work
• 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 ~1.1 GB ONNX model (multilingual-e5-base, FP32) into the transformers.js cache. Verify integrity at any time with pnpm --filter @reftrixmcp/ml repair:e5-cache --check; pass --repair to re-download on size/SHA-256 mismatch, or --force to always re-download
• page.analyze workers are auto-forked by WorkerSupervisor when the MCP server starts (v0.4.0 PR7d-2+); manual start is developer-only (REFTRIX_ALLOW_MANUAL_WORKER=true required when MCP server is running)
• Vision analysis (layout, motion, narrative) requires Ollama + llama3.2-vision running locally
• DINOv2 visual embedding model requires ~330 MB download (ViT-B/14 ONNX)

Release notes / リリースノート

• npm publish automation — Trusted Publishing / OIDC (2026-07-12): npm publishing is now driven by CI. Creating a GitHub Release for a v* tag triggers .github/workflows/publish.yml, which publishes the 5 packages (@reftrixmcp/core, @reftrixmcp/database, @reftrixmcp/ml, @reftrixmcp/webdesign-core, @reftrixmcp/mcp-server) in dependency order via npm Trusted Publishing (OIDC) — no NPM_TOKEN secret is used, and every package is published with --provenance. A verify job builds and validates all tarballs first; a publish job runs only after the npm-publish GitHub Environment's required-reviewer approval. / 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 承認の後にのみ実行されます。
• Plan v4.4 PR-N (2026-05-17): WorkerSupervisorOptions.restartDelayMs field formal removal + env-only canonical SSOT consolidation per ADR-0035 Amendment 1 §Decision 5. The WORKER_RESTART_DELAY_MS and EMBEDDING_BACKFILL_RESTART_DELAY_MS environment variables are now the sole source of truth for per-type restart cooldown values; resolution is performed via getRestartDelayMsForType(workerType). Server version bumped to 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。

License

AGPL-3.0-only -- see LICENSE.

Network use requires source disclosure per Section 13. Source: github.com/TKMD/ReftrixMCP Commercial license: [email protected]

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