@reftrixmcp/mcp-server 0.1.7

package/src/services/vision/mcp-progress-adapter.ts

@@ -0,0 +1,221 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * MCPProgressAdapter - MCP notifications/progress 統合
+ *
+ * Vision CPU完走保証 Phase 4: MCPツール進捗コールバック対応
+ *
+ * ProgressReporterの進捗イベントをMCP SDK の sendNotification を通じて
+ * notifications/progress として送信するアダプター。
+ *
+ * MCP Protocol Specification:
+ * - method: 'notifications/progress'
+ * - params: { progressToken, progress, total?, message? }
+ *
+ * @see https://spec.modelcontextprotocol.io/specification/basic/utilities/progress/
+ * @see apps/mcp-server/src/services/vision/progress-reporter.ts
+ */
+
+import type { ProgressEvent, ProgressCallback } from "./progress-reporter.js";
+import { logger } from "../../utils/logger";
+
+// =============================================================================
+// 型定義
+// =============================================================================
+
+/**
+ * MCP Progress Notification 型
+ *
+ * MCP SDK の ProgressNotificationSchema に準拠
+ */
+export interface MCPProgressNotification {
+  method: "notifications/progress";
+  params: {
+    /** クライアントから提供された進捗トークン */
+    progressToken: string | number;
+    /** 現在の進捗値 */
+    progress: number;
+    /** 合計値（オプション、デフォルト100） */
+    total?: number;
+    /** 進捗メッセージ（オプション） */
+    message?: string;
+  };
+}
+
+/**
+ * sendNotification 関数型
+ *
+ * MCP SDK の RequestHandlerExtra.sendNotification に準拠
+ */
+export type SendNotificationFn = (notification: MCPProgressNotification) => Promise<void>;
+
+/**
+ * MCPProgressAdapter オプション
+ */
+export interface MCPProgressOptions {
+  /** MCP クライアントから提供された progressToken */
+  progressToken: string | number | undefined;
+  /** MCP SDK の sendNotification 関数 */
+  sendNotification: SendNotificationFn | undefined;
+  /** ログ出力を有効にするか（デフォルト: false） */
+  enableLogging?: boolean;
+}
+
+// =============================================================================
+// MCPProgressAdapter クラス
+// =============================================================================
+
+/**
+ * MCP Progress Notification アダプター
+ *
+ * ProgressReporter の進捗イベントを MCP の notifications/progress に変換して送信。
+ *
+ * @example
+ * ```typescript
+ * const adapter = new MCPProgressAdapter({
+ *   progressToken: request._meta?.progressToken,
+ *   sendNotification: extra.sendNotification,
+ * });
+ *
+ * const reporter = new ProgressReporter({
+ *   onProgress: (event) => adapter.sendProgress(event),
+ * });
+ * ```
+ */
+export class MCPProgressAdapter {
+  private readonly progressToken: string | number;
+  private readonly sendNotification: SendNotificationFn;
+  private readonly enableLogging: boolean;
+
+  /**
+   * MCPProgressAdapter のコンストラクタ
+   *
+   * @param options - アダプターオプション
+   * @throws Error - progressToken または sendNotification が未定義の場合
+   */
+  constructor(options: MCPProgressOptions) {
+    if (options.progressToken === undefined) {
+      throw new Error("progressToken is required");
+    }
+    if (options.sendNotification === undefined) {
+      throw new Error("sendNotification is required");
+    }
+
+    this.progressToken = options.progressToken;
+    this.sendNotification = options.sendNotification;
+    this.enableLogging = options.enableLogging ?? false;
+  }
+
+  /**
+   * progressToken を取得
+   *
+   * @returns progressToken
+   */
+  getProgressToken(): string | number {
+    return this.progressToken;
+  }
+
+  /**
+   * アダプターが有効かどうか
+   *
+   * @returns 常に true（コンストラクタで検証済み）
+   */
+  isEnabled(): boolean {
+    return true;
+  }
+
+  /**
+   * 進捗を MCP notifications/progress として送信
+   *
+   * @param event - ProgressReporter からの進捗イベント
+   */
+  async sendProgress(event: ProgressEvent): Promise<void> {
+    try {
+      // 進捗値をクランプ（0-100）
+      const clampedProgress = Math.max(0, Math.min(100, event.progress));
+
+      // メッセージを構築（phase情報を含める）
+      const message = this.buildMessage(event);
+
+      const notification: MCPProgressNotification = {
+        method: "notifications/progress",
+        params: {
+          progressToken: this.progressToken,
+          progress: clampedProgress,
+          total: 100,
+          message,
+        },
+      };
+
+      await this.sendNotification(notification);
+
+      if (this.enableLogging) {
+        logger.info(`[MCPProgressAdapter] Sent progress: ${clampedProgress}% - ${message}`);
+      }
+    } catch (error) {
+      // Graceful Degradation: 進捗送信失敗はエラーとして扱わない
+      if (this.enableLogging) {
+        console.warn("[MCPProgressAdapter] Failed to send progress notification:", error);
+      }
+    }
+  }
+
+  /**
+   * 進捗メッセージを構築
+   *
+   * @param event - 進捗イベント
+   * @returns フォーマットされたメッセージ
+   */
+  private buildMessage(event: ProgressEvent): string {
+    const { phase, message } = event;
+
+    // メッセージに既にphase情報が含まれている場合はそのまま返す
+    if (message.toLowerCase().includes(phase)) {
+      return message;
+    }
+
+    // phase情報を含める
+    return `[${phase}] ${message}`;
+  }
+}
+
+// =============================================================================
+// ファクトリ関数
+// =============================================================================
+
+/**
+ * ProgressReporter 用の MCP Progress Callback を作成
+ *
+ * progressToken または sendNotification が未定義の場合は null を返す。
+ * これにより、進捗報告が利用不可の場合でも処理を続行できる（Graceful Degradation）。
+ *
+ * @param options - MCPProgressOptions
+ * @returns ProgressCallback または null
+ *
+ * @example
+ * ```typescript
+ * const progressCallback = createMCPProgressCallback({
+ *   progressToken: request._meta?.progressToken,
+ *   sendNotification: extra.sendNotification,
+ * });
+ *
+ * const reporter = new ProgressReporter({
+ *   onProgress: progressCallback ?? undefined,
+ * });
+ * ```
+ */
+export function createMCPProgressCallback(options: MCPProgressOptions): ProgressCallback | null {
+  // progressToken または sendNotification が未定義の場合は null を返す
+  if (options.progressToken === undefined || options.sendNotification === undefined) {
+    return null;
+  }
+
+  const adapter = new MCPProgressAdapter(options);
+
+  // 非同期処理を同期的に呼び出すラッパー（fire-and-forget）
+  return (event: ProgressEvent): void => {
+    // エラーは内部でハンドリングされるため、void として呼び出し
+    void adapter.sendProgress(event);
+  };
+}

