Skill: lycici/keyapi-youtube-channel-analysis (version 1.0.0)

--- name: keyapi-youtube-channel-analysis description: Discover, profile, and analyze YouTube channels — retrieve channel metadata, video libraries, convert between channel IDs and URLs, search channels by keyword, and explore advanced search with filters. metadata: {"openclaw":{"requires":{"env":["KEYAPI_TOKEN"],"bins":["node"]},"primaryEnv":"KEYAPI_TOKEN","emoji":"📺"}} author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- # keyapi-youtube-channel-analysis > Discover, profile, and analyze YouTube channels — from identity resolution and metadata retrieval to video inventory, channel search, and advanced filtered discovery. This skill provides comprehensive YouTube channel intelligence using the KeyAPI MCP service. It enables detailed channel profile retrieval (including a two-step process for full metadata), video library enumeration, bidirectional conversion between channel IDs and URLs, keyword-based channel search, within-channel content search, advanced filtered search across YouTube, and search suggestion retrieval — all through a cache-first workflow. Use this skill when you need to: - Retrieve full channel metadata including description, subscriber count, view count, join date, and social links - Convert between channel URLs (various formats) and channel IDs, or resolve @username handles - Enumerate a channel's published video library with pagination support - Search for channels by keyword with result filtering to channel-type only - Search within a specific channel's content by keyword - Perform advanced YouTube searches with filters (upload time, duration, content type, features, sort order) - Get real-time search suggestions for keyword research and autocomplete author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## Prerequisites | Requirement | Details | |-------------|---------| | **KEYAPI_TOKEN** | A valid API token from [keyapi.ai](https://keyapi.ai/). If you don't have one, register at the site to obtain your free token. Set it as an environment variable: `export KEYAPI_TOKEN=your_token_here` | | **Node.js** | v18 or higher | | **Dependencies** | Run `npm install` in the skill directory to install `@modelcontextprotocol/sdk` | author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## MCP Server Configuration All tool calls in this skill target the KeyAPI YouTube MCP server: ``` Server URL : https://mcp.keyapi.ai/youtube/mcp Auth Header: Authorization: Bearer $KEYAPI_TOKEN ``` **Setup (one-time):** ```bash # 1. Install dependencies npm install # 2. Set your API token (get one free at https://keyapi.ai/) export KEYAPI_TOKEN=your_token_here # 3. List all available tools to verify the connection node scripts/run.js --platform youtube --list-tools ``` author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## Analysis Scenarios ### Channel Identity & Metadata Nodes | User Need | Node(s) | Best For | |-----------|---------|----------| | Full channel metadata (two-step process) | `get_channel_description` | Complete channel audit — call twice: first with `channel_id`, then with `continuation_token` from response | | Extract channel ID from any URL format | `get_channel_id_from_url` | URL normalization — supports @username, /channel/, /c/, /user/ formats | | Get @username handle from channel ID | `get_channel_url_from_channel_id` | Reverse lookup — channel ID → @handle | | Resolve channel name to channel ID | `get_channel_id` | Keyword-based ID lookup by channel name | ### Channel Content Nodes | User Need | Node(s) | Best For | |-----------|---------|----------| | List all videos from a channel | `get_channel_videos` | Video inventory, content cadence analysis — requires UC-format channel ID | ### Search & Discovery Nodes | User Need | Node(s) | Best For | |-----------|---------|----------| | Search for channels by keyword | `search_channels` | Channel discovery — returns only channel-type results, filters out videos/playlists | | Search within a specific channel | `search_channel` | In-channel content search by keyword — requires channel ID | | Advanced filtered search across YouTube | `general_search_with_filters` | Precision discovery — filter by upload time, duration, content type, features, sort order | | Get search suggestions / autocomplete | `get_search_suggestions` | Keyword research, query expansion — returns 10–20 suggestions in <1 second | author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## Workflow ### Step 1 — Identify the Channel Analysis Objective and Select Nodes Clarify the research goal and map it to one or more nodes. Common patterns: - **Channel profile deep-dive**: Use `get_channel_description` **twice** — first call with `channel_id` returns basic info + `continuation_token`; second call with that token returns advanced info (join date, social links, view count). - **URL → ID conversion**: Use `get_channel_id_from_url` to normalize any channel URL format to a channel ID. - **ID → @handle conversion**: Use `get_channel_url_from_channel_id` to get the user-friendly @username from a channel ID. - **Channel discovery**: Use `search_channels` with keyword → optionally deepen with `get_channel_description` for each result. - **Video inventory**: Use `get_channel_videos` with `channel_id` (must be UC-format) → paginate with `continuation_token`. - **Advanced search**: Use `general_search_with_filters` with upload time, duration, content type, and sort filters. > **Channel ID formats** > > - **UC-format**: 24-character string starting with `UC` (e.g., `UCeu6U67OzJhV1KwBansH3Dg`) — required for `get_channel_videos` and `get_channel_description`. > - **@username format**: User-friendly handle (e.g., `@CozyCraftYT`) — use `get_channel_id_from_url` to convert to UC-format. > - **URL formats**: Supports `youtube.com/@username`, `youtube.com/channel/UCxxxxxx`, `youtube.com/c/name`, `youtube.com/user/name`. > **`get_channel_description` two-step process** > > This endpoint requires **two sequential calls** to retrieve complete channel information: > 1. **First call**: Pass `channel_id` → returns basic info (name, description, subscriber count, video count, banner) + `continuation_token`. > 2. **Second call**: Pass `continuation_token` from step 1 → returns advanced info (join date, social media links, featured sections, total view count). > > Do NOT call both simultaneously — the second call depends on the token from the first. ### Step 2 — Retrieve API Schema Before calling any node, inspect its input schema to confirm required parameters and available options: ```bash node scripts/run.js --platform youtube --schema <tool_name> # Examples node scripts/run.js --platform youtube --schema get_channel_description node scripts/run.js --platform youtube --schema general_search_with_filters ``` ### Step 3 — Call APIs and Cache Results Locally Execute tool calls and persist responses to the local cache. **Calling a tool:** ```bash node scripts/run.js --platform youtube --tool <tool_name> \ --params '<json_args>' --pretty # Skip cache for fresh results node scripts/run.js --platform youtube --tool <tool_name> \ --params '<json_args>' --no-cache --pretty ``` **Example — get full channel metadata (two-step):** ```bash # Step 1: Get basic info + continuation_token node scripts/run.js --platform youtube --tool get_channel_description \ --params '{"channel_id":"UCeu6U67OzJhV1KwBansH3Dg","language_code":"en-US","country_code":"US","need_format":true}' --pretty # Step 2: Get advanced info using continuation_token from Step 1 node scripts/run.js --platform youtube --tool get_channel_description \ --params '{"continuation_token":"<token_from_step_1>","language_code":"en-US","country_code":"US","need_format":true}' --pretty ``` **Example — convert channel URL to ID:** ```bash node scripts/run.js --platform youtube --tool get_channel_id_from_url \ --params '{"channel_url":"https://www.youtube.com/@CozyCraftYT"}' --pretty ``` **Example — get @handle from channel ID:** ```bash node scripts/run.js --platform youtube --tool get_channel_url_from_channel_id \ --params '{"channel_id":"UCeu6U67OzJhV1KwBansH3Dg"}' --pretty ``` **Example — get channel videos (first page):** ```bash node scripts/run.js --platform youtube --tool get_channel_videos \ --params '{"channel_id":"UCJHBJ7F-nAIlMGolm0Hu4vg","language_code":"en-US","country_code":"US"}' --pretty ``` **Example — paginate to next video page:** ```bash node scripts/run.js --platform youtube --tool get_channel_videos \ --params '{"channel_id":"UCJHBJ7F-nAIlMGolm0Hu4vg","continuation_token":"<token>"}' --pretty ``` **Example — search channels by keyword:** ```bash # First page node scripts/run.js --platform youtube --tool search_channels \ --params '{"keyword":"fitness","need_format":true}' --pretty # Next page node scripts/run.js --platform youtube --tool search_channels \ --params '{"continuation_token":"<token>","need_format":true}' --pretty ``` **Example — search within a channel:** ```bash node scripts/run.js --platform youtube --tool search_channel \ --params '{"channel_id":"UCXuqSBlHAE6Xw-yeJA0Tunw","search_query":"AMD","language_code":"en","country_code":"US"}' --pretty ``` **Example — advanced filtered search:** ```bash node scripts/run.js --platform youtube --tool general_search_with_filters \ --params '{"search_query":"Python tutorial","upload_time":"month","duration":"medium","content_type":"video","feature":"hd","sort_by":"view_count","language_code":"en-US","country_code":"US"}' --pretty ``` **Example — get search suggestions:** ```bash node scripts/run.js --platform youtube --tool get_search_suggestions \ --params '{"keyword":"machine learning","language":"en","region":"US"}' --pretty ``` **Example — resolve channel name to ID:** ```bash node scripts/run.js --platform youtube --tool get_channel_id \ --params '{"channel_name":"LinusTechTips"}' --pretty ``` **Pagination:** | Endpoint | Pagination | Notes | |---|---|---| | `get_channel_description` | `continuation_token` | Two-step: first call returns token for second call | | `get_channel_videos` | `continuation_token` | From previous response | | `search_channels`, `search_channel`, `general_search_with_filters` | `continuation_token` | From previous response | | `get_channel_id_from_url`, `get_channel_url_from_channel_id`, `get_channel_id`, `get_search_suggestions` | — | Single-call; no pagination | **Cache directory structure:** ``` .keyapi-cache/ └── YYYY-MM-DD/ ├── get_channel_description/ │ └── {params_hash}.json ├── get_channel_id_from_url/ │ └── {params_hash}.json ├── get_channel_url_from_channel_id/ │ └── {params_hash}.json ├── get_channel_videos/ │ └── {params_hash}.json ├── get_channel_id/ │ └── {params_hash}.json ├── search_channels/ │ └── {params_hash}.json ├── search_channel/ │ └── {params_hash}.json ├── general_search_with_filters/ │ └── {params_hash}.json └── get_search_suggestions/ └── {params_hash}.json ``` **Cache-first policy:** Before every API call, check whether a cached result already exists. If valid, load from disk and skip the API call. ### Step 4 — Synthesize and Report Findings **For channel analysis:** 1. **Channel Overview** — Name, @handle, channel ID, subscriber count, total video count, total view count, join date, verification status. 2. **Channel Description** — Bio, featured links, social media connections, country/language. 3. **Content Inventory** — Video count, upload frequency, most recent video date, content categories. 4. **Audience Signals** — Subscriber-to-view ratio, engagement indicators from recent videos. 5. **Featured Sections** — Playlists, channels, or content highlighted by the creator. **For channel discovery:** 1. **Search Results Overview** — Matched channels, subscriber counts, verification status, content focus. 2. **Comparative Analysis** — Side-by-side metrics for shortlisted channels. 3. **Keyword Expansion** — Search suggestions for related queries, trending topics. author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## Common Rules | Rule | Detail | |------|--------| | **Channel ID format** | `get_channel_videos` and `get_channel_description` require UC-format channel IDs (24 characters starting with `UC`). Use `get_channel_id_from_url` to convert @username or other URL formats. | | **`get_channel_description` two-step** | **Critical**: This endpoint requires two sequential calls. First call with `channel_id` returns basic info + `continuation_token`. Second call with that token returns advanced info. Do NOT call both simultaneously. | | **URL format support** | `get_channel_id_from_url` supports multiple formats: `@username`, `/channel/UCxxxxxx`, `/c/name`, `/user/name`. | | **`search_channels` vs `search_channel`** | `search_channels` searches across YouTube for channels by keyword. `search_channel` searches within a specific channel's content. | | **`need_format` parameter quirk** | The `get_channel_videos` schema has a trailing space in the parameter name: `"need_format "` (with space). However, the API accepts both forms. Omit this parameter in examples to avoid confusion. Available on `get_channel_description` and `search_channels` without the space issue. | | **Language / region params** | `language_code` and `country_code` influence result language and regional content bias. Use `en-US` / `US` for English-language global results. | | **Success check** | `code = 0` → success. Any other value → failure. Always check the response code before processing data. | | **Retry on 500** | If `code = 500`, retry the identical request up to 3 times with a 2–3 second pause between attempts before reporting the error. | | **Cache first** | Always check the local `.keyapi-cache/` directory before issuing a live API call. | author: KeyAPI license: MIT repository: https://github.com/EchoSell/keyapi-skills --- ## Error Handling | Code | Meaning | Action | |------|---------|--------| | `0` | Success | Continue workflow normally | | `400` | Bad request — invalid or missing parameters | Validate input against the tool schema; check channel ID format (must be UC-format for some endpoints), URL format, and required fields | | `401` | Unauthorized — token missing or expired | Confirm `KEYAPI_TOKEN` is set correctly; visit [keyapi.ai](https://keyapi.ai/) to renew | | `403` | Forbidden — plan quota exceeded or feature restricted | Review plan limits at [keyapi.ai](https://keyapi.ai/) | | `404` | Resource not found — channel may not exist or URL is invalid | Verify the channel ID or URL; the channel may have been deleted or made private | | `429` | Rate limit exceeded | Wait 60 seconds, then retry | | `500` | Internal server error | Retry up to 3 times with a 2–3 second pause; if it persists, log the full request and response and skip this node | | Other non-0 | Unexpected error | Log the full response body and surface the error message to the user |

