Reftrixmcp

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.

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

ReftrixMCP を選ぶ理由

レイアウトを把握	セクション、グリッド、タイポグラフィを構造化データとして抽出します。スクリーンショットだけではありません
モーションを把握	CSS の静的解析とフレームごとの動画キャプチャにより、実際のアニメーションの挙動を把握します
品質を把握	3 軸でスコアリングし、実行可能な改善案を提示します
検索可能	HNSW インデックスとハイブリッド RRF ランキングを備えた 768 次元の多言語埋め込み（e5-base）
ユーザーの好みを把握	ユーザーの好みをプロファイリングし、フィードバックに基づいてすべての検索ツールで再ランキングします
パーツを把握	DINOv2 の視覚埋め込みにより、16 種類の UI パーツを抽出し、サイトをまたいでコンポーネントを比較します
MCP ネイティブ	Claude Desktop と MCP Client CLI 向けに特化して構築された 40 個のツール

クイックスタート

5 分以内に、任意の URL で page.analyze を実行できます。

前提条件

Node.js 20 以上、pnpm 10 以上、Docker と Docker Compose、Ollama

セットアップ

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

注：.env.local を変更した場合は、packages/database/.env も更新してください。 MCP サーバーの起動時に、WorkerSupervisor が page.analyze ワーカーを自動的にフォークします（v0.4.0 PR7d-2 以降）。pnpm --filter @reftrixmcp/mcp-server worker:start:page による手動起動は開発者専用です。MCP サーバーも実行中の場合、Redis ベースの二重実行ガードを回避するには REFTRIX_ALLOW_MANUAL_WORKER=true が必要です。 GPU の設定と詳細については、はじめにを参照してください。

GPU / CUDA：CUDA バイナリのダウンロードはデフォルトでスキップされます（CPU にフォールバックします）。GPU アクセラレーションの設定については、トラブルシューティング：CUDA の検出を参照してください。

pnpm の「Ignored build scripts」：pnpm install の実行時に、pnpm 10 は Ignored build scripts: @prisma/client, esbuild, sharp, ... と表示し、Run "pnpm approve-builds" を提案します。これはエラーではなく、想定された動作です。pnpm 10 はサプライチェーンを保護するため、依存関係のビルド／ライフサイクルスクリプトをデフォルトでブロックします。sharp と esbuild にはビルド済みバイナリが同梱されており、Prisma クライアントは pnpm install 中に @reftrixmcp/database ワークスペースパッケージ独自の postinstall（prisma generate）によって生成されます。これはワークスペースのライフサイクルスクリプトであり、pnpm の依存関係ビルドスクリプト許可リストによる制限を受けないため、セットアップは引き続き完了します。ブロックされた依存関係のいずれかに独自のネイティブビルド手順を実行させる明確な理由がある場合にのみ、pnpm approve-builds を実行してください（onnxruntime-node は pnpm.onlyBuiltDependencies によってすでに許可リストに登録されているため、無視された一覧には表示されません。また、CUDA アクセラレーションは別途オプトインする機能です。上記の GPU / CUDA に関する注を参照してください。pnpm approve-builds で有効にするものではありません）。

Claude に接続する

MCP 設定に追加します。

• Claude Desktop：~/Library/Application Support/Claude/claude_desktop_config.json（macOS）
• MCP Client CLI：プロジェクトルートの.mcp.jsonまたは~/.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"
      }
    }
  }
}

change_meを安全なパスワードに置き換えてください。ポート26432は標準の5432に21000を加えた値です。

OLLAMA_BASE_URLはMCP サーバープロセスで使用され、OLLAMA_HOSTはワーカープロセスで使用されます。Ollamaがデフォルト以外のポートで動作する場合は、両方を一致させる必要があります。

ENABLE_SECTION_SCREENSHOT_FALLBACKを有効にすると、初期スクリーンショットの範囲外のセクション（WebGL／遅延レンダリングされるページ）について、Playwrightベースの個別セクションのスクリーンショットを撮影します。これにより、DINOv2のビジュアル埋め込みのカバー範囲が大幅に向上します。無効にするには"false"に設定します。

