@reftrixmcp/mcp-server 0.1.7 → 0.2.0

package/README.md

@@ -19,7 +19,11 @@ Reftrix MCP Server provides web design layout analysis, motion detection, and qu
 - **統合Web分析**: `page.analyze` による Layout + Motion + Quality 一括分析（非同期、BullMQ）
 - **ナラティブ検索**: 世界観・レイアウト構成セマンティック検索
 - **バックグラウンド検索**: BackgroundDesignセマンティック検索
-- **キャッシュ**: LRUキャッシュによる高速レスポンス
+- **横断検索**: `search.unified` による5サービス並列統合検索
+- **画像類似検索**: `design.search_by_image` によるDINOv2 visual embedding検索
+- **レート制限**: Token Bucket + Redis Lua、3ティア（analysis/search/default）
+- **検索キャッシュ**: LRUキャッシュ（lru-cache v11、500エントリ、5分TTL）
+- **SBOM**: CycloneDX 1.6自動生成
 
 ### 技術スタック / Tech Stack
 
@@ -76,7 +80,7 @@ pnpm start
 }
 ```
 
-## MCPツール一覧（26ツール） / MCP Tool List (26 Tools)
+## MCPツール一覧（28ツール） / MCP Tool List (28 Tools)
 
 ### Layoutツール（5ツール） / Layout Tools (5 Tools)
 
@@ -603,6 +607,20 @@ IDを指定してパーツの詳細情報（computedStyles、boundingBox、inter
 
 MCPサーバーとReftrix Web APIの接続状態を確認します。 / Checks the connection status of MCP server and Reftrix Web API.
 
+### Searchツール（1ツール） / Search Tools (1 Tool)
+
+#### `search.unified` - 横断検索 / Cross-Service Unified Search
+
+5検索サービス（Layout, Part, Motion, Background, Narrative）を統合したマルチモーダル横断検索。
+Cross-service unified search integrating 5 search services (Layout, Part, Motion, Background, Narrative).
+
+### Designツール（1ツール） / Design Tools (1 Tool)
+
+#### `design.search_by_image` - 画像類似検索 / Image Similarity Search
+
+DINOv2 visual embeddingによる画像ベースのデザイン類似検索。Base64画像またはURLから類似デザインを検索。
+Image-based design similarity search using DINOv2 visual embeddings. Search similar designs from Base64 images or URLs.
+
 ---
 
 ## Worker Architecture / ワーカーアーキテクチャ
@@ -717,9 +735,21 @@ pnpm backfill:embeddings
 
 ### レート制限 / Rate Limiting
 
-- 検索: 100 req/min
-- 変換: 50 req/min
-- インジェスト: 20 req/min
+Token Bucket + Redis Lua（CWE-770 DoS対策）。全28ツールに自動適用。
+Token Bucket + Redis Lua (CWE-770 DoS prevention). Auto-applied to all 28 tools.
+
+| ティア / Tier | RPM | 対象ツール / Target Tools                                                                                                                 |
+| ------------- | --- | ----------------------------------------------------------------------------------------------------------------------------------------- |
+| analysis      | 10  | page.analyze, layout.ingest, layout.batch_ingest, quality.batch_evaluate                                                                  |
+| search        | 120 | layout.search, motion.search, narrative.search, background.search, responsive.search, part.search, search.unified, design.search_by_image |
+| default       | 60  | その他すべて / All others                                                                                                                 |
+
+Graceful Degradation: Redis未接続時はインメモリフォールバック / Falls back to in-memory when Redis unavailable
+
+### エラーメッセージサニタイズ / Error Message Sanitization (CWE-209)
+
+`sanitizeErrorMessage()` ユーティリティ（`utils/sanitize-error.ts`）で内部構造の漏洩を防止。47ファイル・28ツールに適用（42ファイルでインポート）。
+`sanitizeErrorMessage()` utility (`utils/sanitize-error.ts`) prevents internal structure leakage. Applied to 47 files and 28 tools (42 import files).
 
 ---
 
@@ -779,7 +809,7 @@ import {
   executeLayoutGenerateCode,
   type LayoutToCodeInput,
   type LayoutToCodeOutput,
-} from "@reftrix/mcp-server";
+} from "@reftrixmcp/mcp-server";
 ```
 
 ### 使用例 / Usage Examples

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "@reftrixmcp/mcp-server",
-  "version": "0.1.7",
+  "version": "0.2.0",
   "license": "AGPL-3.0-only",
   "description": "MCP Server for Reftrix - AI agent integration for web design analysis, layout extraction, motion detection, and quality evaluation",
   "files": [
     "dist/",
     "src/"
   ],
