Reftrixmcp

by TKMD

1 stars

322 downloads

Not rated

GitHub Website

Other

About

MCP server with 39 tools for web design analysis — layout extraction, motion detection, quality scoring, accessibility audit, Core Web Vitals, design comparison, and semantic search via Playwright, pgvector, ONNX Runtime, and Ollama.

Details

Author: TKMD
GitHub stars: 1
Downloads: 322
Categories: Other

- Layout analysis: auto‑detect sections and generate React/Vue/HTML code
- Motion detection: discover CSS/JS animations with frame capture and CLS detection
- Quality evaluation: score designs on originality, craftsmanship, and contextuality
- Semantic search: pgvector HNSW hybrid search for layout, motion, and more
- Preference profiling: learn user design preferences via feedback and reranking (GDPR‑compliant)
- Part‑level analysis: extract 16 UI part types with DINOv2 visual embeddings

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below

Plugin Name Reftrixmcp

Command (node, npx, python, etc.)

Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

JSON

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

From the repository

Clone the repository, install dependencies with pnpm, set up Docker containers for PostgreSQL and Redis, run database migrations and seed, build the project, install Playwright and download the DINOv2 and e5‑base models, then configure the MCP server in your Claude or MCP client config. Start the server with the command node /path/to/ReftrixMCP/apps/mcp-server/dist/index.js and provide environment variables for database, Redis, and Ollama.

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "reftrixmcp": {
            "reftrix": {
                "command": "node",
                "args": [
                    "/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"
                }
            }
        }
    }
}

McpServers

{
    "reftrix": {
        "command": "node",
        "args": [
            "/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"
        }
    }
}

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.

<details>
<summary>Japanese / 日本語の概要</summary>

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

</details>

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 (~800 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.

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; ML features (embedding, visual search) require explicit install: pnpm add onnxruntime-node. Non-ML tools (layout analysis, quality evaluation, code generation) work without it
- 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 ~800 MB download (ViT-B/14 ONNX)

Release notes / リリースノート

- 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: 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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

Claude Desktop / Cursor

McpServers

ReftrixMCP

What it does

Why ReftrixMCP

Quickstart

Prerequisites

Setup

Connect to Claude

Example tools

Architecture

Documentation

Known limitations

Release notes / リリースノート

License

Contributing

Security

Install

More like this

Sequential Thinking

Filesystem

EverArt

Google Drive

Reactive Resume

FastMCP v2 🚀