@reftrixmcp/mcp-server

Reftrix MCP Server

AIエージェント（Claude等）がReftrixのWebデザイン分析機能と連携するためのModel Context Protocol (MCP) サーバー実装です。

A Model Context Protocol (MCP) server implementation that enables AI agents (such as Claude) to interact with Reftrix's web design analysis features.

概要 / Overview

Reftrix MCP Serverは、Webデザインのレイアウト分析・モーション検出・品質評価をMCPツールとして提供します。Claude Desktopなどのクライアントから自然言語でWebデザイン分析が可能になります。

Reftrix MCP Server provides web design layout analysis, motion detection, and quality evaluation as MCP tools. It enables natural language-based web design analysis from clients such as Claude Desktop.

主要機能 / Key Features

• レイアウト分析: Webページの構造解析、セクションパターン抽出
• モーション検出: CSSアニメーション/トランジション検出
• 品質評価: デザイン品質3軸評価（独自性・技巧・文脈適合性）
• コード生成: セクションパターンからReact/Vue/HTML生成
• 統合Web分析: page.analyze による Layout + Motion + Quality 一括分析（非同期、BullMQ）
• ナラティブ検索: 世界観・レイアウト構成セマンティック検索
• バックグラウンド検索: BackgroundDesignセマンティック検索
• キャッシュ: LRUキャッシュによる高速レスポンス

技術スタック / Tech Stack

技術 / Technology	バージョン / Version	用途 / Purpose
MCP SDK	1.26.x	Model Context Protocol実装
Node.js	20.x LTS	ランタイム
TypeScript	5.x	型安全な開発
Zod	3.24.x	入力バリデーション
BullMQ	5.66.x	非同期ジョブキュー（page.analyze）
Redis	-	BullMQジョブキューのバックエンド（ポート: 27379）
ONNX Runtime	1.21.x	ML推論（Embedding生成、Worker Thread化）

インストール / Installation

# モノレポルートから
pnpm install

# ビルド
cd apps/mcp-server
pnpm build

使用方法 / Usage

直接実行 / Direct Execution

# 開発モード
pnpm dev

# プロダクション
pnpm start

Claude Desktop設定 / Claude Desktop Configuration

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) または該当パスに以下を追加:

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

MCPツール一覧（26ツール） / MCP Tool List (26 Tools)

Layoutツール（5ツール） / Layout Tools (5 Tools)

layout.ingest - Webページ取得 / Web Page Ingestion

URLからWebページのHTML・スクリーンショットを取得し、レイアウト解析用データを準備します。

Retrieves HTML and screenshots from a URL and prepares data for layout analysis.

入力スキーマ / Input Schema:

{
  url: string;              // 取得対象URL（https/http、必須）
  source_type?: 'award_gallery' | 'user_provided';
  usage_scope?: 'inspiration_only' | 'owned_asset';
  options?: {
    viewport?: { width: number; height: number };
    full_page?: boolean;          // デフォルト: true
    timeout?: number;             // デフォルト: 30000 (30秒)
    save_to_db?: boolean;         // デフォルト: true（DB保存、motion.detect連携用）
    include_html?: boolean;       // デフォルト: false
    include_screenshot?: boolean; // デフォルト: false
  };
}

layout.inspect - レイアウト解析 / Layout Analysis

HTMLを解析し、セクション構成・グリッド・タイポグラフィ情報を抽出します。 / Analyzes HTML and extracts section structure, grid, and typography information.

入力スキーマ:

{
  id?: string;              // WebページID（htmlと排他）
  html?: string;            // 直接HTML指定
  options?: {
    detectSections?: boolean;
    detectGrid?: boolean;
    analyzeTypography?: boolean;
    extractColors?: boolean;
  };
}

layout.search - レイアウトパターン検索 / Layout Pattern Search

セクションパターンを自然言語でセマンティック検索します。 / Performs semantic search on section patterns using natural language.

入力スキーマ:

{
  query: string;            // 検索クエリ（1-500文字、必須）
  filters?: {
    sectionType?: 'hero' | 'feature' | 'cta' | 'testimonial' | 'pricing' | 'footer' | 'navigation' | 'about' | 'contact' | 'gallery' | 'partners' | 'portfolio' | 'team' | 'stories' | 'research' | 'subscribe' | 'stats' | 'faq';
    sourceType?: 'award_gallery' | 'user_provided';
    usageScope?: 'inspiration_only' | 'owned_asset';
  };
  limit?: number;           // 取得件数（1-50、デフォルト10）
  include_html?: boolean;   // HTMLを含めるか（デフォルトfalse）- snake_case正式形式
  includeHtml?: boolean;    // レガシー互換（include_html推奨）
}

layout.generate_code - コード生成 / Code Generation

セクションパターンからReact/Vue/HTMLコードを生成します。 / Generates React/Vue/HTML code from section patterns.