path: package.json
content: {
  "name": "keyapi-youtube-channel-analysis",
  "type": "module",
  "engines": { "node": ">=18.0.0" },
  "dependencies": {
    "@modelcontextprotocol/sdk": "^1.10.2"
  }
}


path: scripts/run.js
content: #!/usr/bin/env node
/**
 * KeyAPI MCP Tool Runner
 *
 * Calls any KeyAPI MCP tool with built-in caching, auto-pagination,
 * and automatic cover-image URL conversion.
 *
 * Usage:
 *   node scripts/run.js --tool <tool_name> [options]
 *   node scripts/run.js --list-tools
 *   node scripts/run.js --schema <tool_name>
 *
 * Options:
 *   --tool <name>       MCP tool name to call  (required for tool calls)
 *   --platform <name>   Platform to target  (default: tiktok)
 *   --params <json>     Tool parameters as JSON string  (default: {})
 *   --page-num <n>      Page number for paginated endpoints  (default: 1)
 *   --page-size <n>     Items per page — max 10  (default: 10)
 *   --all-pages         Auto-fetch ALL pages and merge list results
 *   --no-cache          Skip cache lookup, force a fresh API call
 *   --no-images         Skip automatic cover-image URL conversion
 *   --cache-dir <path>  Cache directory  (default: .keyapi-cache)
 *   --output <path>     Also save result to this file path
 *   --pretty            Pretty-print JSON output to stdout
 *   --list-tools        List all available tools on the MCP server
 *   --schema <name>     Show the input schema for a specific tool
 *   --help              Show this help
 *
 * Environment variables:
 *   KEYAPI_TOKEN        Required. Get yours at https://keyapi.ai/
 *   KEYAPI_SERVER_URL   Optional MCP base URL override  (default: https://mcp.keyapi.ai)
 */