-  "mcpName": "io.github.tkmd/reftrixmcp",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
   "exports": {
@@ -40,29 +39,66 @@
   "bin": {
     "reftrix-mcp": "./dist/index.js"
   },
+  "scripts": {
+    "build": "tsc",
+    "dev": "NODE_ENV=development tsx watch src/index.ts",
+    "start": "node dist/index.js",
+    "lint": "eslint src --ext .ts",
+    "lint:fix": "eslint src --ext .ts --fix",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "test:smoke": "vitest run --config vitest.smoke.config.ts",
+    "test:unit": "vitest run --exclude 'tests/smoke/**/*.test.ts' --exclude 'tests/integration/**/*.test.ts' --exclude 'tests/e2e/**/*.test.ts' --exclude 'tests/benchmark*/**/*.test.ts'",
+    "test:integration": "vitest run tests/integration",
+    "test:e2e": "vitest run tests/e2e",
+    "test:e2e:playwright": "playwright test",
+    "test:e2e:playwright:ui": "playwright test --ui",
+    "test:e2e:playwright:debug": "playwright test --debug",
+    "test:e2e:playwright:headed": "playwright test --headed",
+    "bench": "vitest bench --config vitest.benchmark.config.ts",
+    "bench:json": "vitest bench --config vitest.benchmark.config.ts --reporter=json --outputFile=./benchmark-results/results.json",
+    "generate:tools": "tsx scripts/generate-tool-list.ts",
+    "validate:tools": "tsx scripts/validate-tool-list.ts --ci",
+    "validate:docs": "tsx scripts/validate-tool-list.ts --check-docs",
+    "validate:all": "tsx scripts/validate-tool-list.ts --ci --check-docs",
+    "worker:start": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts",
+    "worker:start:page": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts --page",
+    "worker:start:quality": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts --quality",
+    "check:embeddings": "tsx src/scripts/check-embedding-coverage.ts",
+    "backfill:embeddings": "NODE_OPTIONS='--max-old-space-size=8192 --expose-gc' tsx src/scripts/backfill-embeddings.ts",
+    "clean": "rm -rf dist node_modules .turbo"
+  },
   "dependencies": {
+    "@bull-board/api": "^6.20.6",
+    "@bull-board/express": "^6.20.6",
     "@modelcontextprotocol/sdk": "^1.26.0",
     "@prisma/client": "^6.19.2",
+    "@reftrixmcp/core": "workspace:*",
+    "@reftrixmcp/database": "workspace:*",
+    "@reftrixmcp/ml": "workspace:*",
+    "@reftrixmcp/webdesign-core": "workspace:*",
     "axe-core": "^4.10.2",
     "bullmq": "^5.66.5",
     "culori": "^4.0.2",
     "dompurify": "^3.3.2",
+    "express": "^5.2.1",
     "ioredis": "^5.9.2",
     "jsdom": "^27.2.0",
+    "lru-cache": "^11.2.7",
     "pixelmatch": "^6.0.0",
     "pngjs": "^7.0.0",
     "sharp": "^0.34.5",
     "ws": "^8.18.0",
-    "zod": "^3.24.0",
-    "@reftrixmcp/core": "0.1.7",
-    "@reftrixmcp/database": "0.1.7",
-    "@reftrixmcp/ml": "0.1.7",
-    "@reftrixmcp/webdesign-core": "0.1.7"
+    "zod": "^3.24.0"
   },
   "devDependencies": {
     "@axe-core/playwright": "^4.11.0",
+    "@reftrixmcp/config": "workspace:*",
     "@types/culori": "^4.0.1",
     "@types/dompurify": "^3.2.0",
+    "@types/express": "^5.0.6",
     "@types/jsdom": "^27.0.0",
     "@types/node": "^22.0.0",
     "@types/pixelmatch": "^5.2.6",
@@ -71,9 +107,9 @@
     "playwright": "^1.57.0",
     "tsx": "^4.0.0",
     "typescript": "^5.9.0",
-    "vitest": "^4.0.14",
-    "@reftrixmcp/config": "0.1.7"
+    "vitest": "^4.0.14"
   },
+  "mcpName": "io.github.TKMD/reftrixmcp",
   "repository": {
     "type": "git",
     "url": "https://github.com/TKMD/ReftrixMCP.git",
@@ -82,36 +118,5 @@
   "homepage": "https://github.com/TKMD/ReftrixMCP#readme",
   "bugs": {
     "url": "https://github.com/TKMD/ReftrixMCP/issues"
-  },
-  "scripts": {
-    "build": "tsc",
-    "dev": "NODE_ENV=development tsx watch src/index.ts",
-    "start": "node dist/index.js",
-    "lint": "eslint src --ext .ts",
-    "lint:fix": "eslint src --ext .ts --fix",
-    "typecheck": "tsc --noEmit",
-    "test": "vitest run",
-    "test:watch": "vitest",
-    "test:coverage": "vitest run --coverage",
-    "test:smoke": "vitest run --config vitest.smoke.config.ts",
-    "test:unit": "vitest run --exclude 'tests/smoke/**/*.test.ts' --exclude 'tests/integration/**/*.test.ts' --exclude 'tests/e2e/**/*.test.ts' --exclude 'tests/benchmark*/**/*.test.ts'",
-    "test:integration": "vitest run tests/integration",
-    "test:e2e": "playwright test",
-    "test:e2e:playwright": "playwright test",
-    "test:e2e:playwright:ui": "playwright test --ui",
-    "test:e2e:playwright:debug": "playwright test --debug",
-    "test:e2e:playwright:headed": "playwright test --headed",
-    "bench": "vitest bench --config vitest.benchmark.config.ts",
-    "bench:json": "vitest bench --config vitest.benchmark.config.ts --reporter=json --outputFile=./benchmark-results/results.json",
-    "generate:tools": "tsx scripts/generate-tool-list.ts",
-    "validate:tools": "tsx scripts/validate-tool-list.ts --ci",
-    "validate:docs": "tsx scripts/validate-tool-list.ts --check-docs",
-    "validate:all": "tsx scripts/validate-tool-list.ts --ci --check-docs",
-    "worker:start": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts",
-    "worker:start:page": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts --page",
-    "worker:start:quality": "NODE_ENV=development NODE_OPTIONS='--max-old-space-size=4096' tsx src/scripts/start-workers.ts --quality",
-    "check:embeddings": "tsx src/scripts/check-embedding-coverage.ts",
-    "backfill:embeddings": "NODE_OPTIONS='--max-old-space-size=8192 --expose-gc' tsx src/scripts/backfill-embeddings.ts",
-    "clean": "rm -rf dist node_modules .turbo"
   }
-}
+}