package/src/services/vision/mood.analyzer.ts

@@ -0,0 +1,332 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * MoodAnalyzer - Vision AIによるムード分析サービス
+ *
+ * Phase 5: スクリーンショットからムード（雰囲気）を抽出
+ *
+ * 機能:
+ * - Base64スクリーンショットからmood（雰囲気）を抽出
+ * - primary/secondary mood検出
+ * - confidence スコア検証（0.6以上が有効）
+ * - Ollama未接続時のgraceful degradation
+ * - LRUキャッシュ検証
+ * - セキュリティ検証（サイズ制限、入力バリデーション）
+ *
+ * Phase 5 REFACTOR:
+ * - OllamaVisionClientを使用してAPIロジック統合
+ * - VisionAnalysisErrorを使用してエラーハンドリング統一
+ * - vision.promptsからプロンプトを取得
+ *
+ * 参照:
+ * -  (page.analyze visualFeatures)
+ * - apps/mcp-server/src/services/vision-adapter/interface.ts
+ */
+
+import { logger } from "../../utils/logger";
+import { z } from "zod";
+import { VisionCache } from "./vision.cache.js";
+import { OllamaVisionClient } from "./ollama-vision-client.js";
+import { VisionAnalysisError } from "./vision.errors.js";
+import { getMoodAnalysisPrompt, getMoodAnalysisWithContextPrompt } from "./vision.prompts.js";
+
+// =============================================================================
+// 定数
+// =============================================================================
+
+/**
+ * 有効なMoodタイプ一覧
+ */
+export const VALID_MOODS = [
+  "professional",
+  "playful",
+  "minimal",
+  "bold",
+  "elegant",
+  "modern",
+  "classic",
+  "energetic",
+  "calm",
+  "luxurious",
+] as const;
+
+/**
+ * 入力サイズ制限（5MB）
+ */
+const MAX_INPUT_SIZE_BYTES = 5 * 1024 * 1024;
+
+/**
+ * デフォルトタイムアウト（30秒）
+ */
+const DEFAULT_TIMEOUT_MS = 30000;
+
+/**
+ * 最小信頼度閾値
+ */
+const MIN_CONFIDENCE_THRESHOLD = 0.6;
+
+// =============================================================================
+// 型定義
+// =============================================================================
+
+export type MoodType = (typeof VALID_MOODS)[number];
+
+/**
+ * Mood分析結果
+ */
+export interface MoodAnalysisResult {
+  primaryMood: MoodType;
+  secondaryMood?: MoodType | undefined;
+  confidence: number;
+  indicators: string[];
+  colorContextUsed: boolean;
+}
+
+/**
+ * カラーコンテキスト（オプション）
+ */
+export interface ColorContext {
+  dominantColors: string[];
+  theme: "light" | "dark";
+  contentDensity: number;
+}
+
+/**
+ * MoodAnalyzer設定
+ */
+export interface MoodAnalyzerConfig {
+  ollamaUrl?: string;
+  timeout?: number;
+  cacheCapacity?: number;
+  cacheTTL?: number;
+  /** リトライを有効化（デフォルト: true） */
+  enableRetry?: boolean;
+}
+
+// =============================================================================
+// Zodスキーマ
+// =============================================================================
+
+const MoodAnalysisResultSchema = z.object({
+  primaryMood: z.enum(VALID_MOODS),
+  secondaryMood: z.enum(VALID_MOODS).optional(),
+  confidence: z.number().min(0).max(1),
+  indicators: z.array(z.string()),
+  colorContextUsed: z.boolean(),
+});
+
+// =============================================================================
+// MoodAnalyzer クラス
+// =============================================================================
+
+export class MoodAnalyzer {
+  private readonly cache: VisionCache<string, MoodAnalysisResult>;
+  private readonly client: OllamaVisionClient;
+
+  constructor(config?: MoodAnalyzerConfig) {
+    this.cache = new VisionCache<string, MoodAnalysisResult>({
+      capacity: config?.cacheCapacity ?? 100,
+      ttlMs: config?.cacheTTL ?? 5 * 60 * 1000, // 5分
+    });
+    this.client = new OllamaVisionClient({
+      ollamaUrl: config?.ollamaUrl,
+      timeout: config?.timeout ?? DEFAULT_TIMEOUT_MS,
+      enableRetry: config?.enableRetry ?? true,
+    });
+  }
+
+  // ===========================================================================
+  // パブリックメソッド
+  // ===========================================================================
+
+  /**
+   * スクリーンショットからムードを分析
+   *
+   * @param screenshot - Base64エンコードされたスクリーンショット
+   * @returns Mood分析結果、または信頼度が低い/エラー時はnull
+   * @throws Error - 入力が無効な場合
+   */
+  async analyze(screenshot: string): Promise<MoodAnalysisResult | null> {
+    // 入力バリデーション
+    this.validateInput(screenshot);
+
+    // キャッシュチェック
+    const cacheKey = VisionCache.generateKey(screenshot);
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      // Ollama API呼び出し（OllamaVisionClient経由）
+      logger.info("[MoodAnalyzer] Ollama API call started");
+      const prompt = getMoodAnalysisPrompt();
+      const rawResult = await this.client.generateJSON<unknown>(screenshot, prompt);
+
+      // 結果のバリデーション
+      const result = this.validateAndSanitizeResult(rawResult);
+      if (!result) {
+        return null;
+      }
+
+      // 信頼度チェック
+      if (result.confidence < MIN_CONFIDENCE_THRESHOLD) {
+        return null;
+      }
+
+      // キャッシュに保存
+      this.cache.set(cacheKey, result);
+
+      return result;
+    } catch (error) {
+      // Graceful degradation: エラー時はnullを返す
+      if (process.env.NODE_ENV === "development") {
+        console.error("[MoodAnalyzer] Error:", error);
+      }
+      return null;
+    }
+  }
+
+  /**
+   * カラーコンテキスト付きでスクリーンショットからムードを分析
+   *
+   * @param screenshot - Base64エンコードされたスクリーンショット
+   * @param colorContext - カラーコンテキスト情報
+   * @returns Mood分析結果、または信頼度が低い/エラー時はnull
+   * @throws Error - 入力が無効な場合
+   */
+  async analyzeWithContext(
+    screenshot: string,
+    colorContext: ColorContext
+  ): Promise<MoodAnalysisResult | null> {
+    // 入力バリデーション
+    this.validateInput(screenshot);
+
+    // キャッシュキーにカラーコンテキストを含める
+    const cacheKey = VisionCache.generateKey(screenshot + JSON.stringify(colorContext));
+    const cached = this.cache.get(cacheKey);
+    if (cached) {
+      return cached;
+    }
+
+    try {
+      // Ollama API呼び出し（OllamaVisionClient経由）
+      logger.info("[MoodAnalyzer] Ollama API call started");
+      const prompt = getMoodAnalysisWithContextPrompt(colorContext);
+      const rawResult = await this.client.generateJSON<unknown>(screenshot, prompt);
+
+      // 結果のバリデーション
+      const result = this.validateAndSanitizeResult(rawResult);
+      if (!result) {
+        return null;
+      }
+
+      // 信頼度チェック
+      if (result.confidence < MIN_CONFIDENCE_THRESHOLD) {
+        return null;
+      }
+
+      // キャッシュに保存
+      this.cache.set(cacheKey, result);
+
+      return result;
+    } catch (error) {
+      // Graceful degradation: エラー時はnullを返す
+      if (process.env.NODE_ENV === "development") {
+        console.error("[MoodAnalyzer] Error:", error);
+      }
+      return null;
+    }
+  }
+
+  // ===========================================================================
+  // プライベートメソッド
+  // ===========================================================================
+
+  /**
+   * 入力バリデーション
+   * @throws VisionAnalysisError - 入力が無効な場合
+   */
+  private validateInput(screenshot: string): void {
+    // 空チェック
+    if (!screenshot || screenshot.length === 0) {
+      throw new VisionAnalysisError("Screenshot is required", "INPUT_VALIDATION", false);
+    }
+
+    // Base64バリデーション
+    if (!this.isValidBase64(screenshot)) {
+      throw new VisionAnalysisError("Invalid Base64 input", "INPUT_VALIDATION", false);
+    }
+
+    // サイズチェック
+    const sizeBytes = Buffer.byteLength(screenshot, "base64");
+    if (sizeBytes > MAX_INPUT_SIZE_BYTES) {
+      throw new VisionAnalysisError("Input exceeds 5MB limit", "INPUT_VALIDATION", false, {
+        sizeBytes,
+        maxSizeBytes: MAX_INPUT_SIZE_BYTES,
+      });
+    }
+  }
+
+  /**
+   * Base64文字列の検証
+   */
+  private isValidBase64(str: string): boolean {
+    // Base64正規表現パターン
+    const base64Regex = /^[A-Za-z0-9+/]*={0,2}$/;
+    if (!base64Regex.test(str)) {
+      return false;
+    }
+
+    try {
+      // 実際にデコードして検証
+      Buffer.from(str, "base64");
+      return true;
+    } catch {
+      return false;
+    }
+  }
+
+  /**
+   * 結果のバリデーションとサニタイズ
+   */
+  private validateAndSanitizeResult(rawResult: unknown): MoodAnalysisResult | null {
+    // 型チェック
+    if (typeof rawResult !== "object" || rawResult === null) {
+      return null;
+    }
+
+    // Zodでバリデーション
+    const parseResult = MoodAnalysisResultSchema.safeParse(rawResult);
+    if (!parseResult.success) {
+      if (process.env.NODE_ENV === "development") {
+        console.warn("[MoodAnalyzer] Validation failed:", parseResult.error);
+      }
+      return null;
+    }
+
+    const result = parseResult.data;
+
+    // indicatorsのサニタイズ
+    const sanitizedIndicators = result.indicators.map((indicator) =>
+      this.sanitizeString(indicator)
+    );
+
+    return {
+      ...result,
+      indicators: sanitizedIndicators,
+    };
+  }
+
+  /**
+   * 文字列のサニタイズ（XSS対策）
+   */
+  private sanitizeString(str: string): string {
+    return str
+      .replace(/<[^>]*>/g, "") // HTMLタグ除去
+      .replace(/[<>"'&]/g, "") // 特殊文字除去
+      .trim()
+      .slice(0, 200); // 長さ制限
+  }
+}