gen_analyze

io.github.poweredbyGEN/gen-mcp-server · Verify this server

Analyze real social data and research the web: collect is the typed collection seam — one synchronous DW /collect call per request, answered as model-visible evidence + a per-target coverage summary + result cards (never a job id, never PENDING). With enrich:"full" collect waits on the DW's full-enrichment job (transcript, hooks, visual analysis on every row) and answers GEN's written analysis plus one display card per row (thumbnail, @handle, view/like/comment counts, post date, post URL); the enriched per-video fields stay server-side unless include names them (transcript|hooks|visual_description|description|stats), and a job still running when the budget expires answers a PENDING receipt whose collect_enrichment_status action ({job_id}) polls the completed rows in the same shape. It takes targets [{platform, scope, target}] over scope user|hashtag|keyword|search|url|id|asset|account|creators|comments|sounds|ads and platform tiktok|instagram|youtube|pinterest|twitter|kick|twitch|meta_ads|tiktok_ads and freshness live (the default) or cache_then_live_deficit (cache_then_live_deficit serves stored rows free and fetches only the missing count live; cache_only is refused; every account target is paired in the same call with the same handle's user scope for that account's latest posts unless options.profile_only=true, and a comments action scoped only by video_ids is served live by collect's comments scope), and it replaces the older social-data branches named below. discover trends (trends) across TikTok, Instagram, YouTube, and Kick; search comments server-side with sentiment (comments); synthesize scoped TikTok, Instagram, or YouTube comment themes and prose as a normalized table card (comment_mining: target is an @creator, a #hashtag — a bare word is read as a hashtag — or a video URL; platform optional, default TikTok), or analyze one social video (video_analysis: deep analysis defaults off and requires include_video_analysis=true). Both synthesis actions submit one owner-scoped job with an idempotency key and GET-only polling, not inline legacy cards. Read the DW aggregate trend report (report); and run bounded web research findings (research_web; save:true keeps the run as a Research Warehouse brief, save:false/omitted is one-shot). Analyze source videos for viral clip moments with clip_moments (1–10 sources, optional clip count, duration bounds, mode, presentation, aspect ratio, reframe, speed and enrich; one paid request returns per-source clips and failures). The DW social warehouse is served directly too: search_posts (DEPRECATED — superseded by collect; still served; the GEN-3096 keyword search — the TikTok cached keyword path by default and the cross-platform search when platforms name more than tiktok, with the Common filter set on the entry), analyze_account (DEPRECATED — superseded by collect; still served: one account's profile + followers), transcribe and transcribe_status (DEPRECATED — superseded by collect url/id; still served: social video transcription by platform and its status), upload_by_ids (upload the stored media), comments_online (DEPRECATED — superseded by collect comments; still served: the live comment fetch beside the cached comments read), monitor_status (the DW monitoring read) and aura_user_stats (AURA stats by emails). hooks returns hook_text/pattern rows plus hook_clusters (pattern clusters) and a truthfulness block (returned, thin_result, note), and needs a scoped target: an @handle, #hashtag or keyword (HOOKS_TARGET_REQUIRED otherwise; HOOKS_UNAVAILABLE when the analyst is off). creators runs the same analyze job door and is served here. One call carries one or more typed actions. trends/hooks take query/mode/target/platform plus the reused CommonFilters bundle (no new dialect), an optional relevance_query, and a raw flag — results are analyzed by default and raw=True opts out to unanalyzed rows. comments takes a scope (query | video_ids | creator | hashtag) plus optional sentiment, days and limit; report takes window (1 | 7 | 30) and limit; research_web takes query plus optional mode (news|social|web|all), research-source platforms (x|news|web|reddit), days, limit, reddit_subreddits and save. mode social is the community sources, X and Reddit. Research tie-break: 'Research X' the user wants kept or followed up is gen_analyze research_web with save:true (kept as a Research Warehouse brief); research_web is one-shot by default and never persists without save:true. research_scrape scrapes any source on the first call with bounded caps: source is a platform (tiktok, instagram, youtube, x/twitter, pinterest, kick, web) or any public URL, and input names the scrape target (keyword | hashtag | username | user URL; x serves user targets only, pinterest user walks take cursor, and a page source takes url/asset_types/limit/query); success returns the scraped rows and billing. apify_scrape runs one caller-named approved provider actor on the first call and bills: actor_id names the actor and input is its own run input, capped by max_items; success returns the dataset rows and billing. web_asset_scrape discovers public-page media candidates and optionally imports each through gen_asset_action behind a single-use confirm_token; success returns candidates, imported_count, imported_assets, import_errors, proxy_used and fetcher.analyze_socials (DEPRECATED — superseded by collect; still served; its hidden legacy names social_posts_scrape and general_scrape are deprecated with it) is the one social-scrape write: a social target (platform + mode + target, with optional cursor/from_db/limit/period/sort_by/min_count) is a live social.posts scrape, and a wide scope (platform + one of keyword/hashtag/userPageURL/video_url, with optional days/last_num_videos/scrape_type/from_db/videoMonitoring) is the DW general scrape. analyze_socials serves Twitch and Kick channel/VOD URLs, resolves a Kick or Twitch mode + target to the wide scope it names, and forwards Kick/Twitch keyword and hashtag scopes to the DW general scrape; the DW's own provider path answers the scopes it does not serve. videoMonitoring forwards unchanged. The paid DW writes the read-only discover lane no longer serves live here: import_urls (paid first-call URL-to-S3 import: platform + public videos_urls, capped at 50 URLs per call, writes S3 and bills on the first call; from_db=true and from_db_only=true are refused as stored-only-unavailable before any request) and analyze_socials (subject to provider support); the DW result preserves returned S3 asset paths. sounds (DEPRECATED — superseded by collect sounds; still served) answers the DW sound endpoints by view (sounds_by_niche | sounds_by_creator | rising_sounds | sound_performance | sound_arbitrage | music | trending_sounds | sound_info) and analytics the DW aggregate endpoints (aggregate | sleepers | posting_times; by_demographics is owner-removed); each view takes its own endpoint fields plus the common GEN-3096 filters object. Paid DW writes and research_scrape execute on the first call — confirmation happens in the FE and a stray confirmed/confirm_token argument is accepted and ignored; web_asset_scrape runs only behind its returned single-use confirm_token. Each result carries a truthfulness block as fields (requested echo, backend run identity and status, billing subject). Spending analysis and research: the run is billed to the envelope agent_id, which is required (no anonymous path). Demographic filters are owner-removed and rejected. Transcribing an audio or video URL into text is gen_generate (transcribe); the transcribe branch here is the DW transcription of stored social video ids into warehouse transcripts. Free-form questions with attachments belong to gen_ask (ask). Reddit is a research source served by the shared research branch, never a DW video collection: 'reddit' is a research platform, a subreddit scope is reddit_subreddits, a one-shot request carries that scope through the same analysis job as X, news and web, and a reddit.com URL carried by collect or research_web is answered as research, not refused. meta_ads and tiktok_ads are paid advertising platforms served by the DW's one ads lane over scope ads|keyword|user|id (scope ads takes a target object with exactly one of query/advertiser_id/ad_id plus optional country and status, and is forwarded verbatim; the alias scopes take a plain string: keyword->query, user->advertiser page id, id->ad id). That lane is what keeps an ad id from ever dispatching organic TikTok/Instagram retrieval. meta_ads serves live and cached ads; tiktok_ads is cache-only, so a live freshness reaches an unsupported coverage entry and never falls back to Meta or organic retrieval. enrich "full" is refused for every ads target: DW full enrichment selects video entities only and can never enrich an ad, so opt in to one creative's analysis with gen_asset_action analyze instead. Ideas, scripts, trends and stats come only from GEN calls: never invent them, call GEN.