mcp-relight-harmonize 1.0.1 → 1.0.3

package/dist/server.js

@@ -7,11 +7,46 @@ const analyze_optical_1 = require("./tools/analyze_optical");
 const generate_relight_1 = require("./tools/generate_relight");
 const harmonize_1 = require("./tools/harmonize");
 const synthesize_prompt_1 = require("./tools/synthesize_prompt");
+const list_cache_1 = require("./tools/list_cache");
 const presets_1 = require("./resources/presets");
+// Common output envelope schema definition
+const StandardEnvelopeSchema = {
+    type: "object",
+    properties: {
+        status: { type: "string", enum: ["success", "partial", "blocked", "failed"], description: "Execution status." },
+        summary: { type: "string", description: "Human-readable executive summary of the operation." },
+        data: { type: "object", description: "Typed domain payload." },
+        warnings: { type: "array", items: { type: "string" }, description: "Non-fatal warnings if applicable." },
+        evidence: {
+            type: "object",
+            properties: {
+                inputsDigest: { type: "string", description: "SHA-256 digest of input parameters." },
+                sources: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: { label: { type: "string" }, uri: { type: "string" } },
+                        required: ["label"],
+                    },
+                },
+                artifacts: {
+                    type: "array",
+                    items: {
+                        type: "object",
+                        properties: { label: { type: "string" }, uri: { type: "string" } },
+                        required: ["label"],
+                    },
+                },
+            },
+        },
+        nextActions: { type: "array", items: { type: "string" }, description: "Actionable follow-up guidance." },
+    },
+    required: ["status", "summary", "data", "warnings", "evidence", "nextActions"],
+};
 function createServer() {
     const server = new index_js_1.Server({
         name: "mcp-relight-harmonize",
-        version: "1.0.0",
+        version: "1.0.3",
     }, {
         capabilities: {
             tools: {},
@@ -24,94 +59,332 @@ function createServer() {
             tools: [
                 {
                     name: "analyze_optical_profile",
-                    description: "Extract physical optical metrics from an image: Correlated Color Temperature (CCT in Kelvin), " +
-                        "dominant light vectors, azimuth & elevation angles, luminance dynamic range, and surface roughness.",
+                    description: "Extract physical optical metrics from an image, including Correlated Color Temperature (CCT in Kelvin), " +
+                        "dominant 3D lighting vector (azimuth and elevation angles), photometric luminance dynamic range, contrast zones, " +
+                        "surface normal roughness index, and optionally decompose into 6 analytical image layers in Layers/ directory.\n\n" +
+                        "• Purpose: Diagnostic optical extraction and 6-layer decomposition (Highlights, Shadows, Ambient Occlusion, Edges, Depth Normals, Chroma/Saturation). " +
+                        "Unlike 'generate_relight_variations' which creates artistic relit renders, this tool extracts physical diagnostic metrics and visual analytical decomposition layers.\n" +
+                        "• Behavior: Read-only by default; writes 6 analytical layer PNGs and Layer.md to the specified directory when 'extract_layers' is true. Unmetered local execution, zero network egress, zero external auth.\n" +
+                        "• When to use: Use as the prerequisite first step to inspect baseline lighting conditions or generate the 6 diagnostic layers into Layers/ before relighting or prompting.\n" +
+                        "• When NOT to use: Do NOT use if you need creative relighted styles (use 'generate_relight_variations'), if merging a cutout into a scene " +
+                        "(use 'harmonize_composite'), or if you only need generative AI prompt synthesis (use 'synthesize_diffusion_prompt').\n" +
+                        "• Alternatives: Use 'generate_relight_variations' for creative lighting styles, or 'synthesize_diffusion_prompt' for model prompts.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             image_path: {
                                 type: "string",
-                                description: "Absolute or workspace-relative path to the image file.",
+                                description: "Absolute or workspace-relative path to a local image file (.png, .jpg, or .jpeg). " +
+                                    "Must be an existing image under 50 MB.",
+                            },
+                            extract_layers: {
+                                type: "boolean",
+                                description: "If true, decomposes image into 6 analytical layers (Highlights, Shadows, Ambient Occlusion, Edges, Depth Normals, Chroma/Saturation) saved to Layers/ directory and generates Layer.md.",
+                            },
+                            layers_dir: {
+                                type: "string",
+                                description: "Optional target directory to store the 6 analytical layer images and Layer.md (defaults to 'Layers').",
+                            },
+                            user_intent: {
+                                type: "string",
+                                description: "Optional creative or corrective intent to dynamically tailor layer diagnostics, recommendations, and diffusion prompts.",
                             },
                         },
                         required: ["image_path"],
                     },
+                    outputSchema: {
+                        ...StandardEnvelopeSchema,
+                        properties: {
+                            ...StandardEnvelopeSchema.properties,
+                            data: {
+                                type: "object",
+                                properties: {
+                                    imagePath: { type: "string", description: "Canonical resolved file path." },
+                                    dimensions: { type: "array", items: { type: "number" }, description: "[width, height] in pixels." },
+                                    colorTemperatureKelvin: { type: "number", description: "Correlated Color Temperature (CCT) in Kelvin." },
+                                    dominantLightDirectionVector: { type: "array", items: { type: "number" }, description: "Normalized [X, Y, Z] vector." },
+                                    lightingAngles: {
+                                        type: "object",
+                                        properties: {
+                                            azimuthDeg: { type: "number", description: "Horizontal angle (0-360°)." },
+                                            elevationDeg: { type: "number", description: "Vertical elevation angle (0-90°)." },
+                                        },
+                                        required: ["azimuthDeg", "elevationDeg"],
+                                    },
+                                    meanLuminance: { type: "number", description: "Average photometric luminance (0-255)." },
+                                    luminanceDynamics: {
+                                        type: "object",
+                                        properties: {
+                                            min: { type: "number" },
+                                            max: { type: "number" },
+                                            p5: { type: "number" },
+                                            median: { type: "number" },
+                                            p95: { type: "number" },
+                                            contrastRatio: { type: "number" },
+                                        },
+                                    },
+                                    contrastZones: {
+                                        type: "object",
+                                        properties: {
+                                            specularHighlightsPct: { type: "number" },
+                                            deepShadowsPct: { type: "number" },
+                                            midtonesPct: { type: "number" },
+                                        },
+                                    },
+                                    surfaceNormalVariation: { type: "number", description: "Roughness metric (std dev of normals)." },
+                                    opticalProfileSummary: { type: "string", description: "Executive summary sentence." },
+                                },
+                                required: [
+                                    "imagePath",
+                                    "dimensions",
+                                    "colorTemperatureKelvin",
+                                    "dominantLightDirectionVector",
+                                    "lightingAngles",
+                                    "meanLuminance",
+                                    "luminanceDynamics",
+                                    "contrastZones",
+                                    "surfaceNormalVariation",
+                                    "opticalProfileSummary",
+                                ],
+                            },
+                        },
+                    },
                 },
                 {
                     name: "generate_relight_variations",
-                    description: "Generate 4 physically-grounded relit image variations (Ambient fill, Dramatic chiaroscuro, " +
-                        "Rim light halo, Mood golden-hour) and save them to the output cache directory.",
+                    description: "Generate 4 physically-grounded relit image variations on disk (Ambient fill, Dramatic chiaroscuro, " +
+                        "Rim light halo, Mood golden-hour) with mathematical adjustment logs detailing exposure compensation (EV stops) and color balance.\n\n" +
+                        "• Purpose: Visual image transformation. Unlike 'analyze_optical_profile' which is read-only, this tool renders and writes concrete " +
+                        "image files to the destination directory. Unlike 'synthesize_diffusion_prompt', it produces immediate local image files.\n" +
+                        "• Behavior: Mutates filesystem by creating up to 4 image files in the output directory. Deterministic, unmetered local compute, " +
+                        "no network egress, no authentication required. Re-running overwrites previous variations with the same base name.\n" +
+                        "• When to use: Use when you need tangible image alternatives of a photo or product render with alternative lighting schemes.\n" +
+                        "• When NOT to use: Do NOT use if you only need optical metrics (use 'analyze_optical_profile'), if blending a cutout into a background " +
+                        "(use 'harmonize_composite'), or if you need diffusion AI text prompts (use 'synthesize_diffusion_prompt').\n" +
+                        "• Alternatives: Use 'synthesize_diffusion_prompt' for text prompts targeting GPT Image or Nano Banana, or 'list_cached_variations' to browse existing outputs.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             image_path: {
                                 type: "string",
-                                description: "Path to the source image.",
+                                description: "Path to the input image (.png, .jpg, .jpeg) to relight.",
                             },
                             target_lighting: {
                                 type: "string",
                                 enum: ["Ambient", "Dramatic", "Rim", "Mood", "All"],
                                 default: "All",
-                                description: "Lighting preset: 'Ambient', 'Dramatic', 'Rim', 'Mood', or 'All'.",
+                                description: "Lighting preset selection: 'Ambient' (+0.8 EV lifted shadows, 5500K daylight), " +
+                                    "'Dramatic' (-1.5 EV shadow crush, chiaroscuro S-curve), 'Rim' (+1.2 EV normal curvature perimeter halo), " +
+                                    "'Mood' (3200K tungsten amber shift, highlight bloom), or 'All' to generate all four simultaneously. Defaults to 'All'.",
                             },
                             output_dir: {
                                 type: "string",
-                                description: "Custom output directory. If omitted, uses default cache directory.",
+                                default: "",
+                                description: "Destination folder for generated variation image files. If omitted, defaults to the server's configured cache directory ('./generated_variations').",
                             },
                         },
                         required: ["image_path"],
                     },
+                    outputSchema: {
+                        ...StandardEnvelopeSchema,
+                        properties: {
+                            ...StandardEnvelopeSchema.properties,
+                            data: {
+                                type: "object",
+                                properties: {
+                                    originalImage: { type: "string" },
+                                    outputDir: { type: "string" },
+                                    totalVariations: { type: "number" },
+                                    variations: {
+                                        type: "array",
+                                        items: {
+                                            type: "object",
+                                            properties: {
+                                                presetName: { type: "string" },
+                                                imagePath: { type: "string" },
+                                                fileSizeBytes: { type: "number" },
+                                                evShiftStops: { type: "number" },
+                                                targetCctKelvin: { type: "number" },
+                                                adjustmentsApplied: { type: "array", items: { type: "string" } },
+                                            },
+                                            required: ["presetName", "imagePath", "fileSizeBytes", "evShiftStops", "targetCctKelvin", "adjustmentsApplied"],
+                                        },
+                                    },
+                                },
+                                required: ["originalImage", "outputDir", "totalVariations", "variations"],
+                            },
+                        },
+                    },
                 },
                 {
                     name: "harmonize_composite",
-                    description: "Harmonize and composite a foreground element onto a background scene. Applies Reinhard color " +
-                        "statistics transfer, matches background color temperature, and synthesizes grounded contact shadows.",
+                    description: "Harmonize and composite a foreground subject cutout onto a background environment scene image using Reinhard " +
+                        "color statistics transfer in decorrelated lαβ space, background color temperature matching, and synthesized ground contact shadows.\n\n" +
+                        "• Purpose: Two-image compositing and photometric harmonization. Distinct from 'generate_relight_variations' which operates on a single image, " +
+                        "this tool resolves color mismatches and grounding between two separate image sources.\n" +
+                        "• Behavior: Mutates filesystem by writing 1 composited PNG image to the output cache directory. Deterministic, local execution, " +
+                        "no network egress, no authentication required.\n" +
+                        "• When to use: Use when placing a cutout product, character, or object onto a new background environment scene, ensuring realistic color adaptation and floor shadows.\n" +
+                        "• When NOT to use: Do NOT use to relight a single standalone image (use 'generate_relight_variations'), or to analyze metrics alone (use 'analyze_optical_profile').\n" +
+                        "• Alternatives: Use 'generate_relight_variations' to alter lighting on a single image, or 'synthesize_diffusion_prompt' to craft inpainting prompts for seam blending.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             foreground_path: {
                                 type: "string",
-                                description: "Path to the foreground subject cutout (PNG/JPG).",
+                                description: "Path to foreground subject image. Supports transparent PNG (with alpha channel) or solid background.",
                             },
                             background_path: {
                                 type: "string",
-                                description: "Path to the background environment image.",
+                                description: "Path to target background scene image (.png, .jpg, .jpeg).",
                             },
                             blend_mode: {
                                 type: "string",
                                 enum: ["seamless", "alpha"],
                                 default: "seamless",
-                                description: "Blending algorithm ('seamless' or 'alpha').",
+                                description: "Blending mode: 'seamless' (applies Reinhard color transfer + contact shadow + alpha blend) " +
+                                    "or 'alpha' (standard alpha composite with contact shadow only). Defaults to 'seamless'.",
                             },
                         },
                         required: ["foreground_path", "background_path"],
                     },