入力スキーマ:

{
  patternId: string;        // パターンID（UUID形式、必須）
  options?: {
    framework?: 'react' | 'vue' | 'html';
    typescript?: boolean;
    tailwind?: boolean;
    componentName?: string;
  };
}

layout.batch_ingest - バッチWebページ取得 / Batch Web Page Ingestion

複数URLからWebページを一括取得します。 / Batch-retrieves web pages from multiple URLs.

入力スキーマ:

{
  urls: string[];           // 取得対象URL配列（1-100件）
  options?: {
    save_to_db?: boolean;   // DB保存（デフォルトtrue）
    auto_analyze?: boolean; // 自動解析（デフォルトtrue）
    concurrency?: number;   // 並列数（1-10、デフォルト5）
    on_error?: 'skip' | 'abort'; // エラー時の動作（デフォルトskip）
  };
}

Motionツール（2ツール） / Motion Tools (2 Tools)

motion.detect - モーション検出 / Motion Detection

Webページからモーション/アニメーションパターンを検出・分類します。 / Detects and classifies motion/animation patterns from web pages.

入力スキーマ:

{
  pageId?: string;          // WebページID（htmlと排他、detection_mode='css'時に使用）
  html?: string;            // HTMLコンテンツ（最大10MB、detection_mode='css'時に使用）
  css?: string;             // 追加CSSコンテンツ
  url?: string;             // 対象URL（detection_mode='video'/'runtime'/'hybrid'時に必須）
  detection_mode?: 'css' | 'runtime' | 'hybrid' | 'video' | 'library_only';
                            // 検出モード（デフォルト: 'video'）
                            // - 'video': フレームキャプチャ+Lighthouse統合（urlが必須）
                            // - 'css': CSS静的解析（html/pageIdが必須）
                            // - 'runtime': JS駆動アニメーション検出（SPA/React/Vue、urlが必須）
                            // - 'hybrid': CSS+runtime複合（urlが必須）
                            // - 'library_only': WebGL/Three.js等のライブラリ専用
  save_to_db?: boolean;     // DB保存（デフォルト: true）
  includeWarnings?: boolean;
  includeSummary?: boolean;
  fetchExternalCss?: boolean;
  baseUrl?: string;         // 外部CSS解決用
}

レスポンス:

{
  patterns: Array<{
    type: string;
    name: string;
    selector: string;
    properties: string[];
    duration: number;
    easing: string;
    trigger: string;
  }>;
  summary: {
    totalPatterns: number;
    byType: Record<string, number>;
    avgDuration: number;
  }
  warnings: Array<{ type: string; severity: string; message: string }>;
}

motion.search - モーションパターン検索 / Motion Pattern Search

モーションパターンを類似検索します。 / Performs similarity search on motion patterns.

入力スキーマ:

{
  query?: string;           // 検索クエリ
  samplePattern?: {
    type?: 'animation' | 'transition' | 'transform' | 'scroll' | 'hover' | 'keyframe';
    duration?: number;
    easing?: string;
  };
  filters?: {
    type?: string;
    minDuration?: number;
    maxDuration?: number;
    trigger?: 'load' | 'hover' | 'scroll' | 'click' | 'focus' | 'custom';
  };
  limit?: number;
  minSimilarity?: number;
}

Qualityツール（3ツール） / Quality Tools (3 Tools)

quality.evaluate - Webデザイン品質評価 / Web Design Quality Evaluation

Webデザインの品質を3軸（独自性・技巧・文脈適合性）で評価します。 / Evaluates web design quality on 3 axes (originality, craftsmanship, contextuality).

入力スキーマ:

{
  action?: 'evaluate' | 'suggest_improvements';
                            // アクション（デフォルト: 'evaluate'）
                            // - 'evaluate': 品質評価
                            // - 'suggest_improvements': 評価結果に基づく改善提案生成
  pageId?: string;          // WebページID（htmlと排他）
  html?: string;            // HTMLコンテンツ（最大10MB）
  weights?: {
    originality?: number;   // 独自性の重み（0-1、デフォルト0.35）
    craftsmanship?: number; // 技巧の重み（0-1、デフォルト0.4）
    contextuality?: number; // 文脈適合性の重み（0-1、デフォルト0.25）
  };                        // 合計は1.0である必要あり
  strict?: boolean;
  includeRecommendations?: boolean;
  summary?: boolean;        // 軽量レスポンス（デフォルト: true）
  save_to_db?: boolean;     // 評価結果をDB保存（デフォルト: false、pageId指定時のみ有効）
}

レスポンス:

{
  success: boolean;
  data: {
    overall: number;          // 総合スコア（0-100）
    grade: 'A' | 'B' | 'C' | 'D' | 'F';
    originality: {            // 独自性スコア
      score: number;          // 0-100
      grade: string;
      details?: string[];
    };
    craftsmanship: {          // 技巧スコア
      score: number;
      grade: string;
      details?: string[];
    };
    contextuality: {          // 文脈適合性スコア
      score: number;
      grade: string;
      details?: string[];
    };
    clicheDetection?: {
      detected: boolean;
      count: number;
      patterns: Array<{ type: string; severity: string; description: string; location?: string }>;
    };
    recommendations?: Array<object>;
    patternAnalysis?: object; // パターン駆動評価結果（v0.1.0）
    axeAccessibility?: object; // aXe WCAG 2.1 AA結果（v0.1.0）
    evaluatedAt: string;      // ISO 8601
  };
}

Note: Service層（executeQualityEvaluate）のレスポンスでは overallScore, axisScores.originality.score 等の形式で返却されます。MCPツールの生レスポンスは上記の data.overall, data.originality.score 形式です。

quality.batch_evaluate - 一括品質評価 / Batch Quality Evaluation

複数ページを一括で品質評価します（最大100件）。 / Batch-evaluates quality for multiple pages (up to 100).

quality.getJobStatus - バッチ評価ジョブステータス確認 / Batch Evaluation Job Status

quality.batch_evaluate で開始した非同期ジョブのステータスを確認します。 / Checks the status of async jobs started by quality.batch_evaluate.

入力スキーマ:

{
  job_id: string; // ジョブID（UUID形式、必須）
}

レスポンス:

{
  job_id: string;
  state: 'waiting' | 'active' | 'completed' | 'failed';
  progress: number;         // 進捗率（0-100）
  items: {
    total: number;
    processed: number;
    success: number;
    failed: number;
  };
  results?: Array<object>;  // 完了時のみ
  error?: object;           // 失敗時のみ
}

Styleツール（1ツール） / Style Tools (1 Tool)

style.get_palette - ブランドパレット取得 / Brand Palette Retrieval

ブランドパレットを取得します。 / Retrieves brand palettes.

入力スキーマ:

{
  id?: string;              // パレットID
  brand_name?: string;      // ブランド名で部分一致検索
  mode?: 'light' | 'dark' | 'both';
  include_gradients?: boolean;
}

Briefツール（1ツール） / Brief Tools (1 Tool)

brief.validate - デザインブリーフ検証 / Design Brief Validation

デザインブリーフを検証し、完成度スコアと改善提案を返します。 / Validates design briefs and returns completeness scores and improvement suggestions.

Projectツール（2ツール） / Project Tools (2 Tools)

project.get - プロジェクト詳細取得 / Project Detail Retrieval

ID指定でプロジェクトの詳細情報を取得します。 / Retrieves project details by ID.

project.list - プロジェクト一覧取得 / Project List Retrieval

ユーザーのプロジェクト一覧を取得します。 / Retrieves the list of user's projects.

Pageツール（2ツール） / Page Tools (2 Tools)

page.analyze - 統合Web分析 / Unified Web Analysis

URLを指定して、Layout + Motion + Qualityを一括分析します。BullMQによる非同期処理で重負荷サイト（WebGL、大量アニメーション等）に対応します。

Performs unified Layout + Motion + Quality analysis for a given URL. Uses BullMQ async processing to handle heavy sites (WebGL, many animations, etc.).

入力スキーマ:

{
  url: string;              // 分析対象URL
  summary?: boolean;        // 軽量レスポンス
  timeout?: number;
  features?: {
    layout?: boolean;
    motion?: boolean;
    quality?: boolean;
  };
}

page.getJobStatus - 非同期ジョブステータス確認 / Async Job Status

page.analyzeの非同期モード（async: true）で実行したジョブのステータスを確認します。 / Checks the status of jobs executed in page.analyze's async mode (async: true).

入力スキーマ:

{
  job_id: string; // ジョブID（UUID形式、必須）
}

レスポンス:

{
  state: 'waiting' | 'active' | 'completed' | 'failed';
  progress: number;         // 進捗率（0-100）
  result?: object;          // 完了時の結果
  error?: string;           // 失敗時のエラー詳細
}

Narrativeツール（1ツール） / Narrative Tools (1 Tool)

narrative.search - ナラティブ検索 / Narrative Search

世界観・レイアウト構成をセマンティック検索します。 / Performs semantic search on worldview and layout composition.

Backgroundツール（1ツール） / Background Tools (1 Tool)

background.search - バックグラウンドデザイン検索 / Background Design Search

BackgroundDesignをセマンティック検索します。 / Performs semantic search on background designs.

Responsiveツール（1ツール） / Responsive Tools (1 Tool)

responsive.search - レスポンシブ分析検索 / Responsive Analysis Search

レスポンシブ分析結果（ビューポート差異、ブレークポイント、スクリーンショット差分）をセマンティック検索します。pgvector HNSW cosine similarity + JSONBフィルタ。