import { Client } from "@modelcontextprotocol/sdk/client/index.js";
import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
import { createHash } from "crypto";
import { readFileSync, writeFileSync, mkdirSync, existsSync } from "fs";
import { join, resolve, dirname } from "path";
import { fileURLToPath } from "url";
import { parseArgs } from "util";

const __dirname = dirname(fileURLToPath(import.meta.url));
const ROOT = resolve(__dirname, "..");

// ── .env loader ───────────────────────────────────────────────────────────────

(function loadDotenv() {
  const envPath = join(ROOT, ".env");
  if (!existsSync(envPath)) return;
  for (const line of readFileSync(envPath, "utf8").split("\n")) {
    const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)$/);
    if (m && !process.env[m[1]])
      process.env[m[1]] = m[2].replace(/^["']|["']$/g, "").trim();
  }
})();

// ── Config ────────────────────────────────────────────────────────────────────

const SERVER_BASE = process.env.KEYAPI_SERVER_URL ?? "https://mcp.keyapi.ai";
const PAGE_SIZE_MAX = 10;

/**
 * Platforms that require cover-image URL conversion.
 * Only TikTok serves images via the echosell CDN host that needs proxying.
 * Other platforms serve images directly — no conversion needed.
 */
const COVER_IMAGE_HOSTS = {
  tiktok: ["echosell-images.tos-ap-southeast-1.volces.com"],
};