package/src/admin/bull-board.ts

@@ -0,0 +1,177 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * BullMQ Board UI - Job Management Dashboard
+ *
+ * BullMQジョブの状態確認・管理を行うWeb UIを提供する。
+ * Express + @bull-board/express で構築し、Basic Auth認証を必須とする。
+ *
+ * セキュリティ:
+ * - Basic Auth必須（BULLMQ_UI_USER / BULLMQ_UI_PASSWORD 未設定時はUI無効化）
+ * - localhost binding のみ（0.0.0.0 禁止）
+ * - /admin/queues パスで公開
+ *
+ * @module admin/bull-board
+ */
+
+import { timingSafeEqual, createHmac } from "crypto";
+import express, { type Request, type Response, type NextFunction } from "express";
+import { createBullBoard } from "@bull-board/api";
+import { BullMQAdapter } from "@bull-board/api/bullMQAdapter";
+import { ExpressAdapter } from "@bull-board/express";
+import { Queue } from "bullmq";
+import { getRedisConfig } from "../config/redis";
+import { logger } from "../utils/logger";
+import { PAGE_ANALYZE_QUEUE_NAME } from "../queues/page-analyze-queue";
+import type { Server } from "http";
+
+/**
+ * Bull Board UI のデフォルトポート
+ * Port offset: 21000 + 80 = 21080
+ */
+const BULL_BOARD_PORT = 21080;
+
+/**
+ * Bull Board の設定インターフェース
+ */
+export interface BullBoardConfig {
+  /** Basic Auth ユーザー名 */
+  username: string;
+  /** Basic Auth パスワード */
+  password: string;
+  /** ポート番号 (default: 21080) */
+  port?: number;
+}
+
+/**
+ * 環境変数から Bull Board 設定を取得
+ *
+ * @returns 設定オブジェクト、またはnull（認証情報未設定の場合）
+ */
+export function getBullBoardConfig(): BullBoardConfig | null {
+  const username = process.env.BULLMQ_UI_USER;
+  const password = process.env.BULLMQ_UI_PASSWORD;
+
+  if (!username || !password) {
+    return null;
+  }
+
+  return {
+    username,
+    password,
+    port: BULL_BOARD_PORT,
+  };
+}
+
+/**
+ * Basic Auth ミドルウェア
+ *
+ * RFC 7617 に準拠した Basic Authentication を実装。
+ * タイミング攻撃を考慮し、固定時間比較を行う。
+ *
+ * @param username - 期待するユーザー名
+ * @param password - 期待するパスワード
+ */
+function basicAuthMiddleware(
+  username: string,
+  password: string
+): (req: Request, res: Response, next: NextFunction) => void {
+  return (req: Request, res: Response, next: NextFunction): void => {
+    const authHeader = req.headers.authorization;
+
+    if (!authHeader || !authHeader.startsWith("Basic ")) {
+      res.setHeader("WWW-Authenticate", 'Basic realm="BullMQ Board"');
+      res.status(401).send("Authentication required");
+      return;
+    }
+
+    const base64Credentials = authHeader.slice(6);
+    let decoded: string;
+    try {
+      decoded = Buffer.from(base64Credentials, "base64").toString("utf-8");
+    } catch {
+      res.status(401).send("Invalid credentials");
+      return;
+    }
+
+    const separatorIndex = decoded.indexOf(":");
+    if (separatorIndex === -1) {
+      res.status(401).send("Invalid credentials");
+      return;
+    }
+
+    const providedUser = decoded.slice(0, separatorIndex);
+    const providedPass = decoded.slice(separatorIndex + 1);
+
+    // HMAC比較パターンで固定時間比較（長さリーク防止: SEC-T1-H1）
+    // HMAC comparison pattern for constant-time comparison (prevents length leak)
+    const hmacKey = "reftrix-auth-comparison";
+    const hmac = (value: string): Buffer => createHmac("sha256", hmacKey).update(value).digest();
+    const userMatch = timingSafeEqual(hmac(providedUser), hmac(username));
+    const passMatch = timingSafeEqual(hmac(providedPass), hmac(password));
+
+    if (userMatch && passMatch) {
+      next();
+    } else {
+      res.setHeader("WWW-Authenticate", 'Basic realm="BullMQ Board"');
+      res.status(401).send("Invalid credentials");
+    }
+  };
+}
+
+/**
+ * Bull Board UI を起動する
+ *
+ * @param config - Bull Board 設定
+ * @returns HTTP Server インスタンス、またはnull（起動失敗時）
+ */
+export async function startBullBoard(config: BullBoardConfig): Promise<Server | null> {
+  try {
+    const redisConfig = getRedisConfig();
+
+    // Queue インスタンスを作成（UI用、読み取り専用）
+    const pageAnalyzeQueue = new Queue(PAGE_ANALYZE_QUEUE_NAME, {
+      connection: {
+        host: redisConfig.host,
+        port: redisConfig.port,
+        maxRetriesPerRequest: redisConfig.maxRetriesPerRequest,
+      },
+    });
+
+    // Bull Board セットアップ
+    const serverAdapter = new ExpressAdapter();
+    serverAdapter.setBasePath("/admin/queues");
+
+    createBullBoard({
+      queues: [new BullMQAdapter(pageAnalyzeQueue)],
+      serverAdapter,
+    });
+
+    // Express アプリ作成
+    const app = express();
+
+    // Basic Auth を /admin/queues 以下全体に適用
+    app.use("/admin/queues", basicAuthMiddleware(config.username, config.password));
+    app.use("/admin/queues", serverAdapter.getRouter());
+
+    // ルートにリダイレクト
+    app.get("/", (_req: Request, res: Response): void => {
+      res.redirect("/admin/queues");
+    });
+
+    const port = config.port ?? BULL_BOARD_PORT;
+
+    // localhost のみバインド（セキュリティ: 0.0.0.0 禁止）
+    const server = app.listen(port, "127.0.0.1", () => {
+      logger.info(`[BullBoard] UI started at http://127.0.0.1:${port}/admin/queues`);
+    });
+
+    return server;
+  } catch (error: unknown) {
+    logger.error("[BullBoard] Failed to start UI", {
+      error: error instanceof Error ? error.message : String(error),
+    });
+    return null;
+  }
+}