Semantic search over responsive analysis results (viewport differences, breakpoints, screenshot diffs). Uses pgvector HNSW cosine similarity + JSONB filters.

入力スキーマ / Input Schema:

{
  query: string;              // 検索クエリ（自然言語、1-500文字） / Search query (natural language, 1-500 chars)
  filters?: {
    diffCategory?: string;    // 差異カテゴリ / Diff category: layout, typography, spacing, visibility, navigation, image, interaction, animation
    viewportPair?: string;    // ビューポートペア / Viewport pair: desktop-tablet, desktop-mobile, tablet-mobile
    breakpointRange?: { min?: number; max?: number }; // ブレークポイント範囲(px) / Breakpoint range (px)
    minDiffPercentage?: number; // 最小スクリーンショット差分率(0-100) / Min screenshot diff percentage
    webPageId?: string;       // WebページIDでフィルタ / Filter by web page UUID
  };
  limit?: number;             // 取得件数（1-50、デフォルト10） / Result limit (default: 10)
  offset?: number;            // オフセット / Pagination offset
}

Preferenceツール（3ツール） / Preference Tools (3 Tools)

preference.hear - 嗜好ヒアリング / Preference Hearing

ユーザーのデザイン嗜好をインタラクティブにヒアリングします。ステートレス設計：フィードバックなし → Mode A（サンプル提示 + 進捗トラッキング）、フィードバックあり → Mode B（フィードバック記録 + プロファイル更新）。新規プロファイル作成時は profiling_notice を返却（GDPR Art.13/14対応）。

Interactively learns user design preferences. Stateless design: no feedback → Mode A (present samples with progress tracking), feedback present → Mode B (record feedback and update profile). Returns profiling_notice on new profile creation (GDPR Art.13/14 compliance).

入力スキーマ / Input Schema:

{
  profile_id?: string;        // プロファイルID（省略時は新規作成） / Profile ID (creates new if omitted)
  feedback?: {
    sample_id: string;        // フィードバック対象のサンプルID / Target sample ID
    rating: 'positive' | 'negative' | 'neutral';
    comment?: string;         // 任意のコメント / Optional comment
  };
  exclude_ids?: string[];     // 除外するサンプルID（クライアント管理） / Sample IDs to exclude (client-managed)
}

preference.get - プロファイル取得 / Get Profile

嗜好プロファイルの詳細を取得します。GDPRデータポータビリティ（Art. 20）に対応し、include_signals: true で全フィードバックシグナルを含む構造化JSONをエクスポートできます。

Retrieves preference profile details. Supports GDPR data portability (Art. 20) — use include_signals: true to export structured JSON including all feedback signals.

入力スキーマ / Input Schema:

{
  profile_id: string;         // プロファイルID（UUID形式、必須） / Profile ID (UUID, required)
  include_signals?: boolean;  // 全シグナルデータを含める（デフォルト: false） / Include all signal data (default: false)
}

preference.reset - プロファイルリセット / Reset Profile

嗜好プロファイルをリセットまたは完全削除します。ソフトリセット（デフォルト）は嗜好データをクリアしプロファイル枠を維持。hard_delete: true で完全に物理削除（GDPR Art. 17 忘れられる権利）。

Resets or permanently deletes a preference profile. Soft reset (default) clears preference data while keeping the profile shell. hard_delete: true permanently deletes all data (GDPR Art. 17 Right to Erasure).

入力スキーマ / Input Schema:

{
  profile_id: string;         // プロファイルID（UUID形式、必須） / Profile ID (UUID, required)
  confirm: boolean;           // 確認フラグ（必須、trueで実行） / Confirmation flag (required, true to execute)
  hard_delete?: boolean;      // 完全削除（デフォルト: false） / Permanent deletion (default: false)
}

プライバシー / Privacy: 嗜好プロファイリングの詳細は PRIVACY.md および DATA_RETENTION.md を参照してください。 / See PRIVACY.md and DATA_RETENTION.md for details on preference profiling.

Partツール（3ツール） / Part Tools (3 Tools)

part.search - UIパーツ検索 / UI Part Search

UIパーツをセマンティック検索します（ハイブリッド: ベクトル + 全文 RRF）。16パーツタイプ対応、searchMode（visual/text/hybrid）切替可能。 / Performs semantic search on UI parts (hybrid: vector + fulltext RRF). Supports 16 part types, switchable searchMode (visual/text/hybrid).

入力スキーマ / Input Schema:

{
  query: string;              // 検索クエリ（1-500文字、必須） / Search query (1-500 chars, required)
  searchMode?: 'visual' | 'text' | 'hybrid'; // 検索モード（デフォルト: 'hybrid'） / Search mode (default: 'hybrid')
  filters?: {
    partType?: string;        // パーツタイプフィルタ / Part type filter
    webPageId?: string;       // WebページIDフィルタ / Web page ID filter
  };
  limit?: number;             // 取得件数（1-50、デフォルト10） / Result limit (default: 10)
}

