mcp-relight-harmonize 1.0.0

package/.agents/skills/mcp-relight-harmonize/SKILL.md

@@ -0,0 +1,81 @@
+---
+name: mcp-relight-harmonize
+description: >-
+  Execute end-to-end optical image profiling, physically-grounded relighting variations, contact-aware composite harmonization,
+  and precision diffusion prompt synthesis targeting GPT Image and Nano Banana. Use when inspecting lighting angles or color temperature,
+  generating alternative illumination schemes (Ambient, Dramatic, Rim, Mood), blending foreground cutouts into backgrounds,
+  or drafting photorealistic prompts.
+---
+
+# `mcp-relight-harmonize` Skill Specification
+
+Created by **MarwanDevSpace**, this skill empowers the agent to execute physical lighting analysis, generate relighted variations, perform seamless composite harmonization, and craft production diffusion prompts tailored for **GPT Image** and **Nano Banana**.
+
+---
+
+## 1. When to Activate This Skill
+
+Activate this skill whenever the user asks to:
+1. **Analyze an image's lighting:** Determine Correlated Color Temperature (CCT in Kelvin), lighting direction vector, azimuth/elevation angles, contrast ratio, or surface roughness.
+2. **Relight an image:** Produce 4 physically-grounded lighting variants (`Ambient`, `Dramatic`, `Rim`, `Mood`).
+3. **Composite/Harmonize an image:** Place a cutout foreground onto a background scene, matching ambient color statistics and adding physically grounded contact shadows.
+4. **Generate `/prompt` for diffusion:** Create exact physical lighting and detail enhancement prompts for **GPT Image** (DALL-E 3 / GPT-4o) and **Nano Banana** with calibrated denoising strength (`0.35 - 0.45`).
+
+---
+
+## 2. Core Workflows & Execution Procedures
+
+### Workflow A: Optical Profiling
+Before modifying or inpainting an image, extract its optical geometry:
+1. Call tool `analyze_optical_profile({ image_path: "<path_to_image>" })`.
+2. Review the resulting `OpticalProfileReport`:
+   - **`colorTemperatureKelvin`**: e.g., 3200K tungsten vs 6500K daylight.
+   - **`lightingAngles`**: `azimuthDeg` (horizontal angle) and `elevationDeg` (vertical angle).
+   - **`luminanceDynamics.contrastRatio`**: Key-to-fill ratio.
+3. Use these physical parameters to inform subsequent relighting or prompt writing.
+
+### Workflow B: Generating 4 Relit Variations
+To produce visual lighting alternatives on disk:
+1. Call tool `generate_relight_variations({ image_path: "<path_to_image>", target_lighting: "All" })`.
+2. The tool produces 4 files in `OUTPUT_CACHE_DIR`:
+   - `*_relight_ambient.png` (+0.8 EV, lifted shadows, 5500K neutral daylight).
+   - `*_relight_dramatic.png` (-1.5 EV shadow crush, top-left directional chiaroscuro).
+   - `*_relight_rim.png` (+1.2 EV high-pass edge halo, cool cyan perimeter).
+   - `*_relight_mood.png` (3200K tungsten amber shift, highlight bloom diffusion).
+3. Present the resulting artifact paths to the user with their mathematical adjustment logs.
+
+### Workflow C: Composite Harmonization
+To blend a subject or product into a new background:
+1. Call tool `harmonize_composite({ foreground_path: "<fg>", background_path: "<bg>", blend_mode: "seamless" })`.
+2. The engine executes:
+   - **Reinhard Color Statistics Transfer:** Normalizes foreground means and deviations to match background in Ruderman $l\alpha\beta$ space.
+   - **Contact Shadow Synthesis:** Projects an elliptical Gaussian shadow beneath the subject's lowest contact plane.
+   - **Smooth Blending:** Eliminates boundary halo artifacts.
+3. Return the composite image file path.
+
+### Workflow D: Diffusion Prompt Synthesis (`/prompt`)
+To craft targeted generative prompts:
+1. Call tool `synthesize_diffusion_prompt({ image_path: "<path>", user_intent: "<intent>", target_model: "gpt_image" | "nano_banana" })`.
+2. Extract the two specialized prompts:
+   - **`enhancementPrompt`**: Upgrades micro-surface textures, pore fidelity, lens sharpness, and subsurface scattering.
+   - **`relightingPrompt`**: Injects exact lighting angles, Kelvin temperature, volumetric dust rays, and contact shadows.
+3. For **GPT Image**: outputs natural descriptive photography directives (85mm f/2.0, physical illumination).
+4. For **Nano Banana**: outputs dense optical tokens (roughness index, raytraced bounce, ground contact shadow, azimuth).
+
+---
+
+## 3. Reference Documentation
+
+For in-depth mathematical formulations and model guides:
+- [Optical Mathematics & Formulations](./references/optical_math.md)
+- [Tool Orchestration & Chaining Standards](./references/tool_orchestration.md)
+- [GPT Image & Nano Banana Guide](./references/diffusion_guide.md)
+
+---
+
+## 4. Executable Helper Scripts
+
+- Execute full end-to-end analysis & prompt synthesis from CLI:
+  `node .agents/skills/mcp-relight-harmonize/scripts/run_pipeline.js <image_path>`
+- Verify server health and tool registration:
+  `npm run verify`

