{
  "markdown": "# ReftrixMCP\n\n**Web design knowledge base platform -- layout analysis, motion detection, and quality evaluation via MCP tools.**\n\n> 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.\n\n[![License: AGPL-3.0-only](https://img.shields.io/badge/License-AGPL--3.0--only-blue.svg)](LICENSE)\n[![TypeScript](https://img.shields.io/badge/TypeScript-5.9-blue)](https://www.typescriptlang.org/)\n[![PostgreSQL](https://img.shields.io/badge/PostgreSQL-18-336791)](https://www.postgresql.org/)\n[![MCP](https://img.shields.io/badge/MCP-Protocol-green)](https://modelcontextprotocol.io/)\n[![pnpm](https://img.shields.io/badge/pnpm-10-f69220)](https://pnpm.io/)\n\n<a href=\"https://glama.ai/mcp/servers/@TKMD/reftrix-mcp\">\n  <img width=\"380\" height=\"200\" src=\"https://glama.ai/mcp/servers/@TKMD/reftrix-mcp/badge\" alt=\"ReftrixMCP MCP server\" />\n</a>\n\n<details>\n<summary>Japanese / 日本語の概要</summary>\n\nReftrixMCPは、Webデザインパターンをベクトル検索(pgvector HNSW)と\nRAGで検索可能なナレッジベースに集約し、MCPツール経由でClaude等の\nAIエージェントと統合するプラットフォームです。\n\n**主要機能**: レイアウト分析 / モーション検出 / 品質評価 / セマンティック検索 / 横断検索 / 画像類似検索 / レスポンシブ解析 / 嗜好プロファイリング / パーツ分析 / レート制限 / 検索キャッシュ / BullMQ UI / SBOM\n\n**<!-- gen:tool-count -->40<!-- /gen:tool-count -->の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)\n\n詳細な日本語ドキュメント: [docs/README.ja.md](docs/README.ja.md)\n\n</details>\n\n## What it does\n\n- **Layout analysis** -- auto-detect sections (hero, feature, CTA, etc.), extract grid/typography, and generate React/Vue/HTML code\n- **Motion detection** -- discover CSS/JS animations with frame capture (15 px/frame video mode), CLS detection via Pixelmatch\n- **Quality evaluation** -- score designs on three axes (originality, craftsmanship, contextuality) with anti-AI-cliche detection\n- **Semantic search** -- find layout, motion, narrative, background, and responsive patterns via pgvector HNSW hybrid search\n- **Preference profiling** -- learn user design preferences through feedback sessions and personalize search results via reranking (GDPR-compliant)\n- **Part-level analysis** -- extract 16 UI part types (button, icon, heading, etc.) with DINOv2 visual embeddings for visual similarity search\n- **Vision integration** -- Ollama llama3.2-vision for richer layout, motion, and narrative understanding\n- **Section post-processing** -- auto merge/split sections by type, heading, and height (Rule 1-4) for optimal structure\n- **Multi-tile capture** -- split large sections (>viewport height) into tiles for complete DINOv2 visual coverage\n- **Blank image detection** -- detect lazy-loading unrendered sections and re-capture via Playwright for full coverage\n- **Code generation** -- convert analyzed sections to React, Vue, or plain HTML with matched motion patterns\n- **Unified search** -- cross-service search across layout, part, motion, background, and narrative patterns in a single query\n- **Image similarity search** -- find visually similar designs via DINOv2 embeddings from Base64/URL input (RRF 3-source)\n- **Rate limiting** -- Token Bucket + Redis Lua (CWE-770 DoS prevention), 3-tier (analysis 10 RPM / search 120 RPM / default 60 RPM)\n- **Search cache** -- LRU in-memory cache (lru-cache v11) with TTL-based natural expiry (5 min)\n- **BullMQ UI** -- Bull Board dashboard for monitoring async page.analyze jobs (port 21080)\n- **SBOM** -- CycloneDX 1.6 auto-generation for EU CRA vulnerability reporting compliance\n\n## Why ReftrixMCP\n\n|                      |                                                                                                             |\n| -------------------- | ----------------------------------------------------------------------------------------------------------- |\n| **Layout-aware**     | Sections, grids, and typography extracted as structured data -- not just screenshots                        |\n| **Motion-aware**     | CSS static analysis + frame-by-frame video capture for real animation behavior                              |\n| **Quality-aware**    | Three-axis scoring with actionable improvement suggestions                                                  |\n| **Searchable**       | 768-dim multilingual embeddings (e5-base) with HNSW index and hybrid RRF ranking                            |\n| **Preference-aware** | User preference profiling with feedback-driven reranking across all search tools                            |\n| **Part-aware**       | 16 UI part types extracted with DINOv2 visual embeddings for cross-site component comparison                |\n| **MCP-native**       | <!-- gen:tool-count -->40<!-- /gen:tool-count --> tools purpose-built for Claude Desktop and MCP Client CLI |\n\n## Quickstart\n\n> Run `page.analyze` on any URL in under 5 minutes.\n\n### Prerequisites\n\nNode.js 20+, pnpm 10+, Docker & Docker Compose, [Ollama](https://ollama.com/)\n\n### Setup\n\n```bash\ngit clone https://github.com/TKMD/ReftrixMCP.git && cd ReftrixMCP\npnpm install                                     # CUDA skip is default; see GPU note below\ncp .env.example .env.local                       # edit DATABASE_URL / REDIS_URL as needed\ncp .env.local packages/database/.env             # Prisma CLI requires this copy\npnpm docker:up                                   # PostgreSQL 18 + pgvector + Redis\npnpm db:migrate && pnpm db:seed\npnpm build\npnpm exec playwright install chromium            # browser for page crawling\npnpm --filter @reftrixmcp/ml download:dinov2        # DINOv2 visual embedding model (~330 MB)\npnpm --filter @reftrixmcp/ml repair:e5-cache --check # (optional) verify multilingual-e5-base ONNX cache (~1.1 GB) integrity\ncurl -fsSL https://ollama.com/install.sh | sh    # install Ollama\nollama pull llama3.2-vision                      # vision model (~7.9 GB)\nollama serve                                     # keep running in a separate terminal\n```\n\n> **Note**: If you change `.env.local`, also update `packages/database/.env`.\n> `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.\n> See [Getting Started](docs/users-guide/01-getting-started.md) for GPU configuration and details.\n>\n> **GPU / CUDA**: CUDA binary download is skipped by default (CPU fallback). For GPU acceleration setup, see [Troubleshooting: CUDA Detection](docs/users-guide/04-troubleshooting.md#onnxruntime-cuda-detection).\n>\n> **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`).\n\n### Connect to Claude\n\nAdd to your MCP config:\n\n- **Claude Desktop**: `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS)\n- **MCP Client CLI**: `.mcp.json` in the project root or `~/.claude/.mcp.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"reftrix\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/ReftrixMCP/apps/mcp-server/dist/index.js\"],\n      \"env\": {\n        \"NODE_ENV\": \"development\",\n        \"DATABASE_URL\": \"postgresql://reftrix:change_me@localhost:26432/reftrix?schema=public\",\n        \"REDIS_URL\": \"redis://localhost:27379\",\n        \"OLLAMA_BASE_URL\": \"http://localhost:11434\",\n        \"OLLAMA_HOST\": \"http://localhost:11434\",\n        \"ENABLE_SECTION_SCREENSHOT_FALLBACK\": \"true\"\n      }\n    }\n  }\n}\n```\n\n> Replace `change_me` with a secure password. Port 26432 = standard 5432 + 21000 offset.\n>\n> `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.\n>\n> `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.\n>\n> **Optional environment variables** (defaults work out of the box):\n> `MAX_TILES_PER_SECTION` (default 20, max 100) -- max tiles per section for multi-tile capture.\n> `BLANK_IMAGE_STDDEV_THRESHOLD` (default 5.0) -- stddev threshold for blank image detection.\n> `DUPLICATE_VECTOR_THRESHOLD` (default 0.995) -- cosine similarity threshold for vision embedding dedup.\n> `EMBEDDING_IDLE_TIMEOUT_MS` (default 30000) -- ONNX Worker VRAM auto-release timer (0 to disable).\n> `DINOV2_MODEL_PATH` -- custom DINOv2 ViT-B/14 ONNX model path.\n> `EMBEDDING_CACHE_ENABLED` (default true) -- enable/disable the Layout Embedding disk cache (additive opt-out flag; set `\"false\"` to write no cache files).\n> `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.\n\n## Example tools\n\nReftrixMCP provides **<!-- gen:tool-count -->40<!-- /gen:tool-count --> MCP tools**. Key examples:\n\n- `layout.ingest` -- fetch a web page, take a screenshot, and extract section patterns\n- `layout.search` -- semantic search over layout sections by natural-language query\n- `motion.detect` -- detect CSS/JS animations with video-mode frame capture\n- `quality.evaluate` -- score design quality on originality, craftsmanship, and contextuality\n- `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\n- `responsive.search` -- search responsive analysis results by viewport and breakpoint\n- `preference.hear` -- interactive preference hearing sessions with sample presentation and feedback collection\n- `preference.get` -- retrieve preference profiles (with GDPR data portability support)\n- `preference.reset` -- reset or permanently delete preference profiles (GDPR Right to Erasure)\n- `part.search` -- semantic search over UI parts with visual (DINOv2) or text embeddings\n- `part.inspect` -- get detailed part info including computed styles, bounding box, and accessibility\n- `part.compare` -- compare 2-5 parts side by side on styles, layout, and interaction\n\nFull tool reference: [MCP Tools Guide](docs/users-guide/02-mcp-tools-guide.md)\n\n## Architecture\n\n```\nMCP Client (Claude Desktop / Code)  --stdio-->  MCP Server (<!-- gen:tool-count -->40<!-- /gen:tool-count --> tools, Zod)\n  +-- Service Layer: Playwright, Sharp+Pixelmatch, DOMPurify\n  +-- ML Layer: ONNX Runtime (multilingual-e5-base + DINOv2 ViT-B/14, 768-dim)\n  +-- BullMQ Workers: page.analyze, quality.evaluate\n  +-- PostgreSQL 18 + pgvector 0.8 (HNSW, tsvector)  +  Redis 7\n```\n\n## Documentation\n\n| Guide                                                                   | Description                                                                     |\n| ----------------------------------------------------------------------- | ------------------------------------------------------------------------------- |\n| [Getting Started](docs/users-guide/01-getting-started.md)               | Installation, setup, and first analysis                                         |\n| [MCP Tools Guide](docs/users-guide/02-mcp-tools-guide.md)               | All <!-- gen:tool-count -->40<!-- /gen:tool-count --> tools with usage examples |\n| [page.analyze Deep Dive](docs/users-guide/03-page-analyze-deep-dive.md) | Async analysis flow and data structures                                         |\n| [Troubleshooting](docs/users-guide/04-troubleshooting.md)               | Common issues and solutions                                                     |\n\n## Known limitations\n\n- `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\n- CPU-mode embedding takes ~2-5 s per text; GPU recommended for batch workloads\n- Minimum 16 GB RAM; 32 GB recommended for concurrent analysis with Ollama Vision\n- 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\n- `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)\n- Vision analysis (layout, motion, narrative) requires Ollama + `llama3.2-vision` running locally\n- DINOv2 visual embedding model requires ~330 MB download (ViT-B/14 ONNX)\n\n## Release notes / リリースノート\n\n- **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 承認の後にのみ実行されます。\n- **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。\n\n## License\n\nAGPL-3.0-only -- see [LICENSE](LICENSE).\n\nNetwork use requires source disclosure per [Section 13](https://www.gnu.org/licenses/agpl-3.0.html#section13).\nSource: [github.com/TKMD/ReftrixMCP](https://github.com/TKMD/ReftrixMCP)\nCommercial license: [licence@reftrix.io](mailto:licence@reftrix.io)\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md).\n\n## Security\n\nReport vulnerabilities per [SECURITY.md](SECURITY.md).\nPrivacy: [docs/legal/PRIVACY_POLICY.md](docs/legal/PRIVACY_POLICY.md) | Profiling privacy: [apps/mcp-server/PRIVACY.md](apps/mcp-server/PRIVACY.md) | Data retention: [apps/mcp-server/DATA_RETENTION.md](apps/mcp-server/DATA_RETENTION.md) | Third-party licenses: [THIRDPARTY_LICENSES.md](THIRDPARTY_LICENSES.md)\n",
  "bytes": 16620,
  "sha": "9178be5880288fd0d8953848650fc8c2d40deaacf2485b771e340b0e0cf53f78",
  "repo_slug": "tkmd/reftrixmcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_tkmd_reftrixmcp_030aec65/readme"
}