part.inspect - パーツ詳細取得 / Part Detail Inspection

IDを指定してパーツの詳細情報（computedStyles、boundingBox、interactionInfo、cssClasses、attributes、piiRiskLevel）を取得します。 / Retrieves detailed part information by ID (computedStyles, boundingBox, interactionInfo, cssClasses, attributes, piiRiskLevel).

入力スキーマ / Input Schema:

{
  id: string;                 // パーツID（UUID形式、必須） / Part ID (UUID, required)
  includeHtml?: boolean;      // HTMLを含めるか（デフォルト: false） / Include HTML (default: false)
  includeEmbedding?: boolean; // Embeddingを含めるか（デフォルト: false） / Include embedding (default: false)
}

part.compare - パーツ比較 / Part Comparison

2〜5個のパーツをスタイル・レイアウト・インタラクション・アクセシビリティの観点で並列比較します。 / Compares 2-5 parts side by side on styles, layout, interaction, and accessibility aspects.

入力スキーマ / Input Schema:

{
  partIds: string[];          // 比較対象パーツID配列（2-5件、UUID形式） / Part IDs to compare (2-5, UUID format)
  aspects?: ('styles' | 'layout' | 'interaction' | 'accessibility')[]; // 比較観点 / Comparison aspects
}

Systemツール（1ツール） / System Tools (1 Tool)

system.health - システムヘルスチェック / System Health Check

MCPサーバーとReftrix Web APIの接続状態を確認します。 / Checks the connection status of MCP server and Reftrix Web API.

Worker Architecture / ワーカーアーキテクチャ

page.analyze は重負荷処理のため、WorkerSupervisor + BullMQ による非同期ワーカーアーキテクチャを採用しています。

page.analyze uses an async worker architecture with WorkerSupervisor + BullMQ for handling heavy processing.

Pipeline Phases / パイプラインフェーズ

INGEST (0→15%)
  → LAYOUT (15→35%)
  → SCROLL_VISION capture (35→45%)    ← Phase 1.5: キャプチャのみ
  → MOTION (45→65%)
  → [browser close]
  → QUALITY (65→80%)
  → NARRATIVE (80→90%)                ← Phase 2.5: SCROLL_VISION_ANALYSIS（Vision LLM分析）をここで実行
  → EMBEDDING (90→100%)

Note: SCROLL_VISION_ANALYSIS（Ollama Vision分析）はNARRATIVEフェーズ内で実行されます。ブラウザクローズ後に実行することでVRAM競合（Chromium + Ollama）を回避しています。

WorkerSupervisor

OOM（メモリ不足）クラッシュを防ぐために、ワーカープロセスを自動管理します。 / Automatically manages worker processes to prevent OOM (out-of-memory) crashes.

• child_process.fork でワーカーを子プロセスとして起動
• N件のジョブ完了後にプロセスを再起動（メモリリーク蓄積を防止）
• クラッシュ時の自動再起動（exit code/signal 両対応）
• Pre-Return Pause + 3-Phase Shutdown Protocol: Processor return前に worker.pause(true) で次ジョブ取得を防止 → IPC 'shutdown' → SIGTERM → SIGKILL

BullMQ Queue 設定 / BullMQ Queue Configuration

パラメータ / Parameter	値 / Value	説明 / Description
Queue名	page-analyze	BullMQキュー名
concurrency	1	シングルトンブラウザとの競合防止
lockDuration	2,400,000ms（40分）	CPU負荷の高いEmbeddingフェーズ対応
stalledInterval	max(60000, lockDuration/4)	stall検出間隔
maxStalledCount	3	stall許容回数

Worker Thread ONNX

ONNX推論を node:worker_threads で別スレッドに分離し、BullMQ heartbeatをブロックしない設計です。

• デュアルモード: Worker Thread（デフォルト）/ In-Process Fallback（EMBEDDING_WORKER_THREAD=false）
• Crashリカバリ最大5回、タイムアウト120秒

GPU Resource Manager

Ollama Vision（SCROLL_VISION_ANALYSISフェーズ）とONNX Embedding（EMBEDDINGフェーズ）間でGPUを動的に切り替えます。

• acquireForVision(): VRAM >= 8192MB を確認してからOllamaに割り当て
• acquireForEmbedding(): Ollamaをアンロードして ONNX CUDA を有効化
• GPU非搭載環境: graceful degradation（CPUモード）

Embedding Backfill

パイプライン完了後にDB駆動で欠損Embeddingを自動修復します。

# Embedding欠損チェック
pnpm check:embeddings

# Embeddingバックフィル（手動実行）
pnpm backfill:embeddings

起動時孤立ジョブ回復 / Startup Orphan Job Recovery

ワーカー起動時に前回クラッシュで孤立したジョブを自動回復します。 / Automatically recovers orphaned jobs from previous crashes at worker startup.

