MCP 服务器

ReftrixMCP

Web design analysis MCP server with 20 tools for layout extraction, motion detection, quality scoring, and semantic search. Uses Playwright, pgvector HNSW, and Ollama Vision to turn web pages into searchable, structured design knowledge.

README

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エージェントと統合するプラットフォームです。

主要機能: レイアウト分析 / モーション検出 / 品質評価 / セマンティック検索 / レスポンシブ解析

20のMCPツールを提供: Layout(5) / Motion(2) / Quality(3) / Page(2) / Narrative(1) / Background(1) / Responsive(1) / Style(1) / Brief(1) / Project(2) / System(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
Vision integration -- Ollama llama3.2-vision for richer layout, motion, and narrative understanding
Code generation -- convert analyzed sections to React, Vue, or plain HTML with matched motion patterns

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
MCP-native	20 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
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
curl -fsSL https://ollama.com/install.sh | sh    # install Ollama
ollama pull llama3.2-vision                      # vision model (~2 GB)
ollama serve                                     # keep running in a separate terminal

Note: If you change .env.local, also update packages/database/.env. page.analyze workers start automatically -- no manual worker launch needed. 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"
      }
    }
  }
}

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

Example tools

ReftrixMCP provides 20 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

Full tool reference: MCP Tools Guide

Architecture

MCP Client (Claude Desktop / Code)  --stdio-->  MCP Server (20 tools, Zod)
  +-- Service Layer: Playwright, Sharp+Pixelmatch, DOMPurify
  +-- ML Layer: ONNX Runtime (multilingual-e5-base, 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 20 tools with usage examples
page.analyze Deep Dive	Async analysis flow and data structures
Troubleshooting	Common issues and solutions

Known limitations

CPU-mode embedding takes ~2-5 s per text; GPU recommended for batch workloads
Minimum 8 GB RAM; 16 GB recommended for concurrent analysis
First embedding call downloads ~400 MB model (multilingual-e5-base)
page.analyze workers auto-start via WorkerSupervisor; manual launch is not required
Vision analysis (layout, motion, narrative) requires Ollama + llama3.2-vision running locally