Skip to main content
Glama

MCP Relight & Harmonize Server

A production-grade, highly-deterministic Model Context Protocol (MCP) server engineered for optical profiling, physical decomposition into 6 visual layers, contact-aware composite harmonization, and dual-format generative prompt synthesis (Detailed JSON + Accurate Master Prompt).

Model Architecture Note: Fully compatible with Any Image Generator Model, with dedicated targets for Universal Image Generator and GEMINI Nano Banana.
Environment Recommendation: Preferred and optimized for use inside Google Antigravity, where native direct visual generation (generate_image) allows zero-friction, instantaneous application of the learned optical layers!


Architectural Principles & Strict Role Separation

  1. Python Role: Optical Extraction & Layer Decomposition Only:

    • Python executes purely deterministic mathematical and optical analysis.

    • Generates exactly 6 visual decomposition layers into the Layers/ directory.

    • Directory Invariant: The server exclusively uses the Layers/ directory. No Variations/ or generated_variations/ directories are ever created.

    • Python never creates the final modified image.

  2. Mandatory Image-by-Image Vision Analysis (Analyze):

    • The AI Assistant must never trigger image generation until it inspects and analyzes the 6 images in Layers/ image-by-image (صورة صورة).

    • Zero canned or pre-written text: All observations and insights stem directly from visual inspection of the actual layer images.

  3. Dual-Format Generative Prompts (Two Formats):

    • Format 1: Detailed JSON Specification (detailedJsonSpecification): Comprehensive structured optical physics (Kelvin, azimuth, elevation, contrast ratio, roughness, contact shadow) and layer-by-layer directives for the generator.

    • Format 2: Accurate General Descriptive Master Prompt (masterDescriptivePrompt): Photorealistic studio photographic narrative integrating the user's intent with physical lighting and an 85mm prime lens at f/2.0.

  4. Direct Execution via AI Image Generator:

    • Once the user answers "ماذا تريد من تعديل؟", the modification is rendered directly through the Image Generator (such as generate_image / GEMINI Nano Banana in Antigravity).


Related MCP server: Enhanced Multimedia Analysis MCP

The 6 Physical Visual Layers (Layers/)

#

Layer Image File

Physical Objective & Inspection Target

1

01_highlights.png

طبقة الألوان الفاتحة: Isolates specular highlights ($Y > 170/255$). Inspected for glint locations and clipping prevention.

2

02_shadows.png

طبقة الألوان الغامقة: Isolates low-key values ($Y < 85/255$). Inspected for shadow density and photometric roll-off.

3

03_ambient_occlusion.png

طبقة الظل العالي والارتكاز: Isolates contact umbra ($Y < 35/255$). Inspected to anchor base plane and prevent floating subjects.

4

04_edges.png

طبقة الحواف والتفاصيل: Sobel gradient magnitude ($M = \sqrt{G_x^2 + G_y^2}$). Inspected for micro-texture and surface roughness.

5

05_depth_normals.png

طبقة العمق والمتجهات: Tangent space normal map ($R=N_x, G=N_y, B=N_z$). Inspected for 3D light vector and volumetric volume.

6

06_chroma_saturation.png

طبقة الألوان والتشبع: HSV chroma purity distribution. Inspected for color casts and spectral balance.


Tool Specification Matrix

Tool Name

Key Inputs

Outputs

analyze_optical_profile

image_path: string, extract_layers?: boolean, layers_dir?: string, user_intent?: string

Mathematical optical metrics, 6 visual layers in Layers/, and dynamic Layer.md.

synthesize_diffusion_prompt

image_path: string, user_intent?: string, target_model?: "universal" | "nano_banana"

Dual Prompts: Detailed JSON Specification + Accurate General Descriptive Master Prompt.

generate_relight_variations

image_path: string, target_lighting?: string, output_dir?: string

Physical relit images saved into Layers/ (Ambient, Dramatic, Rim, Mood).

harmonize_composite

foreground_path: string, background_path: string, blend_mode?: string

Composited image with harmonized CCT, Reinhard color transfer, and contact shadow.

list_cached_variations

cache_dir?: string

Inventory of generated layers and artifacts in the Layers/ directory.


Installation & Client Configuration

1. Build from Source

# 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:

{
  "mcpServers": {
    "mcp-relight-harmonize": {
      "command": "node",
      "args": [
        "c:/Users/DKurdistan/Desktop/mcp-relight-harmonize/dist/index.js"
      ],
      "env": {
        "OUTPUT_CACHE_DIR": "./Layers"
      }
    }
  }
}

