io.github.NovadaLabs/novada-mcp

Single-call account & billing dashboard. Composes wallet balance, plan balances, capture logs, and health entitlements via the `section` param. **Best for:** "what's my account status / balance" one-shot checks. **section="summary" (default):** wallet balance + plan quotas + recent capture logs + product entitlements. **section="balance":** master wallet currency balance. **section="usage":** paginated transaction history (start_time/end_time/page/page_size). **section="plans":** per-product plan balances (residential/isp/mobile/datacenter/static/capture); filter with products[]. **section="traffic":** daily proxy traffic consumption; filter with start_time/end_time/products[]. **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY). **Aliases:** novada_wallet_balance, novada_wallet_usage_record, novada_plan_balance_all, novada_traffic_daily, novada_capture_logs, novada_account_summary, novada_health, novada_health_all all route here.

Search PUBLIC indexed pages on AI-company domains (chatgpt.com/openai.com, perplexity.ai, anthropic.com, etc.) for brand mentions and sentiment. NOT page-change monitoring (novada_monitor) and does NOT query live AI models — a brand absent from indexed pages may still be discussed live; this only reflects indexed-page coverage. **How it works:** for each selected domain group, runs a Google search scoped to that domain (e.g. site:openai.com "brandname") and analyzes snippets for sentiment, claims, and competitor co-mentions. **Best for:** checking brand presence on AI-company public docs/blogs/changelogs. **Not for:** live model answers about your brand (query the model directly), general web search (novada_search), real-time social monitoring (novada_scrape with twitter/instagram). **Output:** per-domain sentiment (positive/neutral/negative), key claims from indexed snippets, competitor mentions, mention counts, source URLs. **Domains:** chatgpt.com+openai.com, perplexity.ai, grok.com+x.com/i/grok, claude.ai+anthropic.com, gemini.google.com. Default: chatgpt, perplexity, grok.

Interact with a web page — click, fill forms, scroll, screenshot, or run JavaScript. Chain multiple actions in one call. **Best for:** login flows, paginated content, SPAs, form submission, visual verification, scraping behind interactions. **Not for:** simple page reads (novada_extract), structured data (novada_scrape), raw HTML (novada_extract format="html"). **Actions:** navigate, click, type, screenshot, snapshot, aria_snapshot, evaluate, wait, scroll, hover, press_key, select — up to 20/call. snapshot = full DOM text; aria_snapshot = smaller semantic tree (prefer it for extraction). **Sessions:** session_id reuses the same page (cookies, login) across calls — reliable only on the local/long-lived server; on hosted serverless, treat each call as one-shot. close_session releases early. **Auth:** NOVADA_API_KEY auto-provisions Browser API credentials; NOVADA_BROWSER_WS optionally overrides. **SPAs:** wait with domcontentloaded, never networkidle. `country` is accepted but not yet applied to the browser exit node — don't rely on it for geo-routing. **Constraint:** close_session/list_sessions must be the ONLY action in the call.

Simplified browser automation — 5 actions (click, scroll, wait, type, screenshot). Use only if you need this simpler interface or novada_browser is unavailable. **novada_browser is primary/more capable** — full CDP access, 12 action types + 2 session-management actions. Prefer it for new automation. **Use this when:** you need the simplified flow API or have an existing workflow built on it. **Actions:** click, scroll, wait, type, screenshot — up to 20/call. **Sessions:** session_id reuses the browser instance (cookies, login) across calls; expires after 10 min idle. **Not for:** reading one URL without interaction (novada_extract) or structured platform data (novada_scrape).