任意の環境変数（デフォルトのままですぐに使用できます）： MAX_TILES_PER_SECTION（デフォルト20、最大100）— 複数タイルのキャプチャにおける、セクションごとの最大タイル数。 BLANK_IMAGE_STDDEV_THRESHOLD（デフォルト5.0）— 空白画像検出の標準偏差しきい値。 DUPLICATE_VECTOR_THRESHOLD（デフォルト0.995）— ビジョン埋め込みの重複排除に使うコサイン類似度のしきい値。 EMBEDDING_IDLE_TIMEOUT_MS（デフォルト30000）— ONNX WorkerのVRAM自動解放タイマー（無効にするには0）。 DINOV2_MODEL_PATH — カスタムDINOv2 ViT-B/14 ONNXモデルのパス。 EMBEDDING_CACHE_ENABLED（デフォルトtrue）— Layout Embeddingディスクキャッシュの有効／無効を切り替えます（追加のオプトアウトフラグです。キャッシュファイルを書き込まない場合は"false"に設定します）。 REFTRIX_EMBEDDING_CACHE_ROOT（デフォルト/tmp/reftrix-embedding-cache）— 埋め込みキャッシュのルートです。デフォルトでは、os.tmpdir()の外部に解決されるルートは拒否されます（フェイルクローズ）。代わりに警告を表示してデフォルトのルートにフォールバックするには、REFTRIX_EMBEDDING_CACHE_ROOT_ALLOW_FALLBACK=trueを設定します。

ツールの例

ReftrixMCPは40個のMCPツールを提供します。主な例：

• layout.ingest — ウェブページを取得し、スクリーンショットを撮影して、セクションのパターンを抽出します
• layout.search — 自然言語のクエリでレイアウトセクションを意味検索します
• motion.detect — ビデオモードのフレームキャプチャを使って、CSS／JSアニメーションを検出します
• quality.evaluate — 独創性、職人技、文脈適合性に基づいてデザイン品質を評価します
• page.analyze — レイアウト、動き、品質、レスポンシブ対応をまとめて分析します（BullMQ経由で非同期実行）。オプトインでPhase 7.5のアクセシビリティ監査、パフォーマンス評価、自動スナップショットにも対応します
• responsive.search — ビューポートとブレークポイントでレスポンシブ分析結果を検索します
• preference.hear — サンプルの提示とフィードバックの収集を行う、インタラクティブな嗜好ヒアリングセッションです
• preference.get — 嗜好プロファイルを取得します（GDPRのデータポータビリティに対応）
• preference.reset — 嗜好プロファイルをリセットまたは完全に削除します（GDPRの消去権）
• part.search — ビジュアル（DINOv2）またはテキストの埋め込みを使ってUIパーツを意味検索します
• part.inspect — 計算済みスタイル、バウンディングボックス、アクセシビリティなど、パーツの詳細情報を取得します
• part.compare — スタイル、レイアウト、インタラクションについて、2～5個のパーツを並べて比較します

ツールの完全なリファレンス：MCP Tools Guide

アーキテクチャ

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

ドキュメント

ガイド	説明
はじめに	インストール、セットアップ、最初の分析
MCP ツールガイド	40 個すべてのツールと使用例
page.analyze 詳細解説	非同期分析のフローとデータ構造
トラブルシューティング	よくある問題と解決方法

既知の制限事項

• onnxruntime-node はオプションの依存関係で、pnpm install の実行時にデフォルトでインストールされます（埋め込みやビジュアル検索など、ML 機能を提供します）。サポート対象外のプラットフォームでインストールに失敗した場合や、pnpm install --no-optional で省略した場合でも、ML を使用しないツール（レイアウト分析、品質評価、コード生成）は引き続き動作します
• CPU モードでの埋め込みにはテキストごとに約 2～5 秒かかります。バッチ処理には GPU を推奨します
• 最低 16 GB の RAM が必要です。Ollama Vision を使った並行分析には 32 GB を推奨します
• 初回の埋め込み呼び出し時に、約 1.1 GB の ONNX モデル（multilingual-e5-base、FP32）が transformers.js のキャッシュにダウンロードされます。pnpm --filter @reftrixmcp/ml repair:e5-cache --check を実行すれば、いつでも整合性を確認できます。サイズまたは SHA-256 の不一致時に再ダウンロードするには --repair を、常に再ダウンロードするには --force を指定します
• MCP サーバーの起動時に、WorkerSupervisor によって page.analyze のワーカーが自動的にフォークされます（v0.4.0 PR7d-2+）。手動起動は開発者専用です（MCP サーバーの実行中に手動起動するには REFTRIX_ALLOW_MANUAL_WORKER=true が必要です）
• ビジョン分析（レイアウト、モーション、ナラティブ）には、Ollama と llama3.2-vision がローカルで実行されている必要があります
• DINOv2 ビジュアル埋め込みモデルのダウンロードには約 330 MB が必要です（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