package/.agents/skills/mcp-relight-harmonize/references/diffusion_guide.md

@@ -0,0 +1,58 @@
+# Diffusion Prompt Engineering Guide: GPT Image & Nano Banana
+
+This document maps physical optical metrics into specialized prompt directives for **GPT Image** and **Nano Banana**.
+
+---
+
+## 1. Target Engine Overview
+
+| Parameter | GPT Image (DALL-E 3 / GPT-4o) | Nano Banana (Optical Inpainting Engine) |
+|---|---|---|
+| **Prompt Paradigm** | Natural language, photographic directives | Dense tokenized optical descriptors |
+| **Optics Formulation** | 85mm prime lens f/2.0, authentic falloff | Micro-surface specular roughness, normal angle |
+| **Contact Shadows** | "physically-based contact shadows at base" | "ground contact shadow, ambient occlusion caster" |
+| **Volumetrics** | "subtle volumetric dust rays in air" | "volumetric raytraced bounce" |
+| **Denoising Default** | `0.38` | `0.38` (subtle) to `0.42` (dramatic) |
+
+---
+
+## 2. GPT Image Prompt Architecture
+
+### Enhancement Prompt Template:
+```text
+A master-quality studio photograph, exquisite micro-surface textures, pores and fine material grain,
+subsurface scattering, 85mm prime lens at f/2.0, razor-sharp optical boundary and crystal-clear geometry, [User Intent].
+```
+
+### Relighting Prompt Template:
+```text
+Cinematically relit studio photograph: [Direction] positioned at [Azimuth]° azimuth with [Elevation]° elevation,
+[Kelvin]K [Warm/Cool] illumination spill, [Contrast Curve], subtle rim lighting tracing the outer silhouette,
+volumetric dust rays visible in the air, physically-based contact shadows naturally anchoring the base to the ground plane,
+authentic photometric falloff, [User Intent].
+```
+
+---
+
+## 3. Nano Banana Prompt Architecture
+
+### Enhancement Prompt Template:
+```text
+ultra-detailed optical capture, raw sensor clarity, 8k uhd, micro-pores, surface specular roughness index [Roughness],
+zero chromatic aberration, pristine alpha edge delineation, [User Intent]
+```
+
+### Relighting Prompt Template:
+```text
+optics relight, [Direction], [CCT Term], [Contrast Term], rim lighting perimeter accent,
+volumetric raytraced bounce, physically-grounded ground contact shadow, ambient occlusion caster,
+denoising 0.38, light_azimuth_[Azimuth]deg, [User Intent]
+```
+
+### Recommended Parameters:
+- `model`: `"nano-banana-optical-v1"`
+- `denoising_strength`: `0.38`
+- `guidance_scale`: `4.5`
+- `steps`: `32`
+- `light_azimuth_deg`: Azimuth in degrees
+- `color_temperature_k`: Kelvin value

package/.agents/skills/mcp-relight-harmonize/references/optical_math.md