Get or reset the Capture API key (wraps POST /v1/capture/get_apikey and /v1/capture/reset_apikey). **Actions:** "get" = retrieve the current key (read-only). "reset" = regenerate it — DESTRUCTIVE, invalidates the old key, gated by a two-step approval_token. **Behavior:** call "reset" once WITHOUT `approval_token` to get a warning preview plus a fresh token (valid 10 minutes) — this does NOT call the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op. **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Use when you need content from a bounded set of pages (up to 20) and don't have the URLs yet. Crawls BFS/DFS, extracts each page inline. Use select_paths globs to target sections (e.g. "/docs/api/**"). **Wrong tool for whole-site jobs:** for >20 pages or a full docs site on disk, use `novada_site_copy` instead (up to 1000 pages, streams to disk, returns a manifest). novada_crawl hard-caps at 20 pages and returns bodies inline. **Best for:** competitive content analysis, a handful of related pages inline (returns bodies directly). **Not for:** a single page (novada_extract), URL discovery only (novada_map — much faster), a whole site to disk (novada_site_copy). **Performance:** avoid max_pages > 10 on large sites — crawl time scales ~1.4s/page (max_pages=20 ≈ 28s minimum). Use select_paths to narrow scope before raising max_pages. **Rendering:** `render` defaults to "auto" (static first, escalates to JS on detection) — not static-only.

List all available Novada tools — name, description, category, group, and status. **agent_instruction:** call this first when starting a task to find the right tool. **Returns:** a markdown table grouped by category, plus a Tool Groups reference (core/scrapers/account/meta). **Filter:** category narrows the catalog (e.g. category="Proxy"); NOVADA_GROUPS/NOVADA_TOOLS (local) or ?groups=/?tools= (hosted) narrow the actual tool set exposed on this connection. **Status:** active = available now. Output includes server_version. **ONE API KEY COVERS ALL PRODUCTS.** NOVADA_API_KEY authenticates search/extract/research/crawl/scrape/unblock/proxy auto-provisioning — no separate keys needed. NOVADA_BROWSER_WS/NOVADA_PROXY_ENDPOINT unlock extras, no extra key. On tool failure, call novada_account (section="summary") for balance/plans/entitlements.

Extract content from any URL. Auto-handles Cloudflare/DataDome/Kasada via escalation (static → JS render → Browser CDP). Batch mode: pass url as an array for up to 10 pages in parallel. **Format selection:** - `format="markdown"` (default): full-page content for reading/analysis. - `format="json"`: structured object (url, title, content, quality, links, structured_data, fields, hints, mode, fetched_at). Use with `fields=["price","title"]` to populate `fields`. Common mistake: using markdown when you need specific fields — use format="json"+fields instead. - `format="html"`: raw HTML (truncated at 100K chars by default; adjust via max_chars). - `clean=true`: strip nav/sidebar, main content only (~15K chars vs ~100K full page). **Use for:** reading pages, batch-extracting search results, structured fields (price, author, date) — works on anti-bot pages automatically. **Not for:** URL discovery (novada_map), multi-page crawl (novada_crawl), rich platform data like Amazon/LinkedIn (novada_scrape). **Key rule:** leave render="auto" (default) — 15-100x faster on static sites; only set render="render" for known JS-heavy SPAs. **Geo-routing:** `country="de"` (ISO 2-letter) routes render fetches through that country's exit IP — for localized pricing or geo-restricted content. **Auto-saved:** every extraction is written to `~/Downloads/novada-mcp/YYYY-MM-DD/` (path shown in the response). **Project grouping:** `project="my-project"` groups outputs under a subfolder.

Manage the proxy IP whitelist — add/list/delete/remark — for Residential (1), Unlimited (4), and Static ISP (5). **Actions:** "add" (WRITE, gated by approval_token), "list" (read-only), "del" (WRITE, gated by approval_token), "remark" (WRITE, gated by approval_token). **Behavior for "add"/"del"/"remark":** call once WITHOUT `approval_token` to get a preview plus a fresh token (valid 10 minutes) — this does NOT hit the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op. **Required:** action, product (1=Residential, 4=Unlimited, 5=Static ISP). **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Discover URLs on a site before deciding what to read. Tries sitemap.xml first (fast), falls back to BFS crawl. Returns URLs only — no content. Hard cap: 100 URLs. **Best for:** site structure discovery, finding the right subpage, pre-flight before novada_crawl/novada_extract. **Not for:** reading content (use novada_crawl/novada_extract) or copying a whole site to disk (novada_site_copy). **Note:** limited results on JS SPAs — flagged in the output.

