@reftrixmcp/mcp-server 0.1.7

package/src/tools/quality/get-job-status.tool.ts

@@ -0,0 +1,344 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * quality.getJobStatus - MCP Tool for checking batch quality evaluation job status
+ *
+ * Phase4: Allows clients to poll for async batch evaluation job status and results.
+ *
+ * Features:
+ * - Returns job state (waiting, active, completed, failed)
+ * - Returns progress percentage (0-100)
+ * - Returns result summary when completed
+ * - Returns error details when failed
+ * - Graceful degradation: Falls back to LRU store when Redis is unavailable
+ *
+ * レスポンス形式:
+ * - 成功: { success: true, data: {...}, metadata: { request_id, ... } }
+ * - エラー: { success: false, error: { code, message }, metadata: { request_id, ... } }
+ *
+ * @module tools/quality/get-job-status.tool
+ */
+
+import { isRedisAvailable } from "../../config/redis";
+import {
+  createBatchQualityQueue,
+  getBatchQualityJobStatus,
+  closeBatchQualityQueue,
+} from "../../queues/batch-quality-queue";
+import {
+  qualityGetJobStatusInputSchema,
+  type QualityGetJobStatusInput,
+  type QualityGetJobStatusOutput,
+  type QualityGetJobStatusData,
+  type QualityJobState,
+} from "./schemas";
+
+// Re-export types for external use
+export type { QualityGetJobStatusInput, QualityGetJobStatusOutput } from "./schemas";
+import { getBatchJob } from "./batch-evaluate.tool";
+import { logger, isDevelopment } from "../../utils/logger";
+import { generateRequestId, createErrorResponseWithRequestId } from "../../utils/mcp-response";
+
+// ============================================================================
+// Constants
+// ============================================================================
+
+/**
+ * Error codes for quality.getJobStatus
+ */
+export const GET_QUALITY_JOB_STATUS_ERROR_CODES = {
+  VALIDATION_ERROR: "VALIDATION_ERROR",
+  REDIS_UNAVAILABLE: "REDIS_UNAVAILABLE",
+  JOB_NOT_FOUND: "JOB_NOT_FOUND",
+  INTERNAL_ERROR: "INTERNAL_ERROR",
+} as const;
+
+// ============================================================================
+// Tool Definition
+// ============================================================================
+
+/**
+ * Tool definition for MCP registration
+ */
+export const qualityGetJobStatusToolDefinition = {
+  name: "quality.getJobStatus",
+  description: `Check the status of an async batch quality evaluation job.
+
+Use this tool to poll for the status and results of a job that was submitted
+with quality.batch_evaluate.
+
+Returns:
+- Job state (waiting, active, completed, failed)
+- Progress percentage (0-100)
+- Item counts (total, processed, success, failed)
+- Result summary when completed
+- Error details when failed
+
+Note: When Redis is unavailable, falls back to LRU store (in-memory).
+Jobs in LRU store are not persisted across server restarts.`,
+  inputSchema: {
+    type: "object" as const,
+    properties: {
+      job_id: {
+        type: "string",
+        format: "uuid",
+        description: "The job ID returned by quality.batch_evaluate",
+      },
+    },
+    required: ["job_id"],
+    additionalProperties: false,
+  },
+  annotations: {
+    title: "Quality Get Job Status",
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+  },
+};
+
+// ============================================================================
+// Helper Functions
+// ============================================================================
+
+/**
+ * Map BullMQ job state to QualityJobState
+ */
+function mapBullMQStateToQualityState(
+  state: "waiting" | "active" | "completed" | "failed" | "delayed" | "unknown"
+): QualityJobState {
+  return state;
+}
+
+/**
+ * Map LRU store status to QualityJobState
+ */
+function mapLRUStatusToQualityState(
+  status: "pending" | "processing" | "completed" | "failed" | "cancelled"
+): QualityJobState {
+  switch (status) {
+    case "pending":
+      return "waiting";
+    case "processing":
+      return "active";
+    case "completed":
+      return "completed";
+    case "failed":
+      return "failed";
+    case "cancelled":
+      return "failed";
+    default:
+      return "unknown";
+  }
+}
+
+// ============================================================================
+// Handler
+// ============================================================================
+
+/**
+ * Handle quality.getJobStatus tool invocation
+ *
+ * @param input - Raw input from MCP
+ * @returns 統一レスポンス形式（success: true/false + data/error + metadata.request_id）
+ */
+export async function qualityGetJobStatusHandler(
+  input: unknown
+): Promise<QualityGetJobStatusOutput> {
+  // router.tsから注入された_request_idを使用、フォールバックとして自動生成
+  const requestId =
+    ((input as Record<string, unknown> | null)?._request_id as string | undefined) ??
+    generateRequestId();
+
+  if (isDevelopment()) {
+    logger.info("[MCP Tool] quality.getJobStatus called", {
+      hasInput: input !== null && input !== undefined,
+      requestId,
+    });
+  }
+
+  // Validate input
+  let validated: QualityGetJobStatusInput;
+  try {
+    validated = qualityGetJobStatusInputSchema.parse(input);
+  } catch (error) {
+    logger.warn("[MCP Tool] quality.getJobStatus validation error", {
+      error: error instanceof Error ? error.message : String(error),
+      requestId,
+    });
+    return createErrorResponseWithRequestId(
+      GET_QUALITY_JOB_STATUS_ERROR_CODES.VALIDATION_ERROR,
+      error instanceof Error ? error.message : "Invalid input",
+      requestId
+    );
+  }
+
+  const jobId = validated.job_id;
+
+  // Check Redis availability
+  const redisAvailable = await isRedisAvailable();
+
+  if (redisAvailable) {
+    // Try BullMQ queue first
+    const queue = createBatchQualityQueue();
+
+    try {
+      const status = await getBatchQualityJobStatus(queue, jobId);
+
+      if (status) {
+        // Job found in BullMQ
+        if (isDevelopment()) {
+          logger.debug("[MCP Tool] quality.getJobStatus job found in BullMQ", {
+            jobId,
+            state: status.state,
+            progress: status.progress,
+            requestId,
+          });
+        }
+
+        const data: QualityGetJobStatusData = {
+          jobId: status.jobId,
+          status: mapBullMQStateToQualityState(status.state),
+          progress: status.progress,
+          totalItems: status.totalItems,
+          processedItems: status.processedItems,
+          successItems: status.successItems,
+          failedItems: status.failedItems,
+          timestamps: status.timestamps,
+        };
+
+        // Add result if completed
+        if (status.state === "completed" && status.result) {
+          data.result = {
+            jobId: status.result.jobId,
+            success: status.result.success,
+            totalItems: status.result.totalItems,
+            processedItems: status.result.processedItems,
+            successItems: status.result.successItems,
+            failedItems: status.result.failedItems,
+            results: status.result.results.map((r) => ({
+              index: r.index,
+              success: r.success,
+              data: r.data,
+              error: r.error,
+            })),
+            processingTimeMs: status.result.processingTimeMs,
+            completedAt: status.result.completedAt,
+            error: status.result.error,
+          };
+        }
+
+        // Add error if failed
+        if (status.state === "failed" && status.error) {
+          data.failedReason = status.error;
+        }
+
+        return {
+          success: true,
+          data,
+          metadata: {
+            request_id: requestId,
+            redis_used: true,
+            lru_fallback: false,
+          },
+        };
+      }
+
+      // Job not found in BullMQ, try LRU store as fallback
+      if (isDevelopment()) {
+        logger.debug("[MCP Tool] quality.getJobStatus job not found in BullMQ, trying LRU store", {
+          jobId,
+          requestId,
+        });
+      }
+    } finally {
+      // Close queue connection
+      await closeBatchQualityQueue(queue);
+    }
+  }
+
+  // Try LRU store (either Redis unavailable or job not found in BullMQ)
+  const lruJob = getBatchJob(jobId);
+
+  if (lruJob) {
+    // Job found in LRU store
+    if (isDevelopment()) {
+      logger.debug("[MCP Tool] quality.getJobStatus job found in LRU store", {
+        jobId,
+        status: lruJob.status,
+        progress: lruJob.progress_percent,
+        requestId,
+      });
+    }
+
+    const data: QualityGetJobStatusData = {
+      jobId: lruJob.job_id,
+      status: mapLRUStatusToQualityState(lruJob.status),
+      progress: lruJob.progress_percent,
+      totalItems: lruJob.total_items,
+      processedItems: lruJob.processed_items,
+      successItems: lruJob.success_items,
+      failedItems: lruJob.failed_items,
+      timestamps: {
+        created: new Date(lruJob.created_at).getTime(),
+        completed: lruJob.completed_at ? new Date(lruJob.completed_at).getTime() : undefined,
+      },
+    };
+
+    // Add result if completed
+    if (lruJob.status === "completed" && lruJob.results) {
+      data.result = {
+        jobId: lruJob.job_id,
+        success: lruJob.failed_items === 0,
+        totalItems: lruJob.total_items,
+        processedItems: lruJob.processed_items,
+        successItems: lruJob.success_items,
+        failedItems: lruJob.failed_items,
+        results: lruJob.results.map((r, index) => ({
+          index,
+          success: true,
+          data: r,
+        })),
+        completedAt: lruJob.completed_at,
+      };
+
+      // Add errors if any
+      if (lruJob.errors && lruJob.errors.length > 0) {
+        data.result.results = [
+          ...(data.result.results ?? []),
+          ...lruJob.errors.map((e) => ({
+            index: e.index,
+            success: false,
+            error: e.error,
+          })),
+        ].sort((a, b) => a.index - b.index);
+      }
+    }
+
+    // Add error if failed
+    if (lruJob.status === "failed" && lruJob.errors && lruJob.errors.length > 0) {
+      data.failedReason = lruJob.errors[0]?.error?.message ?? "Unknown error";
+    }
+
+    return {
+      success: true,
+      data,
+      metadata: {
+        request_id: requestId,
+        redis_used: false,
+        lru_fallback: true,
+      },
+    };
+  }
+
+  // Job not found in either BullMQ or LRU store
+  if (isDevelopment()) {
+    logger.debug("[MCP Tool] quality.getJobStatus job not found", { jobId, requestId });
+  }
+
+  return createErrorResponseWithRequestId(
+    GET_QUALITY_JOB_STATUS_ERROR_CODES.JOB_NOT_FOUND,
+    `Job with ID ${jobId} not found. It may have expired (jobs are retained for 24 hours) or never existed.`,
+    requestId
+  );
+}

