Image gallery module — JetSetGo MCP reference

The gallery module is JetSetGo's central image library. It owns the shared image store every other surface draws from — resource hero shots, thumbnails, brand logos, vehicle photos, cabin and seating imagery, marketing banners. Each record carries storage metadata, a CDN URL, classification, tags, and alt text; other modules attach to an image by referencing its id. The MCP tools drive the same frozen image contract the gallery app itself uses.

What the operator uses it for

Finding images by type, tag, alt-text presence, linkage status, upload date range, or keyword.
Uploading new assets through the guided two-phase flow (reserve → transfer bytes → finalize).
Correcting metadata after upload: filename, alt text, image type, and tags are the editable surface.
Checking what references an image before removing it — detail reads report every linked resource and package node up front.

Where it sits

Some images arrive without an explicit upload: a resource's assigned hero image is mirrored into the library automatically (recorded with source resources), as are package-node images. Downstream, resource records and package-node records hold id references into the library, and those links actively protect images from deletion. Storefront surfaces consume the CDN URLs each record carries. Signed viewing credentials for displaying images are handled by the clients module and are deliberately not duplicated here.

Key concepts

Image record — one row per asset: storage key, CDN URL, filename, MIME type, dimensions and byte size, alt text, image type, tags, uploader, source, and status.
Two-phase upload — phase 1 reserves a pending row and returns signed object-storage POST instructions; phase 2 finalizes dimensions/metadata and marks the row active. The byte transfer itself happens outside MCP scope.
Pending vs active — new uploads start pending; list results default to active only. Finalize performs the transition.
Image type — a 12-value classification: Hero, Thumbnail, Gallery, Brand Logo, Map/Schematic, Vehicle Exterior, Vehicle Interior, Cabin/Seat, Crew/Staff, Certificate/Document, Safety/Compliance, Marketing/Banner.
Tags and alt text — repeatable labels (AND-combined when filtering together) and descriptive/accessibility text.
Linked references — the resources and package nodes currently pointing at an image; surfaced on reads, enforced on delete.
Source — provenance value (gallery, resources, or legacy_backfill); direct uploads are accepted only as gallery.

Tools

Tool	Class	Purpose
`gallery_list_images`	Read	List images with rich filters: repeatable image_type/tag, untagged, keyword search, date range, has_alt_text, has_links, status, pagination.
`gallery_get_image`	Read	Fetch one image including its linked resources and package nodes.
`gallery_create_upload`	Guarded write	Phase 1: create a pending image row and receive signed upload instructions plus optional resized-variant instructions.
`gallery_finalize_image`	Guarded write	Phase 2: set width/height/size, alt text, image type, and tags on a pending row; marks it active.
`gallery_update_image`	Guarded write	Edit the four mutable metadata fields on an active image.
`gallery_delete_image`	Guarded write	Delete an image; blocked with the linked references listed if anything still points at it.

Rules worth knowing

Uploads are cooperative across steps: create_upload yields signed instructions, someone or something else transfers the actual bytes, then finalize completes the record. Finalize requires at least one field and only works on pending rows created in phase 1.
After finalize, exactly four fields are editable — filename, alt_text, image_type, tags. Dimensions, byte size, content type, and CDN URL are fixed once set.
The declared content type must be an image MIME type (jpeg/png/webp/gif family); the signed storage policy enforces this at byte-transfer time regardless of tool-side checks.
Deleting an image still referenced by any resource or package node fails with a conflict error carrying the full list of referencing objects — those references must be removed first. Detail reads expose the same linkage proactively so assistants can warn before attempting deletion.
Filter semantics: multiple image_type values OR together; multiple tags AND together; the sentinel "__null__" as an image_type filters for untyped images; untagged=true is mutually exclusive with supplying tags server-side.
Keyword search terms are escaped server-side — callers must not pre-escape % and _ characters themselves.
There is no bulk-delete operation anywhere in the contract; bulk cleanup is composed by looping single deletions through gallery_delete_image.
All four writes run the guarded sequence — preview, explicit confirm with token, fingerprint re-check before execution — and require the tenant to be stated explicitly.

Resources — resource hero images mirror into this library automatically and reference images by id.
Clients — owns the signed photo-access mechanism used to display gallery images.