Detect changes on a web page over time. Extracts content, computes a hash, and compares it with the previous check. Returns changed/unchanged plus field-level diffs. **Use for:** e-commerce price monitoring, stock tracking, content-change detection, competitive pricing alerts. **How:** the first call sets a baseline; later calls compare against it and report changes. Pass fields=["price","availability"] for field-level % diffs. **Not for:** one-time extraction (novada_extract) or a full crawl (novada_crawl). ⚠️ **Hosted endpoint (mcp.novada.com) limitation:** baselines do NOT survive between calls on hosted's serverless runtime — every call is a cold function with no prior state, so change detection always returns baseline_recorded. Use the local server (`npx novada-mcp`) or diff externally for real change detection.

Route your own HTTP requests through residential or mobile IPs — geo-targeting, IP rotation, bypassing IP-based rate limits. Returns a proxy URL, shell exports, or a curl --proxy flag. **Best for:** a specific country/city IP, sticky multi-step sessions, testing geo-restricted content. **Not for:** page extraction (novada_extract — proxy is automatic) or web search (novada_search). **Formats:** "url" (Node.js/Python), "env" (shell vars), "curl" (CLI). **Requires:** NOVADA_PROXY_ENDPOINT env var; NOVADA_PROXY_USER/PASS auto-fetch from your account via NOVADA_API_KEY if unset. **`type` guide:** - `residential` — strongest anti-bot bypass, real home ISP IPs; escalate here when blocked - `isp` — looks like a home user; best for social/ecommerce; ignores country param - `datacenter` — fastest/cheapest; non-anti-bot, high-volume targets - `mobile` — 4G/5G device IPs; mobile-targeted content and app APIs - `static` — same dedicated ISP IP every request; set session_id + country explicitly for account-management workflows — omitting either silently falls back to a SHARED "default"/"us" identity, not an error - `dedicated` — exclusive datacenter IP; set session_id explicitly for high-trust platforms — omitting it silently falls back to a SHARED "default" identity, not an error **Escalation when blocked:** datacenter → isp → residential.

⚠️ WRITE — Create a proxy sub-account. Two-step approval-token gate. **Behavior:** call once WITHOUT `approval_token` to get a `confirmation_required` JSON preview (password masked) plus a fresh `approval_token` valid for 10 minutes — this does NOT hit the API. Show the preview to the human, then re-call with the EXACT SAME parameters plus that `approval_token` after explicit approval. `confirm: true` is a deprecated no-op and does NOT substitute for the token. **Best for:** provisioning a team-member or per-project sub-account against your master plan. **Params:** product ("1"=Residential, "2"=Rotating ISP, "3"=Rotating Datacenter, "4"=Unlimited, "7"=Unblocker, "9"=Mobile), account (3-64, [a-zA-Z0-9_-]), password (8-64), status ("1" active default | "-3" disabled), remark?, limit_flow? (GB cap), approval_token. **Wire format:** multipart/form-data. **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

List proxy sub-accounts (wraps developer-api POST /v1/proxy_account/list). **Best for:** auditing sub-accounts, finding account names before rotating credentials. **Params:** product (REQUIRED — same codes as create), page, limit (max 200), status? ("1"|"-3"), account? (exact-match filter). **Wire format:** multipart/form-data. **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

One call → 3-10 parallel searches across Google/Bing/DuckDuckGo → dedup → extracts full content from top sources → returns CITED SOURCE MATERIAL (numbered passages), not a written answer. Extractive, not generative — you compose the final answer from the gathered passages. **Use for:** complex questions needing passages from ≥3 independent sources in one call — comparative analysis, market research, technical deep dives, competitive intelligence. Replaces 5-10 manual search+extract calls. **Not for:** a single fact or one URL (novada_search — faster/cheaper), a known URL (novada_extract), or a finished prose report (this returns source material, not an answer). **Depth:** "quick" (3 queries), "deep" (6), "comprehensive" (8-9), "auto" (default — quick or deep by question length, never comprehensive). **Project grouping:** `project="my-project"` groups outputs under a subfolder. **Recency:** `time_range` ("day"|"week"|"month"|"year"), `start_date`/`end_date` (ISO YYYY-MM-DD) propagate to every internal search call.

