Search, fit, color, and curation

V2 execution order

Filters gate. Preferences rank. Selection curates.

Explore Art MCP v2 gives the calling agent direct control of a parametric search. PostgreSQL first computes exact eligibility. The shared semantic engine and deterministic design preferences rank only that population. Final-set controls then build the requested shortlist. Post-engine color/surface scoring, caps, and diversity are bounded to the first 100 engine-ranked candidates, not the full corpus.

If ranked infrastructure is unavailable, the call returns search_unavailable. It never substitutes lexical results, broadens rights, or silently drops a control.

Three namespaces

Put each part of the brief in the right place

{
  "contract": "explore_art_mcp.v2",
  "filters": {
    "genome": [
      "animals"
    ],
    "geometry": {
      "orientation": [
        "landscape"
      ],
      "aspect_ratio": {
        "min": 1.35,
        "max": 2.0
      },
      "minimum_resolution": {
        "width": 2400,
        "height": 1200
      }
    },
    "color": {
      "all_of": [
        {
          "kind": "hex",
          "value": "#2563EB",
          "coverage": "prominent"
        }
      ],
      "none_of": [
        {
          "kind": "family",
          "value": "gray",
          "coverage": "mostly"
        }
      ]
    }
  },
  "preferences": {
    "semantic": {
      "text": "playful asymmetrical creatures with energetic shapes",
      "mode": "looks"
    },
    "color_relations": [
      {
        "relation": "pop",
        "anchor": {
          "kind": "hex",
          "value": "#E0A32C"
        }
      }
    ],
    "target_surface": {
      "width": 1600,
      "height": 900,
      "fit": "cover",
      "allow_upscale": false,
      "max_crop_fraction": 0.18
    }
  },
  "selection": {
    "limit": 12,
    "max_per_artist": 2,
    "max_per_institution": 3,
    "visual_diversity": "moderate"
  },
  "rights": "public_domain_or_cc0"
}

Exact catalog filters

Discover values instead of guessing them

Artist, institution, source, and checked Art Genome values are exact hard filters. Call list_filter_options to search current live-public values and copy the returned criterion fragment into filters.

{
  "facet": "genome",
  "query": "animal",
  "limit": 10
}

Creation-year bounds are inclusive. Explicit filters are additive. An intersection that matches nothing returns a successful zero, and any nearby counts remain labeled not_applied until the agent makes another call.

Geometry filters

Filter for the representation you can actually use

An explicit aspect_ratio.min or aspect_ratio.max is also inclusive. Geometry comes from the active publication’s pinned representation; unknown or zero dimensions cannot satisfy a hard gate.

Hard color

Family, name, hex, or saved swatch

A hard color criterion can use a broad family, one of Explore Art’s authored names, any #RRGGBB target, or the public ID of a palette color returned by get_artwork. Hex and swatch matching is perceptual in OKLab, not identical-RGB matching.

all_of

Every criterion must match.

any_of

At least one criterion must match.

none_of

Matching works are excluded.

Total criteria

Six maximum across all three groups.

Proportions describe the checked accepted chromatic sample after palette exclusions, not every pixel in the source image.

Color preferences

Ask how a palette should behave

Up to three preferences.color_relations may use a family, checked name, hex, or published palette color as an anchor. They reorder the eligible set; they never replace a hard color filter.

Evidence reports the algorithm version, resolved anchor, current checked full-image palette, matched swatch, accepted-sample basis, and the facts used by that relationship.

Target surface

Know what “fits” means before choosing art

allow_upscale, max_crop_fraction, and max_letterbox_fraction express the desired result. Because target surface is a preference, it influences evidence and order without silently removing an otherwise eligible work.

Selection

Build a shortlist, not twelve versions of one idea

Selection happens after ranking. Use max_per_artist, max_per_institution, and max_per_source to cap repetition. visual_diversity may be none, low, moderate, or high.

Requested diversity uses deterministic maximum marginal relevance over the same first-100 curation window and the existing full-image visual vector. The response preserves input rank, selected rank, fixed policy, cap exclusions, and explicit underfill reasons. Its selection evidence reports total_ranked_count, curation_window_count, and outside_window_count so the bound is visible. Counts below the 1,000-result engine window are exact; a count at the boundary is labeled at_least instead of overstating precision.

Visual references

Refine from works or one detail

Search from one to six publication-pinned representation references, then add the same explicit filters, preferences, and selection controls used by ordinary search.

{
  "contract": "explore_art_mcp.v2",
  "references": [
    {
      "representation_id": "<representation-id-1>"
    },
    {
      "representation_id": "<representation-id-2>"
    }
  ],
  "filters": {
    "geometry": {
      "orientation": [
        "landscape",
        "square"
      ]
    }
  },
  "preferences": {
    "semantic": {
      "text": "retain the playful geometry but make it calmer",
      "mode": "looks"
    }
  },
  "selection": {
    "limit": 12,
    "visual_diversity": "low"
  },
  "rights": "public_domain_or_cc0"
}

Region rectangles use normalized 0–1 coordinates, require positive width and height, and must remain inside the artwork.

{
  "contract": "explore_art_mcp.v2",
  "representation_id": "<representation-id>",
  "rectangle": {
    "x": 0.18,
    "y": 0.22,
    "width": 0.42,
    "height": 0.36
  },
  "preferences": {
    "semantic": {
      "text": "similarly cropped animal forms",
      "mode": "looks"
    }
  },
  "selection": {
    "limit": 12
  }
}

A new rectangle may persist and enqueue a bounded derived crop, so region search is not read-only or idempotent. It commonly returns a successful processing state with a crop_id and retry_after. Retry using that crop ID.

Current boundary

What v2 does not infer

V2 does not perform brand-image palette extraction, uploaded-image search, crop-specific palette relationships, subject-aware cropping, arbitrary safe zones, or whole-palette similarity from an external image. Start from semantic text, explicit controls, or published Explore Art references.