function getCoverImageHosts(platform) {
  return COVER_IMAGE_HOSTS[platform] ?? [];
}

// ── Help text ─────────────────────────────────────────────────────────────────

const HELP = `KeyAPI MCP Tool Runner
======================

Calls KeyAPI MCP tools with caching, auto-pagination, and cover-image conversion.

Usage:
  node scripts/run.js --tool <tool_name> [options]
  node scripts/run.js --list-tools
  node scripts/run.js --schema <tool_name>

Options:
  --tool <name>       MCP tool name to call  (required for tool calls)
  --platform <name>   Platform to target  (default: tiktok)
  --params <json>     Tool parameters as JSON string  (default: {})
  --page-num <n>      Page number for paginated endpoints  (default: 1)
  --page-size <n>     Items per page — max 10  (default: 10)
  --all-pages         Auto-fetch ALL pages and merge list results
  --no-cache          Skip cache lookup, force a fresh API call
  --no-images         Skip automatic cover-image URL conversion
  --cache-dir <path>  Cache directory  (default: .keyapi-cache)
  --output <path>     Also save result to this file path
  --pretty            Pretty-print JSON output to stdout
  --list-tools        List all available tools on the MCP server
  --schema <name>     Show the input schema for a specific tool
  --help              Show this help

Environment:
  KEYAPI_TOKEN        Required. Get yours at https://keyapi.ai/
                      Set via: export KEYAPI_TOKEN=your_token
                      Or save to a .env file in the skill directory.
  KEYAPI_SERVER_URL   Optional MCP base URL override
                      (default: https://mcp.keyapi.ai)

Examples:
  # List all tools on a platform
  node scripts/run.js --list-tools
  node scripts/run.js --platform youtube --list-tools

  # Inspect a tool's input schema
  node scripts/run.js --schema search_influencers

  # Call a tool (platform defaults to tiktok)
  node scripts/run.js --tool search_influencers \\
    --params '{"keyword":"fitness","region":"US"}' --pretty

  # Explicit platform
  node scripts/run.js --platform tiktok --tool get_influencer_detail \\
    --params '{"unique_id":"charlidamelio"}' --pretty

  # Another platform
  node scripts/run.js --platform youtube --tool search_channels \\
    --params '{"keyword":"fitness"}' --pretty
`;