Use for structured data from a specific platform — clean tabular records, not raw HTML. Supports 16 platforms (~87 operations): Amazon, Walmart, SHEIN, Google (incl. Shopping), Bing, DuckDuckGo, Yandex, X/Twitter, TikTok, Instagram, Facebook, YouTube, LinkedIn, GitHub, ChatGPT, Perplexity. **Best for:** e-commerce product data, social posts/comments, job listings, reviews, real estate, market data. **Not for:** general web pages outside this platform list — use novada_extract instead. **Prefer the dedicated tool when one exists:** for amazon/google/bing/duckduckgo/yandex/youtube/instagram/facebook/tiktok/x/walmart/shein/linkedin/github/perplexity, call novada_scrape_<platform> instead — same engine, but its `operation` enum uses typed friendly names and is rejected client-side before any network call if wrong. Use THIS generic tool for platforms with no dedicated sibling (e.g. ChatGPT) or when resuming by task_id. **Output formats:** markdown (default table), json (records array inside a fenced "## Scrape Results" block), toon (pipe-separated, 40-65% smaller — best for large result sets), csv, excel (base64), html. **Example:** platform="amazon.com", operation="amazon_product_keywords", params={keyword:"iphone 16", num:5}. **Amazon price fields:** trust `final_price`/`price` (check `_price_source`) — `initial_price` and `buybox_prices.final_price` are often 0 by design, not a bug; `buybox_prices.unit_price` is raw per-unit data, never the listing price. **Discover platforms:** read the `novada://scraper-platforms` resource for the full operation list. **Resume:** pass `task_id` from a prior status:processing call to fetch the result without a new billable task (platform/operation still required, display-only). **Project grouping:** `project="my-project"` groups outputs under a subfolder.

Extract structured Amazon data — product details, reviews, seller info, bestseller lists, category/brand listings — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="amazon.com"). **Use when:** "get the price/rating/title for Amazon ASIN B0...", "pull the reviews for this Amazon product URL", "search Amazon for <keyword> with price and rating", "who is this Amazon seller", "what's in this Amazon Best Sellers list". **Not for:** Any other platform — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). A general Google/web search — use novada_search. Reading one arbitrary URL's raw content — use novada_extract. **Returns:** Structured product/review/seller records (title, price, rating, asin, availability, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 10 verified-working Amazon operations. 3 known backend-broken ones are excluded from this enum (rejected client-side before any backend call) — unlike novada_scrape(platform="amazon.com", ...), which still forwards them with a warning.

Extract structured Bing SERP data — organic web search, video results, news results, shopping listings — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="bing.com"). Bing is NOT a selectable engine on novada_search — this is the only intentional way to query Bing specifically. **Use when:** "get the raw Bing search results (titles, links, ranks) for <query>", "find Bing video results for <query>", "find Bing news results for <query>, sorted by date", "search Bing Shopping for <keyword>". **Not for:** A general question needing just an answer or a few good links — use novada_search — google/duckduckgo/yandex only (Bing is not selectable there); ranked, cheaper than a raw-SERP scrape. A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured SERP records per operation — organic results (title/url/snippet/rank), video results, news results (with date), shopping listings (price/rating) — in the chosen output format, same rendering as novada_scrape. **Ops:** 4 verified-working Bing operations: web search, videos, news, and shopping. Every bing.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured DuckDuckGo web search SERP data via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="duckduckgo.com"). Returns the raw organic-results SERP, with region/time/adult-content filters novada_search does not expose, not a generated answer. **Use when:** "get the raw DuckDuckGo search results (titles, links, ranks) for <query>", "search DuckDuckGo restricted to a specific region (params.kl) or time range (params.df)", "compare DuckDuckGo's ranking for <query> against another engine's raw SERP". **Not for:** A general question needing just an answer or a few good links — use novada_search with engine="duckduckgo" (ranked/reranked instead of a raw SERP dump). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured organic-result SERP records (title/url/snippet/rank) in the chosen output format, same rendering as novada_scrape. **Ops:** 1 verified-working DuckDuckGo operation (web search). The single duckduckgo.com catalog operation is currently status:"ok".