progress	カテゴリ / Category	アクション / Action
= 0%	never_started	failed → retry（waiting に戻す）
0〜90%	processing_interrupted	failed に遷移
>= 90%	db_saved_but_stuck	completed に遷移

エラーハンドリング / Error Handling

エラーコード一覧 / Error Code List

コード / Code	説明 / Description
INTERNAL_ERROR	サーバー内部エラー
VALIDATION_ERROR	入力バリデーションエラー
TOOL_NOT_FOUND	指定されたツールが存在しない
PAGE_NOT_FOUND	指定されたページが存在しない
TRANSFORM_FAILED	変換処理失敗
INVALID_QUERY	無効な検索クエリ
NO_RESULTS	検索結果なし
RATE_LIMIT_EXCEEDED	レート制限超過

セキュリティガイドライン / Security Guidelines

HTMLサニタイズ / HTML Sanitization

• DOMPurify 3.3.xによるXSS対策
• スクリプト要素の除去
• 外部リソース参照の制限

SSRF対策 / SSRF Protection

• プライベートIP（localhost, 127.0.0.1, 192.168.x.x）へのアクセスをブロック
• クラウドメタデータサービス（169.254.x.x）へのアクセスをブロック
• Ollama URLはlocalhostのみに制限

レート制限 / Rate Limiting

• 検索: 100 req/min
• 変換: 50 req/min
• インジェスト: 20 req/min

パフォーマンスガイドライン / Performance Guidelines

パフォーマンス目標 / Performance Targets

指標 / Metric	目標値 / Target
ツールレスポンス（P95）	< 5秒
サーバー起動時間	< 2秒
検索レスポンス（キャッシュヒット）	< 100ms
ベクトル検索速度	< 500ms for 10K items

Service層直接呼び出し / Direct Service Layer Invocation

MCPツールの機能はMCP経由だけでなく、TypeScriptから直接インポートして使用できます。

MCP tool functionality can be directly imported and used from TypeScript, not just via MCP protocol.

インポート方法 / Import Method

import {
  // Page Analyze
  executePageAnalyze,
  type PageAnalyzeInput,
  type PageAnalyzeOutput,

  // Layout Search
  executeLayoutSearch,
  type LayoutSearchInput,
  type LayoutSearchOutput,

  // Motion Search
  executeMotionSearch,
  type MotionSearchInput,
  type MotionSearchOutput,

  // Motion Detect
  executeMotionDetect,
  type MotionDetectInput,
  type MotionDetectOutput,

  // Quality Evaluate
  executeQualityEvaluate,
  type QualityEvaluateInput,
  type QualityEvaluateOutput,

  // Palette
  executeGetPalette,
  type GetPaletteInput,

  // Layout Generate Code
  executeLayoutGenerateCode,
  type LayoutToCodeInput,
  type LayoutToCodeOutput,
} from "@reftrix/mcp-server";

使用例 / Usage Examples

Page Analyze

const result = await executePageAnalyze({
  url: "https://example.com",
  summary: true,
  timeout: 60000,
  features: {
    layout: true,
    motion: true,
    quality: true,
  },
});

if (result.ok) {
  console.log("Analysis result:", result.data);
} else {
  console.error("Analysis failed:", result.error);
}

Layout Search

const result = await executeLayoutSearch({
  query: "modern hero section with gradient",
  filters: {
    sectionType: "hero",
    sourceType: "award_gallery",
  },
  limit: 10,
  offset: 0,
});

if (result.success) {
  console.log("Search results:", result.data.results);
  console.log("Total:", result.data.total);
} else {
  console.error("Search failed:", result.error);
}

Motion Search

const result = await executeMotionSearch({
  query: "smooth fade in animation",
  filters: {
    type: "animation",
    trigger: "scroll",
    minDuration: 200,
    maxDuration: 1000,
  },
  limit: 20,
  minSimilarity: 0.7,
});

if (result.success) {
  console.log("Motion patterns:", result.data.results);
} else {
  console.error("Search failed:", result.error);
}

Quality Evaluate

const result = await executeQualityEvaluate({
  html: "<div>...</div>",
  options: {
    strict: true,
    targetIndustry: "technology",
    includeRecommendations: true,
    weights: {
      originality: 0.4,
      craftsmanship: 0.35,
      contextuality: 0.25,
    },
  },
});

if (result.success) {
  console.log("Overall score:", result.data.overallScore);
  console.log("Grade:", result.data.grade);
  console.log("Axis scores:", result.data.axisScores);
  console.log("Cliche count:", result.data.clicheCount);
} else {
  console.error("Evaluation failed:", result.error);
}

Layout Generate Code

const result = await executeLayoutGenerateCode({
  patternId: "11111111-1111-1111-1111-111111111111",
  options: {
    framework: "react",
    typescript: true,
    tailwind: true,
    componentName: "HeroSection",
  },
});

