mcpscraper-cli 0.50.1 → 0.51.1

package/README.md

@@ -4,7 +4,7 @@ Command-line interface for the unified [mcpscraper.dev](https://mcpscraper.dev)
 
 [Release history](https://github.com/VilovietaSEO/mcpscraper-sdk/blob/main/CHANGELOG.md)
 
-The CLI provides friendly shortcuts for common operations plus universal discovery and invocation for every one of the 364 unified MCP tools, including provider-neutral X-Ray surveys, attribution-impact reporting, and truthful evidence-status operations.
+The CLI provides friendly shortcuts for common operations plus universal discovery and invocation for every one of the 367 unified MCP tools, including retained-file readers, provider-neutral X-Ray surveys, attribution-impact reporting, and truthful evidence-status operations.
 
 ## Install
 
@@ -20,6 +20,20 @@ export MCPSCRAPER_API_KEY=sk_live_your_key
 
 or pass `--api-key <key>` on any command.
 
+## Deployment and client attribution
+
+The default API endpoint is `https://mcpscraper.dev`. To use a selected branch deployment, set `MCPSCRAPER_BASE_URL` or pass `--base-url https://your-preview.example.com`. The URL must not contain credentials, a query or a fragment; authentication still uses the API key.
+
+Attribution labels help the operator identify client usage in reports. They do not affect authentication, credits, provider selection or tool arguments. Declare the installation channel and AI client/model when known:
+
+```bash
+mcpscraper --install-channel npm --ai-client claude-code --ai-model claude-sonnet-4 tools call credits_info --args '{}' --json
+```
+
+The equivalent environment settings are `MCP_SCRAPER_INSTALL_CHANNEL`, `MCP_SCRAPER_AI_CLIENT` and `MCP_SCRAPER_AI_MODEL`. Command flags take precedence. Installation choices are `npx`, `npm`, `source` and `mcpb`; AI client choices are `claude`, `claude-desktop`, `claude-code`, `chatgpt`, `codex`, `cursor`, `gemini` and `other`. Model identifiers are limited to 80 characters, starting with a letter or digit and containing only letters, digits, `.`, `_`, `:`, `/` and `-`.
+
+The CLI automatically reports `npx` only when its observed executable path is inside an `_npx` cache directory. An npm or source installation and AI identity stay unspecified unless declared. Direct API shortcuts report the `rest` surface, including `/memory/mcp-call`; universal `tools call` commands report `mcp-http`. Installation channel is a separate label.
+
 ## Commands
 
 ### Every MCP tool
@@ -34,6 +48,9 @@ mcpscraper tools call export_connected_service_data --args '{"connectionId":"gsc
 mcpscraper tools call describe_service_connection_tool --args '{"connectionId":"conn_123","tool":"provider-tool-name"}' --json
 mcpscraper tools call renew_connected_data_download --args '{"artifactId":"artifact_123"}' --json
 mcpscraper tools call archive_read --args '{"url":"https://github.com/octocat/Hello-World/archive/refs/heads/master.zip"}' --json
+mcpscraper tools call artifact_describe --args '{"artifactId":"artifact_123"}' --json
+mcpscraper tools call artifact_read --args '{"artifactId":"artifact_123","offset":0,"maxBytes":64000}' --json
+mcpscraper tools call artifact_download --args '{"artifactId":"artifact_123"}' --raw-result
 mcpscraper tools call list_scheduled_runs --args '{"view":"inbox","limit":30}' --json
 mcpscraper tools call lead_list_enrich --args '{"idempotencyKey":"roofing-dallas-001","source":{"kind":"rows","rows":[{"Business":"White Rock Roofing","City":"Dallas","Website":"https://roofwhiterock.com"}]},"columnMap":{"name":"Business","city":"City","websiteUrl":"Website"},"defaultEntityType":"business","emailSearchFallback":"serp_snippets","peopleDiscovery":"owners","peopleQueryTemplates":["{business} owner of company {city}","{business} founder {city}"],"outputFormats":["csv","xlsx"]}' --json
 mcpscraper tools call gmail_search_messages --args '{"connectionId":"gmail_conn_123","query":"has:attachment newer_than:30d","limit":25}' --json
@@ -41,11 +58,13 @@ mcpscraper tools call gmail_prepare_selection --args '{"connectionId":"gmail_con
 mcpscraper tools call gmail_import_status --args '{"ingestId":"opaque_ingest_id"}' --json
 ```
 
-`tools list` contains exactly 364 manifest-backed names. `tools call` accepts any one of them. Tools marked destructive require `--yes`.
+`tools list` contains exactly 367 manifest-backed names. `tools call` accepts any one of them. Tools marked destructive require `--yes`.
+
+`tools call --json` keeps the existing output shape: parsed `structuredContent` or text for text-only results, and the MCP envelope when it includes resources or media. Use `--raw-result` to always retain the envelope, including `content`, `structuredContent`, metadata and resource links. Both modes save inline binary blocks to local files and replace their bytes with `savedPath` and byte-count metadata. Retained-file envelopes and resource links remain available in the output. For complete text, use the returned artifact ID with `artifact_read` and follow `nextOffset` until it is null. `artifact_describe` reports MIME type, size, supported readers and retention expiry; `artifact_download` returns or renews the original file's link while retention remains valid. A preview or one read window is not the whole source.
 
 Integration connections are included with an active Starter plan or higher and have no extra connection-operation debit in this release. Scheduled occurrences cost 75 Credits; agent-mode runs also add 1.5 times OpenRouter's actual reported cost. Inspect the live policy with `mcpscraper tools call get-schedule-status --args '{}'`.
 
-Google Search light mode returns organic positions, URLs, titles, and descriptions for 20 Credits per delivered SERP page, or 35 Credits when the backup supplies the result. Unfiltered one-page full mode adds available same-page SERP features for 35 Credits. Both modes default to one page. Past-week and past-month searches use a managed browser for organic results at 35 Credits per delivered page; unfiltered searches use it only as the final backup. Request a second page explicitly. A 35-Credit-per-requested-page hold is settled after delivery. PAA costs 400 Credits plus 10 Credits per returned question. One optional concurrency pack adds two browser slots for $5/month; quantity n adds 2n browser slots.
+Google Search light mode returns organic positions, URLs, titles, and descriptions for 20 Credits per delivered SERP page, or 35 Credits when the backup supplies the result. Unfiltered light mode makes two primary attempts, then one API fallback. Unfiltered one-page full mode adds available same-page SERP features for 35 Credits. Both modes default to one page. Past-week and past-month searches use a managed browser for organic results at 35 Credits per delivered page. Request a second page explicitly. A 35-Credit-per-requested-page hold is settled after delivery. PAA costs 400 Credits plus 10 Credits per returned question. One optional concurrency pack adds two browser slots for $5/month; quantity n adds 2n browser slots.
 
 Use `mcpscraper tools call harvest_paa_start --args '{"query":"...","pages":2,"idempotencyKey":"..."}' --json`
 to request a second organic-results page, then poll the returned `jobId` with
@@ -86,8 +105,8 @@ Poll and read the export without downloading and unpacking the ZIP:
 
 ```bash
 mcpscraper export-status <job-id>
-mcpscraper export-read <job-id> --representation manifest
-mcpscraper export-read <job-id> --representation html --page-id <page-id> --output page.html
+mcpscraper export-read <job-id> --format manifest
+mcpscraper export-read <job-id> --format html --page-id <page-id> --output page.html
 mcpscraper export-image <job-id> <image-id> --output image.jpg
 ```
 
@@ -139,4 +158,6 @@ $ mcpscraper map https://example.com --json
 
 [Repo README](../../README.md) (multi-language examples with real sample output) · [`mcpscraper-sdk`](../scraper) · [`mcpscraper-memory-sdk`](../memory) · Python: [`mcpscraper-sdk`](../scraper-python) · [`mcpscraper-memory-sdk`](../memory-python)
 
-Release changes: [SDK 0.52.0 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.52.0).
+Durable PAA harvests should wait at least 20 seconds between status checks and honor a longer returned polling interval. Keep the same job ID and retry key while the original work is running.
+
+Release changes: [SDK 0.53.1 release notes](https://github.com/VilovietaSEO/mcpscraper-sdk/releases/tag/v0.53.1).