Refine MCP skills: align search-assets/sdk-reference with assets.list overload; drop webhooks

[imagekitio]

Summary

Builds on #2 and refines the two skills that interact most with TypeScript typing, so the agent gets correct results even when a skill isn't loaded. Pairs with companion SDK changes in imagekit-nodejs (an honest assets.list overload + an expanded execute tool prompt).

search-assets

• Rewrote the TypeScript usage section to match the assets.list overload behavior:
  • Without searchQuery → pass { type: 'file' } / { type: 'folder' } for a typed File[] / Folder[] (no narrowing).
  • With searchQuery → the API ignores the type/tags/name params, so the result stays (File | Folder)[]; put type = "file" inside the query and narrow with for...of + if.
• Added a "discover custom-metadata fields first" section: client.customMetadataFields.list() to get valid field names/types before building "customMetadata.<field>" queries (operators depend on the field type).
• Added the key gotcha that searchQuery overrides the top-level type/tags/name params.

imagekit-sdk-reference

• Updated the assets.list narrowing guidance to reflect the overload (narrowing only required for the union / searchQuery cases).
• Reconciled the try/catch rule with the tool prompt: don't try/catch single calls in execute code; when branching on failure, duck-type the error instead of instanceof ImageKit.APIError (a value import of the SDK crashes at runtime in the Deno sandbox).
• Removed the Webhooks section entirely — webhook unwrap verifies an incoming request and isn't usable inside the MCP execute sandbox.

Companion SDK changes (separate imagekit-nodejs PR)

Companion PR - imagekit-developer/imagekit-nodejs#163

• assets.list overloads gated on searchQuery?: undefined so the typed File[]/Folder[] return is only produced when there's no searchQuery (no more type lie).
• execute tool prompt expanded with list/search + pagination + nullable-field + custom-metadata-discovery guidance.

[shivamik]

One issue that i running with custom metadata is agent tries to use custom metadata tag as per user request. And because users dont exactly use custom meta data tag name correctly this usually search files to get the name. Correct path is to first get list of custom metadata tag and then proceed.

Below image shows using some cheaper model agent confuses metadata name. Also sometimes it uses list assets instead of first listing custom metadata. I am adding a section to guide llm to list metadata first

[manu4543]

ye pura section search se related hai, why is it here in general preflight skill and not search-asset skill. Also pls avoid making direct changes here. just leave comment.

[shivamik]

Okay I will leave comment.
This is here because MCP sometimes skips search assets skills when using cheap models! Adding this section at least gives some context to the agent to make correct call in first attempt as this skill is always loaded.

[shivamik]

Task: in my imagekit DAM, use AI task to add tag in these images
imagekit_api_mcp_trial
one of

1. animal
2. human
3. other

---

Rest of things are working fine! One issue that I faced in terms of UX, is that when working with long running tasks, code written is sequential sometimes.

I had to prompt to write code in parallel.

We should tell agent to write code to use APIs in batches like we do for IK Agent now

[shivamik]

---

Parallel Execution for Bulk File Operations

When you have a list of files to operate on, never await in a loop. Chunk into batches of 100 and run each batch concurrently with Promise.allSettled().

// ✅ files is any array of { fileId, name } — from assets.list(), a prior search, etc.
const CHUNK = 100;
const chunks = [];
for (let i = 0; i < files.length; i += CHUNK) chunks.push(files.slice(i, i + CHUNK));

for (const chunk of chunks) {
  await Promise.allSettled(
    chunk.map(({ fileId, name }) =>
      client.files.update(fileId, { tags: ['promo'] })
        .then(() => ({ fileId, name, status: 'ok' }))
        .catch((err: unknown) => ({ fileId, name, status: 'error', error: String(err) }))
    )
  );
}

Same pattern applies for files.delete(fileId), files.copy({...}), and files.move({...}).

For delete / addTags / removeTags, prefer the bulk endpoints (max 50 IDs each) — chunk IDs and run chunks in parallel:

const CHUNK = 50;
const chunks = [];
for (let i = 0; i < allFileIds.length; i += CHUNK) chunks.push(allFileIds.slice(i, i + CHUNK));
await Promise.allSettled(chunks.map(ids => client.files.bulk.delete({ fileIds: ids })));

[shivamik]

we can have a section for parallel execution