package/src/tools/quality/improvement-utils.ts

@@ -0,0 +1,361 @@
+// SPDX-FileCopyrightText: 2026 TKMD and Reftrix Contributors
+// SPDX-License-Identifier: AGPL-3.0-only
+
+/**
+ * 品質改善提案ユーティリティ
+ *
+ * quality.evaluateのaction: "suggest_improvements"で使用される
+ * 改善提案生成ロジックを提供します。
+ *
+ * @module tools/quality/improvement-utils
+ */
+
+import {
+  type Improvement,
+  type ImprovementSummary,
+  type ImprovementCategory,
+  type RecommendationPriority,
+  type QualityEvaluateData,
+} from "./schemas";
+
+// =====================================================
+// 定数
+// =====================================================
+
+/**
+ * 代替グラデーションカラー（AI典型を回避）
+ */
+const ALTERNATIVE_GRADIENTS = [
+  { from: "#3B82F6", to: "#8B5CF6", name: "Blue to Purple" },
+  { from: "#10B981", to: "#3B82F6", name: "Green to Blue" },
+  { from: "#F59E0B", to: "#EF4444", name: "Amber to Red" },
+  { from: "#6366F1", to: "#EC4899", name: "Indigo to Pink" },
+  { from: "#14B8A6", to: "#8B5CF6", name: "Teal to Purple" },
+];
+
+/**
+ * AI典型フレーズの代替
+ */
+const TEXT_ALTERNATIVES: Record<string, string[]> = {
+  "transform your business": [
+    "Streamline your workflow",
+    "Elevate your operations",
+    "Modernize your approach",
+  ],
+  "unlock the power": ["Discover the potential", "Harness the capability", "Leverage the strength"],
+  "cutting-edge solutions": ["Practical solutions", "Effective tools", "Modern approaches"],
+  "seamless integration": ["Easy setup", "Quick connection", "Smooth workflow"],
+  "get started today": ["Begin now", "Start your journey", "Try it free"],
+  "scale effortlessly": ["Grow with confidence", "Expand smoothly", "Scale as you need"],
+};
+
+// =====================================================
+// ヘルパー関数
+// =====================================================
+
+/**
+ * グラデーションクリシェの改善を生成
+ */
+function generateGradientImprovement(
+  html: string,
+  pattern: { description: string; severity: string }
+): Improvement | null {
+  // AI典型グラデーションを検出
+  const gradientMatch = html.match(
+    /(?:background(?:-image)?:\s*)?linear-gradient\s*\([^)]*(?:#667eea|#764ba2|#f857a6|#ff5858)[^)]*\)/i
+  );
+
+  if (!gradientMatch) return null;
+
+  const alternative =
+    ALTERNATIVE_GRADIENTS[Math.floor(Math.random() * ALTERNATIVE_GRADIENTS.length)];
+  if (!alternative) return null;
+
+  return {
+    id: `imp-gradient-${Date.now()}`,
+    category: "originality",
+    priority: pattern.severity as RecommendationPriority,
+    title: "グラデーションカラーを変更",
+    description: `${pattern.description}を独自カラーに変更します。`,
+    originalCode: gradientMatch[0],
+    suggestedCode: `background: linear-gradient(to right, ${alternative.from}, ${alternative.to}); /* ${alternative.name} */`,
+    impact: pattern.severity === "high" ? 15 : 10,
+  };
+}
+
+/**
+ * テキストクリシェの改善を生成
+ */
+function generateTextImprovement(
+  html: string,
+  pattern: { description: string; severity: string }
+): Improvement | null {
+  // パターンからフレーズを抽出
+  const phraseMatch = pattern.description.match(/"([^"]+)"/);
+  const phraseOriginal = phraseMatch?.[1];
+  if (!phraseOriginal) return null;
+
+  const phrase = phraseOriginal.toLowerCase();
+  const alternatives = TEXT_ALTERNATIVES[phrase];
+
+  if (!alternatives || alternatives.length === 0) return null;
+
+  // HTMLからフレーズを検索
+  const regex = new RegExp(phrase.replace(/\s+/g, "\\s+"), "i");
+  const match = html.match(regex);
+
+  if (!match) return null;
+
+  const alternative = alternatives[Math.floor(Math.random() * alternatives.length)];
+  if (!alternative) return null;
+
+  return {
+    id: `imp-text-${Date.now()}`,
+    category: "originality",
+    priority: pattern.severity as RecommendationPriority,
+    title: "AI典型フレーズを変更",
+    description: `"${phraseOriginal}"をより独自性のある表現に変更します。`,
+    originalCode: match[0],
+    suggestedCode: alternative,
+    impact: pattern.severity === "high" ? 12 : 8,
+  };
+}
+
+/**
+ * アクセシビリティ改善を生成（alt属性）
+ */
+function generateAltImprovement(html: string): Improvement | null {
+  // alt属性のない画像を検出
+  const imgWithoutAlt = html.match(/<img(?![^>]*alt=)[^>]*>/i);
+
+  if (!imgWithoutAlt) return null;
+
+  // src属性を取得してファイル名を推測
+  const srcMatch = imgWithoutAlt[0].match(/src="([^"]+)"/i);
+  const srcValue = srcMatch?.[1];
+  const baseFilename = srcValue
+    ?.split("/")
+    .pop()
+    ?.replace(/\.[^.]+$/, "");
+  const filename = baseFilename && baseFilename.length > 0 ? baseFilename : "image";
+  const altText = filename.replace(/[-_]/g, " ") || "Descriptive text here";
+
+  return {
+    id: `imp-alt-${Date.now()}`,
+    category: "accessibility",
+    priority: "high",
+    title: "画像にalt属性を追加",
+    description: "スクリーンリーダー用に代替テキストを追加します。",
+    originalCode: imgWithoutAlt[0],
+    suggestedCode: imgWithoutAlt[0].replace(/<img/, `<img alt="${altText}"`),
+    impact: 10,
+  };
+}
+
+/**
+ * セマンティックHTML改善を生成
+ */
+function generateSemanticImprovement(html: string): Improvement | null {
+  // div.header, div.main, div.footer などを検出
+  const headerDiv = html.match(/<div[^>]*class="[^"]*header[^"]*"[^>]*>/i);
+  const mainDiv = html.match(/<div[^>]*class="[^"]*(?:main|content)[^"]*"[^>]*>/i);
+  const footerDiv = html.match(/<div[^>]*class="[^"]*footer[^"]*"[^>]*>/i);
+
+  if (!headerDiv && !mainDiv && !footerDiv) return null;
+
+  const improvements: string[] = [];
+  let originalCode = "";
+  let suggestedCode = "";
+
+  if (headerDiv) {
+    originalCode = headerDiv[0];
+    suggestedCode = headerDiv[0]
+      .replace(/<div/, "<header")
+      .replace(/class="([^"]*)"/, 'class="$1" role="banner"');
+    improvements.push("headerタグに変更");
+  } else if (mainDiv) {
+    originalCode = mainDiv[0];
+    suggestedCode = mainDiv[0]
+      .replace(/<div/, "<main")
+      .replace(/class="([^"]*)"/, 'class="$1" role="main"');
+    improvements.push("mainタグに変更");
+  } else if (footerDiv) {
+    originalCode = footerDiv[0];
+    suggestedCode = footerDiv[0]
+      .replace(/<div/, "<footer")
+      .replace(/class="([^"]*)"/, 'class="$1" role="contentinfo"');
+    improvements.push("footerタグに変更");
+  }
+
+  return {
+    id: `imp-semantic-${Date.now()}`,
+    category: "craftsmanship",
+    priority: "medium",
+    title: "セマンティックHTMLに変換",
+    description: `divタグを適切なセマンティックタグに変換します（${improvements.join(", ")}）。`,
+    originalCode,
+    suggestedCode,
+    impact: 8,
+  };
+}
+
+/**
+ * インラインイベントハンドラの改善を生成
+ */
+function generateEventHandlerImprovement(html: string): Improvement | null {
+  const onclickMatch = html.match(/<[^>]+onclick="([^"]+)"[^>]*>/i);
+
+  if (!onclickMatch) return null;
+
+  const elementMatch = onclickMatch[0].match(/<(\w+)/);
+  const elementType = elementMatch ? elementMatch[1] : "element";
+  const handler = onclickMatch[1];
+
+  return {
+    id: `imp-event-${Date.now()}`,
+    category: "craftsmanship",
+    priority: "medium",
+    title: "インラインイベントハンドラを削除",
+    description: "onclick属性の代わりにaddEventListenerを使用します。",
+    originalCode: onclickMatch[0],
+    suggestedCode: `<!-- HTMLから削除 -->
+<${elementType} id="myElement">...</${elementType}>
+
+<!-- JavaScriptで追加 -->
+<script>
+  document.getElementById('myElement').addEventListener('click', () => {
+    ${handler}
+  });
+</script>`,
+    impact: 6,
+  };
+}
+
+/**
+ * ピル型ボタンの改善を生成
+ */
+function generateButtonStyleImprovement(html: string): Improvement | null {
+  const pillButtonMatch = html.match(/border-radius:\s*9999px/i);
+
+  if (!pillButtonMatch) return null;
+
+  return {
+    id: `imp-button-${Date.now()}`,
+    category: "originality",
+    priority: "low",
+    title: "ボタンスタイルを調整",
+    description: "AI典型のピル型ボタンからより特徴的なスタイルに変更します。",
+    originalCode: "border-radius: 9999px;",
+    suggestedCode: `border-radius: 8px; /* またはブランドに合わせたカスタム値 */
+/* 例: border-radius: 0; で角ばったスタイル */
+/* 例: border-radius: 4px 12px; で非対称スタイル */`,
+    impact: 5,
+  };
+}
+
+// =====================================================
+// パブリック関数
+// =====================================================
+
+/**
+ * 評価結果から改善提案を生成
+ * @public quality.evaluate の action: "suggest_improvements" から使用
+ */
+export function generateImprovements(
+  evaluation: QualityEvaluateData,
+  html: string,
+  options: {
+    categories?: ImprovementCategory[] | undefined;
+    minPriority?: RecommendationPriority | undefined;
+    maxSuggestions: number;
+  }
+): Improvement[] {
+  const improvements: Improvement[] = [];
+
+  // クリシェパターンから改善を生成
+  if (evaluation.clicheDetection?.patterns) {
+    for (const pattern of evaluation.clicheDetection.patterns) {
+      if (pattern.type === "gradient") {
+        const imp = generateGradientImprovement(html, pattern);
+        if (imp) improvements.push(imp);
+      } else if (pattern.type === "text") {
+        const imp = generateTextImprovement(html, pattern);
+        if (imp) improvements.push(imp);
+      } else if (pattern.type === "button") {
+        const imp = generateButtonStyleImprovement(html);
+        if (imp) improvements.push(imp);
+      }
+    }
+  }
+
+  // アクセシビリティ改善
+  const altImp = generateAltImprovement(html);
+  if (altImp) improvements.push(altImp);
+
+  // セマンティックHTML改善
+  const semanticImp = generateSemanticImprovement(html);
+  if (semanticImp) improvements.push(semanticImp);
+
+  // イベントハンドラ改善
+  const eventImp = generateEventHandlerImprovement(html);
+  if (eventImp) improvements.push(eventImp);
+
+  // カテゴリフィルタ
+  let filtered = improvements;
+  const categories = options.categories;
+  if (categories && categories.length > 0) {
+    filtered = filtered.filter((imp) => categories.includes(imp.category));
+  }
+
+  // 優先度フィルタ
+  if (options.minPriority) {
+    const priorityOrder: Record<RecommendationPriority, number> = {
+      high: 0,
+      medium: 1,
+      low: 2,
+    };
+    const minPriorityLevel = priorityOrder[options.minPriority];
+    filtered = filtered.filter((imp) => priorityOrder[imp.priority] <= minPriorityLevel);
+  }
+
+  // 優先度でソート
+  const priorityOrder: Record<RecommendationPriority, number> = {
+    high: 0,
+    medium: 1,
+    low: 2,
+  };
+  filtered.sort((a, b) => priorityOrder[a.priority] - priorityOrder[b.priority]);
+
+  // 最大数に制限
+  return filtered.slice(0, options.maxSuggestions);
+}
+
+/**
+ * サマリーを計算
+ * @public quality.evaluate の action: "suggest_improvements" から使用
+ */
+export function calculateSummary(improvements: Improvement[]): ImprovementSummary {
+  const categoryCounts: ImprovementSummary["categoryCounts"] = {
+    originality: 0,
+    craftsmanship: 0,
+    contextuality: 0,
+    accessibility: 0,
+    performance: 0,
+    general: 0,
+  };
+
+  let totalImpact = 0;
+
+  for (const imp of improvements) {
+    if (categoryCounts[imp.category] !== undefined) {
+      categoryCounts[imp.category]!++;
+    }
+    totalImpact += imp.impact ?? 0;
+  }
+
+  return {
+    totalImprovements: improvements.length,
+    estimatedScoreGain: Math.min(totalImpact, 100),
+    categoryCounts,
+  };
+}