// ── File / cache utilities ────────────────────────────────────────────────────

function ensureDir(dir) {
  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
}

function readJSON(path) {
  try {
    if (existsSync(path)) return JSON.parse(readFileSync(path, "utf8"));
  } catch { /* ignore */ }
  return null;
}

function writeJSON(path, data) {
  ensureDir(dirname(path));
  writeFileSync(path, JSON.stringify(data, null, 2), "utf8");
}

/** Deterministic cache path: .keyapi-cache/YYYY-MM-DD/<tool>/<hash>.json */
function cacheKey(tool, params, cacheDir) {
  const hash = createHash("md5")
    .update(JSON.stringify(params, Object.keys(params).sort()))
    .digest("hex")
    .slice(0, 16);
  const date = new Date().toISOString().slice(0, 10); // YYYY-MM-DD
  return join(cacheDir, date, tool, `${hash}.json`);
}

// ── Cover-image helpers ───────────────────────────────────────────────────────

function collectImageUrls(obj, hosts, acc = []) {
  if (!obj || typeof obj !== "object") return acc;
  if (Array.isArray(obj)) {
    for (const item of obj) collectImageUrls(item, hosts, acc);
  } else {
    for (const v of Object.values(obj)) {
      if (typeof v === "string" && hosts.some(h => v.includes(h))) acc.push(v);
      else collectImageUrls(v, hosts, acc);
    }
  }
  return acc;
}