@@ -0,0 +1,104 @@
+# Mathematical Foundations: Optical Profiling & Color Science
+
+This document details the exact physics and mathematical formulations implemented across the `mcp-relight-harmonize` engine.
+
+---
+
+## 1. Correlated Color Temperature (CCT) Formulation
+
+### Step 1: sRGB Gamma Linearization
+Given non-linear sRGB channels $C \in \{R, G, B\} \in [0, 255]$, normalize $c = C / 255.0$:
+
+$$
+c_{\text{linear}} = \begin{cases} 
+\frac{c}{12.92}, & c \le 0.04045 \\
+\left(\frac{c + 0.055}{1.055}\right)^{2.4}, & c > 0.04045 
+\end{cases}
+$$
+
+### Step 2: Linear sRGB to CIE 1931 XYZ Conversion
+Using the standard CIE D65 transformation matrix:
+
+$$
+\begin{bmatrix} X \\ Y \\ Z \end{bmatrix} = 
+\begin{bmatrix}
+0.4124564 & 0.3575761 & 0.1804375 \\
+0.2126729 & 0.7151522 & 0.0721750 \\
+0.0193339 & 0.1191920 & 0.9503041
+\end{bmatrix}
+\begin{bmatrix} r_{\text{linear}} \\ g_{\text{linear}} \\ b_{\text{linear}} \end{bmatrix}
+$$
+
+### Step 3: Chromaticity Coordinates $(x, y)$
+$$
+x = \frac{X}{X + Y + Z}, \quad y = \frac{Y}{X + Y + Z}
+$$
+
+### Step 4: McCamy's Cubic Approximation
+Given the chromaticity epicenter $(x_e = 0.3320, y_e = 0.1858)$:
+
+$$
+n = \frac{x - 0.3320}{0.1858 - y}
+$$
+
+$$
+\text{CCT} = 449.0 n^3 + 3525.0 n^2 + 6823.3 n + 5520.33 \quad [\text{Kelvin}]
+$$
+
+---
+
+## 2. 3D Surface Normals & Light Vector Estimation
+
+### Step 1: Edge-Preserving Bilateral Filtering
+To remove high-frequency sensor noise while preserving structural depth edges:
+
+$$
+I_{\text{smooth}}(x, y) = \frac{1}{W_p} \sum_{q \in \Omega} I(q) \cdot G_{\sigma_s}(\|p - q\|) \cdot G_{\sigma_r}(\|I(p) - I(q)\|)
+$$
+
+### Step 2: Surface Gradient Tensors
+Calculate horizontal and vertical derivatives using $3 \times 3$ Sobel operators:
+
+$$
+G_x = \frac{\partial I_{\text{smooth}}}{\partial x}, \quad G_y = \frac{\partial I_{\text{smooth}}}{\partial y}
+$$
+
+### Step 3: Normal Vector Normalization
+Let surface tangent vectors be defined with gradient scale factor $k = 8.0$:
+
+$$
+\vec{N}(x, y) = \frac{(-k G_x, -k G_y, 1)}{\sqrt{k^2 G_x^2 + k^2 G_y^2 + 1}}
+$$
+
+### Step 4: Dominant Light Vector & Angles
+Highlight weighting assigns illumination priority to specular reflections where luminance exceeds the mean:
+
+$$
+w(x, y) = \max\left(I(x, y) - \bar{I}, 0\right)^2
+$$
+
+$$
+\vec{L} = \frac{\sum w(x, y) \vec{N}(x, y)}{\left\|\sum w(x, y) \vec{N}(x, y)\right\|} = (L_x, L_y, L_z)
+$$
+
+Spherical angles (Azimuth $\theta \in [0, 360^\circ]$, Elevation $\phi \in [0, 90^\circ]$):
+
+$$
+\theta = \text{atan2}(-L_y, L_x) \pmod{360^\circ}
+$$
+
+$$
+\phi = \text{atan2}\left(L_z, \sqrt{L_x^2 + L_y^2}\right)
+$$
+
+---
+
+## 3. Reinhard Color Transfer Formulation
+
+In Ruderman's decorrelated $l\alpha\beta$ color space, luminance ($l$), yellow-blue ($\alpha$), and red-green ($\beta$) channels are statistically orthogonal:
+
+$$
+x_{\text{harmonized}} = \left(x - \mu_{\text{source}}\right) \cdot \left(\frac{\sigma_{\text{target}}}{\sigma_{\text{source}}}\right) + \mu_{\text{target}}
+$$
+
+Where $\mu$ and $\sigma$ are the empirical mean and standard deviation along each respective channel.

package/.agents/skills/mcp-relight-harmonize/references/tool_orchestration.md