Extract structured Facebook data — public profile pages, posts, comments, and events — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="facebook.com"). **Use when:** "get this public Facebook page's profile info", "pull the comments on this Facebook post", "get details for this Facebook event", "find events matching <query> on Facebook", "list the upcoming events on this Facebook page". **Not for:** A single Facebook URL to read as plain text — use novada_extract. A general web search not scoped to Facebook — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured profile/post/comment/event records (page name, post text, comment author/text, event name/date/location, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 6 verified-working Facebook operations spanning public profile pages, posts, comments, and events (search / single event / event list). Every facebook.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured GitHub repository data — repository details by URL, or multiple repositories from a GitHub search-results URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="github.com"). **Use when:** "get repository info (stars, forks, description, language, etc.) for this GitHub repo URL", "get the repositories listed on this GitHub search-results URL". **Not for:** A single GitHub URL (repo, issue, PR, user) to read as plain text — use novada_extract. A general web/code search not scoped to GitHub, or a GitHub issue/PR/user lookup (no catalog operation exists for those) — use novada_search, or novada_extract for a known URL. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured repository records (name, description, stars, forks, language, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 3 verified-working GitHub operations: two repository-by-URL lookups (`repository_by_url` and `repository_details_by_url` map to distinct catalog scraper_ids — github_repository_repo-url and github_repository_url respectively — both taking the same `url` param; the catalog documents no behavioral difference between them) and repository listing from a GitHub search-results URL. Every github.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Google SERP data — organic web search, AI Mode answers, Maps place/review details, Shopping, Jobs, Hotels, Videos — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="google.com"). Returns raw structured SERP records, not a generated answer. **Use when:** "get the raw Google search results (titles, links, ranks) for <query>", "what's in Google's AI Mode answer for <query>", "pull Google Maps reviews or place details for this URL / place_id / CID", "search Google Shopping for <keyword>", "find Google Jobs, Hotels, or Videos results for <query>". **Not for:** A general question needing just an answer or a few good links — use novada_search (multi-engine: google/duckduckgo/yandex, ranked/reranked, cheaper than a raw-SERP scrape). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured SERP records per operation — organic results (title/url/snippet/rank), AI Mode answer content, Maps place details/reviews, Shopping listings (price/rating), Jobs/Hotels/Videos listings — in the chosen output format, same rendering as novada_scrape. **Ops:** 13 verified-working Google operations spanning web search, AI Mode, Maps (location/place_id/CID/URL lookups + reviews), Shopping, Jobs, Hotels, and Videos. Every google.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Instagram data — profiles, posts, reels, and comments — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="instagram.com"). **Use when:** "get the latest posts from this Instagram profile", "pull the comments on this Instagram post or reel", "get details for this single Instagram post or reel URL", "get Instagram profile info by URL or username", "get the reels posted by this Instagram profile". **Not for:** A single Instagram URL to read as plain text — use novada_extract. A general web search not scoped to Instagram — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured profile/post/reel/comment records (username, follower count, caption, like count, comment author/text, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 7 verified-working Instagram operations spanning profile lookup (by URL or username), posts and reels (by profile or by direct URL), and comments. `posts_by_profile` requires BOTH `profileurl` AND `resultsLimit` together. Every instagram.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured LinkedIn data — job listings (by location/filters, jobs search-results URL, or a single job posting URL) and company profile info by URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="linkedin.com"). **Use when:** "find LinkedIn job listings in <location> matching <keyword/level/remote/etc.>", "get all the job listings from this LinkedIn jobs search URL", "get details for this single LinkedIn job posting URL", "get company info for this LinkedIn company URL". **Not for:** A single LinkedIn URL to read as plain text — use novada_extract. A general web search not scoped to LinkedIn — use novada_search. A LinkedIn personal PROFILE (not a company or job) — no catalog operation exists for this today — use novada_extract on the profile URL, or novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured job-listing/company records (title, location, level, company name, follower count, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 4 verified-working LinkedIn operations spanning job search (by location, with optional keyword/level/remote/company filters), job listings from a search-results URL, a single job posting by URL, and company info by URL. `jobs_search` requires `params.location` — the catalog's actual required key for this op, despite its upstream name reading "By Keywords" (keyword itself is optional there). Every linkedin.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract the actual AI-generated answer Perplexity returns for a query — by a Perplexity query URL or a raw search term — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="perplexity.ai"). Scrapes Perplexity's own live-rendered answer page (the model's actual response text) — NOT a web search results list and NOT an indexed-page brand-mention scan. **Use when:** "what does Perplexity AI answer for <query>", "get Perplexity's generated answer for this perplexity.ai URL", "get Perplexity's answer for the search term <term>". **Not for:** A general web/multi-engine search for information (not Perplexity's own generated answer) — use novada_search. Checking whether a brand is mentioned on AI-company indexed public pages — use novada_ai_monitor — scans INDEXED PUBLIC PAGES for brand mentions across AI-company domains; does not fetch a live generated answer for an arbitrary query. A complex question needing cited, multi-source synthesis — use novada_research. Reading one already-known URL's raw page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Perplexity's rendered answer content (the text of its generated response) in the chosen output format — same rendering as novada_scrape. **Ops:** 2 verified-working Perplexity operations: answer by a perplexity.ai query URL, or answer by a raw search term. Every perplexity.ai catalog operation is currently status:"ok" — unlike its sibling chatgpt.com, whose only 2 catalog operations are BOTH backend_broken (verified 2026-07-13, "submit hangs >120s") — which is why no novada_scrape_chatgpt tool exists.

Extract structured SHEIN product data — product details by product ID or product URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="shein.com"). **Use when:** "get SHEIN product details for this product ID", "get SHEIN product details for this product URL". **Not for:** A single SHEIN URL to read as plain text — use novada_extract. A general web search not scoped to SHEIN — use novada_search. SHEIN keyword or category product-list search (no working operation exists for these today) — use novada_search, or novada_extract on a SHEIN category/search page URL — the 3 ops that would cover this are all backend_broken (60s+ submit hang) and deliberately excluded from this enum. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured product records (title, price, rating, images, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 2 verified-working SHEIN operations: product lookup by product ID or by product URL. 3 known backend_broken SHEIN operations — product-list by keyword, by category ID, and by category URL, all failing with a 60s+ submit-endpoint hang — are intentionally NOT in this enum; this tool rejects them before any backend call, unlike novada_scrape(platform="shein.com", ...), which still forwards them with a warning.

Extract structured TikTok data — profile info, post/video details, and post lists by profile, hashtag, or search URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="tiktok.com"). **Use when:** "get the latest posts from this TikTok profile", "get details for this single TikTok video URL", "pull TikTok profile info for this URL", "search TikTok profiles from this discover/search URL", "get posts from this TikTok hashtag/discover page". **Not for:** A single TikTok URL to read as plain text — use novada_extract. A general web search not scoped to TikTok — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured profile/post records (username, follower count, video description, likes, view count, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 5 verified-working TikTok operations: profile search by list URL, profile by URL, posts by list URL, posts by profile URL, and a single post by URL. Every tiktok.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Walmart data — product details by keyword search, category URL, SKU, zip-code-specific pricing, or direct product URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="walmart.com"). **Use when:** "search Walmart for <keyword> and give me prices/ratings", "get product listings from this Walmart category URL", "what's the price/availability for this Walmart SKU", "get this Walmart product's info for a specific zip code", "get product details for this Walmart product URL". **Not for:** A single Walmart URL to read as plain text — use novada_extract. A general web search not scoped to Walmart — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured product records (title, price, rating, availability, SKU, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 5 verified-working Walmart operations spanning keyword search, category-URL listings, SKU lookup, zip-code-specific pricing, and direct product URL. `product_by_keyword` requires BOTH `domain` AND `keyword` together; `product_by_category_url` requires ALL THREE of `category_url`, `all`, AND `page_limit` together; `product_by_url_and_zipcode` requires BOTH `url` AND `zipcode` together. Every walmart.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured X (Twitter) data — a single post and profile lookups by username or URL — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="x.com"). **Use when:** "get the text/engagement stats for this X post URL", "get this X profile's info by username", "get this X profile's info by profile URL". **Not for:** A single X/Twitter URL to read as plain text — use novada_extract. A general web search not scoped to X — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured post/profile records (post text, like/reply/repost counts, profile bio, follower count, etc.) in the chosen output format — same rendering as novada_scrape. **Ops:** 3 verified-working X (Twitter) operations: a single post by URL, and profile lookup by username or by profile URL. Every x.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Extract structured Yandex web search SERP data via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="yandex.com"). Returns the raw organic-results SERP, with TLD/language/time-range controls novada_search does not expose, not a generated answer. **Use when:** "get the raw Yandex search results (titles, links, ranks) for <query>", "search a specific Yandex TLD (params.yandex_domain, e.g. "yandex.ru") for Russian/Eastern European content", "search Yandex restricted to a time range (params.within)". **Not for:** A general question needing just an answer or a few good links — use novada_search with engine="yandex" (ranked/reranked instead of a raw SERP dump). A complex question needing cited multi-source synthesis — use novada_research. Reading one already-known URL's page content — use novada_extract. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured organic-result SERP records (title/url/snippet/rank) in the chosen output format, same rendering as novada_scrape. **Ops:** 1 verified-working Yandex operation (web search, requires params.yandex_domain TLD selector). The single yandex.com catalog operation is currently status:"ok".