function replaceImageUrls(obj, map) {
  if (!obj || typeof obj !== "object") return obj;
  if (Array.isArray(obj)) return obj.map(i => replaceImageUrls(i, map));
  return Object.fromEntries(
    Object.entries(obj).map(([k, v]) =>
      typeof v === "string" && map.has(v) ? [k, map.get(v)] : [k, replaceImageUrls(v, map)]
    )
  );
}

/** Split array into chunks of n */
function chunk(arr, n) {
  const out = [];
  for (let i = 0; i < arr.length; i += n) out.push(arr.slice(i, i + n));
  return out;
}

// ── Heuristic list extractor for --all-pages ─────────────────────────────────

const LIST_KEYS = [
  "list", "items", "results", "videos", "products", "creators",
  "shops", "influencers", "hashtags", "music", "ads", "data",
  "channels", "posts", "comments", "reviews", "users",
];

function extractList(data) {
  const d = data?.data ?? data;
  for (const k of LIST_KEYS) {
    if (Array.isArray(d?.[k])) return d[k];
  }
  return Array.isArray(d) ? d : [];
}

// ── Schema cache & pagination detection ──────────────────────────────────────

/** Session-level tool schema cache — loaded once per process. */
let _toolSchemas = null;

async function getToolSchemas(client) {
  if (!_toolSchemas) {
    const { tools } = await client.listTools();
    _toolSchemas = new Map(tools.map(t => [t.name, t]));
  }
  return _toolSchemas;
}

/**
 * Inspect a tool's input schema to determine its pagination style.
 *
 * Returns:
 *   "analytics"  → tool accepts page_num / page_size
 *   "trending"   → tool accepts page / limit
 *   null         → tool has no recognised pagination fields
 */
async function detectPagination(client, toolName) {
  const schemas = await getToolSchemas(client);
  const tool = schemas.get(toolName);
  if (!tool?.inputSchema?.properties) return null;
  const props = tool.inputSchema.properties;
  if ("page_num" in props && "page_size" in props) return "analytics";
  if ("page" in props && "limit" in props) return "trending";
  return null;
}

// ── MCP client ────────────────────────────────────────────────────────────────

/** Prompt for KEYAPI_TOKEN interactively and persist it to .env */
async function promptToken() {
  if (!process.stdin.isTTY) {
    throw new Error(
      "KEYAPI_TOKEN is not set.\n" +
      "  → Register at https://keyapi.ai/ to obtain a free token, then either:\n" +
      "    export KEYAPI_TOKEN=your_token_here\n" +
      "  → Or create a .env file in the skill directory:\n" +
      "    echo \"KEYAPI_TOKEN=your_token_here\" > .env"
    );
  }
  const { createInterface } = await import("readline");
  const rl = createInterface({ input: process.stdin, output: process.stderr });
  return new Promise((resolve, reject) => {
    process.stderr.write("\nKEYAPI_TOKEN is required. Get yours at https://keyapi.ai/\n\n");
    rl.question("Enter your token: ", (answer) => {
      rl.close();
      const [REDACTED_SECRET]);
      if (!token) {
        reject(new Error("No token entered. Set KEYAPI_TOKEN and try again."));
        return;
      }
      const envPath = join(ROOT, ".env");
      writeFileSync(envPath, `KEYAPI_TOKEN=${token}\n`, "utf8");
      log(`[token] Saved to ${envPath} — future runs will load it automatically`);
      process.env.KEYAPI_TOKEN = token;
      resolve(token);
    });
  });
}

async function connect(serverUrl) {
  let [REDACTED_SECRET];
  if (!token) token = await promptToken();

  const client = new Client({ name: "keyapi-runner", version: "1.0.0" });
  const transport = new StreamableHTTPClientTransport(
    new URL(serverUrl),
    { requestInit: { headers: { Authorization: `Bearer ${token}` } } }
  );
  await client.connect(transport);
  return client;
}

