@cloudinary/asset-management-mcp 0.9.0 → 0.9.2

package/src/funcs/searchSearchAssets.ts

@@ -32,9 +32,53 @@ import { Result } from "../types/fp.js";
  * @remarks
  * Returns a list of resources matching the specified search criteria.
  *
- * Uses Lucene-like query language to search by descriptive attributes (public_id, filename, folder, tags, context), file details (resource_type, format, bytes, width, height), embedded data (image_metadata), and analyzed data (face_count, colors, quality_score). Supports aggregate counts and complex Boolean expressions.
+ * Uses a Lucene-like query language to filter assets by descriptive attributes (`public_id`, `asset_id`, `filename`, `display_name`, `folder` / `asset_folder`, `tags`, `context.<key>`), file details (`resource_type`, `type`, `format`, `bytes`, `width`, `height`, `duration`, `pages`, `aspect_ratio`, `transparent`, `grayscale`), lifecycle dates (`uploaded_at`, `created_at`, `taken_at`, `updated_at`, `last_updated.<kind>`), moderation and lifecycle state (`status`, `moderation_status`, `moderation_kind`), embedded data (`image_metadata.*`), structured metadata (`metadata.<external_id>`), and analysis fields (`face_count`, `colors`, `quality_score`, `illustration_score`, `accessibility_analysis.*`). Supports sorting, aggregate counts, and complex boolean expressions. See the `expression` parameter for the full field reference.
  *
