mcp-scraper 0.2.5 → 0.2.7

package/README.md

@@ -8,7 +8,7 @@ Use the MCPB Desktop Extension for the branded Claude Desktop install, or use th
 
 MCP Scraper ships three local stdio entrypoints:
 
-- `mcp-scraper` — live web intelligence, SERP, PAA, site extraction, YouTube, Facebook, Maps, directory, and credit tools.
+- `mcp-scraper` — live web intelligence, SERP, PAA, site extraction, YouTube, Facebook, Maps, directory, rank tracker blueprint, and credit tools.
 - `browser-agent` — an agent-controlled live cloud browser with screenshots, clicks, typing, scrolling, live watch URLs, replay links, and MP4 replay download.
 - `mcp-scraper-combined` — one local MCP server that exposes both tool sets. This is the entrypoint used by the MCPB Desktop Extension.
 - `mcp-scraper-install` — a human-facing terminal installer card with the branded ASCII intro and copyable install commands. This command is safe to print because it is not an MCP stdio server.
@@ -31,7 +31,7 @@ Build the branded one-click bundle:
 npm run build:mcpb
 ```
 
-The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.2.5`, SHA-256 `aa988681b211a4d6183754ffaeb3f512c522e724a45b769c0d2023d68f1a019f`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb` and copied to `public/downloads/` for the hosted download. The current public bundle is `https://mcpscraper.dev/downloads/mcp-scraper.mcpb` (`0.2.6`, SHA-256 `d316c1e3744d61c84b8fbbf2b155dba7da4062be52d9024d9fa7adde04c5b73c`). Install it by opening or dragging it into Claude Desktop. Claude displays the `MCP Scraper` install card, icon, and API-key configuration field from the bundle manifest.
 
 The MCPB install exposes the same web-intelligence tools as `mcp-scraper` plus all `browser_*` tools from `browser-agent` through one server.
 
@@ -108,13 +108,15 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 - `maps_search` — search Google Maps for multiple business/profile candidates. Use for GMB/GBP prospect lists, competitors, categories, and anything needing more than the Google 3-pack. `maxResults` defaults to 10 and is capped at 50.
 - `maps_place_intel` — hydrate one known/named Google Maps business with profile details and optional reviews. Use after `maps_search` when a selected candidate needs full details.
 - `directory_workflow` — build city-by-city directory/prospecting datasets from Census place selection plus Google Maps searches. Use it for requests like "all cities over 100k population in Tennessee, then get 20 roofers from Maps." The saved CSV includes `source_location`, `result_position`, `business_name`, `review_stars`, `category`, `address`, `phone`, `hours_status`, `website_url`, `directions_url`, `place_url`, `cid`, `cid_decimal`, Census population, and ZIP groups. It captures Maps star ratings from list cards, not profile review counts.
+- `rank_tracker_blueprint` — generate a database schema, cron/heartbeat plan, ingestion workflow, metrics list, and implementation prompt for building rank trackers. It has modes for Maps rankings via `directory_workflow`/`maps_search`, organic rankings via `search_serp`, AI Overview citation tracking, and PAA source presence tracking. This is a local planning tool and does not spend credits.
 - `credits_info`
 
 ### Browser-agent tools
 
 - `browser_open` — open a live cloud browser session. Returns a `session_id`, a human `watch_url`, and the raw `live_view_url` when available.
-- `browser_screenshot` — capture a screenshot plus visible text and clickable element coordinates.
-- `browser_read` — read the current page text and elements without an image.
+- `browser_screenshot` — capture a screenshot plus visible text and clickable element center coordinates and DOM bounds.
+- `browser_read` — read the current page text and elements with center coordinates and DOM bounds, without an image.
+- `browser_locate` — locate exact visible DOM elements or text ranges and return screenshot-pixel bounds.
 - `browser_goto`
 - `browser_click`
 - `browser_type`
