@sunkimkk/inspo-mcp 0.0.0-stage → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 sunkimk
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE. 

package/README.md

@@ -1,3 +1,56 @@
-# Temporary Holding Version
+# Inspo MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Pinterest and Dribbble for your AI agent in **one** MCP server. Search, look at thumbnails, browse boards and designers, and download originals (images and MP4s). No login, no API key, no browser.
+
+It merges [pinterest-mcp](https://github.com/sunkimk/pinterest-mcp) and dribbble-mcp. Tool names and inputs are unchanged, so prompts and skills written for either keep working.
+
+## Tools
+
+| Source | Tools |
+|---|---|
+| Pinterest | `pinterest_search`, `pinterest_get_pin`, `pinterest_related_pins`, `pinterest_board_pins`, `pinterest_preview_images`, `pinterest_download` |
+| Dribbble | `dribbble_search`, `dribbble_explore`, `dribbble_user_shots`, `dribbble_preview_images`, `dribbble_download` |
+
+Known issue: since November 2026 Pinterest requires login for related pins, so `pinterest_related_pins` returns "Login required". Search, boards and single pins still work.
+
+## Install
+
+Claude Code:
+
+```bash
+claude mcp add inspo -s user -- npx -y @sunkimkk/inspo-mcp
+```
+
+Any other MCP client: run `npx -y @sunkimkk/inspo-mcp` over stdio. Needs Node.js 20.18.1 or later.
+
+## Settings (environment variables, all optional)
+
+| Variable | Default |
+|---|---|
+| `MCP_PINTEREST_DOWNLOAD_DIR` | `~/Downloads/pinterest-mcp` |
+| `MCP_DRIBBBLE_DOWNLOAD_DIR` | `~/Downloads/dribbble-mcp` |
+| `MCP_PINTEREST_PROXY`, `MCP_DRIBBBLE_PROXY` (or `HTTPS_PROXY`) | none; set one if the site is blocked on your network |
+| `MCP_PINTEREST_LOCALE` | `en-US` |
+
+## Local extensions
+
+You can add your own tools without forking the package: write an ES module that default-exports a function, and list its absolute path either in `MCP_INSPO_EXTENSIONS` (separate several with `:`) or on its own line in `~/.config/inspo-mcp/extensions`. The file works even when the server is started by a plugin you cannot configure.
+
+```js
+// ~/my-tools/hello.js
+export default ({ tool, z, json, READ_ONLY }) =>
+  tool('hello', { description: 'Say hi', inputSchema: { name: z.string() }, annotations: READ_ONLY },
+    async ({ name }) => ({ content: [json({ hi: name })] }));
+```
+
+The function gets `{ tool, z, json, log, READ_ONLY, MAX_PREVIEWS }`. An extension that fails to load is logged to stderr and skipped. Extensions run with your user's permissions, so only list files you wrote or trust.
+
+## Credit
+
+Pins and shots belong to their creators. Use downloads as private references and keep the source link for credit. Not affiliated with Pinterest or Dribbble.
+
+## Develop
+
+```bash
+cd src && npm install && npm test   # live tests against pinterest.com and dribbble.com
+```

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@sunkimkk/inspo-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.0",
+  "description": "Pinterest and Dribbble for your AI agent in one MCP server: search, see thumbnails, follow related pins, browse designers and download originals. No login, no API key, no browser.",
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "pinterest",
+    "dribbble",
+    "claude-code",
+    "codex",
+    "design-inspiration",
+    "moodboard",
+    "ui-design"
+  ],
+  "type": "module",
+  "license": "MIT",
+  "bin": {
+    "inspo-mcp": "src/server.js"
+  },
+  "main": "src/server.js",
+  "files": [
+    "src"
+  ],
+  "engines": {
+    "node": ">=20.18.1"
+  },
+  "scripts": {
+    "start": "node src/server.js",
+    "test": "node --test test/*.test.js",
+    "prepack": "cp ../README.md ../LICENSE .",
+    "postpack": "rm -f README.md LICENSE"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "undici": "^7.30.1",
+    "zod": "^4.6.7"
+  },
+  "author": "sunkimk",
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/server.js

