Images

search_assets

Searches for approved, ready-to-use PNG, JPEG, and WebP images (under 5 MB) in the connected workspace, optionally limited to one image collection. With no filters it also names every collection.

• Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Default	Description
  collection	string	No	—	A collection's name (ignoring case) or ID; limits results to it.
  query	string	No	—	Search term (min 2, max 100 characters).
  page	number	No	1	Page number.
  limit	number	No	8	Items per page (capped at 12).

• Output Schema:

  {
    items: Array<{
      id: string;             // Asset UUID
      filename: string | null;
      contentType: "image/png" | "image/jpeg" | "image/webp";
      sizeBytes: number;      // Size in bytes (under 5 MB)
      width?: number;         // Pixel width; left out when the file does not say
      height?: number;
      createdAt: string;      // ISO 8601 timestamp
      previewUrl: string;     // URL to inspect or preview the asset
    }>;
    total: number;
    page: number;
    limit: number;
    collections?: Array<{     // Only with no filters: every image collection
      id: string;
      name: string;
      description: string | null;
      itemCount: number;
      createdAt: string;
    }>;
  }

---

upload_images

Brings the user's own images (PNG, JPEG, or WebP, up to 5 MB each) into the connected workspace, optionally into a collection (made when no collection has that name). Needs assets:create.

The flow has three steps, reported in the output's step field:

1. link: called without files, it returns a link to the workspace's Images page (the collection's page when collection is given) for the user to drop files into. Once they say they are done, search_assets finds the images.
2. uploads: an agent that has the files (a shell, files on disk) passes files with each file's SHA-256, content type, and size. Each result has an uploadUrl to PUT the bytes to with its contentType as the Content-Type header, or alreadyStored: true when the workspace holds the file already.
3. done: call again with done listing every file (already stored ones too) by sha256 and name. The recorded images come back with an id, which is the asset id an image input takes in batch rows.

Images that are already online, such as product photos from a store, go in urls instead. Kalpana fetches each one (up to 20 a call, 10 at a time, 5 MB each) and returns it recorded in one step, as step: "done". Each URL's host has to be on the workspace's domain whitelist; cdn.shopify.com is on it by default. A URL that fails is listed in failed with its reason while the rest are stored, and a host that is not whitelisted comes back with a link to the workspace's settings page. urls cannot be combined with files or done.

• Annotations: readOnlyHint: false, destructiveHint: false, idempotentHint: true, openWorldHint: true

• Input Parameters:

  Parameter	Type	Required	Default	Description
  collection	string	No	—	Collection to put the images in, by name. Made if missing.
  files	Array<{ sha256, contentType, sizeBytes }>	No	—	Files you will upload yourself (up to 20). sha256 is lowercase hex, contentType is image/png, image/jpeg, or image/webp, sizeBytes is at most 5 MB (5242880).
  done	Array<{ sha256, name? }>	No	—	Files you uploaded, to record them (up to 20).
  urls	Array<{ url, name? }>	No	—	Public image URLs for Kalpana to fetch (up to 20). name defaults to the URL's last segment.

• Output Schema:

  {
    step: "link" | "uploads" | "done";
    link?: string;            // Workspace Images page, when step is "link"
    uploads?: Array<{         // When step is "uploads"
      sha256: string;
      uploadUrl?: string;     // Signed URL to PUT the file to
      contentType?: string;
      alreadyStored?: boolean;
    }>;
    images?: Array<{          // When step is "done"
      id: string;             // The asset id an image input takes in batch rows
      name: string;
      format: string;
      width?: number;
      height?: number;
    }>;
    collection?: string;
    failed?: Array<{ contentHash?: string; url?: string; message: string }>;
  }

---

inspect_image

Fetches and visually inspects an image from a Kalpana preview or download URL (e.g. template previewUrl, asset previewUrl, or batch output downloadUrl). Returns the image as an MCP ImageContent object for direct visual analysis by multimodal LLM agents.

• Annotations: readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false

• Input Parameters:

  Parameter	Type	Required	Description
  url	string	Yes	Kalpana previewUrl or downloadUrl to inspect visually.

• Output Schema:

  {
    contentType: string;      // MIME type (e.g., "image/png", "image/webp")
    sizeBytes: number;        // Size in bytes (under 5 MB)
  }

• Returns: Native MCP ImageContent (base64-encoded image) and TextContent summary.