@scavio/mcp-server 0.11.0 → 0.13.0

package/README.md

@@ -3,7 +3,9 @@
 ![GitHub Repo stars](https://img.shields.io/github/stars/scavio-ai/scavio-mcp?style=social)
 ![License](https://img.shields.io/github/license/scavio-ai/scavio-mcp)
 
-[Scavio](https://scavio.dev) is a unified [Web Search API](https://scavio.dev/docs/search-api) and MCP server that connects AI agents to Google, YouTube, Amazon, Walmart, TikTok, Instagram, Reddit, X, LinkedIn, and TikTok Shop. 99 tools for web search, product lookup, video discovery, and social media data through a single [Search API](https://scavio.dev/docs/search-api) endpoint.
+[Scavio](https://scavio.dev) is a unified [Web Search API](https://scavio.dev/docs/search-api) and MCP server that gives AI agents web search, page extraction, and structured data from e-commerce, social, travel, jobs, real-estate, app-store, ad-library and company-filing sources. 191 tools across 32 platforms, one API key.
+
+**The 22 platforms added in 0.13.0 are opt-in.** Registering all 191 tools puts 262KB of tool definitions — roughly 70k tokens — into every session before you type anything. So the default is the surface 0.12.x already had, plus Extract: 106 tools, 102KB. Upgrading never removes a tool you were using. Everything else is one env var away: see [Choosing which tools load](#choosing-which-tools-load).
 
 ## Remote MCP Server
 
@@ -190,8 +192,114 @@ Add to settings (`Cmd+,`):
 
 ---
 
+## Choosing which tools load
+
+Scavio exposes 191 tools. Loading all of them costs 262KB of `tools/list` —
+roughly 70k tokens of context in every session before the user has said anything,
+and more tools than some clients will accept at all. So the server registers a
+curated subset by default and lets you pick the rest. The sizes below are
+measured, not estimated: `npm run toolslist` reproduces them.
+
+`SCAVIO_PLATFORMS` is a comma-separated allowlist of platform keys:
+
+| Value | Registers |
+|-------|-----------|
+| *(unset)* | Everything 0.12.x had, plus `extract` — **106 tools, 102KB** |
+| `all` | every platform — **191 tools, 262KB** |
+| `extract,sec,g2` | just those platforms — 11 tools, 20KB |
+| `default,walmart,metaads` | the default set plus two more — 58 tools |
+| `none` | no platform tools, only `get_usage` |
+
+Keys are matched case- and punctuation-insensitively, so `meta-ads`, `metaads`
+and `META_ADS` are the same thing, and `twitter` resolves to `x`. An unknown key
+is logged to stderr and skipped rather than failing the server.
+
+`get_usage` always registers — it is free, and it is what every install guide
+tells you to call to check the server works.
+
+**Platform keys:** `extract`, `google`, `youtube`, `tiktok`, `instagram`,
+`reddit`, `x`, `linkedin`, `threads`, `kuaishou`, `amazon`, `walmart`, `ebay`,
+`target`, `homedepot`, `tiktok-shop`, `booking`, `airbnb`, `tripadvisor`,
+`yelp`, `zillow`, `redfin`, `indeed`, `glassdoor`, `appstore`, `googleplay`,
+`g2`, `capterra`, `googleads`, `metaads`, `sec`, `companieshouse`
+
+### Local (stdio)
+
+```json
+{
+  "mcpServers": {
+    "scavio": {
+      "command": "npx",
+      "args": ["-y", "@scavio/mcp-server"],
+      "env": {
+        "SCAVIO_API_KEY": "YOUR_SCAVIO_API_KEY",
+        "SCAVIO_PLATFORMS": "extract,google,zillow,redfin"
+      }
+    }
+  }
+}
+```
+
+### Remote (HTTP)
+
+The hosted server has no env var to read, so pass the allowlist per connection —
+either as a header or as a query parameter:
+
+```json
+{
+  "scavio": {
+    "type": "http",
+    "url": "https://mcp.scavio.dev/mcp",
+    "headers": {
+      "x-api-key": "YOUR_SCAVIO_API_KEY",
+      "x-scavio-platforms": "extract,google,sec,companieshouse"
+    }
+  }
+}
+```
+
+```
+https://mcp.scavio.dev/mcp?platforms=all
+```
+
+### Upgrading from 0.12.x
+
+Nothing to do. The default set is exactly the 10 platforms 0.12.x registered,
+plus Extract — every tool you were using still loads, and the context cost is
+unchanged. Walmart grew from 2 tools to 7, so the count moves 100 → 106.
+
+The 22 platforms added in 0.13.0 are opt-in. Add them additively:
+
+```
+SCAVIO_PLATFORMS=default,zillow,redfin,sec
+```
+
+One breaking fix worth knowing: `search_walmart` previously sent
+`fulfillment_speed: "anytime"` on every call, which the API rejects. The
+parameter is now `today` or `tomorrow` with no default.
+
+---
+
 ## Available Tools
 
+Every tool costs 1 credit per call unless its section says otherwise. Several
+platforms price per endpoint (YouTube, Instagram, LinkedIn, Kuaishou) or per
+request body (Extract, Threads, Walmart); `get_amazon_options` and `get_usage`
+are free.
+
+### [Extract](https://scavio.dev/docs/extract)
+
+| Tool | Description |
+|------|-------------|
+| `extract_url` | Read any web page and return it as clean Markdown, plain text, or raw HTML |
+
+Extract is tier-priced by the `mode` parameter, not flat: `normal` (plain fetch)
+and `advanced` (full JavaScript rendering) cost 1 credit, `ultra` (residential
+proxy, for hard bot walls) costs 2. Start at `normal` and escalate only when the
+content comes back empty or blocked. You are billed only on a successful
+extraction — a dead link, a bot wall or a timeout costs nothing. There is no
+pagination: the whole page comes back in one call.
+
 ### [Google Search API](https://scavio.dev/docs/search-api)
 
 | Tool | Description |
@@ -232,6 +340,11 @@ Add to settings (`Cmd+,`):
 | `resolve_youtube_channel` | Resolve a handle or URL to a channel ID |
 | `get_youtube_streams` | Get direct media stream URLs for a video |
 
+Credit cost varies: `get_youtube_transcript` costs 8, `get_youtube_streams` 3,
+`search_youtube` and `search_youtube_shorts` 2, and every other YouTube tool 1.
+`get_youtube_related` accepts a cursor but never returns one, so treat it as a
+single page.
+
 ### [Amazon Product API](https://scavio.dev/docs/amazon-api)
 
 | Tool | Description |
@@ -239,6 +352,7 @@ Add to settings (`Cmd+,`):
 | `search_amazon` | Search product listings across 22 marketplaces (no sort option) |
 | `get_amazon_product` | Get full product details by ASIN |
 | `get_amazon_offers` | List every seller offering an ASIN, with buy-box winner |
+| `get_amazon_options` | List the supported marketplaces and their country codes (free) |
 
 ### [Walmart API](https://scavio.dev/docs/walmart-api)
 
@@ -246,6 +360,25 @@ Add to settings (`Cmd+,`):
 |------|-------------|
 | `search_walmart` | Search product listings with price and delivery filters |
 | `get_walmart_product` | Get full product details by product ID |
+| `get_walmart_reviews` | Customer reviews with ratings, text, author, date and the rating breakdown |
+| `get_walmart_category` | Products within a category, same product shape as search |
+| `get_walmart_offers` | The buy-box offer for a product: price, seller, condition, buy-box flag |
+| `get_walmart_seller` | Marketplace seller storefront: name, rating, Pro Seller badge, business details |
+| `get_walmart_seller_products` | A seller's catalogue; `total_count` is the real size |
+
+Walmart is priced by the `domain` parameter, not at a flat rate: `com` (US,
+default) and `ca` cost 1 credit, `com.mx` costs 2. Only `search_walmart` and
+`get_walmart_category` accept `domain`, so only those two can cost 2 — the other
+five are always 1. The id-keyed tools are US-only, because walmart.ca product
+pages cannot be fetched.
+
+Two shapes to plan for. `get_walmart_offers` returns the buy-box winner only —
+Walmart server-renders just that one offer, so expect a single row even when
+`total_offer_count` is higher. And `get_walmart_seller_products` is capped at
+roughly the first 40 items with no page or cursor parameter; read `total_count`
+to know you are looking at a slice. Both seller tools need the NUMERIC
+`seller_catalog_id` from a product, search or offers response — the GUID-form
+`seller_id` in those same responses 404s.
 
 ### [TikTok API](https://scavio.dev/docs/tiktok-api)
 
@@ -280,12 +413,17 @@ Add to settings (`Cmd+,`):
 | `get_instagram_user_followers` | Get a user's follower list |
 | `get_instagram_user_followings` | Get a user's following list |
 
+Instagram is priced per endpoint, not at a flat rate: `get_instagram_user_posts`
+costs 2, `get_instagram_post` and `get_instagram_comment_replies` cost 8, and the
+other nine tools cost 10. The 10-credit endpoints hedge two upstream providers and
+bill both legs, which is what the price reflects.
+
 ### [Reddit API](https://scavio.dev/docs/reddit-api)
 
 | Tool | Description |
 |------|-------------|
-| `search_reddit` | Search Reddit posts by query with sort and pagination |
-| `get_reddit_post` | Get a full post with threaded comments by URL |
+| `search_reddit` | Search Reddit posts by query, relevance order, cursor pagination |
+| `get_reddit_post` | Get a single post by URL or id (no comments; see below) |
 | `get_reddit_search_suggestions` | Get search autocomplete suggestions |
 | `get_reddit_post_comments` | Get a post's top-level comments with pagination |
 | `get_reddit_comment_replies` | Get replies to a specific comment |
@@ -297,6 +435,12 @@ Add to settings (`Cmd+,`):
 | `get_reddit_popular` | Get the site-wide popular feed |
 | `get_reddit_trending` | Get current trending search queries |
 
+Every Reddit tool costs 1 credit. Two things to know: `search_reddit` takes a query
+and a cursor only - there is no sort or post-type filter, results come back in
+relevance order - and `get_reddit_post` returns a flat post object with no comments,
+so call `get_reddit_post_comments` with the post id for those. Reddit is the slowest
+platform here, typically 5-15 seconds per call.
+
 ### [X API](https://scavio.dev/docs/x-search)
 
 | Tool | Description |
@@ -313,6 +457,10 @@ Add to settings (`Cmd+,`):
 | `get_x_user_followings` | List accounts a user follows |
 | `get_x_trending` | Get trending topics for a country |
 
+`get_x_user_tweets`, `get_x_user_replies` and `get_x_user_media` return a
+`next_cursor` but no `has_more`, so page until the cursor is absent or the timeline
+comes back empty.
+
 ### [LinkedIn API](https://scavio.dev/docs/linkedin-person)
 
 | Tool | Description |
@@ -363,6 +511,238 @@ looping. For an id that will not resolve, `get_tiktok_shop_product_reviews` is o
 across 8 measured ids that failed on detail, 8 of 8 returned HTTP 200 on reviews and 7 of 8 returned
 at least one review.
 
+### [Threads](https://scavio.dev/docs/threads-profile)
+
+| Tool | Description |
+|------|-------------|
+| `get_threads_profile` | Profile details for a Threads user, by `user_id` or `username` |
+| `get_threads_user_posts` | A user's Threads posts, cursor-paginated |
+| `get_threads_user_replies` | A user's replies, cursor-paginated |
+| `get_threads_post` | A single post by id or threads.net URL |
+| `get_threads_post_comments` | Replies to a post, cursor-paginated |
+| `search_threads_users` | Profiles matching a name or handle - the only search Threads exposes |
+
+Threads is priced by how you address a user, not per endpoint: 2 credits when you pass `user_id`, 4 credits when you pass `username`. Only `get_threads_profile`, `get_threads_user_posts` and `get_threads_user_replies` accept a username; the other three are always 2. Prefer `user_id` - a handle buys a second upstream lookup.
+
+### [Kuaishou (China)](https://scavio.dev/docs/kuaishou-profile)
+
+| Tool | Description |
+|------|-------------|
+| `get_kuaishou_profile` | Profile details for a Kuaishou user (10 credits) |
+| `get_kuaishou_user_posts` | A user's top posts, cursor-paginated |
+| `get_kuaishou_user_live` | A user's current live-stream status |
+| `resolve_kuaishou_user` | Turn a Kuaishou share link into a user id |
+| `get_kuaishou_video` | A single video by photo id or URL (2 credits) |
+| `get_kuaishou_video_comments` | Comments on a video, cursor-paginated |
+| `get_kuaishou_comment_replies` | Replies under a root comment |
+| `get_kuaishou_videos_batch` | Up to 20 videos in one call (40 credits) |
+| `search_kuaishou` | Mixed-result search across Kuaishou (10 credits) |
+| `search_kuaishou_videos` | Video search results (10 credits) |
+| `search_kuaishou_users` | User search results (10 credits) |
+| `search_kuaishou_live` | Live-stream search results (10 credits) |
+| `get_kuaishou_tag_feed` | Posts under a hashtag, cursor-paginated |
+| `get_kuaishou_trending` | Hot, live, shopping, brand and music leaderboards |
+
+Kuaishou is priced per endpoint, not at a flat rate: `get_kuaishou_profile` and all four search tools cost 10, `get_kuaishou_video` 2, `get_kuaishou_videos_batch` 40, and every other tool 1.
+
+### [eBay](https://scavio.dev/docs/ebay-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_ebay` | Search live or SOLD listings: price, condition, bids, shipping, seller feedback |
+| `get_ebay_product` | One listing in full: price, condition, images, item specifics, shipping, returns, auction state |
+| `get_ebay_seller` | Seller profile card: store name, feedback score, items sold, followers, location |
+
+1 credit per call. `get_ebay_seller` is a profile card and cannot enumerate a catalogue - list a seller's inventory with `search_ebay` and `seller` set and no keyword. `sold: true` searches completed listings that actually sold; on that view eBay publishes no headline count, so `total_results` is null. `per_page` accepts only 60, 120 or 240.
+
+### [Target](https://scavio.dev/docs/target-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_target_products` | Search Target.com: prices, ratings, badges and promotions |
+| `get_target_category` | Products in a category, same shape as search plus the breadcrumb |
+| `get_target_product` | Product details by TCIN: price, images, specifications, variants, fulfillment |
+| `get_target_reviews` | Reviews with the rating breakdown, per-attribute averages and guest photos |
+
+1 credit per call. `get_target_product` and `get_target_reviews` are single-shot; search and category page with `page` + `count`.
+
+### [Home Depot](https://scavio.dev/docs/home-depot-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_home_depot` | Search Home Depot: price, brand and model, ratings, per-store pickup/delivery |
+| `get_home_depot_product` | Full item detail: pricing, media, spec table, dimensions, documents, return policy |
+| `get_home_depot_reviews` | Full review bodies, rating distribution, per-attribute ratings, seller responses |
+
+2 credits per call. Search page size is fixed at 12 and cannot be changed. Reviews return 30 per page; `total_pages` is the last page that exists and asking past it is a 404.
+
+### [Booking.com](https://scavio.dev/docs/booking-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_booking` | Properties for a destination and stay: live nightly price, review score, room type |
+| `get_booking_hotel` | One property in full: rooms and rate plans, facilities, house rules, policies, images |
+| `get_booking_reviews` | Guest reviews with the score breakdown by category and Booking's own summary |
+
+1 credit per call. Search returns 25 properties per page; `get_booking_hotel` and `get_booking_reviews` are single-shot.
+
+### [Airbnb](https://scavio.dev/docs/airbnb-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_airbnb` | Stays with stay-total and per-night price, the full discount ledger, rating, coordinates |
+| `get_airbnb_listing` | One listing in full: description, capacity, grouped amenities, host, house rules, rating breakdown |
+| `get_airbnb_reviews` | Review bodies with per-review rating, date and reviewer profile |
+
+1 credit per call. `search_airbnb` takes `page` XOR `cursor` - sending both is rejected, and `cursor` wins. 18 listings per page. `get_airbnb_reviews` pages with `limit` + `offset`.
+
+### [Tripadvisor](https://scavio.dev/docs/tripadvisor-locations)
+
+| Tool | Description |
+|------|-------------|
+| `resolve_tripadvisor_location` | START HERE - resolve a place or business name to the `geo_id` / `location_id` pair |
+| `search_tripadvisor` | Restaurants, hotels or attractions in a geo, TripAdvisor-ranked |
+| `get_tripadvisor_location` | One location in full: rating histogram, sub-ratings, city ranking, amenities, first review page |
+| `get_tripadvisor_reviews` | A page of reviews: rating, trip date and type, reviewer profile, management response |
+
+2 credits per call. Start with `resolve_tripadvisor_location` for the `geo_id` / `location_id` pair everything else needs. Search returns 30 per page and a page past the last is a 404, not an empty result. Reviews return 15 per page for restaurants and 10 for hotels and attractions, so `category` must match the location's own type on any page past the first.
+
+### [Yelp](https://scavio.dev/docs/yelp-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_yelp` | Businesses in Yelp's ranked order: rating, review count, price band, categories, hours |
+| `get_yelp_business` | One business in full: per-star histogram, contact, hours, amenities, health inspections, Q&A |
+| `get_yelp_reviews` | A page of reviews: rating, full text, author profile, photos, owner response |
+
+2 credits per call. Yelp fixes the page size at 10. `get_yelp_business` already includes the first page of reviews at no extra cost. A review page past the last is a 404, not an empty result.
+
+### [Zillow](https://scavio.dev/docs/zillow-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_zillow` | Listings in a region: price, beds, baths, living area, Zestimate, coordinates, days on market |
+| `get_zillow_property` | Full listing: price and price history, Zestimate, tax history, RESO facts, schools, photos |
+| `get_zillow_agent_reviews` | A Zillow AGENT's profile and reviews, specialties, licenses, service areas, sales counts |
+
+1 credit per call. Only `search_zillow` paginates. `get_zillow_agent_reviews` is an AGENT profile, not a property.
+
+### [Redfin](https://scavio.dev/docs/redfin-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_redfin` | Listings: price, price per sqft, beds, baths, living area, lot size, year built, photos |
+| `get_redfin_property` | Full listing: Redfin Estimate, MLS fact sheet, price and tax history, schools, climate risk, comps |
+| `get_redfin_market` | Market stats for a region: median list and sale price, sale-to-list ratio, days on market, compete score |
+
+1 credit per call. `search_redfin` pages with `page` + `limit`, up to 350 listings per page; the other two are single-shot.
+
+### [Indeed](https://scavio.dev/docs/indeed-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_indeed_jobs` | Job postings: title, employer, rating, location, salary range, job type, apply route |
+| `get_indeed_job` | One posting in full: description text and HTML, structured salary, benefits, original ATS link |
+| `get_indeed_company` | Employer profile: industry, HQ, size, revenue, CEO approval, per-category ratings, open roles |
+| `get_indeed_company_reviews` | Employee reviews with per-category ratings, pros/cons, reviewer job title and location |
+
+2 credits per call. Job search returns 10 postings per page, company reviews 20 per page. `get_indeed_job` and `get_indeed_company` are single-shot.
+
+### [Glassdoor](https://scavio.dev/docs/glassdoor-companies)
+
+| Tool | Description |
+|------|-------------|
+| `resolve_glassdoor_company` | START HERE - resolve a company name to the `employer_id` the other tools need |
+| `get_glassdoor_company` | Employer profile: ratings, star distribution, CEO approval, size and revenue bands, awards |
+| `get_glassdoor_reviews` | Up to three full reviews with per-axis scores and employer response, plus complete rating statistics |
+| `get_glassdoor_salaries` | Salaries by job title: base-pay and total-pay percentiles P10-P90, sample counts, pay period |
+
+1 credit per call. Start with `resolve_glassdoor_company` for the `employer_id`. Only `get_glassdoor_salaries` paginates (10 job titles per page; `page_count` is how many exist). `get_glassdoor_reviews` returns up to three full reviews plus complete rating statistics - it is not a paginated review feed.
+
+### [Apple App Store](https://scavio.dev/docs/app-store-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_app_store` | Up to 200 fully-shaped apps - doubles as a bulk metadata fetch and a publisher lookup |
+| `get_app_store_app` | Full listing: developer identity, price, all-time and current-version ratings, release notes, screenshots |
+| `get_app_store_reviews` | A page of reviews: star rating, title, full text, author, and the app version reviewed |
+
+1 credit per call. Reviews page 1-10 at 50 per page and stop hard at page 10: 500 reviews per storefront is Apple's anonymous ceiling, and you reach further by asking a different `country`. Search and app detail do not paginate.
+
+### [Google Play](https://scavio.dev/docs/google-play-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_google_play` | Ranked apps: package name, developer, rating, install count, price and IAP range, screenshots |
+| `get_google_play_app` | Full store listing: the real install count, star histogram, IAPs, permissions, Data safety table |
+| `get_google_play_reviews` | A page of reviews: star score, full text, thumbs-up count, developer reply, app version |
+
+2 credits per call - a separate namespace from `google` and not on the Google-exempt price. Reviews are cursor-paginated, and the cursor is opaque, single-use and encodes the sort as well as the position, so send it back with the same `sort` it came from. A cursor past the last review is a 404. Search and app detail do not paginate.
+
+### [G2 Software Reviews](https://scavio.dev/docs/g2-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_g2_software` | Search B2B software: star rating, review count, vendor, categories; each row carries `product_id` |
+| `get_g2_product` | Full profile: per-star histogram, pricing editions, feature groups, integrations, alternatives, AI pros/cons |
+| `get_g2_reviews` | A page of reviews: rating, likes/dislikes, problems solved, reviewer firmographics, validated flags |
+
+5 credits per call - the most expensive platform on Scavio. `search_g2_software` pages with `page` + `limit` (capped at 100 on our side); `get_g2_reviews` is fixed at 10 per page and paginates well past the 10 pages G2's own widget links to. `get_g2_product` is single-shot.
+
+### [Capterra Software Reviews](https://scavio.dev/docs/capterra-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_capterra_software` | Search B2B software: 20 ranked products with rating, review count and paid-placement flag |
+| `get_capterra_product` | Full profile: per-star histogram, four scored criteria, pricing table, features, plus 25 recent reviews |
+| `get_capterra_reviews` | A page of reviews: overall plus five per-criterion scores, pros, cons, alternatives considered |
+
+2 credits per call. Only `get_capterra_reviews` paginates: 25 per page, capped at page 100 - past it Capterra answers 200 with page one, so check what came back. `get_capterra_product` already includes the 25 most recent reviews.
+
+### [Google Ads Transparency](https://scavio.dev/docs/google-ads-advertisers)
+
+| Tool | Description |
+|------|-------------|
+| `resolve_google_ads_advertiser` | START HERE - resolve a brand name or domain to the `advertiser_id` |
+| `search_google_ads` | Every ad Google is running for one advertiser, with first/last seen dates and days actually run |
+| `get_google_ads_creative` | One creative in full - the only tool carrying size variations, impression bucket and region breakdown |
+
+1 credit per call. Start with `resolve_google_ads_advertiser` to turn a brand name or domain into an `advertiser_id`. `search_google_ads` is cursor-paginated at 100 ads per page - re-send the same filters alongside the cursor. `get_google_ads_creative` is the only tool carrying a creative's history, region breakdown and impression bucket.
+
+### [Meta Ad Library](https://scavio.dev/docs/meta-ads-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_meta_ads` | Search the Meta Ad Library with full creative: ad copy, headline, CTA, media, platforms, run dates |
+| `get_meta_ads_advertiser` | Every ad a Facebook Page is running, by numeric page id, with the same creative detail |
+| `get_meta_ad` | One ad in full by archive id: creative, advertiser, run dates, platforms, political disclosure |
+
+1 credit per call, and every cursor page is another credit: page 1 returns 30 ads, then 10 per page thereafter, so the cost of walking a whole query scales with depth. `search_meta_ads` and `get_meta_ads_advertiser` both cursor-paginate - walk `has_next_page`. `get_meta_ad` is single-shot.
+
+### [SEC EDGAR](https://scavio.dev/docs/sec-edgar-lookup)
+
+| Tool | Description |
+|------|-------------|
+| `resolve_sec_company` | START HERE - resolve a company name or ticker to the CIK everything else is keyed by |
+| `get_sec_company` | Filer profile: legal and former names, SIC industry, EIN, LEI, fiscal year end, tickers |
+| `get_sec_filings` | A page of one filer's filings: accession number, form, dates, 8-K item codes, document links |
+| `get_sec_concept` | Every value a filer reported for one XBRL concept, newest first, with its source filing |
+| `get_sec_facts` | The index of every XBRL concept a filer reports - use it to find what to ask `get_sec_concept` for |
+| `search_sec_filings` | EDGAR full-text search, 2001-today, with facets by company, form, industry and state |
+
+1 credit per call on the official free EDGAR JSON API. Start with `resolve_sec_company` to turn a name or ticker into a CIK. `get_sec_filings` pages with `page` + `limit`; `search_sec_filings` pages up to 100, because the index refuses a result window past 10,000.
+
+### [Companies House](https://scavio.dev/docs/companies-house-search)
+
+| Tool | Description |
+|------|-------------|
+| `search_companies_house` | START HERE - search the UK register by name for the `company_number` |
+| `get_companies_house_company` | Full register entry: status, type, dates, registered office, SIC codes, accounts due dates |
+| `get_companies_house_officers` | Officers current and resigned: role, appointment and resignation dates, nationality, DOB |
+| `get_companies_house_filing_history` | Filings most recent first: date, type code, description, link to the filed PDF |
+
+1 credit per call on the official UK register. Start with `search_companies_house` for a `company_number`. Search returns 20 per page and is capped at page 50 - the register serves a 1000-result window per term whatever hit count it prints, then answers page 51 with a 416. Officers (35/page) and filing history have no upper page bound; past the last page they return an ordinary 200 with an empty list, which looks identical to having none.
+
 ### Account
 
 | Tool | Description |
@@ -376,8 +756,14 @@ at least one review.
 [Scavio](https://scavio.dev) is a unified [search API for AI agents](https://scavio.dev/search-api-for-ai-agents) and a data API for developers. One key, structured JSON, no scraping or proxies:
 
 - [Google Search API](https://scavio.dev/google-search-api) — SERP results, news, images, maps, and knowledge graph
-- [Amazon Product API](https://scavio.dev/amazon-product-api) and [Walmart Product API](https://scavio.dev/walmart-product-api) — product search and details
+- [Extract](https://scavio.dev/docs/extract) — read any URL as Markdown, plain text or raw HTML
+- [Amazon Product API](https://scavio.dev/amazon-product-api) and [Walmart Product API](https://scavio.dev/walmart-product-api) — product search and details, alongside [eBay](https://scavio.dev/docs/ebay-search), [Target](https://scavio.dev/docs/target-search) and [Home Depot](https://scavio.dev/docs/home-depot-search)
 - [TikTok API](https://scavio.dev/tiktok-api), [Instagram API](https://scavio.dev/instagram-api), [Reddit API](https://scavio.dev/reddit-api), [X API](https://scavio.dev/x-api), [LinkedIn API](https://scavio.dev/linkedin-api), and [YouTube API](https://scavio.dev/youtube-transcript-api) — social and video data
+- Travel and local — [Booking.com](https://scavio.dev/docs/booking-search), [Airbnb](https://scavio.dev/docs/airbnb-search), [Tripadvisor](https://scavio.dev/docs/tripadvisor-locations), [Yelp](https://scavio.dev/docs/yelp-search)
+- Real estate — [Zillow](https://scavio.dev/docs/zillow-search), [Redfin](https://scavio.dev/docs/redfin-search)
+- Jobs and employer data — [Indeed](https://scavio.dev/docs/indeed-search), [Glassdoor](https://scavio.dev/docs/glassdoor-companies)
+- Apps, software reviews and ad libraries — [App Store](https://scavio.dev/docs/app-store-search), [Google Play](https://scavio.dev/docs/google-play-search), [G2](https://scavio.dev/docs/g2-search), [Capterra](https://scavio.dev/docs/capterra-search), [Google Ads Transparency](https://scavio.dev/docs/google-ads-advertisers), [Meta Ad Library](https://scavio.dev/docs/meta-ads-search)
+- Company filings — [SEC EDGAR](https://scavio.dev/docs/sec-edgar-lookup), [Companies House](https://scavio.dev/docs/companies-house-search)
 
 Teams use it as a [SerpAPI alternative](https://scavio.dev/alternatives/serpapi) with structured multi-platform data — see [Tavily vs Scavio](https://scavio.dev/compare/tavily/vs-scavio) for a head-to-head comparison.
 

package/dist/index.js

@@ -1,10 +1,19 @@
 #!/usr/bin/env node
+import { readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { env } from "./lib/env.js";
 import { ScavioClient } from "./lib/client.js";
-import { registerAllTools } from "./tools/index.js";
+import { registerAllTools, PLATFORM_KEYS, DEFAULT_PLATFORMS } from "./tools/index.js";
 const SERVER_NAME = "scavio-mcp";
-const SERVER_VERSION = "0.1.0";
+/**
+ * Read from package.json rather than a literal. The literal drifted to five
+ * minor versions behind npm, and it is the version every client is handed
+ * during `initialize`. src/ and dist/ are both one level under the package
+ * root, so this resolves identically under tsx and under node dist/index.js.
+ */
+const SERVER_VERSION = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "..", "package.json"), "utf8")).version;
 if (env.TRANSPORT === "stdio") {
     await startStdio();
 }
@@ -20,17 +29,24 @@ async function startStdio() {
     }
     const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
     const client = new ScavioClient(apiKey);
-    registerAllTools(server, () => client);
+    const platforms = registerAllTools(server, () => client);
     const transport = new StdioServerTransport();
     await server.connect(transport);
-    console.error(`${SERVER_NAME} started (stdio)`);
+    console.error(`${SERVER_NAME} v${SERVER_VERSION} started (stdio) - platforms: ${platforms.join(", ") || "none"}` +
+        `${env.SCAVIO_PLATFORMS ? "" : " (default set; set SCAVIO_PLATFORMS=all for every platform)"}`);
 }
 async function startHttp() {
     const { Hono } = await import("hono");
     const { serve } = await import("@hono/node-server");
     const { WebStandardStreamableHTTPServerTransport } = await import("@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js");
     const app = new Hono();
-    app.get("/", (c) => c.json({ status: "ok", server: SERVER_NAME }));
+    app.get("/", (c) => c.json({
+        status: "ok",
+        server: SERVER_NAME,
+        version: SERVER_VERSION,
+        platforms: PLATFORM_KEYS,
+        default_platforms: DEFAULT_PLATFORMS,
+    }));
     app.get("/health", (c) => c.json({ status: "ok" }));
     app.post("/mcp", async (c) => {
         const apiKey = c.req.header("x-api-key") ??
@@ -39,15 +55,18 @@ async function startHttp() {
         if (!apiKey) {
             return c.json({ error: "Missing SCAVIO_API_KEY. Provide x-api-key or Authorization: Bearer header." }, 401);
         }
+        // A hosted remote has no per-user env var, so the allowlist is selectable
+        // per connection. Falls back to SCAVIO_PLATFORMS, then to the default set.
+        const platforms = c.req.header("x-scavio-platforms") ?? c.req.query("platforms") ?? env.SCAVIO_PLATFORMS;
         const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION });
         const client = new ScavioClient(apiKey);
-        registerAllTools(server, () => client);
+        registerAllTools(server, () => client, platforms);
         const transport = new WebStandardStreamableHTTPServerTransport({ sessionIdGenerator: undefined });
         await server.connect(transport);
         return transport.handleRequest(c.req.raw);
     });
     serve({ fetch: app.fetch, port: env.PORT }, (info) => {
-        console.error(`${SERVER_NAME} started (http) on port ${info.port}`);
+        console.error(`${SERVER_NAME} v${SERVER_VERSION} started (http) on port ${info.port}`);
     });
 }
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,GAAG,EAAE,MAAM,cAAc,CAAC;AACnC,OAAO,EAAE,YAAY,EAAE,MAAM,iBAAiB,CAAC;AAC/C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AAEpD,MAAM,WAAW,GAAG,YAAY,CAAC;AACjC,MAAM,cAAc,GAAG,OAAO,CAAC;AAE/B,IAAI,GAAG,CAAC,SAAS,KAAK,OAAO,EAAE,CAAC;IAC9B,MAAM,UAAU,EAAE,CAAC;AACrB,CAAC;KAAM,CAAC;IACN,MAAM,SAAS,EAAE,CAAC;AACpB,CAAC;AAED,KAAK,UAAU,UAAU;IACvB,MAAM,EAAE,oBAAoB,EAAE,GAAG,MAAM,MAAM,CAC3C,2CAA2C,CAC5C,CAAC;IAEF,MAAM,MAAM,GAAG,GAAG,CAAC,cAAc,CAAC;IAClC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,CAAC,KAAK,CAAC,gDAAgD,CAAC,CAAC;QAChE,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;IAClB,CAAC;IAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;IAC7E,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;IACxC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;IAEvC,MAAM,SAAS,GAAG,IAAI,oBAAoB,EAAE,CAAC;IAC7C,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;IAChC,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,kBAAkB,CAAC,CAAC;AAClD,CAAC;AAED,KAAK,UAAU,SAAS;IACtB,MAAM,EAAE,IAAI,EAAE,GAAG,MAAM,MAAM,CAAC,MAAM,CAAC,CAAC;IACtC,MAAM,EAAE,KAAK,EAAE,GAAG,MAAM,MAAM,CAAC,mBAAmB,CAAC,CAAC;IACpD,MAAM,EAAE,wCAAwC,EAAE,GAAG,MAAM,MAAM,CAC/D,+DAA+D,CAChE,CAAC;IAEF,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IAEvB,GAAG,CAAC,GAAG,CAAC,GAAG,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IACnE,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC;IAEpD,GAAG,CAAC,IAAI,CAAC,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE;QAC3B,MAAM,MAAM,GACV,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,WAAW,CAAC;YACzB,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,EAAE,OAAO,CAAC,SAAS,EAAE,EAAE,CAAC;YACrD,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC;QAEzB,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,CAAC,CAAC,IAAI,CAAC,EAAE,KAAK,EAAE,4EAA4E,EAAE,EAAE,GAAG,CAAC,CAAC;QAC9G,CAAC;QAED,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC,EAAE,IAAI,EAAE,WAAW,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC;QAC7E,MAAM,MAAM,GAAG,IAAI,YAAY,CAAC,MAAM,CAAC,CAAC;QACxC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,CAAC,MAAM,CAAC,CAAC;QAEvC,MAAM,SAAS,GAAG,IAAI,wCAAwC,CAAC,EAAE,kBAAkB,EAAE,SAAS,EAAE,CAAC,CAAC;QAClG,MAAM,MAAM,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC;QAChC,OAAO,SAAS,CAAC,aAAa,CAAC,CAAC,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC5C,CAAC,CAAC,CAAC;IAEH,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QACnD,OAAO,CAAC,KAAK,CAAC,GAAG,WAAW,2BAA2B,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IACtE,CAAC,CAAC,CAAC;AACL,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/lib/env.d.ts

@@ -3,4 +3,5 @@ export declare const env: {
     PORT: number;
     TRANSPORT: "http" | "stdio";
     SCAVIO_API_KEY?: string | undefined;
+    SCAVIO_PLATFORMS?: string | undefined;
 };

package/dist/lib/env.js

@@ -3,6 +3,10 @@ const envSchema = z.object({
     SCAVIO_API_BASE_URL: z.string().url()
         .default("https://api.scavio.dev"),
     SCAVIO_API_KEY: z.string().optional(),
+    // Comma-separated allowlist of platform keys to register (see src/tools/index.ts).
+    // Unset = the curated default set. "all" = every platform. Left as a free-form
+    // string on purpose: an unknown key is warned about and skipped, never fatal.
+    SCAVIO_PLATFORMS: z.string().optional(),
     PORT: z.coerce.number().int().min(1).max(65535)
         .default(3000),
     TRANSPORT: z.enum(["http", "stdio"])

package/dist/lib/env.js.map

@@ -1 +1 @@
-{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;SAClC,OAAO,CAAC,wBAAwB,CAAC;IACpC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;SAC5C,OAAO,CAAC,IAAI,CAAC;IAChB,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACjC,OAAO,CAAC,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC"}
+{"version":3,"file":"env.js","sourceRoot":"","sources":["../../src/lib/env.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,MAAM,SAAS,GAAG,CAAC,CAAC,MAAM,CAAC;IACzB,mBAAmB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE;SAClC,OAAO,CAAC,wBAAwB,CAAC;IACpC,cAAc,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACrC,mFAAmF;IACnF,+EAA+E;IAC/E,8EAA8E;IAC9E,gBAAgB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,QAAQ,EAAE;IACvC,IAAI,EAAE,CAAC,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,GAAG,EAAE,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC;SAC5C,OAAO,CAAC,IAAI,CAAC;IAChB,SAAS,EAAE,CAAC,CAAC,IAAI,CAAC,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SACjC,OAAO,CAAC,OAAO,CAAC;CACpB,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,GAAG,GAAG,SAAS,CAAC,KAAK,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC"}

package/dist/lib/tool-error.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The catch block every tool handler shares.
+ *
+ * This lived as a verbatim copy-paste inside each of the tool modules (plus an
+ * inlined 32nd copy in usage.ts). At 11 files that was tolerable; at 33 it was
+ * a guaranteed drift surface, so it lives here now and is imported.
+ *
+ * Two distinct error channels, deliberately:
+ *  - 401 throws an McpError, because a bad key is a configuration fault the
+ *    agent cannot recover from by retrying or rewording — the client should
+ *    surface it to the human.
+ *  - everything else returns `isError: true`, which the model can read and act
+ *    on (back off on a 429, try another id on a 404) instead of the call
+ *    blowing up the turn.
+ */
+export declare function handleApiError(err: unknown): never | {
+    isError: true;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};

package/dist/lib/tool-error.js

@@ -0,0 +1,28 @@
+import { McpError, ErrorCode } from "@modelcontextprotocol/sdk/types.js";
+import { ApiError } from "./errors.js";
+/**
+ * The catch block every tool handler shares.
+ *
+ * This lived as a verbatim copy-paste inside each of the tool modules (plus an
+ * inlined 32nd copy in usage.ts). At 11 files that was tolerable; at 33 it was
+ * a guaranteed drift surface, so it lives here now and is imported.
+ *
+ * Two distinct error channels, deliberately:
+ *  - 401 throws an McpError, because a bad key is a configuration fault the
+ *    agent cannot recover from by retrying or rewording — the client should
+ *    surface it to the human.
+ *  - everything else returns `isError: true`, which the model can read and act
+ *    on (back off on a 429, try another id on a 404) instead of the call
+ *    blowing up the turn.
+ */
+export function handleApiError(err) {
+    if (err instanceof ApiError) {
+        if (err.status === 429)
+            return { isError: true, content: [{ type: "text", text: "Rate limited. Wait and retry." }] };
+        if (err.status === 401)
+            throw new McpError(ErrorCode.InternalError, "Invalid SCAVIO_API_KEY. Check your configuration.");
+        return { isError: true, content: [{ type: "text", text: `Scavio API error (${err.status}): ${err.message}` }] };
+    }
+    throw new McpError(ErrorCode.InternalError, String(err));
+}
+//# sourceMappingURL=tool-error.js.map

package/dist/lib/tool-error.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tool-error.js","sourceRoot":"","sources":["../../src/lib/tool-error.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,MAAM,oCAAoC,CAAC;AACzE,OAAO,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAEvC;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,cAAc,CAAC,GAAY;IACzC,IAAI,GAAG,YAAY,QAAQ,EAAE,CAAC;QAC5B,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,+BAA+B,EAAE,CAAC,EAAE,CAAC;QACrH,IAAI,GAAG,CAAC,MAAM,KAAK,GAAG;YAAE,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,EAAE,mDAAmD,CAAC,CAAC;QACzH,OAAO,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,qBAAqB,GAAG,CAAC,MAAM,MAAM,GAAG,CAAC,OAAO,EAAE,EAAE,CAAC,EAAE,CAAC;IAClH,CAAC;IACD,MAAM,IAAI,QAAQ,CAAC,SAAS,CAAC,aAAa,EAAE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC;AAC3D,CAAC"}

package/dist/tools/airbnb.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ScavioClient } from "../lib/client.js";
+export declare function registerAirbnbTools(server: McpServer, getClient: () => ScavioClient): void;