mcp-relight-harmonize

Overview Schema Source Related Servers Discussions Admin

harmonize_composite

Composite a foreground cutout onto a background scene, automatically matching colors and adding ground contact shadows for realistic integration.

Instructions

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.

Input Schema

TableJSON Schema

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.

Output Schema

TableJSON Schema

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.

Schema Changelog

Changes observed during successful MCP inspections.

Changed4 schema fields changedv1.0.2Sep 13, 2026

changedInput schema / properties / background_path / description

Previous value: -"Path to the background environment image."New value: +"Path to target background scene image (.png, .jpg, .jpeg)."

changedInput schema / properties / blend_mode / description

Previous 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'."

changedInput schema / properties / foreground_path / description

Previous 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."

changedOutput 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"
+}

First observedv0.1.1Sep 13, 2026

TDQS

A4.8/5.0

Behavior5/5

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.

Conciseness4/5

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.

Completeness5/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines5/5

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.

Deploy Server