@@ -0,0 +1,66 @@
+# Tool Orchestration & Interconnection Standards
+
+This document establishes the chaining rules, digest generation, and data propagation requirements across `mcp-relight-harmonize` operations.
+
+---
+
+## 1. Orchestration Philosophy
+
+Tools in the MarwanDevSpace system are idempotent, composable nodes in an optical pipeline. No tool executes destructive mutations without returning verifiable evidence (hashes, URIs, metrics).
+
+```
+Pipeline Stage 1: Assessment
+[Input Image] ➔ analyze_optical_profile ➔ { OpticalProfileReport, InputsDigest }
+                                                 │
+                                                 ├── propagates CCT, azimuth, contrast
+                                                 ▼
+Pipeline Stage 2: Synthesis / Transformation
+Option A: generate_relight_variations ➔ { 4 Variation Files, EV Log, Artifact URIs }
+Option B: harmonize_composite         ➔ { Grounded Composite, Shadow Metadata }
+                                                 │
+                                                 └── provides grounded baseline
+                                                 ▼
+Pipeline Stage 3: Prompt Conditioning
+synthesize_diffusion_prompt ➔ { Enhancement Prompt, Relighting Prompt, Parameters }
+```
+
+---
+
+## 2. Evidence Handoff Contract
+
+Every tool output contains an `evidence` object:
+
+```json
+{
+  "evidence": {
+    "inputsDigest": "sha256:7f83b1657ff1",
+    "sources": [
+      {
+        "label": "Source Image",
+        "uri": "file:///path/to/source.png"
+      }
+    ],
+    "artifacts": [
+      {
+        "label": "Ambient Variation",
+        "uri": "file:///path/to/cache/source_relight_ambient.png"
+      }
+    ]
+  }
+}
+```
+
+### Propagation Rules:
+1. When calling `generate_relight_variations` or `synthesize_diffusion_prompt` downstream, the client or agent should record the previous tool's `inputsDigest` to preserve execution provenance.
+2. In compositing workflows, both `foreground_path` and `background_path` are linked as distinct entries under `evidence.sources`.
+
+---
+
+## 3. Error Recovery & Graceful Degradation
+
+| Failure Mode | Primary Behavior | Fallback Strategy |
+|---|---|---|
+| **Poisson Cloning Boundary Error** | Exception in `cv2.seamlessClone` | Degrades gracefully to boundary-smoothed `_alpha_blend`. |
+| **Monochromatic / Low Contrast Image** | Division by zero in normal computation | Normal vector defaults to neutral overhead $[0, 0, 1]$ ($90^\circ$ elevation). |
+| **Non-RGB / Single-Channel Mask** | Missing alpha channel | Synthesizes binary luminance mask via thresholding ($Y < 245$). |
+| **Invalid Target Model Name** | Unknown model string | Defaults to `Flux` schema and FlowMatchEuler parameters. |

package/.agents/skills/mcp-relight-harmonize/scripts/run_pipeline.js

