Curate

MCP tools for ratings, labels, keywords, collections and what DarkRay shows.

update_photos

Rate, label and tag photos. Set rating, color label, pick or reject flag and caption, add or remove keywords, and add to or take out of the Quick Collection. One undoable step.

Bridge method: photos.update

Parameter	Type	Required	Details
ids	array of integer	yes	Photo ids from search_photos (at most 1000). Not empty, at most 1000 items.
rating	integer		Stars; 0 clears. Min 0, max 5.
label	string or null		A color label; null clears. One of red, orange, yellow, green, teal, blue, purple, pink, null.
flag	string or null		Pick or reject; null clears. One of pick, reject, null.
caption	string or null		The caption; null clears.
add_keywords	array of string		Keywords to add; new ones are created.
remove_keywords	array of string		Keywords to take off.
quick_collection	boolean		In the Quick Collection or not.
catalog	string		A catalog from list_catalogs; omitted, the one DarkRay shows.

Python: app.update_photos(…)

from darkray_bridge import DarkRay

with DarkRay.connect() as app:
    ids = [photo.id for photo in app.iter_photos("kw:beach date:2026-07")]

    # One call is one undoable step in DarkRay.
    app.update_photos(ids, rating=3, label="blue", add_keywords=["summer", "Portugal"])

    # Mark the best one, and caption it.
    app.update_photos(ids[:1], flag="pick", caption="Praia da Marinha at sunrise")

    # None clears a label, flag or caption; a parameter left out stays as it is.
    app.update_photos(ids[1:], label=None, remove_keywords=["summer"])

update_collection

Change a collection. Create a collection, rename one, or add and remove photos. One undoable step. Give id for an existing collection (0 is the Quick Collection) or create for a new one.

Bridge method: collections.update

Parameter	Type	Required	Details
id	integer		Min 0.
create	string		A new collection’s name. At least 1 characters.
rename	string		At least 1 characters.
add	array of integer		At most 1000 items.
remove	array of integer		At most 1000 items.
catalog	string		A catalog from list_catalogs; omitted, the one DarkRay shows.

Python: app.update_collection(…)

from darkray_bridge import DarkRay

with DarkRay.connect() as app:
    picks = [photo.id for photo in app.iter_photos("flag:pick kw:wedding")]

    # Create a collection and fill it in one step.
    coll = app.update_collection(create="Wedding: client picks", add=picks)

    # Later: rename it, and take out a photo the client dropped.
    app.update_collection(id=coll, rename="Wedding: album", remove=picks[-1:])

    # Id 0 is the Quick Collection.
    app.update_collection(id=0, add=picks[:5])

show_photos

Show photos. Change what DarkRay shows. source switches the grid to All Photographs, a collection (0 is the Quick Collection) or a folder, as clicking it does; ids selects photos (within that source when one is given); mode switches to the grid, loupe or Edit. Give ids, source or both.

Bridge method: view.show

Parameter	Type	Required	Details
ids	array of integer		Photo ids from search_photos (at most 1000). Not empty, at most 1000 items.
source	object		What the grid shows: kind all, collection or folder, with the id from list_collections or list_folders. Fields: kind, id.
mode	string		One of grid, loupe, edit.
catalog	string		A catalog from list_catalogs; omitted, the one DarkRay shows.

Python: app.show_photos(…)

from darkray_bridge import DarkRay

with DarkRay.connect() as app:
    rejects = [photo.id for photo in app.iter_photos("flag:reject")]

    # Select photos in the grid (DarkRay switches to All Photographs when needed).
    app.show_photos(ids=rejects, mode="grid")

    # Switch the grid to the Quick Collection.
    app.show_photos(source={"kind": "collection", "id": 0})

    # Open one photo in Edit.
    app.show_photos(ids=rejects[:1], mode="edit")