@@ -124,16 +126,20 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 - `browser_replay_stop` — stop a replay. Returns the final `view_url` and `download_url`.
 - `browser_list_replays` — list replay videos for a session.
 - `browser_replay_download` — download and save the replay MP4 locally under `MCP_SCRAPER_OUTPUT_DIR/browser-replays`.
+- `browser_replay_mark` — while recording, locate a DOM target and return a replay-timed annotation object.
+- `browser_replay_annotate` — download a replay MP4, render timed boxes, circles, underlines, arrows, and labels using annotation objects from `browser_replay_mark` or exact bounds from `browser_locate`, and save a new annotated MP4 locally.
 - `browser_close`
 - `browser_list_sessions`
 
+For accurate annotated videos, do not guess annotation times from a script. Start the replay, navigate until each target is visible and stable, call `browser_replay_mark` for each callout, then stop the replay and pass the returned annotations to `browser_replay_annotate` with the returned `source_width` and `source_height`.
+
 For US local SERP tools (`harvest_paa` and `search_serp`), keep `proxyMode` at the default `location` unless you are debugging. Location mode uses fresh residential proxy IDs across retries and treats CAPTCHA, proxy tunnel failure, and wrong-location evidence as retryable before returning.
 
 The MCPB bundle and `mcp-scraper-combined` expose both sections through one local MCP server. The split `mcp-scraper` entrypoint exposes only the web-intelligence tools, and the split `browser-agent` entrypoint exposes only the browser-agent tools.
 
-Chaining tools (`maps_search`, `map_site_urls`, `youtube_harvest`, `facebook_ad_search`, `facebook_page_intel`) advertise an `outputSchema` and return `structuredContent` with the IDs and URLs needed by the next tool. All tools carry MCP annotations (`readOnlyHint: true`, `openWorldHint: true` for live-web tools).
+Chaining and planning tools (`maps_search`, `directory_workflow`, `rank_tracker_blueprint`, `map_site_urls`, `youtube_harvest`, `facebook_ad_search`, `facebook_page_intel`) advertise an `outputSchema` and return `structuredContent` with the IDs, URLs, CSV paths, or blueprint fields needed by the next step. All tools carry MCP annotations (`readOnlyHint: true`; live-web tools use `openWorldHint: true`, while local planning and credit tools are closed-world/idempotent).
 
-The hosted MCP endpoint at `https://mcpscraper.dev/mcp` exposes the 14 web-intelligence tools plus `capture_serp_snapshot` and `capture_serp_page_snapshots` (16 total). Browser-agent tools are local stdio tools backed by the REST API under `https://mcpscraper.dev/agent/*`.
+The hosted MCP endpoint at `https://mcpscraper.dev/mcp` exposes the 15 web-intelligence tools plus `capture_serp_snapshot` and `capture_serp_page_snapshots` (17 total). Browser-agent tools are local stdio tools backed by the REST API under `https://mcpscraper.dev/agent/*`.
 
 ## Resources
 
@@ -173,7 +179,7 @@ npm update -g mcp-scraper
 npm install mcp-scraper@latest
 ```
 
-Users who do not update can keep using the tools their local package already advertises, but they will not see newly added local stdio tools, schemas, or AI-facing descriptions. For example, a client running an older local package cannot call `directory_workflow` through stdio even if the hosted API already supports it. Users who configured only `mcp-scraper` must switch to `mcp-scraper-combined` or add `browser-agent` separately; MCP clients do not auto-create a second server entry from an existing config.
+Users who do not update can keep using the tools their local package already advertises, but they will not see newly added local stdio tools, schemas, or AI-facing descriptions. For example, a client running an older local package cannot call `rank_tracker_blueprint`, `directory_workflow`, or browser tools through stdio even if the hosted API already supports adjacent endpoints. Users who configured only `mcp-scraper` must switch to `mcp-scraper-combined` or add `browser-agent` separately; MCP clients do not auto-create a second server entry from an existing config.
 
 ## Branded One-Click Installs