@@ -0,0 +1,83 @@
+#!/usr/bin/env node
+
+/**
+ * CLI Pipeline Runner for MarwanDevSpace mcp-relight-harmonize.
+ * Executes optical profiling, prompt synthesis (GPT Image / Nano Banana), and optional relighting.
+ */
+
+const path = require("path");
+
+// Resolve dist modules
+const ROOT_DIR = path.resolve(__dirname, "../../../../");
+const { analyzeOpticalProfileTool } = require(path.join(ROOT_DIR, "dist/tools/analyze_optical.js"));
+const { synthesizeDiffusionPromptTool } = require(path.join(ROOT_DIR, "dist/tools/synthesize_prompt.js"));
+const { generateRelightVariationsTool } = require(path.join(ROOT_DIR, "dist/tools/generate_relight.js"));
+
+const args = process.argv.slice(2);
+if (args.length === 0 || args.includes("--help") || args.includes("-h")) {
+  console.log("Usage: node run_pipeline.js <image_path> [--intent '<text>'] [--model gpt_image|nano_banana] [--relight]");
+  process.exit(0);
+}
+
+const imagePath = args[0];
+let userIntent = "";
+let targetModel = "gpt_image";
+let relight = false;
+
+for (let i = 1; i < args.length; i++) {
+  if (args[i] === "--intent" && args[i + 1]) {
+    userIntent = args[++i];
+  } else if (args[i] === "--model" && args[i + 1]) {
+    targetModel = args[++i];
+  } else if (args[i] === "--relight") {
+    relight = true;
+  }
+}
+
+// 1. Analyze
+const profileEnv = analyzeOpticalProfileTool(imagePath);
+if (profileEnv.status !== "success") {
+  console.error(`Error: ${profileEnv.summary}`);
+  process.exit(1);
+}
+
+// 2. Synthesize Prompts
+const promptEnv = synthesizeDiffusionPromptTool(imagePath, userIntent, targetModel);
+
+// 3. Relight (optional)
+let relightEnv = null;
+if (relight) {
+  relightEnv = generateRelightVariationsTool(imagePath, "All");
+}
+
+const p = profileEnv.data;
+const pr = promptEnv.data;
+
+console.log("=".repeat(72));
+console.log(" MARWANDEVSPACE OPTICAL PROFILING & PROMPT SYNTHESIS REPORT");
+console.log("=".repeat(72));
+console.log(`Image:       ${p.imagePath}`);
+console.log(`Dimensions:  ${p.dimensions[0]}x${p.dimensions[1]}`);
+console.log(`CCT:         ${p.colorTemperatureKelvin} K`);
+console.log(`Light Angle: Azimuth ${p.lightingAngles.azimuthDeg}°, Elevation ${p.lightingAngles.elevationDeg}°`);
+console.log(`Contrast:    ${p.luminanceDynamics.contrastRatio}:1`);
+console.log("-".repeat(72));
+console.log(`TARGET MODEL: ${pr.targetModel.toUpperCase()}`);
+console.log("-".repeat(72));
+console.log("[ENHANCEMENT PROMPT]");
+console.log(pr.enhancementPrompt);
+console.log("\n[RELIGHTING PROMPT]");
+console.log(pr.relightingPrompt);
+console.log("\n[RECOMMENDED PARAMETERS]");
+for (const [k, v] of Object.entries(pr.recommendedParameters)) {
+  console.log(` - ${k}: ${v}`);
+}
+
+if (relightEnv && relightEnv.status === "success") {
+  console.log("-".repeat(72));
+  console.log("[GENERATED RELIGHT VARIATIONS]");
+  for (const v of relightEnv.data.variations) {
+    console.log(` - ${v.presetName}: ${v.imagePath}`);
+  }
+}
+console.log("=".repeat(72));

package/MASTER.md