Extract structured YouTube data — video/channel metadata, transcripts, comments, downloadable video/audio files — via a closed, typed `operation` enum (same engine as novada_scrape, pinned to platform="youtube.com"). **Use when:** "get the transcript/subtitles for this YouTube video", "pull the comments on this YouTube video", "get channel info for this YouTube channel URL", "search YouTube channels for <keyword>", "find YouTube videos matching <keyword>, filtered by duration/upload date/attributes". **Not for:** A single YouTube URL to read as plain text — use novada_extract. A general web/video search not scoped to YouTube — use novada_search. A different platform's data — use its own novada_scrape_<platform> tool, or novada_scrape(platform="<domain>"). **Returns:** Structured video/channel/comment records (title, views, transcript text, comment author/text, channel subscriber count, etc.) plus downloadable video/audio file links, in the chosen output format — same rendering as novada_scrape. **Ops:** 13 verified-working YouTube operations spanning transcripts, video/audio downloads, channel lookup + search, comments, and video search by keyword/label/filters/playlist/channel. Every youtube.com catalog operation is currently status:"ok" — none are excluded for being backend_broken.

Search the web for clean, ready-to-use content — titles, URLs, snippets, reranked by relevance. For multi-source questions, use novada_research instead (faster, more thorough). **Use for:** current events, URL lookup, fact-checking, competitive research. enrich_top=true auto-extracts the #1 result. **Not for:** a known URL (novada_extract) or a multi-source report (novada_research). **Tip:** engine='google' (default) is fastest/most reliable; duckduckgo/yandex are slower fallbacks. **Domain filtering:** includeDomains/excludeDomains inject `site:domain` into the query (not API-side). **Project grouping:** `project="my-project"` groups outputs under a subfolder (~/Downloads/novada-mcp/<date>/<project>/).

