mcp-scraper 0.2.1 → 0.2.3

package/README.md

@@ -4,10 +4,27 @@ MCP Scraper is an MCP server for live web intelligence tools backed by `https://
 
 ## Install
 
-Use the npm package from any MCP client that can run local stdio commands. MCP Scraper ships two separate local MCP servers:
+Use the MCPB Desktop Extension for the branded Claude Desktop install, or use the npm package from any MCP client that can run local stdio commands.
+
+MCP Scraper ships three local stdio entrypoints:
 
 - `mcp-scraper` — live web intelligence, SERP, PAA, site extraction, YouTube, Facebook, Maps, directory, 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.
+
+### Claude Desktop MCPB
+
+Build the branded one-click bundle:
+
+```bash
+npm run build:mcpb
+```
+
+The generated bundle is written to `build/mcpb/mcp-scraper-<version>.mcpb`. 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.
+
+### Raw stdio config
 
 Claude Desktop:
 
@@ -16,14 +33,7 @@ Claude Desktop:
   "mcpServers": {
     "mcp-scraper": {
       "command": "npx",
-        "args": ["-y", "mcp-scraper@latest"],
-      "env": {
-        "MCP_SCRAPER_API_KEY": "sk_live_your_key"
-      }
-    },
-    "browser-agent": {
-      "command": "npx",
-        "args": ["-y", "-p", "mcp-scraper@latest", "browser-agent"],
+      "args": ["-y", "-p", "mcp-scraper@latest", "mcp-scraper-combined"],
       "env": {
         "MCP_SCRAPER_API_KEY": "sk_live_your_key"
       }
@@ -32,10 +42,16 @@ Claude Desktop:
 }
 ```
 
-Existing MCP configs that use only `npx -y mcp-scraper` still work for the web intelligence server, but they do not automatically add the `browser-agent` server. Add the second config entry if you want browser tools. Use `mcp-scraper@latest` to force npm to resolve the newest published package whenever the MCP client starts a fresh `npx` process.
+Existing MCP configs that use only `npx -y mcp-scraper` still work for the web intelligence server, but they do not automatically add browser tools. Switch to `mcp-scraper-combined` or add the second `browser-agent` config entry if you want browser tools. Use `mcp-scraper@latest` to force npm to resolve the newest published package whenever the MCP client starts a fresh `npx` process.
 
 Claude Code:
 
+```bash
+claude mcp add mcp-scraper --scope user --env MCP_SCRAPER_API_KEY=sk_live_your_key -- npx -y -p mcp-scraper@latest mcp-scraper-combined
+```
+
+Split-server raw config still works:
+
 ```bash
 claude mcp add mcp-scraper --scope user --env MCP_SCRAPER_API_KEY=sk_live_your_key -- npx -y mcp-scraper@latest
 claude mcp add browser-agent --scope user --env MCP_SCRAPER_API_KEY=sk_live_your_key -- npx -y -p mcp-scraper@latest browser-agent
@@ -43,6 +59,15 @@ claude mcp add browser-agent --scope user --env MCP_SCRAPER_API_KEY=sk_live_your
 
 Codex config:
 
+```toml
+[mcp_servers.mcp-scraper]
+command = "npx"
+args = ["-y", "-p", "mcp-scraper@latest", "mcp-scraper-combined"]
+env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
+```
+
+Split-server Codex config:
+
 ```toml
 [mcp_servers.mcp-scraper]
 command = "npx"
@@ -57,7 +82,7 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 
 ## Tools
 
-### `mcp-scraper` stdio tools
+### Web-intelligence tools
 
 - `harvest_paa`
 - `search_serp`
