This MCP server provides tools for optical image analysis, physically-based relighting, composite harmonization, and diffusion prompt synthesis.
analyze_optical_profile: Extract CCT (Kelvin), dominant light vectors, azimuth/elevation angles, luminance dynamic range, and surface roughness from an image.
generate_relight_variations: Generate 4 physically-grounded relit variations (Ambient, Dramatic, Rim, Mood) and save them to the output cache.
harmonize_composite: Composite a foreground onto a background using Reinhard color transfer, CCT matching, and contact shadow synthesis.
synthesize_diffusion_prompt: Produce enhancement and relighting prompts for GPT Image (DALL-E 3 / GPT-4o) and Nano Banana, including calibrated denoising parameters (0.35–0.45).
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 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.
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.
Related MCP server: Enhanced Multimedia Analysis MCP
Tool Name | Key Inputs | Outputs |
|
| JSON technical report: CCT (Kelvin), light vectors, azimuth/elevation, luminance dynamics, contrast zones. |
|
| 4 generated images (Ambient, Dramatic, Rim, Mood) + EV adjustments log. |
|
| Composited image with harmonized CCT, Reinhard color transfer, and contact shadow. |
|
| Enhancement prompt, Relighting prompt, and calibrated generation parameters. |
|
| Inventory of generated relight variations and composite artifacts in the output cache. |
# Install dependencies
npm install
# Compile TypeScript
npm run build
# Run quality test suite
npm test
# Health check
npm run verifymcp_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": "./generated_variations"
}
}
}
}Or via npx when published:
{
"mcpServers": {
"mcp-relight-harmonize": {
"command": "npx",
"args": ["-y", "mcp-relight-harmonize"]
}
}
}# Build image locally
docker build -t mcp-relight-harmonize .
# Run container over stdio
docker run -i --rm mcp-relight-harmonizeConsult MASTER.md for the complete persona specification, optical formulations, and system invariants.
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.
• 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. • Behavior: Completely read-only, deterministic, zero filesystem modifications, no network egress, and no authentication required. • When to use: Use as the prerequisite first step before relighting, inpainting, or compositing an image to inspect baseline lighting conditions. • 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'). • Alternatives: Use 'generate_relight_variations' for visual lighting files, or 'synthesize_diffusion_prompt' for model prompts.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Absolute or workspace-relative path to a local image file (.png, .jpg, or .jpeg). Must be an existing image under 50 MB. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full behavioral burden and does so thoroughly: read-only, deterministic, zero filesystem modifications, no network egress, no authentication required. It also discloses that no image files are produced. This covers the safety and side-effect profile completely.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose in the first sentence, then structured into labeled bullets (Purpose, Behavior, When to use, When NOT to use, Alternatives). Well organized, though somewhat verbose with mild redundancy between the Purpose and Alternatives bullets.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter deterministic read tool with an output schema, the description provides everything needed: purpose, side-effect profile, prerequisites, and sibling routing. Return value details are appropriately left to the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single parameter is fully documented in the schema (path types, format, size limit). The description doesn't add parameter syntax beyond that, so it sits at the schema-done baseline, slightly elevated because the description frames the operational precondition (baseline inspection) that motivates supplying the path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description names a specific verb (Extract) and resource (physical optical metrics from an image), then enumerates the exact metrics returned (CCT, lighting vector, dynamic range, contrast zones, roughness index). It explicitly distinguishes itself from two siblings, generate_relight_variations and synthesize_diffusion_prompt, so an agent can route without opening either schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use (prerequisite first step before relighting, inpainting, compositing) and when not to use with named sibling alternatives for each exclusion case. The Alternatives section reinforces the routing. This is about as complete as usage guidance gets.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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 text prompts targeting GPT Image or Nano Banana, or 'list_cached_variations' to browse existing outputs.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to the input image (.png, .jpg, .jpeg) to relight. | |
| output_dir | No | Destination folder for generated variation image files. If omitted, defaults to the server's configured cache directory ('./generated_variations'). | |
| target_lighting | No | 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'. | All |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does so thoroughly: it discloses filesystem mutation (creating up to 4 files), the overwrite-on-rerun hazard, determinism, unmetered local compute, no network egress, and no authentication requirement. This is precisely the mutation/reversibility/permission context an agent needs for a write tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the outcome and variants, then organized into labelled bullets that each carry distinct routing or behavioral content. It is somewhat long and the 'Purpose: Visual image transformation' line is mildly redundant with the opening sentence, but overall the structure is efficient and scannable.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
An output schema exists, so return values need not be explained, and the description covers the remaining gaps: what gets written, where, the default output location via output_dir, the overwrite semantics, and the compute/auth profile. An agent has everything needed to invoke this correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, including per-enum EV and color-temperature details, so the schema already documents all three parameters. The description's lighting names and adjustment-log mention largely restate what the schema enumerates, adding no format or constraint detail beyond it. Baseline 3 applies when the schema does the heavy lifting.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence names a specific verb (Generate) and resource (relit image variations on disk), enumerates the four concrete variants produced, and states the auxiliary output (mathematical adjustment logs). It explicitly contrasts itself with analyze_optical_profile and synthesize_diffusion_prompt, so an agent can distinguish it from every relevant sibling without opening a schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use', an enumerated 'When NOT to use' with the correct alternative named for each excluded case (analyze_optical_profile, harmonize_composite, synthesize_diffusion_prompt), and a dedicated Alternatives section including list_cached_variations. Nothing about tool selection is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| blend_mode | No | Blending mode: 'seamless' (applies Reinhard color transfer + contact shadow + alpha blend) or 'alpha' (standard alpha composite with contact shadow only). Defaults to 'seamless'. | seamless |
| background_path | Yes | Path to target background scene image (.png, .jpg, .jpeg). | |
| foreground_path | Yes | Path to foreground subject image. Supports transparent PNG (with alpha channel) or solid background. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden and it does so: it declares the mutation (writes 1 composited PNG to the output cache directory), determinism, local execution, no network egress, and no authentication required. This is precisely the behavioral profile an agent needs for a filesystem-mutating tool.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the one-line purpose, then well-organized labelled sections. It is somewhat long, and the bullet labels read a bit like documentation scaffolding, but every sentence earns its place and nothing is wasted.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a two-image, filesystem-mutating tool with 100% schema coverage and an output schema, the description is complete: purpose, behavior, selection criteria, and alternatives are all present, and return-value explanation is unnecessary given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the baseline is 3. The description adds meaningful context beyond the schema by naming the algorithms (Reinhard transfer in decorrelated lαβ space, background color temperature matching, contact shadows), which explains what 'seamless' actually does and why the foreground can be either transparent PNG or solid background.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (harmonize/composite) and resource (foreground cutout onto background scene), and the opening line names the actual technique. It explicitly distinguishes itself from the sibling 'generate_relight_variations' as a two-image tool versus a single-image tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use', 'When NOT to use', and 'Alternatives' sections name three sibling tools and the exact conditions that select each. An agent can route correctly without opening any schema.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| cache_dir | No | Optional custom directory path to inspect. If omitted, uses server's default cache directory. |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations present, the description must carry the behavioral burden, and it does well: 'Completely read-only,' 'no network calls,' 'no authentication required,' and the filesystem-local scope are all stated. It stops short of describing pagination, ordering, or what happens on a missing/empty cache directory.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The prose lead is front-loaded and each bulleted section is on-topic, though the Purpose/Behavior/When-to-use/When-NOT/Alernatives scaffolding is heavier than strictly needed for a one-parameter read-only lister. Nothing is redundant, but it is slightly verbose.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only list tool with a fully documented single parameter and an output schema present, the description covers purpose, safety traits, triggering conditions, and sibling routing. An agent has everything needed to call it correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% and the single 'cache_dir' parameter is fully documented in the schema, including its default and fallback behavior, so the baseline is 3. The description adds no syntax or format detail beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The opening sentence states a specific verb ('List and inspect') and resource ('relight variation images and harmonized composite files in the output cache'), and the 'Purpose' bullet reinforces it as 'Cache inventory and artifact retrieval.' It is clearly distinguishable from siblings that generate or analyze images.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit 'When to use' names the producing siblings ('generate_relight_variations', 'harmonize_composite') and the triggering condition; 'When NOT to use' names alternatives for generation and analysis with the correct sibling per rejected intent. Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
• 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. • 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 GPT Image or Nano Banana. • 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.
| Name | Required | Description | Default |
|---|---|---|---|
| image_path | Yes | Path to the local reference image (.png, .jpg, .jpeg) to extract optical geometry from. | |
| user_intent | No | Optional creative context or scenario description (e.g., 'golden sunset portrait', 'cyberpunk studio product'). | |
| target_model | No | 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'. | gpt_image |
| Name | Required | Description |
|---|---|---|
| data | Yes | |
| status | Yes | Execution status. |
| summary | Yes | Human-readable executive summary of the operation. |
| evidence | Yes | |
| warnings | Yes | Non-fatal warnings if applicable. |
| nextActions | Yes | Actionable follow-up guidance. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations at all, the description carries the full burden and discharges it: read-only, deterministic, zero filesystem modifications, no network calls, no authentication required. It also discloses the output shape (photorealistic prompt text plus calibrated denoising parameters 0.35-0.45), which is behavioral context beyond a plain read.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Front-loaded with the core purpose, then cleanly bulleted by Purpose/Behavior/When-to-use/Alternatives. Slightly verbose and partly restates schema-level enum detail, but no sentence is wasted and the structure is easy to scan.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a 3-parameter, read-only synthesis tool with an output schema present, the description supplies everything an agent needs: purpose, side-effect profile, selection criteria, and sibling routing. Return-value explanation is unnecessary given the output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so image_path, user_intent, and target_model are already documented with examples and enum semantics in the schema. The description reinforces the output character for each target model but adds little parameter syntax or format detail beyond what the schema already provides; baseline 3 applies.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
States a specific verb (synthesize) and resource (diffusion prompts from physical optical analysis) and names the target engines. It explicitly distinguishes itself from siblings such as generate_relight_variations and analyze_optical_profile, so an agent can route without opening any schema.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Provides explicit 'When to use', 'When NOT to use', and 'Alternatives' sections naming concrete siblings for each condition (generate_relight_variations for local rendering, harmonize_composite for local merging, analyze_optical_profile for raw stats). Nothing is left to inference.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v1.0.2analyze_optical_profile2 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Absolute or workspace-relative path to the image file."New value: +"Absolute or workspace-relative path to a local image file (.png, .jpg, or .jpeg). Must be an existing image under 50 MB."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "colorTemperatureKelvin": {
+ "description": "Correlated Color Temperature (CCT) in Kelvin.",
+ "type": "number"
+ },
+ "contrastZones": {
+ "properties": {
+ "deepShadowsPct": {
+ "type": "number"
+ },
+ "midtonesPct": {
+ "type": "number"
+ },
+ "specularHighlightsPct": {
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "dimensions": {
+ "description": "[width, height] in pixels.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
+ "dominantLightDirectionVector": {
+ "description": "Normalized [X, Y, Z] vector.",
+ "items": {
+ "type": "number"
+ },
+ "type": "array"
+ },
+ "imagePath": {
+ "description": "Canonical resolved file path.",
+ "type": "string"
+ },
+ "lightingAngles": {
+ "properties": {
+ "azimuthDeg": {
+ "description": "Horizontal angle (0-360°).",
+ "type": "number"
+ },
+ "elevationDeg": {
+ "description": "Vertical elevation angle (0-90°).",
+ "type": "number"
+ }
+ },
+ "required": [
+ "azimuthDeg",
+ "elevationDeg"
+ ],
+ "type": "object"
+ },
+ "luminanceDynamics": {
+ "properties": {
+ "contrastRatio": {
+ "type": "number"
+ },
+ "max": {
+ "type": "number"
+ },
+ "median": {
+ "type": "number"
+ },
+ "min": {
+ "type": "number"
+ },
+ "p5": {
+ "type": "number"
+ },
+ "p95": {
+ "type": "number"
+ }
+ },
+ "type": "object"
+ },
+ "meanLuminance": {
+ "description": "Average photometric luminance (0-255).",
+ "type": "number"
+ },
+ "opticalProfileSummary": {
+ "description": "Executive summary sentence.",
+ "type": "string"
+ },
+ "surfaceNormalVariation": {
+ "description": "Roughness metric (std dev of normals).",
+ "type": "number"
+ }
+ },
+ "required": [
+ "imagePath",
+ "dimensions",
+ "colorTemperatureKelvin",
+ "dominantLightDirectionVector",
+ "lightingAngles",
+ "meanLuminance",
+ "luminanceDynamics",
+ "contrastZones",
+ "surfaceNormalVariation",
+ "opticalProfileSummary"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}generate_relight_variations5 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Path to the source image."New value: +"Path to the input image (.png, .jpg, .jpeg) to relight."Input schema / properties / output_dir / defaultAdded value: +""Input schema / properties / output_dir / descriptionPrevious value: -"Custom output directory. If omitted, uses default cache directory."New value: +"Destination folder for generated variation image files. If omitted, defaults to the server's configured cache directory ('./generated_variations')."Input schema / properties / target_lighting / descriptionPrevious value: -"Lighting preset: 'Ambient', 'Dramatic', 'Rim', 'Mood', or 'All'."New value: +"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 schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "originalImage": {
+ "type": "string"
+ },
+ "outputDir": {
+ "type": "string"
+ },
+ "totalVariations": {
+ "type": "number"
+ },
+ "variations": {
+ "items": {
+ "properties": {
+ "adjustmentsApplied": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "evShiftStops": {
+ "type": "number"
+ },
+ "fileSizeBytes": {
+ "type": "number"
+ },
+ "imagePath": {
+ "type": "string"
+ },
+ "presetName": {
+ "type": "string"
+ },
+ "targetCctKelvin": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "presetName",
+ "imagePath",
+ "fileSizeBytes",
+ "evShiftStops",
+ "targetCctKelvin",
+ "adjustmentsApplied"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "originalImage",
+ "outputDir",
+ "totalVariations",
+ "variations"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}harmonize_composite4 fields changedInput schema / properties / background_path / descriptionPrevious value: -"Path to the background environment image."New value: +"Path to target background scene image (.png, .jpg, .jpeg)."Input schema / properties / blend_mode / descriptionPrevious value: -"Blending algorithm ('seamless' or 'alpha')."New value: +"Blending mode: 'seamless' (applies Reinhard color transfer + contact shadow + alpha blend) or 'alpha' (standard alpha composite with contact shadow only). Defaults to 'seamless'."Input schema / properties / foreground_path / descriptionPrevious value: -"Path to the foreground subject cutout (PNG/JPG)."New value: +"Path to foreground subject image. Supports transparent PNG (with alpha channel) or solid background."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "backgroundCctKelvin": {
+ "description": "Target background color temperature.",
+ "type": "number"
+ },
+ "backgroundPath": {
+ "type": "string"
+ },
+ "blendMode": {
+ "type": "string"
+ },
+ "compositeImagePath": {
+ "description": "Absolute path to the rendered composite file on disk.",
+ "type": "string"
+ },
+ "contactShadowApplied": {
+ "description": "True if contact shadow was synthesized at base.",
+ "type": "boolean"
+ },
+ "details": {
+ "type": "object"
+ },
+ "foregroundPath": {
+ "type": "string"
+ },
+ "luminanceScalingFactor": {
+ "type": "number"
+ }
+ },
+ "required": [
+ "compositeImagePath",
+ "blendMode",
+ "foregroundPath",
+ "backgroundPath",
+ "backgroundCctKelvin",
+ "luminanceScalingFactor",
+ "contactShadowApplied"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}list_cached_variationssynthesize_diffusion_prompt5 fields changedInput schema / properties / image_path / descriptionPrevious value: -"Path to the reference image."New value: +"Path to the local reference image (.png, .jpg, .jpeg) to extract optical geometry from."Input schema / properties / target_model / descriptionPrevious value: -"Target engine: 'gpt_image' (GPT Image) or 'nano_banana' (Nano Banana)."New value: +"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'."Input schema / properties / user_intent / defaultAdded value: +""Input schema / properties / user_intent / descriptionPrevious value: -"Creative intent (e.g. 'golden sunset', 'studio commercial')."New value: +"Optional creative context or scenario description (e.g., 'golden sunset portrait', 'cyberpunk studio product')."Output schema / (root)Previous value: -nullNew value: +{
+ "properties": {
+ "data": {
+ "properties": {
+ "enhancementPrompt": {
+ "description": "Prompt for micro-surface detail and lens clarity upgrade.",
+ "type": "string"
+ },
+ "opticalKeywordsUsed": {
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "recommendedParameters": {
+ "description": "Calibrated diffusion settings (denoising 0.35-0.45, etc.).",
+ "type": "object"
+ },
+ "relightingPrompt": {
+ "description": "Prompt for physical relighting with angles, CCT, and contact shadows.",
+ "type": "string"
+ },
+ "targetModel": {
+ "enum": [
+ "GPT Image",
+ "Nano Banana"
+ ],
+ "type": "string"
+ },
+ "userIntent": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "targetModel",
+ "userIntent",
+ "enhancementPrompt",
+ "relightingPrompt",
+ "recommendedParameters",
+ "opticalKeywordsUsed"
+ ],
+ "type": "object"
+ },
+ "evidence": {
+ "properties": {
+ "artifacts": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ },
+ "inputsDigest": {
+ "description": "SHA-256 digest of input parameters.",
+ "type": "string"
+ },
+ "sources": {
+ "items": {
+ "properties": {
+ "label": {
+ "type": "string"
+ },
+ "uri": {
+ "type": "string"
+ }
+ },
+ "required": [
+ "label"
+ ],
+ "type": "object"
+ },
+ "type": "array"
+ }
+ },
+ "type": "object"
+ },
+ "nextActions": {
+ "description": "Actionable follow-up guidance.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ },
+ "status": {
+ "description": "Execution status.",
+ "enum": [
+ "success",
+ "partial",
+ "blocked",
+ "failed"
+ ],
+ "type": "string"
+ },
+ "summary": {
+ "description": "Human-readable executive summary of the operation.",
+ "type": "string"
+ },
+ "warnings": {
+ "description": "Non-fatal warnings if applicable.",
+ "items": {
+ "type": "string"
+ },
+ "type": "array"
+ }
+ },
+ "required": [
+ "status",
+ "summary",
+ "data",
+ "warnings",
+ "evidence",
+ "nextActions"
+ ],
+ "type": "object"
+}v0.1.1analyze_optical_profilegenerate_relight_variationsharmonize_compositesynthesize_diffusion_promptScored across 5 tools
Each tool has a clearly distinct purpose: read-only optical analysis, image file generation, two-image compositing, prompt synthesis, and cache listing. The descriptions explicitly contrast each tool against its neighbors, eliminating overlap.
All names follow a consistent verb_noun snake_case pattern (analyze_optical_profile, generate_relight_variations, harmonize_composite, synthesize_diffusion_prompt, list_cached_variations). No deviations in style or convention.
Five tools form a tight, well-scoped pipeline where each tool earns its place. No redundancy and no bloat for the relighting/harmonization domain.
The pipeline covers analysis, generation, compositing, prompt synthesis, and artifact discovery, forming a coherent end-to-end workflow. Minor gaps exist, such as no cache cleanup/deletion or batch orchestration tool, but core operations are fully covered.
AI photoshoot studio: garments, avatars, locations, and art direction
AI visual generation agent: multi-pipeline rendering, prompt crafting, and image composition.
AI film lab for filmmakers: generate and review images/clips with input provenance, cost preflight
Design, save, and run outcome-aligned AI workflows and verifiers, with reliable image output.