Record search-result quality so future ranking can learn from it. Returns a thank-you/echo confirmation with an agent_instruction. **Best for:** after a novada_search call, report which result URLs were useful and rate the set (good/ok/bad) — biases future ranking. **Params:** search_id (prior search's id), query, rating ('good'|'ok'|'bad'), useful_urls? (max 50), note? (what was missing). **Scope:** in-memory, per-process — resets on restart. Nothing persists. Auth-free.

Per-process / per-session usage telemetry: tool-call counts, the last-N calls, and process uptime. **Best for:** "what have I called this session?" / debugging an agent loop / seeing which tools dominate usage. **Returns:** session_started, uptime, total_calls, per-tool counts (high→low), most-recent calls (newest first, capped by recent_limit). **Scope:** in-memory, per-process — resets on restart. Nothing persists or leaves the process. Auth-free.

The onboarding concierge and first-run front door. Call this FIRST when starting out, or whenever a tool reports a missing/invalid key. **What it does:** 1. **Validates your key** — one cheap account read (wallet balance) confirms it works and shows your balance. No per-product probes, no credit cost. 2. **Guides you if keyless** — register at the Novada dashboard (free credits included), copy your API key, get exact config snippets for Claude Code/Desktop/Cursor/VS Code/Windsurf. 3. **Orients you** — a plain-language list of core capabilities (search, extract, scrape, browser, account) plus add-ons. **Reports one of 3 states:** valid key (ready) · invalid key (fix it) · no key (register). Output includes server_version. **Auth-free by design:** a missing key never errors here — it guides, with a machine-usable agent_instruction for what to tell the user next. **Unified key:** NOVADA_API_KEY covers search/extract/unblock/scraper/research/crawl/map/browser/proxy auto-provisioning. NOVADA_BROWSER_WS/NOVADA_PROXY_ENDPOINT are optional add-ons needing no separate key.

Copy an entire docs site/section to disk as clean markdown — one .md file per page — returning a COMPACT manifest, not page bodies. Use for a whole knowledge base on disk (offline docs ingest, RAG corpus, full-site mirror). **Discovery order:** (1) llms.txt/llms-full.txt if present, (2) sitemap.xml, (3) scoped same-host BFS to completion. select_paths/exclude_paths and same-host are always enforced. **Best for:** "copy all of docs.x.com", a local docs corpus, ingesting an llms.txt index. **Not for:** a single page (novada_extract), a few pages inline (novada_crawl), URL discovery only (novada_map). **Output:** each page streams to `~/Downloads/novada-mcp/<date>/<project|domain>/site-copy/<slug>.md`; `manifest.json` records {url,file,title,word_count,depth,bytes,status} per page. The tool returns a compact summary + manifest path, not inline content — read the .md files or manifest.json after it completes. **Scale:** max_pages default 200, hard max 1000, drained until the queue is empty or the ceiling is hit.

Manage static ISP IPs (wraps /v1/static_house/* developer-api endpoints). **Actions:** "open" = purchase new IPs (WRITE, gated by approval_token). "renew" = renew existing IPs (WRITE, gated by approval_token). "export"/"list" = read-only. **Behavior:** call "open"/"renew" once WITHOUT `approval_token` to get a preview plus a fresh token (valid 10 minutes) — this does NOT hit the API. Re-call with the EXACT SAME parameters plus that token to execute. `confirm: true` is a deprecated no-op. **Auth:** NOVADA_DEVELOPER_API_KEY (falls back to NOVADA_API_KEY).

Check whether a factual claim is supported by web sources. Runs 3 parallel searches (supporting, skeptical, fact-check angles) and returns a verdict: supported / unsupported / contested / insufficient_data. **Best for:** checking claims before citing them, cross-validating findings, detecting misinformation. **Not for:** open-ended questions (novada_research) or reading a specific URL (novada_extract). **Note:** signal-based (search balance), not definitive. Confidence 0–100 indicates certainty.