if (result.success) {
  console.log("Generated code:", result.data.code);
  console.log("Framework:", result.data.framework);
  console.log("Component name:", result.data.componentName);
} else {
  console.error("Generation failed:", result.error);
}

開発 / Development

テスト実行 / Running Tests

# ユニットテスト
pnpm test

# ウォッチモード
pnpm test:watch

ワーカー単体起動 / Starting Workers Individually

# 全ワーカー起動
pnpm worker:start

# PageAnalyzeWorkerのみ起動
pnpm worker:start:page

# BatchQualityWorkerのみ起動
pnpm worker:start:quality

ディレクトリ構造 / Directory Structure

apps/mcp-server/
├── src/
│   ├── index.ts              # エントリポイント
│   ├── server.ts             # MCPサーバー実装
│   ├── router.ts             # ツールルーティング
│   ├── transport.ts          # StdIOトランスポート
│   ├── api/                  # API（ヘルスチェック等）
│   │   └── health.ts
│   ├── config/               # 設定
│   │   ├── index.ts
│   │   └── redis.ts
│   ├── lib/                  # ライブラリ
│   │   ├── index.ts
│   │   └── project-context.ts
│   ├── middleware/            # ミドルウェア
│   │   ├── auth.ts                    # API認証（MCP_API_KEYS）
│   │   ├── args-type-coercion.ts      # 引数型変換
│   │   ├── light-response-controller.ts # レスポンスサイズ制御
│   │   └── response-size-warning.ts   # レスポンスサイズ警告
│   ├── schemas/              # 共有スキーマ
│   │   ├── creative/
│   │   │   ├── index.ts
│   │   │   └── palette.schema.ts
│   │   └── mood-brandtone-filters.ts
│   ├── types/                # 型定義
│   │   └── creative/
│   ├── tools/                # MCPツール実装
│   │   ├── layout/           # レイアウトツール
│   │   ├── motion/           # モーションツール
│   │   ├── quality/          # 品質評価ツール
│   │   ├── brief/            # ブリーフツール
│   │   ├── narrative/        # ナラティブツール
│   │   ├── background/       # バックグラウンドツール
│   │   ├── responsive/       # レスポンシブツール
│   │   ├── preference/       # 嗜好プロファイリングツール
│   │   ├── page/             # page.analyze ツール
│   │   └── schemas/          # 共有Zodスキーマ
│   ├── workers/              # BullMQワーカー
│   │   ├── page-analyze-worker.ts   # page.analyze 非同期ワーカー
│   │   └── batch-quality-worker.ts  # quality.batch_evaluate ワーカー
│   ├── queues/               # BullMQキュー定義
│   ├── scripts/              # スタンドアロン起動スクリプト
│   │   ├── start-workers.ts          # ワーカー起動エントリポイント
│   │   ├── backfill-embeddings.ts    # Embeddingバックフィル
│   │   └── check-embedding-coverage.ts # Embedding欠損チェック
│   ├── services/             # サービス層
│   │   ├── background/       # 背景デザイン検出
│   │   ├── brief/            # ブリーフ検証
│   │   ├── layout/           # レイアウト分析・セクション検出
│   │   ├── ml/               # Embedding生成（ONNX Runtime）
│   │   ├── motion/           # モーション・アニメーション検出
│   │   ├── narrative/        # ナラティブ分析
│   │   ├── page/             # ページ分析パイプライン
│   │   ├── quality/          # デザイン品質評価
│   │   ├── repositories/     # データアクセス層
│   │   ├── responsive/       # レスポンシブ検出
│   │   ├── search/           # 検索サービス（Hybrid/Vector/Full-text）
│   │   ├── storage/          # スクリーンショット保存
│   │   ├── style/            # スタイル・パレット抽出
│   │   ├── vision/           # Vision推論（Ollama連携）
│   │   ├── vision-adapter/   # Visionアダプタ（Mock/Ollama切替）
│   │   ├── visual/           # ビジュアル要素抽出
│   │   └── visual-extractor/ # ビジュアル詳細抽出
│   └── utils/
│       ├── errors.ts
│       └── logger.ts
├── tests/                    # テストファイル
├── package.json
└── tsconfig.json

環境変数 / Environment Variables

基本設定 / Basic Settings