@@ -0,0 +1,72 @@
+#!/usr/bin/env node
+// Inspo MCP server (stdio): Pinterest and Dribbble in one server, plus optional local
+// extensions. Everything diagnostic goes to stderr: stdout carries JSON-RPC.
+//
+// Extensions are ES modules on this machine that add more tools. They are listed, as
+// absolute paths, in MCP_INSPO_EXTENSIONS (separated by ":" on macOS/Linux) and/or one per
+// line in ~/.config/inspo-mcp/extensions (lines starting with # are comments). The file lets
+// a server started by a plugin pick up local extensions without touching the plugin.
+// Each module default-exports a function that receives the same helpers the built-in sources
+// use ({ tool, z, json, READ_ONLY, MAX_PREVIEWS, log }). A broken extension is logged and
+// skipped; it never stops the server.
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { z } from 'zod';
+import registerDribbble from './tools/dribbble.js';
+import registerPinterest from './tools/pinterest.js';
+
+const VERSION = '1.0.0';
+const server = new McpServer({ name: 'inspo', version: VERSION });
+
+const log = (msg) => process.stderr.write(`[inspo] ${msg}\n`);
+const json = (value) => ({ type: 'text', text: JSON.stringify(value) });
+
+function tool(name, config, handler) {
+  server.registerTool(name, config, async (args) => {
+    try {
+      return await handler(args);
+    } catch (err) {
+      log(`${name} failed: ${err.stack || err.message}`);
+      return { isError: true, content: [{ type: 'text', text: err.message }] };
+    }
+  });
+}
+
+const ctx = { tool, z, json, log, READ_ONLY: { readOnlyHint: true, openWorldHint: true }, MAX_PREVIEWS: 16 };
+
+registerPinterest(ctx);
+registerDribbble(ctx);
+
+const CONFIG_FILE =
+  process.env.MCP_INSPO_EXTENSIONS_FILE ||
+  path.join(process.env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'inspo-mcp', 'extensions');
+
+function listExtensions() {
+  const fromEnv = (process.env.MCP_INSPO_EXTENSIONS || '').split(path.delimiter);
+  let fromFile = [];
+  try {
+    fromFile = fs.readFileSync(CONFIG_FILE, 'utf8').split(/\r?\n/).filter((l) => !l.trim().startsWith('#'));
+  } catch (err) {
+    if (err.code !== 'ENOENT') log(`could not read ${CONFIG_FILE}: ${err.message}`);
+  }
+  return [...new Set([...fromEnv, ...fromFile].map((s) => s.trim()).filter(Boolean))];
+}
+
+for (const file of listExtensions()) {
+  try {
+    if (!path.isAbsolute(file)) throw new Error('path must be absolute');
+    const mod = await import(pathToFileURL(file).href);
+    if (typeof mod.default !== 'function') throw new Error('module has no default-exported function');
+    await mod.default(ctx);
+    log(`loaded extension ${file}`);
+  } catch (err) {
+    log(`skipped extension ${file}: ${err.message}`);
+  }
+}
+
+await server.connect(new StdioServerTransport());
+log(`MCP server ${VERSION} ready on stdio`);

package/src/sources/dribbble.js