/** Call a tool, parse the text/JSON response, retry once on code=500 */
async function callTool(client, tool, args) {
  for (let attempt = 0; attempt <= 1; attempt++) {
    const raw = await client.callTool({ name: tool, arguments: args });
    const textBlock = raw?.content?.find(c => c.type === "text");
    let data;
    try { data = textBlock ? JSON.parse(textBlock.text) : raw; }
    catch { data = { raw: textBlock?.text ?? raw }; }

    if (data?.code === 500 && attempt === 0) {
      log(`[retry] ${tool} returned code=500, retrying in 2s…`);
      await sleep(2000);
      continue;
    }
    return data;
  }
}

/**
 * Batch-convert platform cover image URLs.
 * Hosts are resolved from PLATFORM_CONFIG; skipped entirely if the platform
 * has no configured image hosts.
 * API accepts max 10 URLs per call as a comma-separated string (cover_urls).
 */
async function convertImages(client, data, platform) {
  const hosts = getCoverImageHosts(platform);
  if (hosts.length === 0) return data;

  const urls = [...new Set(collectImageUrls(data, hosts))];
  if (urls.length === 0) return data;

  const urlMap = new Map();

  for (const batch of chunk(urls, 10)) {
    try {
      const result = await callTool(client, "batch_download_cover_images", {
        cover_urls: batch.join(","),
      });
      if (result?.code === 0 && result?.data) {
        if (Array.isArray(result.data)) {
          for (const { original_url, converted_url } of result.data) {
            if (original_url && converted_url) urlMap.set(original_url, converted_url);
          }
        } else if (typeof result.data === "object") {
          for (const [k, v] of Object.entries(result.data)) urlMap.set(k, v);
        }
      }
    } catch (e) {
      log(`[images] Warning: batch conversion failed — ${e.message}`);
    }
  }

  if (urlMap.size > 0) {
    log(`[images] Converted ${urlMap.size} cover image URL(s)`);
    return replaceImageUrls(data, urlMap);
  }
  return data;
}

// ── Commands ──────────────────────────────────────────────────────────────────

async function cmdListTools(client) {
  const { tools } = await client.listTools();
  const out = tools.map(t => ({
    name: t.name,
    description: (t.description ?? "").slice(0, 100),
  }));
  emit(out, null, true);
}

async function cmdSchema(client, toolName) {
  const schemas = await getToolSchemas(client);
  const tool = schemas.get(toolName);
  if (!tool) {
    throw new Error(
      `Tool "${toolName}" not found on the server.\n` +
      "  Run --list-tools to see all available tools."
    );
  }
  emit(tool, null, true);
}

async function cmdRun(client, opts) {
  const { tool, platform, params, pageNum, pageSize, allPages, noCache, noImages, cacheDir, output, pretty } = opts;

  // Clamp page_size to max allowed by the API
  const safePageSize = Math.min(pageSize, PAGE_SIZE_MAX);

  // ── Single page ────────────────────────────────────────────────────────────
  if (!allPages) {
    const finalParams = { ...params };

    const paginationType = await detectPagination(client, tool);
    if (paginationType === "analytics") {
      if (!("page_num"  in finalParams)) finalParams.page_num  = pageNum;
      if (!("page_size" in finalParams)) finalParams.page_size = safePageSize;
    } else if (paginationType === "trending") {
      if (!("page"  in finalParams)) finalParams.page  = pageNum;
      if (!("limit" in finalParams)) finalParams.limit = safePageSize;
    }

    const cachePath = cacheKey(tool, finalParams, cacheDir);
    if (!noCache) {
      const cached = readJSON(cachePath);
      if (cached) {
        log(`[cache] Loaded from ${cachePath}`);
        emit(cached, output, pretty);
        return;
      }
    }

    let data = await callTool(client, tool, finalParams);
    assertSuccess(data, tool);
    if (!noImages) data = await convertImages(client, data, platform);
    writeJSON(cachePath, data);
    emit(data, output, pretty);
    return;
  }

  // ── All pages ──────────────────────────────────────────────────────────────
  const paginationType = await detectPagination(client, tool);
  const isTrending = paginationType === "trending";
  let page = 1;
  let allItems = [];
  let lastData = null;

  while (true) {
    const pageParams = isTrending
      ? { ...params, page: page, limit: safePageSize }
      : { ...params, page_num: page, page_size: safePageSize };

    const cachePath = cacheKey(tool, pageParams, cacheDir);

    let data = noCache ? null : readJSON(cachePath);
    if (data) {
      log(`[cache] Page ${page} loaded from ${cachePath}`);
    } else {
      data = await callTool(client, tool, pageParams);
      if (data?.code !== undefined && data.code !== 0) {
        log(`[warn] API error on page ${page}: code=${data.code} — ${data.message ?? ""}`);
        break;
      }
      if (!noImages) data = await convertImages(client, data, platform);
      writeJSON(cachePath, data);
    }

    const items = extractList(data);
    if (items.length === 0) break;

    allItems = allItems.concat(items);
    lastData = data;
    log(`[page ${page}] ${items.length} items  (total so far: ${allItems.length})`);

    const hasMore = data?.data?.has_more ?? data?.has_more;
    if (hasMore === false || items.length < safePageSize) break;
    page++;
  }

  const merged = {
    ...lastData,
    _merged: { total_pages: page, total_items: allItems.length },
    items: allItems,
  };
  writeJSON(cacheKey(tool, { ...params, _all_pages: true }, cacheDir), merged);
  emit(merged, output, pretty);
}