変数名 / Variable	説明 / Description	デフォルト値 / Default	必須 / Required
NODE_ENV	環境（development/test/production）	-	Yes
DATABASE_URL	PostgreSQL接続URL（ポート: 26432）	-	Yes
MCP_AUTH_ENABLED	API認証有効化（本番ではtrueを強く推奨）	false	No
MCP_API_KEYS	APIキー（MCP_AUTH_ENABLED=true時に必須、JSON配列形式）。例: '[{"key":"reftrix_...","role":"ADMIN","userId":"user-1"}]'。各キーに role（ADMIN/USER/VIEWER）、userId、オプションで expiresAt（ISO 8601）を指定。レガシー互換: MCP_API_KEY（単一キー文字列、環境変数フォールバック）も使用可 / API keys (required when MCP_AUTH_ENABLED=true, JSON array format). Example: '[{"key":"reftrix_...","role":"ADMIN","userId":"user-1"}]'. Each key specifies role (ADMIN/USER/VIEWER), userId, and optional expiresAt (ISO 8601). Legacy compat: MCP_API_KEY (single key string, env var fallback) also supported	-	Conditional
REDIS_URL	Redis接続URL	-	Conditional
REDIS_HOST	Redisホスト	localhost	No
REDIS_PORT	Redisポート（ポートオフセット: 21000）	27379	No

WorkerSupervisor設定 / WorkerSupervisor Settings

変数名 / Variable	説明 / Description	デフォルト値 / Default
WORKER_MAX_JOBS_BEFORE_RESTART	N件完了後にワーカーを再起動（OOM防止）	1
WORKER_RESTART_DELAY_MS	再起動間の最小間隔（ms）	3000
WORKER_MAX_RESTART_ATTEMPTS	クラッシュ時の最大再起動試行回数	10
WORKER_SHUTDOWN_TIMEOUT_MS	graceful shutdownタイムアウト（ms）	10000
WORKER_SCRIPT_PATH	ワーカースクリプトの絶対パス（未設定時は自動解決）	-

BullMQ / ワーカー設定 / BullMQ / Worker Settings

変数名 / Variable	説明 / Description	デフォルト値 / Default
BULLMQ_LOCK_DURATION	ジョブロック時間（ms、最小60秒）	2400000（40分）
BULLMQ_LOCK_EXTEND_INTERVAL_MS	ロック延長間隔（ms、最小10秒）	300000（5分）
PAGE_WORKER_CONCURRENCY	PageAnalyzeWorkerの並列数	1
WORKER_CONCURRENCY	BatchQualityWorkerの並列数	3

ML / GPU設定 / ML / GPU Settings

変数名 / Variable	説明 / Description	デフォルト値 / Default
ONNX_EXECUTION_PROVIDER	ONNX実行プロバイダ（cuda/rocm/未設定でCPU）	-
EMBEDDING_WORKER_THREAD	Worker Thread ONNX推論を有効化	true
LD_LIBRARY_PATH	CUDA 12ライブラリパス（自動検出される）	-

メモリ管理設定 / Memory Management Settings

変数名 / Variable	説明 / Description	デフォルト値 / Default
WORKER_MEMORY_CRITICAL_MB	クリティカルRSS閾値（MB）、超過でDB保存フェーズにスキップ	14336（14GB）
WORKER_MEMORY_DEGRADATION_MB	デグレードRSS閾値（MB）、超過でnarrative/vision無効化	12288（12GB）
WORKER_HTML_LARGE_BYTES	Vision LLM無効化HTMLサイズ閾値（バイト）	5000000（5MB）
WORKER_HTML_HUGE_BYTES	narrative+vision無効化HTMLサイズ閾値（バイト）	10000000（10MB）

セキュリティに関する重要な注意事項 / Important Security Notes

本番環境では以下の設定を強く推奨します:

# 本番環境推奨設定 / Production recommended settings
NODE_ENV=production
MCP_AUTH_ENABLED=true

# MCP_API_KEYS: JSON配列形式（各キーは64文字以上を推奨）
# MCP_API_KEYS: JSON array format (each key should be 64+ characters)
MCP_API_KEYS='[{"key":"reftrix_your_64char_random_string_here...","role":"ADMIN","userId":"admin-1"},{"key":"reftrix_another_key...","role":"VIEWER","userId":"viewer-1","expiresAt":"2027-01-01T00:00:00Z"}]'

# レガシー互換: MCP_API_KEY（単一キー文字列）も使用可（リクエスト _meta にキーがない場合のフォールバック）
# Legacy compat: MCP_API_KEY (single key string) also supported (fallback when no key in request _meta)
# MCP_API_KEY=reftrix_single_key_fallback_string

MCP_AUTH_ENABLED=falseかつNODE_ENV=productionの場合、サーバー起動時に警告ログが出力されます。

When MCP_AUTH_ENABLED=false and NODE_ENV=production, a warning log is output at server startup.

page.analyze非同期モード / page.analyze Async Mode

page.analyzeツールでBullMQによるジョブキューを使用するためRedisが必要です:

REDIS_URL=redis://localhost:27379
# または
REDIS_HOST=localhost
REDIS_PORT=27379

Redisが未設定の場合、非同期モードは使用できません（同期モードのみ動作）。

ライセンス / License

AGPL-3.0-only -- 詳細は LICENSE を参照 / See LICENSE for details

関連リンク / Related Links

• Model Context Protocol (MCP)
• MCP SDK