@@ -74,7 +99,7 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 - `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.
 - `credits_info`
 
-### `browser-agent` stdio tools
+### 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.
@@ -93,13 +118,15 @@ env = { MCP_SCRAPER_API_KEY = "sk_live_your_key" }
 
 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).
 
-The hosted MCP endpoint at `https://mcpscraper.dev/mcp` exposes the 14 `mcp-scraper` tools plus `capture_serp_snapshot` and `capture_serp_page_snapshots` (16 total). The `browser-agent` server is currently a separate local stdio server; its REST backing API lives under `https://mcpscraper.dev/agent/*`.
+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/*`.
 
 ## Resources
 
-The `mcp-scraper` NPX stdio server also exposes saved reports as MCP resources: `resources/list` returns the most recent Markdown reports from your output directory as `report://` URIs, and `resources/read` returns their content — so an MCP client can pull prior research into context without re-scraping or spending credits. The hosted endpoint does not expose resources (it saves no files).
+The `mcp-scraper` and `mcp-scraper-combined` NPX stdio servers also expose saved reports as MCP resources: `resources/list` returns the most recent Markdown reports from your output directory as `report://` URIs, and `resources/read` returns their content — so an MCP client can pull prior research into context without re-scraping or spending credits. The hosted endpoint does not expose resources (it saves no files).
 
 ## Environment
 
@@ -109,7 +136,7 @@ The `mcp-scraper` NPX stdio server also exposes saved reports as MCP resources:
 - `MCP_SCRAPER_SAVE_REPORTS=false` disables automatic Markdown report files.
 - `MCP_SCRAPER_KEY_PATH` is optional. When no API key env var is set, the server also reads `~/.mcp-scraper-key` for compatibility with older installs.
 
-Every web intelligence tool call made through the `mcp-scraper` NPX stdio server saves a full Markdown report locally by default and returns the file path in the MCP response. The hosted `/mcp` endpoint returns reports inline only and never writes files. Browser replay downloads are saved by `browser_replay_download` under `MCP_SCRAPER_OUTPUT_DIR/browser-replays`.
+Every web intelligence tool call made through `mcp-scraper` or `mcp-scraper-combined` saves a full Markdown report locally by default and returns the file path in the MCP response. The hosted `/mcp` endpoint returns reports inline only and never writes files. Browser replay downloads are saved by `browser_replay_download` under `MCP_SCRAPER_OUTPUT_DIR/browser-replays`.
 
 ## Updating Existing Installs
 
@@ -117,6 +144,12 @@ Hosted API and website changes deploy immediately to `https://mcpscraper.dev`. L
 
 Recommended config for update-friendly installs:
 
+```bash
+npx -y -p mcp-scraper@latest mcp-scraper-combined
+```
+
+Split-server config:
+
 ```bash
 npx -y mcp-scraper@latest
 npx -y -p mcp-scraper@latest browser-agent
@@ -129,13 +162,19 @@ 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 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 `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.
 
 ## Branded One-Click Installs
 
 Raw `npx` MCP installs are command/config based. They do not provide a reliable user-facing install card, logo, or setup screen inside MCP clients. Do not print marketing text to stdout from an MCP server; stdout is reserved for JSON-RPC protocol messages.
 
-For a branded Claude Desktop install, package MCP Scraper as an MCPB Desktop Extension. An MCPB bundle can include a `manifest.json`, bundled server files/dependencies, `user_config` fields for API-key setup, and an optional `icon.png`. That is the right path for a designed install experience with a logo and guided configuration.
+For a branded Claude Desktop install, package MCP Scraper as an MCPB Desktop Extension. The repository now builds one combined MCPB bundle with a generated icon, `manifest.json`, bundled runtime dependencies, and `user_config` fields for API-key setup, API URL, and output folder.
+
+```bash
+npm run build:mcpb
+```
+
+The bundle uses `mcp-scraper-combined` internally, so the user installs `MCP Scraper` once and gets web-intelligence tools plus live browser tools in one MCP server.
 
 ## Development
 

package/dist/bin/api-server.cjs

@@ -17082,7 +17082,7 @@ var PACKAGE_VERSION;
 var init_version = __esm({
   "src/version.ts"() {
     "use strict";
-    PACKAGE_VERSION = "0.2.1";
+    PACKAGE_VERSION = "0.2.3";
   }
 });
 
@@ -17513,10 +17513,14 @@ function registerSavedReportResources(server) {
   );
 }
 function buildPaaExtractorMcpServer(executor, options = {}) {
+  const server = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION });
+  registerPaaExtractorMcpTools(server, executor, options);
+  return server;
+}
+function registerPaaExtractorMcpTools(server, executor, options = {}) {
   const savesReports = options.savesReportsLocally !== false;
   const reportNote = savesReports ? " Saves a full Markdown report locally." : " Reports are returned inline; no files are saved on this hosted endpoint.";
   const withReportNote = (description) => `${description}${reportNote}`;
-  const server = new import_mcp.McpServer({ name: "mcp-scraper", version: PACKAGE_VERSION });
   if (savesReports) registerSavedReportResources(server);
   server.registerTool("harvest_paa", {
     title: "Google PAA + SERP Harvest",
@@ -17620,7 +17624,6 @@ function buildPaaExtractorMcpServer(executor, options = {}) {
       openWorldHint: false
     }
   }, async (input) => formatCreditsInfo(await executor.creditsInfo(input), input));
-  return server;
 }
 var import_mcp, import_node_fs5, import_node_path8;
 var init_paa_mcp_server = __esm({