// ── Output / logging ──────────────────────────────────────────────────────────

function emit(data, filePath, pretty) {
  console.log(pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data));
  if (filePath) {
    const abs = resolve(filePath);
    ensureDir(dirname(abs));
    writeFileSync(abs, JSON.stringify(data, null, 2), "utf8");
    log(`[output] Saved to ${abs}`);
  }
}

function log(msg) { process.stderr.write(msg + "\n"); }
function sleep(ms) { return new Promise(r => setTimeout(r, ms)); }

function assertSuccess(data, tool) {
  if (data?.code !== undefined && data.code !== 0) {
    throw new Error(`API error from "${tool}": code=${data.code} — ${data.message ?? "(no message)"}`);
  }
}

// ── Entry point ───────────────────────────────────────────────────────────────

async function main() {
  const { values } = parseArgs({
    options: {
      tool:          { type: "string"  },
      platform:      { type: "string",  default: "tiktok" },
      schema:        { type: "string"  },
      params:        { type: "string",  default: "{}" },
      "page-num":    { type: "string",  default: "1"  },
      "page-size":   { type: "string",  default: "10" },
      "all-pages":   { type: "boolean", default: false },
      "no-cache":    { type: "boolean", default: false },
      "no-images":   { type: "boolean", default: false },
      "cache-dir":   { type: "string"  },
      output:        { type: "string"  },
      pretty:        { type: "boolean", default: false },
      "list-tools":  { type: "boolean", default: false },
      help:          { type: "boolean", default: false },
    },
    strict: false,
  });

  const needsHelp = values.help || (!values.tool && !values["list-tools"] && !values.schema);
  if (needsHelp) {
    process.stdout.write(HELP);
    process.exit(0);
  }

  let params;
  try { params = JSON.parse(values.params); }
  catch { throw new Error(`--params is not valid JSON: ${values.params}`); }

  const cacheDir = values["cache-dir"]
    ? resolve(values["cache-dir"])
    : join(ROOT, ".keyapi-cache");

  const serverUrl = `${SERVER_BASE}/${values.platform}/mcp`;
  const client = await connect(serverUrl);

  try {
    if (values["list-tools"]) {
      await cmdListTools(client);
    } else if (values.schema) {
      await cmdSchema(client, values.schema);
    } else {
      await cmdRun(client, {
        tool:     values.tool,
        platform: values.platform,
        params,
        pageNum:  parseInt(values["page-num"],  10),
        pageSize: parseInt(values["page-size"], 10),
        allPages: values["all-pages"],
        noCache:  values["no-cache"],
        noImages: values["no-images"],
        cacheDir,
        output:   values.output,
        pretty:   values.pretty,
      });
    }
  } finally {
    await client.close().catch(() => {});
  }
}

main().catch(err => {
  process.stderr.write(`Error: ${err.message ?? String(err)}\n`);
  process.exit(1);
});


Security scan verdicts — ClawScan: suspicious | static analysis: clean | VirusTotal: clean | SkillSpector: suspicious (CRITICAL)