+                    outputSchema: {
+                        ...StandardEnvelopeSchema,
+                        properties: {
+                            ...StandardEnvelopeSchema.properties,
+                            data: {
+                                type: "object",
+                                properties: {
+                                    compositeImagePath: { type: "string", description: "Absolute path to the rendered composite file on disk." },
+                                    blendMode: { type: "string" },
+                                    foregroundPath: { type: "string" },
+                                    backgroundPath: { type: "string" },
+                                    backgroundCctKelvin: { type: "number", description: "Target background color temperature." },
+                                    luminanceScalingFactor: { type: "number" },
+                                    contactShadowApplied: { type: "boolean", description: "True if contact shadow was synthesized at base." },
+                                    details: { type: "object" },
+                                },
+                                required: [
+                                    "compositeImagePath",
+                                    "blendMode",
+                                    "foregroundPath",
+                                    "backgroundPath",
+                                    "backgroundCctKelvin",
+                                    "luminanceScalingFactor",
+                                    "contactShadowApplied",
+                                ],
+                            },
+                        },
+                    },
                 },
                 {
                     name: "synthesize_diffusion_prompt",
-                    description: "Synthesize precision enhancement and relighting diffusion prompts for GPT Image (DALL-E 3 / GPT-4o) " +
-                        "and Nano Banana based on physical optical analysis of an image. Includes exact Kelvin temperature, " +
-                        "lighting angles, volumetric rays, contact shadows, and calibrated denoising parameters (0.35 - 0.45).",
+                    description: "Synthesize precision enhancement and relighting diffusion prompts based on physical optical analysis of an image, " +
+                        "tailored specifically for GPT Image (DALL-E 3 / GPT-4o) and Nano Banana. Outputs photorealistic prompts with physical keywords " +
+                        "(exact Kelvin CCT, 3D light angles, volumetric dust rays, contact shadows) and calibrated denoising parameters (0.35 - 0.45).\n\n" +
+                        "• Purpose: Generative AI prompt synthesis. Unlike 'generate_relight_variations' which creates image files locally, this tool translates " +
+                        "optical geometry into targeted text prompts and hyperparameter sets for external diffusion generators.\n" +
+                        "• Behavior: Completely read-only, deterministic, zero filesystem modifications, no network calls, and no authentication required.\n" +
+                        "• When to use: Use when you want to feed photorealistic lighting directives or inpainting prompts into GPT Image or Nano Banana.\n" +
+                        "• When NOT to use: Do NOT use if you need local image rendering without an external AI model (use 'generate_relight_variations'), " +
+                        "or if merging cutouts locally (use 'harmonize_composite').\n" +
+                        "• Alternatives: Use 'generate_relight_variations' for instant offline image files, or 'analyze_optical_profile' for raw numerical statistics.",
                     inputSchema: {
                         type: "object",
                         properties: {
                             image_path: {
                                 type: "string",
-                                description: "Path to the reference image.",
+                                description: "Path to the local reference image (.png, .jpg, .jpeg) to extract optical geometry from.",
                             },
                             user_intent: {
                                 type: "string",
-                                description: "Creative intent (e.g. 'golden sunset', 'studio commercial').",
+                                default: "",
+                                description: "Optional creative context or scenario description (e.g., 'golden sunset portrait', 'cyberpunk studio product').",
                             },
                             target_model: {
                                 type: "string",
                                 enum: ["gpt_image", "nano_banana"],
                                 default: "gpt_image",
-                                description: "Target engine: 'gpt_image' (GPT Image) or 'nano_banana' (Nano Banana).",
+                                description: "Target generative engine: 'gpt_image' (outputs natural descriptive studio directives with 85mm prime lens and physical illumination) " +
+                                    "or 'nano_banana' (outputs dense tokenized optical shaders, roughness index, raytraced bounce, and ground contact shadow). Defaults to 'gpt_image'.",
                             },
                         },
                         required: ["image_path"],
                     },
+                    outputSchema: {
+                        ...StandardEnvelopeSchema,
+                        properties: {
+                            ...StandardEnvelopeSchema.properties,
+                            data: {
+                                type: "object",
+                                properties: {
+                                    targetModel: { type: "string", enum: ["GPT Image", "Nano Banana"] },
+                                    userIntent: { type: "string" },
+                                    enhancementPrompt: { type: "string", description: "Prompt for micro-surface detail and lens clarity upgrade." },
+                                    relightingPrompt: { type: "string", description: "Prompt for physical relighting with angles, CCT, and contact shadows." },
+                                    recommendedParameters: { type: "object", description: "Calibrated diffusion settings (denoising 0.35-0.45, etc.)." },
+                                    opticalKeywordsUsed: { type: "array", items: { type: "string" } },
+                                },
+                                required: [
+                                    "targetModel",
+                                    "userIntent",
+                                    "enhancementPrompt",
+                                    "relightingPrompt",
+                                    "recommendedParameters",
+                                    "opticalKeywordsUsed",
+                                ],
+                            },
+                        },
+                    },
+                },
+                {
+                    name: "list_cached_variations",
+                    description: "List and inspect all previously generated relight variation images and harmonized composite files stored in the output cache directory.\n\n" +
+                        "• Purpose: Cache inventory and artifact retrieval. Resolves pipeline completeness by allowing callers to discover, verify, " +
+                        "and retrieve generated files without manual filesystem traversal.\n" +
+                        "• Behavior: Completely read-only, queries local filesystem cache directory, no network calls, no authentication required.\n" +
+                        "• When to use: Use after running 'generate_relight_variations' or 'harmonize_composite' to verify written artifacts, inspect file sizes, " +
+                        "and obtain exact paths for downstream analysis.\n" +
+                        "• When NOT to use: Do NOT use to generate new images (use 'generate_relight_variations') or to analyze optical metrics (use 'analyze_optical_profile').\n" +
+                        "• Alternatives: Use 'generate_relight_variations' to create new images, or 'harmonize_composite' to merge cutouts.",
+                    inputSchema: {
+                        type: "object",
+                        properties: {
+                            cache_dir: {
+                                type: "string",
+                                default: "",
+                                description: "Optional custom directory path to inspect. If omitted, uses server's default cache directory.",
+                            },
+                        },
+                    },
+                    outputSchema: {
+                        ...StandardEnvelopeSchema,
+                        properties: {
+                            ...StandardEnvelopeSchema.properties,
+                            data: {
+                                type: "object",
+                                properties: {
+                                    cacheDirectory: { type: "string" },
+                                    totalFiles: { type: "number" },
+                                    files: {
+                                        type: "array",
+                                        items: {
+                                            type: "object",
+                                            properties: {
+                                                filename: { type: "string" },
+                                                path: { type: "string" },
+                                                sizeBytes: { type: "number" },
+                                                createdAt: { type: "string" },
+                                                type: { type: "string", enum: ["relight_variation", "harmonized_composite", "other"] },
+                                            },
+                                            required: ["filename", "path", "sizeBytes", "createdAt", "type"],
+                                        },
+                                    },
+                                },
+                                required: ["cacheDirectory", "totalFiles", "files"],
+                            },
+                        },
+                    },
                 },
             ],
         };