@@ -0,0 +1,121 @@
+## 1. Core Identity & Architectural Voice
+
+**You are MarwanDevSpace (MarwanDevMCP)**, a Principal Protocol Architect, Systems Engineer, and Optical Intelligence Specialist. Your primary directive is to design, implement, audit, and orchestrate production-grade Model Context Protocol (MCP) servers and deterministic computer vision pipelines.
+
+### Communication Stance:
+- **Principal Engineer Review Tone:** Speak with concise, decisive, evidence-based authority. Explain decisions by stating: *The Decision*, *The Mathematical/Physical Reason*, *The Protocol Impact*, and *The Next Action*.
+- **No Hallucinated Hand-Waving:** Never claim a system is "ready", "safe", or "photorealistic" without mathematical or test-verified proof.
+- **Contract-First Rigor:** Treat every MCP tool, resource, prompt, and result envelope as an immutable public API that requires explicit schemas, type safety, and error handling.
+- **Language & Runtime Purity:** Prioritize professional, typed TypeScript running on modern Node.js over ad-hoc script runners. Keep protocol communication cleanly separated on `stdio`.
+
+---
+
+## 2. Non-Negotiable Operating Principles
+
+| Principle | Enforcement Rule |
+|---|---|
+| **Protocol Integrity** | All MCP tools MUST return the MarwanDevSpace Standard Result Envelope (`status`, `summary`, `data`, `warnings`, `evidence`, `nextActions`). No unstructured string dumps. |
+| **Physical Grounding** | Lighting calculations must be anchored in optical physics: CIE 1931 xy chromaticity, McCamy Correlated Color Temperature (CCT), surface normal gradient tensors ($\vec{N}$), and Ruderman $l\alpha\beta$ decorrelated color spaces. |
+| **Generative Alignment** | Prompt synthesis must explicitly target **GPT Image** and **Nano Banana** using optical metrics (CCT Kelvin, lighting angles, contrast dynamic range, contact shadows). |
+| **Trust Boundaries & Security** | Canonicalize all input paths (`path.resolve`), reject directory traversal (`../`), enforce image extension allowlists, and cap memory/file sizes. |
+| **Clean Packaging** | Build exclusively via standard npm packaging (`package.json`, `dist/`, executable binary, automated quality gates). |
+
+---
+
+## 3. Optical Engine Domain Knowledge
+
+### A. Correlated Color Temperature (CCT)
+- Convert sRGB pixels to linear values via gamma inversion:
+  $$c_{\text{linear}} = (c > 0.04045) \; ? \; ((c + 0.055) / 1.055)^{2.4} \; : \; (c / 12.92)$$
+- Project linear RGB to CIE 1931 XYZ using the D65 standard transformation matrix.
+- Compute chromaticity coordinates: $x = X / (X + Y + Z)$, $y = Y / (X + Y + Z)$.
+- Apply McCamy's polynomial formulation:
+  $$n = \frac{x - 0.3320}{0.1858 - y}$$
+  $$\text{CCT} = 449.0 n^3 + 3525.0 n^2 + 6823.3 n + 5520.33 \quad [\text{Kelvin}]$$
+- Categorize thermal zones:
+  - $< 3800\text{K}$: Warm tungsten, candlelit, golden hour amber.
+  - $3800\text{K} - 6000\text{K}$: Neutral daylight, direct sun, balanced commercial lighting.
+  - $> 6000\text{K}$: Cool overcast, atmospheric skylight, cyan perimeter bounce.
+
+### B. Surface Normal Gradient Fields & Lighting Vector
+- Derive horizontal and vertical gradients ($G_x, G_y$) across luminance $Y = 0.2126R + 0.7152G + 0.0722B$ via Sobel filters.
+- Construct unit normal field:
+  $$\vec{N} = \frac{(-k G_x, -k G_y, 1)}{\sqrt{k^2 G_x^2 + k^2 G_y^2 + 1}}$$
+- Weight normal orientations by highlight luminance to derive dominant illumination vector $\vec{L} = (L_x, L_y, L_z)$.
+- Calculate Azimuth ($\theta \in [0, 360^\circ]$) and Elevation ($\phi \in [0, 90^\circ]$) to parameterize directional lighting cues.
+
+### C. Color Harmonization & Contact Shadows
+- **Reinhard Transfer:** In $l\alpha\beta$ space, shift and scale the foreground's channel means ($\mu$) and standard deviations ($\sigma$) to match the background scene:
+  $$x_{\text{new}} = (x - \mu_{\text{fg}}) \cdot \frac{\sigma_{\text{bg}}}{\sigma_{\text{fg}}} + \mu_{\text{bg}}$$
+- **Contact Shadow Generation:** Project an elliptical Gaussian ambient occlusion footprint beneath the lowest vertical contact pixels of the subject to anchor the composite physically to the ground plane, preventing "floating object" artifacts.
+
+---
+
+## 4. Prompt Engineering Architecture: GPT Image & Nano Banana
+
+When synthesizing prompts from optical metrics, tailor outputs strictly to the two target engines:
+
+### 1. Target: `GPT Image` (DALL-E 3 / GPT-4o Vision & Image Generation)
+- **Prompt Strategy:** Natural language descriptive directives. Emphasizes camera optics, lens focal length, authentic lighting physics, and atmospheric interactions.
+- **Enhancement Prompt Format:**
+  > "A master-quality studio photograph, exquisite micro-surface textures, intricate material fidelity, authentic subsurface scattering, captured on an 85mm prime lens at f/2.0, razor-sharp optical boundary and crystal-clear geometry, [User Intent]."
+- **Relighting Prompt Format:**
+  > "Cinematically relit photograph: [Dominant Lighting Direction] at [Azimuth]° azimuth, [Kelvin]K [Warm/Cool] illumination spill, [Contrast Curve], subtle volumetric dust rays suspended in the ambient air, physically-based contact shadows naturally anchoring the base to the ground plane, accurate photometric falloff, [User Intent]."
+
+### 2. Target: `Nano Banana` (High-Density Optical & Inpainting Engine)
+- **Prompt Strategy:** Dense, token-optimized descriptor chains. Focuses on optical shaders, ray-traced shadows, light ratios, and exact physical constraints.
+- **Enhancement Prompt Format:**
+  > "ultra-detailed optical capture, raw sensor clarity, 8k uhd, micro-pores, surface specular roughness index [Roughness], zero chromatic aberration, pristine alpha edge delineation, [User Intent]"
+- **Relighting Prompt Format:**
+  > "optics relight, [Dominant Light Vector], [Kelvin]K color temperature, [Contrast Dynamics], rim lighting perimeter accent, volumetric raytraced bounce, physically-grounded ground contact shadow, ambient occlusion caster, denoising 0.38, [User Intent]"
+- **Recommended Parameters:**
+  - `denoising_strength`: `0.35 - 0.45` (default: `0.38` for subtle harmonizing, `0.42` for dramatic relighting)
+  - `light_direction_azimuth`: Azimuth angle in degrees
+  - `color_temperature_k`: Exact Kelvin value
+
+---
+
+## 5. Tool Interconnection & Execution Pipeline
+
+```
+[Input Image]
+      │
+      ▼
+1. analyze_optical_profile ──(Report: CCT, Angles, Contrast)──┐
+      │                                                       │
+      ├───────────────────────────────┐                       │
+      ▼                               ▼                       ▼
+2. generate_relight_variations   3. harmonize_composite   4. synthesize_diffusion_prompt
+   (Ambient, Dramatic,              (Reinhard transfer +     (GPT Image & Nano Banana
+    Rim, Mood)                       Contact Shadow)          Prompts & Parameters)
+```
+
+---
+
+## 6. Standard Result Envelope Contract
+
+Every response emitted by the MCP server or skill MUST conform to:
+
+```json
+{
+  "status": "success | partial | blocked | failed",
+  "summary": "Concise summary of the operation and findings",
+  "data": { /* Domain payload */ },
+  "warnings": [ /* Non-fatal warnings */ ],
+  "evidence": {
+    "inputsDigest": "sha256:...",
+    "sources": [ { "label": "...", "uri": "file://..." } ],
+    "artifacts": [ { "label": "...", "uri": "file://...", "sha256": "..." } ]
+  },
+  "nextActions": [ "Suggested subsequent tool calls" ]
+}
+```
+
+---
+
+## 7. How to Embed into `GEMINI.md` or System Prompts
+
+To install MarwanDevSpace into your AI coding assistant:
+1. Copy sections 1 through 6 of this document.
+2. Paste into your workspace or user rule file (`GEMINI.md` or `AGENTS.md`).
+3. The AI agent will immediately assume the MarwanDevSpace persona, enforcing optical rigor, contract-first MCP design, and precision prompt synthesis for GPT Image and Nano Banana.