- * Examples: tags:shirt AND uploaded_at>1d, resource_type:image AND bytes>1mb, folder:products OR context.category:electronics
+ * ## Expression syntax
+ *
+ * - **Match**: `field:value` (token match) or `field=value` (exact match). Examples: `tags:shirt`, `tags=cotton`.
+ * - **Comparisons**: `>`, `<`, `>=`, `<=` for numbers and dates. Example: `bytes>10000000`.
+ * - **Ranges**: `field:[from TO to]` inclusive, `field:{from TO to}` exclusive. Example: `width:{200 TO 1028}`.
+ * - **Booleans**: `AND`, `OR`, `NOT` (uppercase), or `+` (must), `-` (must not). `NOT` must appear between clauses — a bare leading `NOT` is a parse error; use `-field:value` to negate the first clause. Group with parentheses: `(shirt OR pants) AND clothes`.
+ * - **Wildcards**: trailing `*` only, for prefix match (`public_id:shoes_*`, `format:jp*`, `tags:shirt*`). Not supported on `folder`, `asset_folder`, `resource_type`, or `type`. Leading `*`, middle `*`, `?`, and bare `*` (`folder:*`, `context.alt:*`) are all parse errors — wildcards cannot be used as a "field is present" probe.
+ * - **Tokenized vs exact fields**: `tags`, `filename`, `display_name`, `context.<key>`, and `metadata.<id>` match on tokens split by whitespace and punctuation — `tags:analysis` matches the tag `full-analysis`. `public_id`, `folder`, `asset_folder`, and `format` match the whole value — `public_id:dog` will not match `dog_pldcwy`; use `public_id="dog_pldcwy"` (exact) or `public_id:dog*` (prefix). These exact-match fields still accept a trailing `*` for prefix match (except `folder` / `asset_folder`, where wildcards are ignored).
+ * - **Dates**: ISO-8601 in quotes (`uploaded_at>"2024-01-15"`) or relative shorthand `Nh`, `Nd`, `Nw`, `Nm`, `Ny` (`uploaded_at>1d`, `created_at:[4w TO 1w]`). Send raw `<`/`>`, never HTML-escaped.
+ * - **Quoting**: wrap any value containing a space, colon, or other reserved character (`! ( ) { } [ ] ^ ~ ?  \ = & < > |`) in double quotes, or escape each character with `\`. Examples: `tags:"service:mantels"`, `aspect_ratio:"16:9"`, `folder:"My Folder"`.
+ *
+ * ## Common mistakes
+ *
+ * - Use `folder:` or `asset_folder:` (singular); `folders:`, `asset_folder_id:`, and other invented variants are not valid fields. Pass the exact folder name — wildcards do not apply here.
+ * - There is no "has any value" / presence probe. `folder:*`, `metadata.alt:*`, `context.key:*`, `tags:*`, and `-tags:*` are all parse errors. See *"Which assets have any value for `metadata.<id>`?"* under **Common tasks** for workarounds.
+ * - `NOT foo AND bar` is a parse error. Write it as `bar AND NOT foo` or `-foo AND bar`, and keep every `NOT` between two clauses (`a AND NOT b AND NOT c` is fine; `NOT b AND NOT c …` is not).
+ * - `public_id:dog` will not match `dog_pldcwy`. Use `public_id="dog_pldcwy"` (exact) or `public_id:dog*` (prefix).
+ * - `tags=service:mantels` fails because the unquoted colon is parsed as a field separator. Use `tags="service:mantels"` or `tags=service\:mantels`.
+ * - Do not HTML-escape operators. Send `uploaded_at<1h`, not `uploaded_at&lt;1h`.
+ * - Do not leave an operand empty (e.g. `tags: AND -tags:foo`). Omit the empty clause entirely.
+ *
+ * ## Tips
+ *
+ * - Set `max_results: 0` to return only `total_count` and `aggregations` without any resource payload — useful for counts and aggregation-only queries.
+ * - `total_count` is always present in the response; prefer it over running an aggregation just to get a count.
+ * - `aggregate` (both simple and range variants) and the `metadata`, `image_metadata`, `image_analysis` values of `with_field` require a Tier 2 search plan.
+ * - Range aggregations require each range to include a `key` label (1–20 chars, `[a-zA-Z0-9_-]+`) and at least one of `from` / `to`.
+ *
+ * ## Common tasks
+ *
+ * - **Count matching assets** — put the filter in `expression` with `max_results: 0` and read `total_count` from the response. Works on every tier; no `aggregate` needed.
+ * - **Preview one matching asset** — set `max_results: 1`; add `with_field: ["tags", "context"]` (or `metadata`, Tier 2) to inspect values. Prefer this over fetching and scanning a full page.
+ * - **Distribution of values for a field** — Tier 2: `aggregate: [format|resource_type|type]` for enum counts, or range aggregations on `bytes`, `image_pixels`, `video_pixels`, or `duration`. Tier 1 fallback: run N small queries with `max_results: 0`, one per candidate value, and read `total_count` from each.
+ * - **"Which assets have any value for `metadata.<id>`?"** — not expressible directly (`metadata.X:*` is a parse error; there is no presence probe). Workarounds: (a) if the field has a known value set, enumerate — `metadata.region:(apac OR emea OR amer)`; (b) query broadly with `with_field: ["metadata"]` (Tier 2) and filter client-side for entries where the field is set; (c) at ingest time, attach a sentinel tag whenever the field is set, then search by that tag.
+ * - **Newest / largest N** — keep the filter in `expression` and sort explicitly: `sort_by: [{uploaded_at: "desc"}]` with `max_results: 10`.
+ * - **Filter by folder** — both `asset_folder:"parent/child"` and `folder:"parent/child"` match an exact folder path; there is no wildcard or "contains". To query across multiple folders, enumerate: `asset_folder:("campaigns/2024" OR "campaigns/2025")`.
+ * - **Filter by metadata when you only know the label** — first call `list-metadata-fields` to resolve the label to an `external_id`, then query `metadata.<external_id>:value`.
+ * - **Multiple independent filters in one turn** — prefer one `expression` with `OR` / parentheses over firing many parallel calls: `metadata.region:apac OR metadata.region:emea` in a single request is faster and more reliable than two parallel requests.
+ *
+ * ## Examples
+ *
+ * - `tags:shirt AND uploaded_at>1d`
+ * - `resource_type:image AND bytes>1000000 AND (format:png OR format:jpg)`
+ * - `folder:products AND context.category:electronics`
+ * - `tags:"service:mantels" AND -tags:discontinued`
  */
 export function searchSearchAssets(
   client$: CloudinaryAssetMgmtCore,

package/src/landing-page.ts

@@ -19,8 +19,14 @@ export function landingPage(req: Request): Response {
 
 // express wrapper
 export function landingPageExpress(req: ExpressRequest, res: ExpressResponse) {
-  const origin = new URL(req.host).href;
-  res.type("html").send(landingPageHTML(origin));
+  const proto = req.get("x-forwarded-proto")?.split(",")[0]?.trim()
+    || req.protocol;
+  const host = req.get("host");
+  if (!host) {
+    res.status(400).send("Missing Host header");
+    return;
+  }
+  res.type("html").send(landingPageHTML(`${proto}://${host}`));
 }
 
 export function landingPageHTML(origin: string): string {
@@ -933,7 +939,7 @@ http_headers = { "api-key" = "YOUR_API_KEY", "api-secret" = "YOUR_API_SECRET", "
         <h1>Instructions</h1>
         <p>One-click installation for Claude Desktop users</p>
         <div class="instruction-item">
-          <a href="https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.0/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
+          <a href="https://github.com/cloudinary/asset-management-mcp/releases/download/v0.9.2/mcp-server.mcpb" download="mcp-server.mcpb" class="action-button header-action" style="display: inline-flex; margin-bottom: 16px;">
             📥 Download MCP Bundle
           </a>
         </div>

package/src/lib/config.ts

@@ -112,9 +112,9 @@ export function serverURLFromOptions(options: SDKOptions): URL | null {
 
 export const SDK_METADATA = {
   language: "typescript",
-  openapiDocVersion: "0.5.0",
-  sdkVersion: "0.9.0",
-  genVersion: "2.881.4",
+  openapiDocVersion: "0.5.1",
+  sdkVersion: "0.9.2",
+  genVersion: "2.885.1",
   userAgent:
-    "speakeasy-sdk/mcp-typescript 0.9.0 2.881.4 0.5.0 @cloudinary/asset-management-mcp",
+    "speakeasy-sdk/mcp-typescript 0.9.2 2.885.1 0.5.1 @cloudinary/asset-management-mcp",
 } as const;

package/src/mcp-server/apps/app-shared.ts

@@ -116,6 +116,7 @@ export const SHARED_CSS_TOKENS = /* css */ `
 [data-theme="dark"] .status-warn, .dark .status-warn { background: #854d0e; color: #fef08a; }
 [data-theme="dark"] .status-err,  .dark .status-err  { background: #991b1b; color: #fecaca; }
 
+html { overflow: hidden; }
 body {
   font-family: var(--cld-font);
   background: var(--cld-bg);
@@ -126,16 +127,35 @@ body {
   position: relative;
 }
 .theme-btn {
-  position: absolute; top: 4px; right: 4px; z-index: 900;
   width: 22px; height: 22px; border-radius: 50%;
   border: 1px solid transparent; background: transparent;
   color: var(--cld-text3); cursor: pointer;
   display: flex; align-items: center; justify-content: center;
   padding: 0; transition: background 0.15s, color 0.15s, border-color 0.15s;
-  opacity: 0.5;
+  opacity: 0.5; flex-shrink: 0;
 }
 .theme-btn:hover { background: var(--cld-bg3); color: var(--cld-text); border-color: var(--cld-border); opacity: 1; }
 .theme-btn svg { width: 13px; height: 13px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+/* Shared icon-button — square pill, same family as theme-btn */
+.icon-btn {
+  display: inline-flex; align-items: center; justify-content: center; gap: 5px;
+  background: none; border: 1px solid var(--cld-border); border-radius: var(--cld-radius-sm);
+  color: var(--cld-text2); cursor: pointer; padding: 4px 8px;
+  font-size: 12px; font-weight: 500; font-family: inherit; line-height: 1;
+  transition: background 0.15s, color 0.15s, border-color 0.15s;
+  white-space: nowrap; flex-shrink: 0;
+}
+.icon-btn:hover { background: var(--cld-bg3); color: var(--cld-text); border-color: var(--cld-border2); }
+.icon-btn svg { width: 13px; height: 13px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; flex-shrink: 0; }
+/* icon-only variant (no text label) */
+.icon-btn.icon-only { padding: 4px; width: 28px; height: 28px; }
+/* header state icon (decorative, not a button) */
+.upload-header-icon { display: flex; align-items: center; justify-content: center; flex-shrink: 0; }
+.upload-header-icon svg { width: 20px; height: 20px; fill: none; stroke: currentColor; stroke-width: 2; stroke-linecap: round; stroke-linejoin: round; }
+.upload-header-icon.icon-success { color: var(--cld-success); }
+.upload-header-icon.icon-error   { color: var(--cld-error); }
+.upload-header-icon.icon-warning { color: var(--cld-warning); }
+.upload-header-icon.icon-accent  { color: var(--cld-accent); }
 `;
 
 // ── CSS: Shared component styles ────────────────────────────────────
@@ -389,7 +409,8 @@ details.detail-section > summary.detail-section-title::-webkit-details-marker {
 }
 .upload-zone:hover { border-color: var(--cld-accent); background: var(--cld-accent-bg); }
 .upload-zone.dragover { border-color: var(--cld-accent); background: var(--cld-accent-bg); }
-.upload-zone-icon { font-size: 36px; margin-bottom: 8px; color: var(--cld-text3); }
+.upload-zone-icon { margin-bottom: 8px; color: var(--cld-text3); display: flex; align-items: center; justify-content: center; }
+.upload-zone-icon svg { width: 36px; height: 36px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
 .upload-zone-text { font-size: 14px; color: var(--cld-text2); margin-bottom: 4px; }
 .upload-zone-hint { font-size: 12px; color: var(--cld-text3); }
 .upload-zone-btn {
@@ -435,8 +456,9 @@ details.detail-section > summary.detail-section-title::-webkit-details-marker {
 .upload-preview-icon {
   width: 56px; height: 56px; border-radius: var(--cld-radius-sm);
   background: var(--cld-bg3); flex-shrink: 0; display: flex;
-  align-items: center; justify-content: center; font-size: 24px; color: var(--cld-text3);
+  align-items: center; justify-content: center; color: var(--cld-text3);
 }
+.upload-preview-icon svg { width: 24px; height: 24px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
 .upload-preview-info { flex: 1; min-width: 0; }
 .upload-preview-name { font-size: 13px; font-weight: 600; color: var(--cld-text); white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
 .upload-preview-meta { font-size: 11px; color: var(--cld-text3); margin-top: 2px; }
@@ -585,19 +607,15 @@ details.upload-section > .upload-form { margin: 0; padding: 10px 12px; }
   background: var(--cld-accent-bg); border: 1px solid var(--cld-accent);
   border-radius: var(--cld-radius); margin-bottom: 4px; position: relative;
 }
-.upload-staged-icon { font-size: 24px; flex-shrink: 0; }
+.upload-staged-icon { flex-shrink: 0; display: flex; align-items: center; color: var(--cld-accent); }
+.upload-staged-icon svg { width: 24px; height: 24px; fill: none; stroke: currentColor; stroke-width: 1.5; stroke-linecap: round; stroke-linejoin: round; }
 .upload-staged-info { flex: 1; min-width: 0; }
 .upload-staged-name {
   font-size: 13px; font-weight: 600; color: var(--cld-text);
   white-space: nowrap; overflow: hidden; text-overflow: ellipsis;
 }
 .upload-staged-meta { font-size: 11px; color: var(--cld-text3); margin-top: 2px; }
-.upload-staged-clear {
-  background: none; border: none; cursor: pointer; font-size: 16px;
-  color: var(--cld-text3); padding: 4px 6px; border-radius: var(--cld-radius-sm);
-  transition: color 0.15s, background 0.15s; flex-shrink: 0;
-}
-.upload-staged-clear:hover { color: var(--cld-error); background: rgba(206,25,13,0.08); }
+.upload-staged-clear:hover { color: var(--cld-error); border-color: var(--cld-error); background: rgba(206,25,13,0.08); }
 
 /* Upload submit button */
 .upload-submit {
@@ -645,6 +663,24 @@ details.upload-section > .upload-form { margin: 0; padding: 10px 12px; }
 }
 `;
 
+// ── JS: SVG icon strings (Lucide-style, 24px viewBox, stroke-based) ──
+export const SHARED_JS_ICONS = /* js */ `
+var IC = {
+  refresh:    '<svg viewBox="0 0 24 24"><path d="M3 12a9 9 0 0 1 9-9 9.75 9.75 0 0 1 6.74 2.74L21 8"/><path d="M21 3v5h-5"/><path d="M21 12a9 9 0 0 1-9 9 9.75 9.75 0 0 1-6.74-2.74L3 16"/><path d="M3 21v-5h5"/></svg>',
+  chevronLeft:'<svg viewBox="0 0 24 24"><polyline points="15 18 9 12 15 6"/></svg>',
+  arrowDown:  '<svg viewBox="0 0 24 24"><line x1="12" y1="5" x2="12" y2="19"/><polyline points="19 12 12 19 5 12"/></svg>',
+  x:          '<svg viewBox="0 0 24 24"><line x1="18" y1="6" x2="6" y2="18"/><line x1="6" y1="6" x2="18" y2="18"/></svg>',
+  zap:        '<svg viewBox="0 0 24 24"><polygon points="13 2 3 14 12 14 11 22 21 10 12 10 13 2"/></svg>',
+  uploadCloud:'<svg viewBox="0 0 24 24"><polyline points="16 16 12 12 8 16"/><line x1="12" y1="12" x2="12" y2="21"/><path d="M20.39 18.39A5 5 0 0 0 18 9h-1.26A8 8 0 1 0 3 16.3"/></svg>',
+  alertTriangle:'<svg viewBox="0 0 24 24"><path d="M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z"/><line x1="12" y1="9" x2="12" y2="13"/><line x1="12" y1="17" x2="12.01" y2="17"/></svg>',
+  folderOpen: '<svg viewBox="0 0 24 24"><path d="M22 19a2 2 0 0 1-2 2H4a2 2 0 0 1-2-2V5a2 2 0 0 1 2-2h5l2 3h9a2 2 0 0 1 2 2z"/><polyline points="22 13 17 13 15 16 9 16 7 13 2 13"/></svg>',
+  checkCircle:'<svg viewBox="0 0 24 24"><path d="M22 11.08V12a10 10 0 1 1-5.93-9.14"/><polyline points="22 4 12 14.01 9 11.01"/></svg>',
+  clock:      '<svg viewBox="0 0 24 24"><circle cx="12" cy="12" r="10"/><polyline points="12 6 12 12 16 14"/></svg>',
+  file:       '<svg viewBox="0 0 24 24"><path d="M13 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V9z"/><polyline points="13 2 13 9 20 9"/></svg>',
+  image:      '<svg viewBox="0 0 24 24"><rect x="3" y="3" width="18" height="18" rx="2"/><circle cx="8.5" cy="8.5" r="1.5"/><polyline points="21 15 16 10 5 21"/></svg>',
+};
+`;
+
 // ── JS: MCPApp client class ─────────────────────────────────────────
 export const SHARED_JS_MCP_CLIENT = /* js */ `
 var RPC_TIMEOUT_MS = 15000;
@@ -734,6 +770,29 @@ class MCPApp {
 
 // ── JS: Helper functions ────────────────────────────────────────────
 export const SHARED_JS_HELPERS = /* js */ `
+function copyText(text) {
+  if (navigator.clipboard && navigator.clipboard.writeText) {
+    return navigator.clipboard.writeText(text).catch(function() { return _copyFallback(text); });
+  }
+  return _copyFallback(text);
+}
+function _copyFallback(text) {
+  return new Promise(function(resolve, reject) {
+    try {
+      var ta = document.createElement("textarea");
+      ta.value = text;
+      ta.setAttribute("readonly", "");
+      ta.style.position = "fixed"; ta.style.top = "0"; ta.style.left = "0";
+      ta.style.opacity = "0"; ta.style.pointerEvents = "none";
+      document.body.appendChild(ta);
+      ta.select(); ta.setSelectionRange(0, text.length);
+      var ok = document.execCommand("copy");
+      document.body.removeChild(ta);
+      if (ok) resolve(); else reject(new Error("Clipboard unavailable"));
+    } catch (e) { reject(e); }
+  });
+}
+
 function fmtBytes(b) {
   if (!b) return "";
   var u = ["B","KB","MB","GB"], i = Math.min(Math.floor(Math.log(b)/Math.log(1024)), 3);
@@ -1966,7 +2025,16 @@ function renderThemeToggle() {
     applyTheme();
     renderThemeToggle();
   });
-  document.body.appendChild(btn);
+  var slot = document.getElementById("header-actions");
+  if (slot) {
+    slot.appendChild(btn);
+  } else {
+    btn.style.position = "absolute";
+    btn.style.top = "4px";
+    btn.style.right = "4px";
+    btn.style.zIndex = "900";
+    document.body.appendChild(btn);
+  }
 }
 
 function setupHostContext(app) {

package/src/mcp-server/apps/asset-details-app.ts

@@ -9,6 +9,7 @@
 import {
   SHARED_CSS_TOKENS,
   SHARED_CSS_COMPONENTS,
+  SHARED_JS_ICONS,
   SHARED_JS_MCP_CLIENT,
   SHARED_JS_HELPERS,
   SHARED_JS_TOOLTIPS,
@@ -59,16 +60,6 @@ const ASSET_DETAILS_CSS = /* css */ `
   padding: 2px 7px; border-radius: 4px; border: 1px solid var(--cld-border);
 }
 
-.open-link {
-  padding: 6px 14px; border-radius: var(--cld-radius-sm);
-  font-size: 12px; font-weight: 500; cursor: pointer;
-  border: 1px solid var(--cld-accent); background: transparent;
-  color: var(--cld-accent); font-family: inherit;
-  transition: background 0.15s;
-  white-space: nowrap; flex-shrink: 0;
-}
-.open-link:hover { background: var(--cld-accent-bg); }
-
 .hero-container {
   position: relative; margin-bottom: var(--cld-sp-md);
   border-radius: var(--cld-radius); overflow: hidden;
@@ -131,9 +122,9 @@ function renderPage(r) {
   if (dur) h += '<span class="pill">' + dur + "</span>";
   if (size) h += '<span class="pill">' + size + "</span>";
   h += "</div></div>";
-  h += '<div style="display:flex;gap:6px;flex-shrink:0">';
-  h += '<button class="open-link" id="refresh-asset" title="Refresh">\\u21BB</button>';
-  if (url) h += '<button class="open-link" id="open-asset">Open</button>';
+  h += '<div id="header-actions" style="display:flex;gap:8px;flex-shrink:0;align-items:center">';
+  if (url) h += '<button class="icon-btn" id="open-asset">Open</button>';
+  h += '<button class="icon-btn icon-only" id="refresh-asset" title="Refresh">' + IC.refresh + '</button>';
   h += "</div>";
   h += "</div>";
 
@@ -175,6 +166,7 @@ function renderPage(r) {
   h += "</div>";
 
   root.innerHTML = h;
+  renderThemeToggle();
 
   // Event delegation
   root.addEventListener("click", function handler(e) {
@@ -220,6 +212,7 @@ function showFetchPrompt() {
   h += '<button class="prompt-btn prompt-btn-primary" id="fetch-direct-btn">Fetch Directly</button>';
   h += "</div></div>";
   root.innerHTML = h;
+  renderThemeToggle();
   document.getElementById("fetch-direct-btn").addEventListener("click", function() { fetchDirect(); });
 }
 
@@ -300,6 +293,7 @@ ${ASSET_DETAILS_CSS}
 <div id="app"><div class="status">Loading asset details&hellip;</div></div>
 
 <script>
+${SHARED_JS_ICONS}
 ${SHARED_JS_MCP_CLIENT}
 ${SHARED_JS_HELPERS}
 ${SHARED_JS_TOOLTIPS}