@@ -0,0 +1,358 @@
+// Dribbble client built on the HTML fragments the dribbble.com web app loads while you
+// scroll (the same requests the site's infinite scroll makes). No login, no API key, no
+// browser. Dribbble's official API only exposes your own shots, so it is not used.
+//
+// Limits we know about, and do not try to get around:
+//  - Shot pages (dribbble.com/shots/<id>) answer plain HTTP clients with an empty bot check
+//    (HTTP 202), so there is no per-shot details tool; list results carry what we need.
+//  - Logged-out search only returns the first batch of results (about 36-48 shots); later
+//    pages repeat it. Explore feeds and designer profiles paginate normally.
+import { fetch, ProxyAgent } from 'undici';
+import crypto from 'node:crypto';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+export const BASE = 'https://dribbble.com';
+const UA =
+  'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/130.0.0.0 Safari/537.36';
+const TIMEOUT_MS = Number(process.env.MCP_DRIBBBLE_TIMEOUT_MS) || 20000;
+const PER_PAGE = 24;
+const MAX_PAGES = 8;
+
+const proxyUrl =
+  process.env.MCP_DRIBBBLE_PROXY ||
+  process.env.HTTPS_PROXY ||
+  process.env.https_proxy ||
+  process.env.HTTP_PROXY ||
+  process.env.http_proxy ||
+  '';
+const dispatcher = proxyUrl ? new ProxyAgent(proxyUrl) : undefined;
+
+export const DOWNLOAD_ROOT =
+  process.env.MCP_DRIBBBLE_DOWNLOAD_DIR || path.join(os.homedir(), 'Downloads', 'dribbble-mcp');
+
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+
+// `timeout` covers the whole response, body included, so large videos get a longer one.
+async function request(url, { timeout = TIMEOUT_MS, ...init } = {}, retries = 2) {
+  for (let attempt = 0; ; attempt++) {
+    let res;
+    try {
+      res = await fetch(url, {
+        ...init,
+        dispatcher,
+        signal: AbortSignal.timeout(timeout),
+        headers: { 'User-Agent': UA, 'Accept-Language': 'en-US', ...init.headers },
+      });
+    } catch (err) {
+      if (attempt < retries) {
+        await sleep(600 * (attempt + 1));
+        continue;
+      }
+      const hint = proxyUrl ? '' : ' (if dribbble.com is blocked on your network, set MCP_DRIBBBLE_PROXY)';
+      throw new Error(`Network error reaching ${new URL(url).host}: ${err.cause?.message || err.message}${hint}`);
+    }
+    if ((res.status === 429 || res.status >= 500) && attempt < retries) {
+      await sleep(1000 * (attempt + 1));
+      continue;
+    }
+    return res;
+  }
+}
+
+// One page of a shot grid, as the site's infinite scroll requests it.
+async function gridPage(pathname, params) {
+  const qs = new URLSearchParams({ ...params, per_page: String(PER_PAGE) });
+  const url = `${BASE}${pathname}?${qs}`;
+  const res = await request(url, {
+    headers: { Accept: 'text/html, */*; q=0.01', 'X-Requested-With': 'XMLHttpRequest' },
+  });
+  const html = await res.text();
+  if (res.status === 404) {
+    const err = new Error(`Dribbble has no page at ${pathname}`);
+    err.status = 404;
+    throw err;
+  }
+  if (res.status === 202 || (res.ok && !html.trim())) {
+    throw new Error(
+      `Dribbble answered ${pathname} with a bot check (HTTP ${res.status}, empty body). ` +
+        'This server does not try to get past it; wait a while and try again.'
+    );
+  }
+  if (!res.ok) throw new Error(`Dribbble ${pathname}: HTTP ${res.status}`);
+  return parseShots(html);
+}
+
+// ---------- parsing ----------
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+export function decode(s) {
+  return String(s).replace(/&(#x[0-9a-f]+|#\d+|[a-z]+);/gi, (m, e) => {
+    if (e[0] === '#') {
+      const n = e[1] === 'x' || e[1] === 'X' ? parseInt(e.slice(2), 16) : parseInt(e.slice(1), 10);
+      return Number.isFinite(n) ? String.fromCodePoint(n) : m;
+    }
+    return ENTITIES[e.toLowerCase()] ?? m;
+  });
+}
+
+const clean = (s, max = 280) => {
+  if (!s || typeof s !== 'string') return undefined;
+  const t = decode(s).replace(/\s+/g, ' ').trim();
+  if (!t) return undefined;
+  return t.length > max ? `${t.slice(0, max - 1)}…` : t;
+};
+
+function strip(obj) {
+  for (const k of Object.keys(obj)) if (obj[k] === undefined || obj[k] === null || obj[k] === '') delete obj[k];
+  return obj;
+}
+
+const attr = (html, name) => html.match(new RegExp(`${name}="([^"]*)"`))?.[1];
+const baseUrl = (u) => (u ? decode(u).split('?')[0] : undefined);
+
+// "107k" / "1.2m" / "66" -> number
+export function count(s) {
+  const m = String(s ?? '').trim().toLowerCase().replace(/,/g, '').match(/^([\d.]+)\s*([km])?$/);
+  if (!m) return undefined;
+  const n = Number(m[1]) * (m[2] === 'k' ? 1e3 : m[2] === 'm' ? 1e6 : 1);
+  return Number.isFinite(n) ? Math.round(n) : undefined;
+}
+
+// The fragment also ships a `newestShots = [...]` array with publish dates and counts.
+function shotMeta(html) {
+  const m = html.match(/newestShots\s*=\s*(\[[\s\S]*?\])\s*\n/);
+  if (!m) return new Map();
+  try {
+    return new Map(JSON.parse(m[1]).map((s) => [String(s.id), s]));
+  } catch {
+    return new Map();
+  }
+}
+
+const MONTHS = 'January February March April May June July August September October November December'.split(' ');
+function isoDate(s) {
+  const m = String(s || '').match(/^(\w+) (\d{1,2}), (\d{4})$/);
+  const mi = m ? MONTHS.indexOf(m[1]) : -1;
+  if (mi < 0) return undefined;
+  return `${m[3]}-${String(mi + 1).padStart(2, '0')}-${m[2].padStart(2, '0')}`;
+}
+
+export function parseShots(html) {
+  const meta = shotMeta(html);
+  const starts = [...html.matchAll(/<li\b[^>]*\bdata-thumbnail-id="(\d+)"/g)];
+  const shots = [];
+  for (let i = 0; i < starts.length; i++) {
+    const id = starts[i][1];
+    const chunk = html.slice(starts[i].index, starts[i + 1]?.index ?? html.length);
+    const shot = normalizeShot(id, chunk, meta.get(id));
+    if (shot) shots.push(shot);
+  }
+  return shots;
+}
+
+function normalizeShot(id, chunk, meta = {}) {
+  const img = chunk.match(/<img\b[^>]*\bdata-src="([^"]+)"[^>]*>/) || chunk.match(/<noscript>\s*<img\b[^>]*\bsrc="([^"]+)"/);
+  const image = baseUrl(img?.[1]);
+  if (!image || !/\/userupload\//.test(image)) return null;
+  const titleHtml = chunk.match(/<div class="shot-title">([\s\S]*?)<\/div>/)?.[1];
+  const title = clean(titleHtml, 140) || clean(meta.title, 140);
+  const alt = clean(attr(chunk, 'alt'), 400);
+  // The alt text is the title followed by the shot's tags.
+  const tags = alt && title && alt.startsWith(title) ? clean(alt.slice(title.length), 200) : undefined;
+  const animated = baseUrl(attr(chunk, 'data-animated-url'));
+  const teaser = baseUrl(attr(chunk, 'data-video-teaser-large'));
+  const video = [animated, teaser].find((u) => u && /\.mp4$/i.test(u));
+  const gif = animated && /\.gif$/i.test(animated) ? animated : undefined;
+  const pathname = chunk.match(/href="(\/shots\/\d+[^"]*)"/)?.[1] || meta.path;
+  const user = chunk.match(/<a\b[^>]*rel="contact"[^>]*href="\/([^"/?]+)"/)?.[1];
+  const designer = clean(chunk.match(/<span class="display-name">([\s\S]*?)<\/span>/)?.[1], 80);
+  const likes = count(chunk.match(/data-shot-like-count>\s*([^<]+)</)?.[1]) ?? count(meta.likes_count);
+  const views = count(chunk.match(/js-shot-views-count[^>]*>\s*([^<]+)</)?.[1]) ?? count(meta.view_count);
+  return strip({
+    id,
+    shot_url: pathname ? `${BASE}${decode(pathname)}` : `${BASE}/shots/${id}`,
+    title,
+    tags,
+    image_url: image,
+    video_url: video,
+    gif_url: gif,
+    dominant_color: chunk.match(/background-color:\s*(#[0-9a-f]{3,8})/i)?.[1],
+    designer,
+    designer_url: user ? `${BASE}/${user}` : undefined,
+    team_or_pro: /pro-badge/.test(chunk) || undefined,
+    likes,
+    views,
+    attachments: meta.attachments_count || undefined,
+    published: isoDate(meta.published_at),
+  });
+}
+
+// ---------- paging ----------
+
+const MEDIA = {
+  any: () => true,
+  video: (s) => Boolean(s.video_url || s.gif_url),
+  image: (s) => !s.video_url && !s.gif_url,
+};
+
+// Walks pages until `limit` shots are collected. A page that adds nothing new ends the
+// feed (logged-out search replays its first batch instead of paging).
+async function paged(fetchPage, { limit, page = 1, media = 'any' }) {
+  const keep = MEDIA[media] || MEDIA.any;
+  const out = [];
+  const seen = new Set();
+  let p = page;
+  let more = true;
+  for (let n = 0; n < MAX_PAGES && out.length < limit; n++, p++) {
+    const shots = await fetchPage(p);
+    let fresh = 0;
+    for (const s of shots) {
+      if (seen.has(s.id)) continue;
+      seen.add(s.id);
+      fresh++;
+      if (out.length < limit && keep(s)) out.push(s);
+    }
+    if (!fresh || shots.length < PER_PAGE) {
+      more = false;
+      break;
+    }
+  }
+  return { shots: out, next_page: more ? p : undefined };
+}
+
+// ---------- public API ----------
+
+export const SORTS = ['popular', 'recent'];
+
+export async function searchShots(query, { limit = 24, page = 1, sort = 'popular', media = 'any' } = {}) {
+  return paged((p) => gridPage(`/search/shots/${sort}`, { q: query, page: String(p) }), { limit, page, media });
+}
+
+export const CATEGORIES = [
+  'animation',
+  'branding',
+  'illustration',
+  'mobile',
+  'print',
+  'product-design',
+  'typography',
+  'web-design',
+];
+
+export async function exploreShots({ category, sort = 'popular', limit = 24, page = 1, media = 'any' } = {}) {
+  const pathname = `/shots/${sort}${category ? `/${category}` : ''}`;
+  return paged((p) => gridPage(pathname, { page: String(p) }), { limit, page, media });
+}
+
+export function parseUser(input) {
+  let s = String(input).trim().replace(/^@/, '');
+  if (/^https?:\/\//.test(s) || /dribbble\.com/.test(s)) {
+    s = new URL(/^https?:\/\//.test(s) ? s : `https://${s}`).pathname.split('/').filter(Boolean)[0] || '';
+  }
+  if (!/^[\w-]+$/.test(s) || s === 'shots') throw new Error(`Expected a designer profile like dribbble.com/<name>, got: ${input}`);
+  return s;
+}
+
+export async function userShots(input, { limit = 24, page = 1, media = 'any' } = {}) {
+  const user = parseUser(input);
+  const designer_url = `${BASE}/${user}`;
+  const res = await paged(
+    async (p) => (await gridPage(`/${user}/shots`, { page: String(p) })).map((s) => ({ ...s, designer_url: s.designer_url || designer_url })),
+    { limit, page, media }
+  );
+  return { designer_url, ...res };
+}
+
+// ---------- images ----------
+
+function assertCdn(u) {
+  let url;
+  try {
+    url = new URL(u);
+  } catch {
+    throw new Error(`Invalid media URL: ${u}`);
+  }
+  if (url.protocol !== 'https:' || url.hostname !== 'cdn.dribbble.com') {
+    throw new Error(`Only https://cdn.dribbble.com URLs are allowed: ${u}`);
+  }
+  return url;
+}
+
+// The CDN serves some .mp4 uploads as video/quicktime; those keep the URL's extension.
+const EXT = { 'image/jpeg': 'jpg', 'image/png': 'png', 'image/gif': 'gif', 'image/webp': 'webp', 'video/mp4': 'mp4' };
+const MAX_BYTES = 200 * 1024 * 1024;
+const VIDEO_TIMEOUT_MS = Math.max(TIMEOUT_MS, 180000);
+
+async function fetchMedia(u, kind) {
+  const timeout = kind === 'video' ? VIDEO_TIMEOUT_MS : TIMEOUT_MS;
+  const res = await request(u, { timeout, headers: { Referer: `${BASE}/` } }, 1);
+  const type = (res.headers.get('content-type') || '').split(';')[0];
+  if (!res.ok || !type.startsWith(`${kind}/`)) {
+    await res.body?.cancel();
+    throw new Error(`Could not fetch ${u}: HTTP ${res.status}${res.ok ? ` (${type})` : ''}`);
+  }
+  if (Number(res.headers.get('content-length')) > MAX_BYTES) {
+    await res.body?.cancel();
+    throw new Error(`${u} is larger than ${MAX_BYTES / 1024 / 1024} MB`);
+  }
+  return { type, buf: Buffer.from(await res.arrayBuffer()) };
+}
+
+// The CDN resizes and converts on the fly; a JPEG thumbnail keeps token cost low.
+export async function fetchPreview(u, width = 400) {
+  const url = assertCdn(u);
+  if (/\.(mp4|webm)$/i.test(url.pathname)) throw new Error('Videos cannot be previewed; pass the shot\'s image_url instead');
+  const h = Math.round((width * 3) / 4);
+  const { type, buf } = await fetchMedia(
+    `${url.origin}${url.pathname}?format=jpg&resize=${width}x${h}&vertical=center`,
+    'image'
+  );
+  return { mimeType: type, data: buf.toString('base64') };
+}
+
+async function mapLimit(items, n, fn) {
+  const out = new Array(items.length);
+  let i = 0;
+  await Promise.all(
+    Array.from({ length: Math.min(n, items.length) }, async () => {
+      while (i < items.length) {
+        const idx = i++;
+        out[idx] = await fn(items[idx], idx);
+      }
+    })
+  );
+  return out;
+}
+
+const safeName = (s) =>
+  String(s || '')
+    .normalize('NFKC')
+    .replace(/[\\/:*?"<>|\x00-\x1f]+/g, ' ')
+    .replace(/\s+/g, '_')
+    .replace(/^[._]+|[._]+$/g, '')
+    .slice(0, 60);
+
+export async function downloadMedia(urls, { folder, directory } = {}) {
+  const root = path.resolve(directory || DOWNLOAD_ROOT);
+  const dir = folder ? path.join(root, safeName(folder) || 'shots') : root;
+  await fs.mkdir(dir, { recursive: true });
+  const results = await mapLimit(urls, 4, async (u, idx) => {
+    try {
+      const url = assertCdn(u);
+      const clean = `${url.origin}${url.pathname}`;
+      const kind = /\.(mp4|webm)$/i.test(url.pathname) ? 'video' : 'image';
+      const media = await fetchMedia(clean, kind);
+      const stem = path.basename(url.pathname).replace(/\.\w+$/, '') ||
+        crypto.createHash('sha1').update(clean).digest('hex').slice(0, 16);
+      const ext = EXT[media.type] || path.extname(url.pathname).slice(1).toLowerCase() || 'bin';
+      const file = path.join(dir, `${String(idx + 1).padStart(2, '0')}_${stem}.${ext}`);
+      await fs.writeFile(file, media.buf);
+      return { ok: true, url: clean, path: file, bytes: media.buf.length };
+    } catch (err) {
+      return { ok: false, url: u, error: err.message };
+    }
+  });
+  return { directory: dir, saved: results.filter((r) => r.ok), failed: results.filter((r) => !r.ok) };
+}