mcp-relight-harmonize 1.0.2 → 1.0.3

package/dist/domain/layer_extractor.js

@@ -0,0 +1,350 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildDynamicDiagnostics = buildDynamicDiagnostics;
+exports.extractLayersImpl = extractLayersImpl;
+const fs_1 = __importDefault(require("fs"));
+const path_1 = __importDefault(require("path"));
+const image_io_1 = require("./image_io");
+const optical_analyzer_1 = require("./optical_analyzer");
+const security_1 = require("../core/security");
+function buildDynamicDiagnostics(cctKelvin, azimuthDeg, elevationDeg, hlPct, shPct, aoPct, meanGradient, meanSaturation, userIntent) {
+    const findings = [];
+    const tailoredOptions = [];
+    // 1. Thermal & Chromatic Diagnostics
+    let thermalDesc = "";
+    if (cctKelvin < 3800) {
+        thermalDesc = `طيف لوني دافئ جداً (${Math.round(cctKelvin)}K - Tungsten/Golden Hour)`;
+        findings.push(`🔥 **انحياز طيفي دافئ**: الصورة مسجلة بحرارة \`${Math.round(cctKelvin)}K\` مع غلبة للأطياف الكهرمانية والبرتقالية في القنوات الضوئية.`);
+        tailoredOptions.push(`موازنة حرارة الألوان من \`${Math.round(cctKelvin)}K\` إلى 5500K نهارية محايدة لإزالة المسحة الكهرمانية.`);
+    }
+    else if (cctKelvin > 6500) {
+        thermalDesc = `طيف لوني بارد (${Math.round(cctKelvin)}K - Cool Atmospheric Skylight)`;
+        findings.push(`❄️ **انحياز طيفي بارد**: الصورة مسجلة بحرارة \`${Math.round(cctKelvin)}K\` مع غلبة للزرقة والارتداد السماوي البارد.`);
+        tailoredOptions.push(`تدفئة المشهد الضوئي برفع حرارة الألوان إلى 3200K (Mood Tungsten) أو 4500K سينمائي.`);
+    }
+    else {
+        thermalDesc = `طيف نهاري متوازن (${Math.round(cctKelvin)}K - Balanced Daylight)`;
+        findings.push(`☀️ **حرارة ألوان متوازنة**: حرارة الألوان عند \`${Math.round(cctKelvin)}K\` تماثل الإضاءة الاستوديوية المتوازنة.`);
+    }
+    // 2. Lighting Direction & Dynamic Contrast
+    const lightDir = (azimuthDeg >= 0 && azimuthDeg < 90) || (azimuthDeg >= 270 && azimuthDeg <= 360) ? "يمين" : "يسار";
+    const lightVert = elevationDeg > 50 ? "علوية" : "أفقية جانبية";
+    findings.push(`💡 **توجيه الإضاءة الرئيسية**: زاوية السمت \`${Math.round(azimuthDeg)}°\` (إضاءة من جهة ال${lightDir}) مع زاوية ارتفاع \`${Math.round(elevationDeg)}°\` (${lightVert}).`);
+    if (shPct > 35.0 && hlPct > 15.0) {
+        findings.push(`⚡ **تباين درامي عالي (Chiaroscuro)**: كثافة الظلال \`${shPct.toFixed(1)}%\` مع مساحة ساطعة \`${hlPct.toFixed(1)}%\` تدل على تباين قوي بين المفتاح الضوئي والملء.`);
+        tailoredOptions.push("تنعيم التباين ورفع تفاصيل الظلال المغلقة عبر وضع الإضاءة المحيطية (Ambient Fill +0.8 EV).");
+    }
+    else if (shPct < 12.0 && hlPct < 12.0) {
+        findings.push("🌫️ **إضاءة منبسطة ناعمة (Flat Diffuse)**: تباين منخفض وغياب للمناطق الساطعة الحادة، ما يعطي مظهراً هادئاً ومنبسطاً.");
+        tailoredOptions.push("إضافة عمق درامي وزيادة التباين بنمط Chiaroscuro عالي التحديد مع إضاءة اتجاهية بارزة.");
+    }
+    // 3. Grounding & Ambient Occlusion
+    if (aoPct < 2.0) {
+        findings.push(`⚠️ **فقدان الارتكاز الأرضي (Lack of Grounding)**: نسبة الظلال التلامسية العميقة \`${aoPct.toFixed(2)}%\` تكاد تنعدم، مما قد يظهر العنصر كأنه طافٍ في الفراغ.`);
+        tailoredOptions.push("بناء وتثبيت ظل تلامسي أرضي فيزيائي (Contact Shadow Footprint) أسفل أدنى نقطة ارتكاز لمنع الظهور الطافي.");
+    }
+    else {
+        findings.push(`⚓ **ارتكاز أرضي متماسك**: نسبة ظلال التلامس والانغلاق الموضعي \`${aoPct.toFixed(1)}%\` تؤمن التصاقاً بصرياً طبيعياً بالأرضية.`);
+    }
+    // 4. Micro-texture & Edges
+    if (meanGradient > 0.03) {
+        findings.push(`🔍 **تفاصيل سطحية دقيقة وحواف حادة**: متوسط تباين سوبل \`${meanGradient.toFixed(4)}\` يشير إلى وفرة في التفاصيل المجهرية والأنسجة السطحية الواضحة.`);
+    }
+    else {
+        findings.push(`🎨 **حواف ناعمة وسطح انسيابي**: متوسط تدرج سوبل \`${meanGradient.toFixed(4)}\` يشير إلى مساحات ناعمة متصلة ومناسبة للتنعيم وإعادة التوزيع.`);
+    }
+    // 5. Chroma / Saturation
+    if (meanSaturation > 0.4) {
+        findings.push(`🌈 **تشبع لوني مكثف**: متوسط التشبع \`${meanSaturation.toFixed(3)}\` يظهر كثافة لونية حيوية في البكسلات.`);
+    }
+    else {
+        findings.push(`🔘 **لوحة لونية هادئة أو معتدلة**: متوسط التشبع \`${meanSaturation.toFixed(3)}\` يعكس تدرجات رصينة غير مبالغ بها.`);
+    }
+    // User intent or default options
+    if (userIntent) {
+        tailoredOptions.unshift(`تطبيق طلبك المخصص فوراً: "${userIntent}" بتطابق فيزيائي دقيق مع بيانات الطبقات الست.`);
+    }
+    else {
+        tailoredOptions.push("إعادة إضاءة بنمط هالة الحواف (Rim Light Halo +1.2 EV) لإبراز حدود المجسم وعزله عن الخلفية.");
+        tailoredOptions.push("دمج العنصر في خلفية جديدة مع مطابقة إحصائيات الألوان ودرجة الحرارة وظلال الارتكاز.");
+    }
+    const intentClause = userIntent ? `, ${userIntent}` : "";
+    const gptPrompt = `A master-quality studio photograph${intentClause}, calibrated optical lighting at ${Math.round(azimuthDeg)}° azimuth ` +
+        `and ${Math.round(elevationDeg)}° elevation, authentic ${Math.round(cctKelvin)}K color temperature balance, ` +
+        `physically-grounded ambient occlusion contact shadows firmly anchoring the base plane, ` +
+        `crisp micro-surface geometry (Sobel roughness index ${meanGradient.toFixed(3)}), ` +
+        `smooth luminance falloff and authentic subsurface scattering, 85mm prime lens f/2.0.`;
+    const nanoPrompt = `optics relight, cct ${Math.round(cctKelvin)}K, light vector azimuth ${Math.round(azimuthDeg)} deg elevation ${Math.round(elevationDeg)} deg, ` +
+        `surface roughness ${meanGradient.toFixed(4)}, saturation index ${meanSaturation.toFixed(3)}, ` +
+        `ground contact occlusion caster, volumetric photon bounce, high-key rim highlight accents, ` +
+        `denoising strength 0.38${intentClause}`;
+    return {
+        thermalDescription: thermalDesc,
+        findings,
+        tailoredOptions,
+        gptImagePrompt: gptPrompt,
+        nanoBananaPrompt: nanoPrompt,
+    };
+}
+function extractLayersImpl(imagePath, outputDir = "Layers", userIntent) {
+    const resolvedImagePath = (0, security_1.validateImagePath)(imagePath);
+    const resolvedOutputDir = path_1.default.resolve(outputDir);
+    if (!fs_1.default.existsSync(resolvedOutputDir)) {
+        fs_1.default.mkdirSync(resolvedOutputDir, { recursive: true });
+    }
+    const raw = (0, image_io_1.readImage)(resolvedImagePath);
+    const { width, height, data } = raw;
+    const numPixels = width * height;
+    const lumArray = new Float32Array(numPixels);
+    let sumR = 0;
+    let sumG = 0;
+    let sumB = 0;
+    let sumSat = 0;
+    for (let i = 0; i < numPixels; i++) {
+        const idx = i * 4;
+        const r = data[idx];
+        const g = data[idx + 1];
+        const b = data[idx + 2];
+        sumR += r;
+        sumG += g;
+        sumB += b;
+        const lum = 0.2126 * r + 0.7152 * g + 0.0722 * b;
+        lumArray[i] = lum / 255.0;
+        const maxC = Math.max(r, g, b);
+        const minC = Math.min(r, g, b);
+        const chroma = maxC - minC;
+        const sat = maxC > 0 ? chroma / maxC : 0;
+        sumSat += sat;
+    }
+    const meanR = sumR / numPixels;
+    const meanG = sumG / numPixels;
+    const meanB = sumB / numPixels;
+    const meanLum = 0.2126 * meanR + 0.7152 * meanG + 0.0722 * meanB;
+    const meanSaturation = sumSat / numPixels;
+    const cctKelvin = (0, optical_analyzer_1.calculateCctFromRgb)(meanR, meanG, meanB);
+    const { roughness, lightVector, angles } = (0, optical_analyzer_1.computeSurfaceNormalsAndLightVector)(lumArray, width, height);
+    const bufHighlights = Buffer.alloc(numPixels * 4);
+    const bufShadows = Buffer.alloc(numPixels * 4);
+    const bufAO = Buffer.alloc(numPixels * 4);
+    const bufEdges = Buffer.alloc(numPixels * 4);
+    const bufNormals = Buffer.alloc(numPixels * 4);
+    const bufChroma = Buffer.alloc(numPixels * 4);
+    let highlightsCount = 0;
+    let shadowsCount = 0;
+    let aoCount = 0;
+    let edgeSum = 0;
+    const scale = 6.0;
+    for (let y = 0; y < height; y++) {
+        for (let x = 0; x < width; x++) {
+            const idx = y * width + x;
+            const pIdx = idx * 4;
+            const r = data[pIdx];
+            const g = data[pIdx + 1];
+            const b = data[pIdx + 2];
+            const lum = lumArray[idx] * 255.0;
+            // 1. Highlights
+            if (lum > 170)
+                highlightsCount++;
+            const hlMask = Math.min(Math.max((lum - 170.0) / 75.0, 0.0), 1.0);
+            bufHighlights[pIdx] = Math.round(r * hlMask);
+            bufHighlights[pIdx + 1] = Math.round(g * hlMask);
+            bufHighlights[pIdx + 2] = Math.round(b * hlMask);
+            bufHighlights[pIdx + 3] = 255;
+            // 2. Shadows
+            if (lum < 85)
+                shadowsCount++;
+            const shMask = Math.min(Math.max((95.0 - lum) / 80.0, 0.0), 1.0);
+            bufShadows[pIdx] = Math.round(r * shMask);
+            bufShadows[pIdx + 1] = Math.round(g * shMask);
+            bufShadows[pIdx + 2] = Math.round(b * shMask);
+            bufShadows[pIdx + 3] = 255;
+            // 3. Deep Ambient Occlusion
+            if (lum < 35)
+                aoCount++;
+            const aoMask = Math.min(Math.max((40.0 - lum) / 40.0, 0.0), 1.0);
+            bufAO[pIdx] = Math.round((1.0 - aoMask) * 230.0);
+            bufAO[pIdx + 1] = Math.round((1.0 - aoMask) * 240.0 + aoMask * 15.0);
+            bufAO[pIdx + 2] = Math.round((1.0 - aoMask) * 255.0 + aoMask * 30.0);
+            bufAO[pIdx + 3] = 255;
+            // 4. Edges via Sobel
+            let gx = 0;
+            let gy = 0;
+            if (x > 0 && x < width - 1 && y > 0 && y < height - 1) {
+                gx =
+                    -lumArray[(y - 1) * width + (x - 1)] +
+                        lumArray[(y - 1) * width + (x + 1)] -
+                        2 * lumArray[y * width + (x - 1)] +
+                        2 * lumArray[y * width + (x + 1)] -
+                        lumArray[(y + 1) * width + (x - 1)] +
+                        lumArray[(y + 1) * width + (x + 1)];
+                gy =
+                    -lumArray[(y - 1) * width + (x - 1)] -
+                        2 * lumArray[(y - 1) * width + x] -
+                        lumArray[(y - 1) * width + (x + 1)] +
+                        lumArray[(y + 1) * width + (x - 1)] +
+                        2 * lumArray[(y + 1) * width + x] +
+                        lumArray[(y + 1) * width + (x + 1)];
+            }
+            const edgeMag = Math.sqrt(gx * gx + gy * gy);
+            edgeSum += edgeMag;
+            const edgeVal = Math.min(Math.round(edgeMag * 4.0 * 255.0), 255);
+            bufEdges[pIdx] = edgeVal;
+            bufEdges[pIdx + 1] = edgeVal;
+            bufEdges[pIdx + 2] = edgeVal;
+            bufEdges[pIdx + 3] = 255;
+            // 5. Depth Normals
+            const nx = -gx * scale;
+            const ny = -gy * scale;
+            const nz = 1.0;
+            const mag = Math.sqrt(nx * nx + ny * ny + nz * nz) || 1e-6;
+            const normX = nx / mag;
+            const normY = ny / mag;
+            const normZ = nz / mag;
+            bufNormals[pIdx] = Math.round((normX * 0.5 + 0.5) * 255);
+            bufNormals[pIdx + 1] = Math.round((normY * 0.5 + 0.5) * 255);
+            bufNormals[pIdx + 2] = Math.round((normZ * 0.5 + 0.5) * 255);
+            bufNormals[pIdx + 3] = 255;
+            // 6. Chroma / Saturation
+            const maxC = Math.max(r, g, b);
+            const minC = Math.min(r, g, b);
+            const chroma = maxC - minC;
+            const sat = maxC > 0 ? chroma / maxC : 0;
+            bufChroma[pIdx] = Math.min(Math.round(sat * 255.0 * 1.5), 255);
+            bufChroma[pIdx + 1] = Math.min(Math.round((1.0 - Math.abs(sat - 0.5) * 2.0) * 220.0), 255);
+            bufChroma[pIdx + 2] = Math.min(Math.round((1.0 - sat) * 200.0), 255);
+            bufChroma[pIdx + 3] = 255;
+        }
+    }
+    const hlPath = path_1.default.join(resolvedOutputDir, "01_highlights.png");
+    const shPath = path_1.default.join(resolvedOutputDir, "02_shadows.png");
+    const aoPath = path_1.default.join(resolvedOutputDir, "03_ambient_occlusion.png");
+    const edPath = path_1.default.join(resolvedOutputDir, "04_edges.png");
+    const normPath = path_1.default.join(resolvedOutputDir, "05_depth_normals.png");
+    const chrPath = path_1.default.join(resolvedOutputDir, "06_chroma_saturation.png");
+    (0, image_io_1.writeImage)(hlPath, { width, height, data: bufHighlights });
+    (0, image_io_1.writeImage)(shPath, { width, height, data: bufShadows });
+    (0, image_io_1.writeImage)(aoPath, { width, height, data: bufAO });
+    (0, image_io_1.writeImage)(edPath, { width, height, data: bufEdges });
+    (0, image_io_1.writeImage)(normPath, { width, height, data: bufNormals });
+    (0, image_io_1.writeImage)(chrPath, { width, height, data: bufChroma });
+    const hlPct = (highlightsCount / numPixels) * 100.0;
+    const shPct = (shadowsCount / numPixels) * 100.0;
+    const aoPct = (aoCount / numPixels) * 100.0;
+    const meanEdge = edgeSum / numPixels;
+    // Build Dynamic Diagnostics
+    const diagnostics = buildDynamicDiagnostics(cctKelvin, angles.azimuthDeg, angles.elevationDeg, hlPct, shPct, aoPct, meanEdge, meanSaturation, userIntent);
+    const layerMdPath = path_1.default.join(resolvedOutputDir, "Layer.md");
+    const toForwardSlash = (p) => p.replace(/\\/g, "/");
+    const findingsRendered = diagnostics.findings.join("\n\n");
+    const optionsRendered = diagnostics.tailoredOptions.map((opt, idx) => `- **خيار ${idx + 1}**: ${opt}`).join("\n");
+    const userIntentHeader = userIntent ? `\n**الهدف المخصص المطلوب**: \`${userIntent}\`\n` : "";
+    const mdContent = `# تقرير الطبقات التحليلية الست (Layer.md)
+**مصدر الصورة**: \`${resolvedImagePath}\`  
+**أبعاد الصورة**: \`${width}x${height}\` بكسل  
+**التصنيف الضوئي المكتشف**: \`${diagnostics.thermalDescription}\`  
+**زاوية الإضاءة المسجلة**: سمت \`${angles.azimuthDeg}°\` | ارتفاع \`${angles.elevationDeg}°\`${userIntentHeader}
+
+---
+
+## 1. فهرس الطبقات التحليلية الست (The 6 Extracted Layers)
+
+| # | اسم الطبقة | الملف المولد | القراءة الفيزيائية المكتشفة |
+|---|---|---|---|
+| **1** | **طبقة الألوان الفاتحة (Highlights)** | [\`01_highlights.png\`](file:///${toForwardSlash(hlPath)}) | نسبة تغطية الأضواء الساطعة: \`${hlPct.toFixed(2)}%\` |
+| **2** | **طبقة الألوان الغامقة (Shadows)** | [\`02_shadows.png\`](file:///${toForwardSlash(shPath)}) | مساحة الظلال والمناطق الداكنة: \`${shPct.toFixed(2)}%\` |
+| **3** | **طبقة الظل العالي (Ambient Occlusion)** | [\`03_ambient_occlusion.png\`](file:///${toForwardSlash(aoPath)}) | كثافة الارتكاز الأرضي وظلال التلامس: \`${aoPct.toFixed(2)}%\` |
+| **4** | **طبقة الحواف (Edges & Contours)** | [\`04_edges.png\`](file:///${toForwardSlash(edPath)}) | تباين الحواف المجهرية لسوبل: \`${meanEdge.toFixed(4)}\` |
+| **5** | **طبقة العمق (3D Depth Normals)** | [\`05_depth_normals.png\`](file:///${toForwardSlash(normPath)}) | توجيه التنسور المتجهي ثلاثي الأبعاد: سمت \`${angles.azimuthDeg}°\` |
+| **6** | **طبقة الألوان والتشبع (Chroma / Saturation)** | [\`06_chroma_saturation.png\`](file:///${toForwardSlash(chrPath)}) | متوسط تشبع وتوزيع نقاء الألوان: \`${meanSaturation.toFixed(3)}\` |
+
+---
+
+## 2. النتائج البصرية الديناميكية المستخلصة من الصورة (Dynamic Findings)
+
+${findingsRendered}
+
+---
+
+## 3. التوجيه التوليدي المخصص (Calibrated Prompts for Generative Engines)
+
+### أ. موجه GPT Image (DALL-E 3 / GPT-4o Vision):
+> "${diagnostics.gptImagePrompt}"
+
+### ب. موجه Nano Banana (High-Density Optical Tokenizer):
+> "${diagnostics.nanoBananaPrompt}"
+
+---
+
+## 4. الخطوة التفاعلية الموجهة بالبيانات (Dynamic Interactive Decision)
+
+**ماذا تريد من تعديل؟**
+بناءً على المعطيات الضوئية المكتشفة في هذه الصورة تحديداً، إليك خيارات التعديل المقترحة:
+
+${optionsRendered}
+
+💬 *يمكنك أيضاً طلب أي تعديل مخصص بحرية تامة، وسيتم فوراً توليد برومبت دقيق للغاية أو إنشاء الصورة المعدلة بالكامل!*
+`;
+    fs_1.default.writeFileSync(layerMdPath, mdContent, "utf-8");
+    return {
+        sourceImage: resolvedImagePath,
+        layersDirectory: resolvedOutputDir,
+        dimensions: [width, height],
+        opticalMetrics: {
+            cctKelvin: Math.round(cctKelvin * 10) / 10,
+            dominantLightVector: lightVector,
+            lightingAngles: angles,
+            meanLuminance: Math.round(meanLum * 100) / 100,
+            meanSaturation: Math.round(meanSaturation * 1000) / 1000,
+            edgeRoughness: Math.round(roughness * 10000) / 10000,
+        },
+        diagnostics,
+        layers: {
+            highlights: {
+                file: "01_highlights.png",
+                path: hlPath,
+                description: "طبقة الألوان الفاتحة - High-key Luminance & Specular Zones",
+                metricLabel: "coveragePct",
+                metricValue: Math.round(hlPct * 100) / 100,
+            },
+            shadows: {
+                file: "02_shadows.png",
+                path: shPath,
+                description: "طبقة الألوان الغامقة - Low-key & Shadow Zones",
+                metricLabel: "coveragePct",
+                metricValue: Math.round(shPct * 100) / 100,
+            },
+            ambientOcclusion: {
+                file: "03_ambient_occlusion.png",
+                path: aoPath,
+                description: "طبقة الظل العالي - High Contact Shadows & Deep Occlusion Crevices",
+                metricLabel: "coveragePct",
+                metricValue: Math.round(aoPct * 100) / 100,
+            },
+            edges: {
+                file: "04_edges.png",
+                path: edPath,
+                description: "طبقة الحواف - Sobel High-Frequency Gradient Contours",
+                metricLabel: "meanGradient",
+                metricValue: Math.round(meanEdge * 10000) / 10000,
+            },
+            depthNormals: {
+                file: "05_depth_normals.png",
+                path: normPath,
+                description: "طبقة العمق - 3D Surface Normal Gradient Field (RGB Tangent Map)",
+                metricLabel: "dominantAzimuth",
+                metricValue: angles.azimuthDeg,
+            },
+            chromaSaturation: {
+                file: "06_chroma_saturation.png",
+                path: chrPath,
+                description: "طبقة الألوان والتشبع والبكسلات - Chrominance & Saturation Distribution",
+                metricLabel: "meanSaturation",
+                metricValue: Math.round(meanSaturation * 1000) / 1000,
+            },
+        },
+        layerMarkdownPath: layerMdPath,
+    };
+}

package/dist/index.js

@@ -8,7 +8,7 @@ async function main() {
     const args = process.argv.slice(2);
     if (args.includes("--verify")) {
         console.log("[MarwanDevSpace] Verifying TypeScript mcp-relight-harmonize server...");
-        console.log("Server 'mcp-relight-harmonize' v1.0.2 initialized.");
+        console.log("Server 'mcp-relight-harmonize' v1.0.3 initialized.");
         console.log("Registered tools: ['analyze_optical_profile', 'generate_relight_variations', 'harmonize_composite', 'synthesize_diffusion_prompt', 'list_cached_variations']");
         console.log("Registered resources: ['optical://presets']");
         console.log("Output cache directory:", (0, config_1.ensureOutputDirectory)());

package/dist/resources/presets.js

@@ -3,7 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.LIGHTING_PRESETS_REFERENCE = void 0;
 exports.getPresetsJson = getPresetsJson;
 exports.LIGHTING_PRESETS_REFERENCE = {
-    version: "1.0.2",
+    version: "1.0.3",
     target_generators: ["GPT Image", "Nano Banana"],
     presets: [
         {

package/dist/server.js

@@ -46,7 +46,7 @@ const StandardEnvelopeSchema = {
 function createServer() {
     const server = new index_js_1.Server({
         name: "mcp-relight-harmonize",
-        version: "1.0.2",
+        version: "1.0.3",
     }, {
         capabilities: {
             tools: {},
@@ -61,14 +61,14 @@ function createServer() {
                     name: "analyze_optical_profile",
                     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, " +
-                        "and surface normal roughness index.\n\n" +
-                        "• Purpose: Diagnostic optical extraction. Unlike 'generate_relight_variations', this tool produces no image files, " +
-                        "and unlike 'synthesize_diffusion_prompt', it returns pure numerical color-science data rather than text prompts.\n" +
-                        "• Behavior: Completely read-only, deterministic, zero filesystem modifications, no network egress, and no authentication required.\n" +
-                        "• When to use: Use as the prerequisite first step before relighting, inpainting, or compositing an image to inspect baseline lighting conditions.\n" +
-                        "• When NOT to use: Do NOT use if you need modified image files on disk (use 'generate_relight_variations'), if merging a cutout into a scene " +
-                        "(use 'harmonize_composite'), or if you need generative AI prompts (use 'synthesize_diffusion_prompt').\n" +
-                        "• Alternatives: Use 'generate_relight_variations' for visual lighting files, or 'synthesize_diffusion_prompt' for model prompts.",
+                        "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: {
@@ -77,6 +77,18 @@ function createServer() {
                                 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"],
                     },
@@ -384,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": {

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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-relight-harmonize",
-  "version": "1.0.2",
+  "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",