package/src/index.ts

@@ -28,13 +28,15 @@ import {
   isProductionEnvironment,
 } from "./services/production-guard";
 import { embeddingService } from "@reftrixmcp/ml";
-import { prisma } from "@reftrixmcp/database";
+import { prisma, enableHnswIterativeScan } from "@reftrixmcp/database";
 import { webPageService } from "./services/web-page.service";
 import {
   initializeAllServices,
   type ServiceInitializerConfig,
 } from "./services/service-initializer";
 import { getWorkerSupervisor } from "./services/worker-supervisor.service";
+import { getBullBoardConfig, startBullBoard } from "./admin/bull-board";
+import type { Server } from "http";
 
 /**
  * メイン関数
@@ -71,6 +73,11 @@ async function main(): Promise<void> {
 
     logger.info("[Main] Service factories registered via initializeAllServices()");
 
+    // pgvector 0.8 HNSW iterative scan 有効化
+    // Reduces search latency P95 by ~50% with 95-99% result quality
+    await enableHnswIterativeScan(prisma);
+    logger.info("[Main] pgvector HNSW iterative scan enabled (relaxed_order)");
+
     // 本番環境では認証を強制（MCP-AUTH-01）
     // NODE_ENV=production かつ MCP_AUTH_ENABLED!==true の場合、起動を失敗させる
     // 回避オプション: MCP_ALLOW_INSECURE_PRODUCTION=true（非推奨）
@@ -138,6 +145,22 @@ async function main(): Promise<void> {
     logger.info("StdIO transport is ready to accept connections");
     logger.info("MCP Server is ready (StdIO Mode)");
 
+    // =====================================================
+    // BullMQ Board UI（オプション）
+    // =====================================================
+    // BULLMQ_UI_ENABLED=true かつ認証情報設定時のみ起動
+    let bullBoardServer: Server | null = null;
+    if (process.env.BULLMQ_UI_ENABLED === "true") {
+      const bullBoardConfig = getBullBoardConfig();
+      if (bullBoardConfig) {
+        bullBoardServer = await startBullBoard(bullBoardConfig);
+      } else {
+        logger.warn(
+          "[Main] BullMQ UI enabled but BULLMQ_UI_USER/BULLMQ_UI_PASSWORD not set — UI disabled"
+        );
+      }
+    }
+
     // プロセス終了シグナルのハンドリング
     const handleShutdown = async (): Promise<void> => {
       logger.info("Shutting down server...");
@@ -157,6 +180,14 @@ async function main(): Promise<void> {
           });
         }
 
+        // Bull Board UI を停止
+        if (bullBoardServer) {
+          await new Promise<void>((resolve) => {
+            bullBoardServer!.close(() => resolve());
+          });
+          logger.info("BullBoard UI shutdown complete");
+        }
+
         // StdIO Serverを停止
         await server.close();
         logger.info("StdIO transport shutdown complete");

package/src/middleware/auth.ts

@@ -245,6 +245,12 @@ export const TOOL_PERMISSIONS: Record<string, string[]> = {
   "page.analyze": [PERMISSIONS.LAYOUT_READ, PERMISSIONS.MOTION_READ, PERMISSIONS.QUALITY_READ],
   "page.getJobStatus": [PERMISSIONS.LAYOUT_READ],
 
+  // 横断検索系（Unified Search）
+  "search.unified": [PERMISSIONS.LAYOUT_READ],
+
+  // デザイン検索系（Visual Search）
+  "design.search_by_image": [PERMISSIONS.LAYOUT_READ],
+
   // システム系（公開ツール）
   "system.health": [PERMISSIONS.SYSTEM_HEALTH],
 };

package/src/middleware/index.ts

@@ -54,3 +54,16 @@ export {
   clearCoercionMapCache,
   type CoercionMap,
 } from "./args-type-coercion";
+
+export {
+  RateLimiter,
+  getRateLimiter,
+  resetRateLimiter,
+  checkRateLimit,
+  isRateLimitEnabled,
+  DEFAULT_TIER_CONFIGS,
+  TOOL_TIER_MAP,
+  type RateLimitResult,
+  type RateLimitTier,
+  type RateLimitTierConfig,
+} from "./rate-limiter";