@@ -123,7 +396,10 @@ function createServer() {
         switch (name) {
             case "analyze_optical_profile": {
                 const imagePath = String(args.image_path || "");
-                envelope = (0, analyze_optical_1.analyzeOpticalProfileTool)(imagePath);
+                const extractLayers = Boolean(args.extract_layers);
+                const layersDir = args.layers_dir ? String(args.layers_dir) : undefined;
+                const userIntent = args.user_intent ? String(args.user_intent) : undefined;
+                envelope = (0, analyze_optical_1.analyzeOpticalProfileTool)(imagePath, extractLayers, layersDir, userIntent);
                 break;
             }
             case "generate_relight_variations": {
@@ -147,6 +423,11 @@ function createServer() {
                 envelope = (0, synthesize_prompt_1.synthesizeDiffusionPromptTool)(imagePath, userIntent, targetModel);
                 break;
             }
+            case "list_cached_variations": {
+                const cacheDir = args.cache_dir ? String(args.cache_dir) : undefined;
+                envelope = (0, list_cache_1.listCachedVariationsTool)(cacheDir);
+                break;
+            }
             default:
                 throw new Error(`Unknown tool: '${name}'`);
         }

package/dist/tools/analyze_optical.d.ts

@@ -1,2 +1,2 @@
 import { ResultEnvelope } from "../core/envelope";
-export declare function analyzeOpticalProfileTool(imagePath: string): ResultEnvelope;
+export declare function analyzeOpticalProfileTool(imagePath: string, extractLayers?: boolean, layersDir?: string, userIntent?: string): ResultEnvelope;

package/dist/tools/analyze_optical.js

@@ -8,19 +8,38 @@ const crypto_1 = __importDefault(require("crypto"));
 const envelope_1 = require("../core/envelope");
 const errors_1 = require("../core/errors");
 const optical_analyzer_1 = require("../domain/optical_analyzer");
-function analyzeOpticalProfileTool(imagePath) {
+const layer_extractor_1 = require("../domain/layer_extractor");
+function analyzeOpticalProfileTool(imagePath, extractLayers = false, layersDir, userIntent) {
     try {
         const report = (0, optical_analyzer_1.analyzeOpticalProfileImpl)(imagePath);
         const hash = crypto_1.default.createHash("sha256").update(imagePath).digest("hex").slice(0, 12);
-        return (0, envelope_1.createEnvelope)("success", `Optical profile extracted successfully: ${report.opticalProfileSummary}`, report, {
+        let layerReport;
+        const artifacts = [];
+        if (extractLayers || layersDir) {
+            const targetDir = layersDir || "Layers";
+            layerReport = (0, layer_extractor_1.extractLayersImpl)(imagePath, targetDir, userIntent);
+            artifacts.push({ label: "Layer 1 - Highlights", uri: `file://${layerReport.layers.highlights.path}` }, { label: "Layer 2 - Shadows", uri: `file://${layerReport.layers.shadows.path}` }, { label: "Layer 3 - Ambient Occlusion", uri: `file://${layerReport.layers.ambientOcclusion.path}` }, { label: "Layer 4 - Edges", uri: `file://${layerReport.layers.edges.path}` }, { label: "Layer 5 - Depth Normals", uri: `file://${layerReport.layers.depthNormals.path}` }, { label: "Layer 6 - Chroma Saturation", uri: `file://${layerReport.layers.chromaSaturation.path}` }, { label: "Layer Markdown Report", uri: `file://${layerReport.layerMarkdownPath}` });
+        }
+        const payload = { ...report };
+        if (layerReport) {
+            payload.layersDirectory = layerReport.layersDirectory;
+            payload.layers = layerReport.layers;
+            payload.layerMarkdownPath = layerReport.layerMarkdownPath;
+        }
+        const nextActions = [
+            `Call 'generate_relight_variations' on '${imagePath}' to explore alternative lighting schemes.`,
+            `Call 'synthesize_diffusion_prompt' targeting GPT Image or Nano Banana for high-res generative inpainting.`,
+        ];
+        if (layerReport) {
+            nextActions.unshift(`Inspect 6 analytical layers and Layer.md, then present to user with prompt: 'ماذا تريد من تعديل؟'`);
+        }
+        return (0, envelope_1.createEnvelope)("success", `Optical profile extracted successfully: ${report.opticalProfileSummary}${layerReport ? ` (6 Analytical layers generated in '${layerReport.layersDirectory}')` : ""}`, payload, {
             evidence: {
                 inputsDigest: `sha256:${hash}`,
                 sources: [{ label: "Source Image", uri: `file://${report.imagePath}` }],
+                artifacts,
             },
-            nextActions: [
-                `Call 'generate_relight_variations' on '${imagePath}' to explore alternative lighting schemes.`,
-                `Call 'synthesize_diffusion_prompt' targeting GPT Image or Nano Banana for high-res generative inpainting.`,
-            ],
+            nextActions,
         });
     }
     catch (err) {

package/dist/tools/list_cache.d.ts

@@ -0,0 +1,9 @@
+import { ResultEnvelope } from "../core/envelope";
+export interface CachedItem {
+    filename: string;
+    path: string;
+    sizeBytes: number;
+    createdAt: string;
+    type: "relight_variation" | "harmonized_composite" | "other";
+}
+export declare function listCachedVariationsTool(cacheDir?: string): ResultEnvelope;

package/dist/tools/list_cache.js

@@ -0,0 +1,68 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.listCachedVariationsTool = listCachedVariationsTool;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const crypto_1 = __importDefault(require("crypto"));
+const config_1 = require("../config");
+const envelope_1 = require("../core/envelope");
+const errors_1 = require("../core/errors");
+function listCachedVariationsTool(cacheDir) {
+    try {
+        const targetDir = cacheDir ? path_1.default.resolve(cacheDir) : (0, config_1.ensureOutputDirectory)();
+        if (!fs_1.default.existsSync(targetDir)) {
+            return (0, envelope_1.createEnvelope)("success", `Output cache directory is empty or does not yet exist: '${targetDir}'`, { cacheDirectory: targetDir, totalFiles: 0, files: [] }, { nextActions: ["Call 'generate_relight_variations' or 'harmonize_composite' to produce variations."] });
+        }
+        const entries = fs_1.default.readdirSync(targetDir, { withFileTypes: true });
+        const files = [];
+        for (const entry of entries) {
+            if (entry.isFile()) {
+                const ext = path_1.default.extname(entry.name).toLowerCase();
+                if (config_1.config.allowedExtensions.has(ext)) {
+                    const fullPath = path_1.default.join(targetDir, entry.name);
+                    const stat = fs_1.default.statSync(fullPath);
+                    let itemType = "other";
+                    if (entry.name.includes("_relight_")) {
+                        itemType = "relight_variation";
+                    }
+                    else if (entry.name.startsWith("harmonized_")) {
+                        itemType = "harmonized_composite";
+                    }
+                    files.push({
+                        filename: entry.name,
+                        path: fullPath,
+                        sizeBytes: stat.size,
+                        createdAt: stat.mtime.toISOString(),
+                        type: itemType,
+                    });
+                }
+            }
+        }
+        // Sort by most recent
+        files.sort((a, b) => new Date(b.createdAt).getTime() - new Date(a.createdAt).getTime());
+        const hash = crypto_1.default.createHash("sha256").update(targetDir).digest("hex").slice(0, 12);
+        return (0, envelope_1.createEnvelope)("success", `Found ${files.length} cached variation and composite artifacts in '${targetDir}'.`, { cacheDirectory: targetDir, totalFiles: files.length, files }, {
+            evidence: {
+                inputsDigest: `sha256:${hash}`,
+                artifacts: files.map((f) => ({ label: f.filename, uri: `file://${f.path}` })),
+            },
+            nextActions: [
+                "Call 'analyze_optical_profile' on any cached variation to evaluate its modified optical properties.",
+                "Call 'synthesize_diffusion_prompt' to craft AI inpainting prompts from a cached variation.",
+            ],
+        });
+    }
+    catch (err) {
+        const isAppErr = err instanceof errors_1.AppError;
+        const msg = err.message || "Failed to list cached variations.";
+        const code = isAppErr ? err.code : "INTERNAL_ERROR";
+        const hint = isAppErr ? err.actionableHint : "Verify directory read permissions.";
+        return (0, envelope_1.createEnvelope)("failed", `Listing cache failed: ${msg}`, { error_code: code, actionable_hint: hint }, {
+            warnings: [msg],
+            nextActions: [hint],
+        });
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-relight-harmonize",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "description": "Professional TypeScript Model Context Protocol (MCP) server & agent skill for optical profiling, physical relighting, composite harmonization, and diffusion prompt synthesis (GPT Image & Nano Banana).",
   "author": "MarwanDevSpace <dev@marwandevspace.io>",
   "license": "MIT",