Or via npx:

{
  "mcpServers": {
    "mcp-relight-harmonize": {
      "command": "npx",
      "args": ["-y", "mcp-relight-harmonize@latest"]
    }
  }
}

3. Docker Deployment (Glama Standard)

# Build image locally
docker build -t mcp-relight-harmonize .

# Run container over stdio
docker run -i --rm -e OUTPUT_CACHE_DIR=/app/Layers mcp-relight-harmonize

License

MIT © MarwanDevSpace

Available Tools

5 tools
analyze_optical_profileA

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.

• 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. • 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. • 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. • 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'). • Alternatives: Use 'generate_relight_variations' for creative lighting styles, or 'synthesize_diffusion_prompt' for model prompts.

Inputs: image_path (required), layers_dir, user_intent, extract_layers. Returns: data, status, summary, evidence, +2 more

generate_relight_variationsA

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.

• 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. • 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. • When to use: Use when you need tangible image alternatives of a photo or product render with alternative lighting schemes. • 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'). • Alternatives: Use 'synthesize_diffusion_prompt' for your Image Generator (GEMINI Nano Banana / Universal), or 'list_cached_variations' to browse existing outputs.

Inputs: image_path (required), output_dir, target_lighting. Returns: data, status, summary, evidence, +2 more

harmonize_compositeA

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.

• 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. • Behavior: Mutates filesystem by writing 1 composited PNG image to the output cache directory. Deterministic, local execution, no network egress, no authentication required. • 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. • 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'). • Alternatives: Use 'generate_relight_variations' to alter lighting on a single image, or 'synthesize_diffusion_prompt' to craft inpainting prompts for seam blending.

Inputs: background_path (required), foreground_path (required), blend_mode. Returns: data, status, summary, evidence, +2 more

list_cached_variationsA

List and inspect all previously generated relight variation images and harmonized composite files stored in the output cache directory.

• Purpose: Cache inventory and artifact retrieval. Resolves pipeline completeness by allowing callers to discover, verify, and retrieve generated files without manual filesystem traversal. • Behavior: Completely read-only, queries local filesystem cache directory, no network calls, no authentication required. • 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. • When NOT to use: Do NOT use to generate new images (use 'generate_relight_variations') or to analyze optical metrics (use 'analyze_optical_profile'). • Alternatives: Use 'generate_relight_variations' to create new images, or 'harmonize_composite' to merge cutouts.

Inputs: cache_dir. Returns: data, status, summary, evidence, +2 more

synthesize_diffusion_promptA

Synthesize precision enhancement and relighting diffusion prompts based on physical optical analysis of an image, compatible with Any Image Generator Model (optimized for GEMINI 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).

• 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 Any Image Generator (optimized for Antigravity). • Behavior: Completely read-only, deterministic, zero filesystem modifications, no network calls, and no authentication required. • When to use: Use when you want to feed photorealistic lighting directives or inpainting prompts into your Image Generator or Antigravity's generate_image. • 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'). • Alternatives: Use 'generate_relight_variations' for instant offline image files, or 'analyze_optical_profile' for raw numerical statistics.

Inputs: image_path (required), user_intent, target_model. Returns: data, status, summary, evidence, +2 more

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.7/5.0

    Scored across 5 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: analyze_optical_profile is read-only diagnostics, generate_relight_variations creates local images, synthesize_diffusion_prompt generates AI prompts, harmonize_composite blends two images, and list_cached_variations lists artifacts. The descriptions explicitly cross-reference and differentiate each tool, leaving no ambiguity.

    Naming Consistency5/5

    All tool names follow a consistent verb_noun snake_case pattern: analyze_, generate_, synthesize_, harmonize_, list_. The verbs are descriptive and match the action, and the objects are specific. No deviations or mixed conventions.

    Tool Count5/5

    Five tools is well-scoped for this domain, covering analysis, generation, prompt synthesis, compositing, and artifact listing. Each tool earns its place and there is no bloat or unnecessary overlap.

    Completeness5/5

    The tool surface covers the full lifecycle of relighting and harmonization: analyze a source image, generate variations, synthesize prompts, composite cutouts, and list results. There are no obvious dead ends or missing operations for the stated purpose.

    Maintenance

    ActivityStale
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers