mcp-relight-harmonize
This server provides deterministic optical analysis and physical layer decomposition of images, plus tools for relighting, compositing, and generating AI image prompts.
Analyze optical profiles: Extract metrics like color temperature (Kelvin), lighting angles, luminance dynamics, contrast zones, and surface roughness; optionally decompose into 6 visual layers (highlights, shadows, ambient occlusion, edges, depth normals, chroma/saturation).
Generate relight variations: Create four physically grounded lighting presets (Ambient, Dramatic, Rim, Mood) as local image files with exposure and color adjustments.
Harmonize composites: Blend a foreground subject into a background scene using color transfer, temperature matching, and synthesized contact shadows.
Synthesize diffusion prompts: Produce dual-format generative prompts (detailed JSON specification + descriptive master prompt) tailored for universal image generators or GEMINI Nano Banana.
List cached variations: Inventory and retrieve previously generated relight images and composite files from the local cache directory.
Provides integration with Google's AI image generation models (e.g., GEMINI Nano Banana) via Google Antigravity, enabling direct application of relighting and harmonization through generated images.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-relight-harmonize harmonize my subject with the new background"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
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. NoVariations/orgenerated_variations/directories are ever created.Python never creates the final modified image.
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.
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.
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 |
| طبقة الألوان الفاتحة: Isolates specular highlights ($Y > 170/255$). Inspected for glint locations and clipping prevention. |
2 |
| طبقة الألوان الغامقة: Isolates low-key values ($Y < 85/255$). Inspected for shadow density and photometric roll-off. |
3 |
| طبقة الظل العالي والارتكاز: Isolates contact umbra ($Y < 35/255$). Inspected to anchor base plane and prevent floating subjects. |
4 |
| طبقة الحواف والتفاصيل: Sobel gradient magnitude ($M = \sqrt{G_x^2 + G_y^2}$). Inspected for micro-texture and surface roughness. |
5 |
| طبقة العمق والمتجهات: Tangent space normal map ($R=N_x, G=N_y, B=N_z$). Inspected for 3D light vector and volumetric volume. |
6 |
| طبقة الألوان والتشبع: HSV chroma purity distribution. Inspected for color casts and spectral balance. |
Tool Specification Matrix
Tool Name | Key Inputs | Outputs |
|
| Mathematical optical metrics, 6 visual layers in |
|
| Dual Prompts: Detailed JSON Specification + Accurate General Descriptive Master Prompt. |
|
| Physical relit images saved into |
|
| Composited image with harmonized CCT, Reinhard color transfer, and contact shadow. |
|
| Inventory of generated layers and artifacts in the |
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 verify2. 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-harmonizeLicense
MIT © MarwanDevSpace
Available Tools
5 toolsanalyze_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
Scored across 5 tools
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.
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.
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.
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
Related MCP Connectors
Generate and edit images (PNG, transparent, GIF, SVG) with GPT Image and Nano Banana models.
AI photoshoot studio: garments, avatars, locations, and art direction
Generate images with GPT Image 2, Nano Banana Pro and more, placed on your Banana Art Lab canvas.
Run AI-powered analysis on images including moderation, captioning, tagging, and more.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables AI-powered image analysis using OpenAI's Vision API and image generation with DALL-E models. Supports image description, content analysis, comparison, editing, and creating variations with intelligent caching.3MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI agents to analyze images and videos, and generate optimized prompts for AI video generation systems.MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to analyze design images for composition, color harmony, typography, and accessibility compliance with actionable recommendations.66MIT
- FlicenseNot gradedqualityDmaintenanceProvides Claude with detailed image inspection capabilities, including metadata extraction, histogram analysis, tonal and color analysis, sharpness detection, and more, supporting both standard and RAW formats.7-