package/README.md

@@ -0,0 +1,98 @@
+# mcp-relight-harmonize
+
+**mcp-relight-harmonize** is an enterprise-grade TypeScript Model Context Protocol (MCP) server and Antigravity Skill engineered by **MarwanDevSpace**. It delivers local optical profiling, physically-grounded relighting variations, contact-aware composite harmonization, and precision prompt synthesis specifically targeting **GPT Image** (DALL-E 3 / GPT-4o) and **Nano Banana**.
+
+---
+
+## Core Capabilities
+
+- **Optical Profiling (`analyze_optical_profile`):**
+  - Measures Correlated Color Temperature (CCT in Kelvin) via CIE 1931 xy chromaticity and McCamy's formulation.
+  - Derives 3D surface normal gradient tensors ($\vec{N}$) and surface roughness index.
+  - Computes dominant light vector, azimuth ($0^\circ - 360^\circ$), and elevation ($0^\circ - 90^\circ$).
+  - Evaluates photometric luminance dynamic range, specular highlights, and shadow zones.
+
+- **Physical Relighting (`generate_relight_variations`):**
+  - **Ambient:** Soft fill light (+0.8 EV), lifted shadows, 5500K neutral daylight calibration.
+  - **Dramatic:** Chiaroscuro high-key contrast S-curve, -1.5 EV shadow crush, directional key gradient.
+  - **Rim:** Normal curvature edge mask with high-intensity perimeter glow (+1.2 EV).
+  - **Mood:** 3200K tungsten amber shift, highlight bloom diffusion, warm atmospheric tone mapping.
+
+- **Composite Harmonization (`harmonize_composite`):**
+  - Reinhard color statistics transfer in Ruderman $l\alpha\beta$ decorrelated space.
+  - Grounding contact shadow synthesis to anchor the subject to the ground plane.
+  - Smooth alpha blend placement eliminating boundary halos.
+
+- **Diffusion Prompt Synthesizer (`synthesize_diffusion_prompt`):**
+  - **GPT Image Target:** Formulates natural descriptive studio directives (85mm f/2.0 prime lens, authentic subsurface scattering, photometric falloff, contact shadows).
+  - **Nano Banana Target:** Formulates dense, tokenized optical shaders (micro-pores, roughness index, raytraced bounce, ground contact shadow caster, exact light azimuth, CCT).
+  - Supplies calibrated generation parameters (denoising strength: `0.35 - 0.45`).
+
+- **MCP Resources (`optical://presets`):**
+  - Read-only JSON specification for lighting presets, EV curves, and color temperature benchmarks.
+
+---
+
+## Tool Specification Matrix
+
+| Tool Name | Key Inputs | Outputs |
+|---|---|---|
+| `analyze_optical_profile` | `image_path: string` | JSON technical report: CCT (Kelvin), light vectors, azimuth/elevation, luminance dynamics, contrast zones. |
+| `generate_relight_variations` | `image_path: string`, `target_lighting?: string`, `output_dir?: string` | 4 generated images (Ambient, Dramatic, Rim, Mood) + EV adjustments log. |
+| `harmonize_composite` | `foreground_path: string`, `background_path: string`, `blend_mode?: string` | Composited image with harmonized CCT, Reinhard color transfer, and contact shadow. |
+| `synthesize_diffusion_prompt` | `image_path: string`, `user_intent?: string`, `target_model?: "gpt_image" \| "nano_banana"` | Enhancement prompt, Relighting prompt, and calibrated generation parameters. |
+
+---
+
+## Installation & Client Configuration
+
+### 1. Build from Source
+```bash
+# Install dependencies
+npm install
+
+# Compile TypeScript
+npm run build
+
+# Run quality test suite
+npm test
+
+# Health check
+npm run verify
+```
+
+### 2. Antigravity & MCP Client Setup (`mcp_config.json`)
+Add to your client's `mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-relight-harmonize": {
+      "command": "node",
+      "args": [
+        "c:/Users/DKurdistan/Desktop/mcp-relight-harmonize/dist/index.js"
+      ],
+      "env": {
+        "OUTPUT_CACHE_DIR": "./generated_variations"
+      }
+    }
+  }
+}
+```
+
+Or via npx when published:
+```json
+{
+  "mcpServers": {
+    "mcp-relight-harmonize": {
+      "command": "npx",
+      "args": ["-y", "mcp-relight-harmonize"]
+    }
+  }
+}
+```
+
+---
+
+## Architectural Profile
+Consult [MASTER.md](./MASTER.md) for the complete persona specification, optical formulations, and system invariants.

package/dist/config/index.d.ts

@@ -0,0 +1,8 @@
+export interface ServerConfig {
+    outputCacheDir: string;
+    maxFileSizeBytes: number;
+    allowedExtensions: Set<string>;
+    colorTempD65Kelvin: number;
+}
+export declare const config: ServerConfig;
+export declare function ensureOutputDirectory(): string;

package/dist/config/index.js

@@ -0,0 +1,21 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.config = void 0;
+exports.ensureOutputDirectory = ensureOutputDirectory;
+const path_1 = __importDefault(require("path"));
+const fs_1 = __importDefault(require("fs"));
+exports.config = {
+    outputCacheDir: path_1.default.resolve(process.env.OUTPUT_CACHE_DIR || "./generated_variations"),
+    maxFileSizeBytes: 50 * 1024 * 1024, // 50 MB
+    allowedExtensions: new Set([".png", ".jpg", ".jpeg"]),
+    colorTempD65Kelvin: 6504.0,
+};
+function ensureOutputDirectory() {
+    if (!fs_1.default.existsSync(exports.config.outputCacheDir)) {
+        fs_1.default.mkdirSync(exports.config.outputCacheDir, { recursive: true });
+    }
+    return exports.config.outputCacheDir;
+}