mcp-scraper 0.32.2 → 0.33.0

package/dist/{worker-ZZCZNY3R.js → worker-JU5FX3NE.js}

@@ -6,7 +6,7 @@ import {
 } from "./chunk-SDHPQTFM.js";
 import {
   harvest
-} from "./chunk-AEMABLEL.js";
+} from "./chunk-ERORC7AP.js";
 import {
   browserServiceApiKey,
   runWithCostContext
@@ -139,4 +139,4 @@ export {
   startWorker,
   tickOnce
 };
-//# sourceMappingURL=worker-ZZCZNY3R.js.map
+//# sourceMappingURL=worker-JU5FX3NE.js.map

package/docs/adr/0003-waive-unrecoverable-scheduled-model-cost.md

@@ -0,0 +1,22 @@
+# ADR-0003: Waive unrecoverable scheduled model cost during repair
+
+**Status:** Accepted
+
+**Date:** 2026-07-22
+
+## Context
+
+An agent-mode scheduled run completed provider/model work on 2026-07-14, but OpenRouter did not return a model-cost value. The 75-Credit base charge was already captured. Its settlement remained `cost_pending`, which correctly prevented an unverified model delta from being guessed but also blocked every later scheduled run for the account. The original authorization token and exact vendor cost are not recoverable.
+
+## Decision
+
+For this historical repair, preserve the captured base charge, waive the unknown model-cost delta, and close the settlement and authorization as settled with an explicit `model_cost_unavailable_waived` audit reason. Do not invent or estimate a vendor cost.
+
+Future runs continue to require exact reported OpenRouter cost under the existing billing contract. A new missing-cost occurrence must retain enough durable provider evidence for reconciliation or be explicitly waived by an audited operator repair; it must never be silently estimated.
+
+## Consequences
+
+- The account is no longer permanently blocked by an unrecoverable historical delta.
+- MCP Scraper absorbs the unknown model expense for this run.
+- The repair remains visible in billing-event metadata and preserves the original base-charge receipt.
+- A productized recovery path is still needed if missing provider cost recurs.

package/docs/adr/README.md

@@ -10,3 +10,4 @@ Write one when a decision is hard to reverse, surprising, or encodes a constrain
 ## Index
 - [0001 — In-page API interception for anti-bot scraping (Facebook Ad Library)](./0001-in-page-graphql-interception-for-anti-bot-scraping.md)
 - [0002 — Hybrid Smart RAG retrieval for memory vaults](./0002-hybrid-smart-rag-vault-retrieval.md)
+- [0003 — Waive unrecoverable scheduled model cost during repair](./0003-waive-unrecoverable-scheduled-model-cost.md)

package/docs/mcp-tool-manifest.generated.json

@@ -1,12 +1,12 @@
 {
-  "generatedAt": "2026-07-22T02:43:42.271Z",
+  "generatedAt": "2026-07-22T17:24:08.984Z",
   "generatedFrom": "dist/bin/mcp-stdio-server.js",
   "serverInfo": {
     "name": "mcp-scraper",
-    "version": "0.32.2"
+    "version": "0.33.0"
   },
   "counts": {
-    "unified_stdio": 165
+    "unified_stdio": 166
   },
   "surfaces": {
     "unified_stdio": [
@@ -85,6 +85,7 @@
       "get-schedule-status",
       "get-vault-app-link",
       "get-vault-contract",
+      "gmail_search_contacts",
       "gmail_send_message",
       "google_ads_page_intel",
       "google_ads_search",
@@ -4621,12 +4622,11 @@
           "proxyMode": {
             "type": "string",
             "enum": [
-              "location",
               "configured",
               "none"
             ],
             "default": "none",
-            "description": "Leave unset (clean egress). Do NOT set \"location\" just because a city was named — that comes from city-in-query wording. \"location\" forces residential geo-IP, is frequently CAPTCHA-blocked, and accepts failures."
+            "description": "Leave unset for clean egress (the default). Country/region localization comes from gl/hl plus the city or region in the query — not from a proxy."
           },
           "proxyZip": {
             "type": "string",
@@ -6293,12 +6293,11 @@
           "proxyMode": {
             "type": "string",
             "enum": [
-              "location",
               "configured",
               "none"
             ],
             "default": "none",
-            "description": "Proxy behavior per city search. Leave unset for the default route (stealth browser on the managed ISP proxy, retried fresh on a Google block). location forces an explicit residential proxy — not recommended for Google."
+            "description": "Proxy behavior per city search. Leave unset for the default route (stealth browser on the managed ISP proxy, retried fresh on a Google block). Country/region localization comes from the city or region in the query plus gl/hl — not from a proxy."
           },
           "proxyZip": {
             "type": "string",
@@ -9027,6 +9026,167 @@
         "taskSupport": "forbidden"
       }
     },
+    {
+      "name": "gmail_search_contacts",
+      "title": "Search Gmail Contacts",
+      "description": "Search Gmail with standard Gmail query syntax (e.g. \"from:acme.com after:2026/03/22\") and get back deduplicated sender contacts (email, name, domain, message count, first/last seen, sample subjects) instead of raw messages. Read-only — works on any connected Gmail connection from list_service_connections, no actionsEnabled required. Use this instead of looping list-messages/get-message yourself: those return bare message IDs and full raw MIME per message, which does not scale past a handful of messages. Reports totalMatches and truncated so incomplete coverage from a large result set is never silent — pass the returned nextPageToken to continue.",
+      "inputSchema": {
+        "type": "object",
+        "properties": {
+          "connectionId": {
+            "type": "string",
+            "minLength": 1,
+            "description": "A Gmail connectionId from list_service_connections. Read-only — does not require actionsEnabled."
+          },
+          "query": {
+            "type": "string",
+            "minLength": 1,
+            "maxLength": 500,
+            "description": "Gmail search syntax, e.g. \"from:brandnorth.com after:2026/03/22\" or \"brandnorth.com\"."
+          },
+          "maxMessages": {
+            "type": "integer",
+            "minimum": 1,
+            "maximum": 150,
+            "default": 50,
+            "description": "Max messages to fetch and aggregate in this call. Paginate with pageToken for more; the response reports totalMatches and truncated so undercoverage is never silent."
+          },
+          "pageToken": {
+            "type": "string",
+            "description": "Continuation token from a prior response to fetch the next page."
+          }
+        },
+        "required": [
+          "connectionId",
+          "query"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "outputSchema": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "totalMatches": {
+            "type": "number",
+            "description": "Gmail's estimated total matches for the query, independent of how many were fetched this call."
+          },
+          "messagesFetched": {
+            "type": "number"
+          },
+          "truncated": {
+            "type": "boolean",
+            "description": "True when totalMatches exceeds messagesFetched — more results exist, use nextPageToken."
+          },
+          "nextPageToken": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "messages": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "id": {
+                  "type": "string"
+                },
+                "date": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "from": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "to": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "subject": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "snippet": {
+                  "$ref": "#/properties/nextPageToken"
+                }
+              },
+              "required": [
+                "id",
+                "date",
+                "from",
+                "to",
+                "subject",
+                "snippet"
+              ],
+              "additionalProperties": false
+            }
+          },
+          "contacts": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "email": {
+                  "type": "string"
+                },
+                "name": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "domain": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "messageCount": {
+                  "type": "number"
+                },
+                "firstSeen": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "lastSeen": {
+                  "$ref": "#/properties/nextPageToken"
+                },
+                "sampleSubjects": {
+                  "type": "array",
+                  "items": {
+                    "type": "string"
+                  }
+                }
+              },
+              "required": [
+                "email",
+                "name",
+                "domain",
+                "messageCount",
+                "firstSeen",
+                "lastSeen",
+                "sampleSubjects"
+              ],
+              "additionalProperties": false
+            },
+            "description": "Messages deduped by sender email address, newest-to-oldest within this fetch only — not the full query result set when truncated."
+          },
+          "error": {
+            "$ref": "#/properties/nextPageToken"
+          }
+        },
+        "required": [
+          "ok",
+          "nextPageToken",
+          "error"
+        ],
+        "additionalProperties": false,
+        "$schema": "http://json-schema.org/draft-07/schema#"
+      },
+      "annotations": {
+        "title": "Search Gmail Contacts",
+        "readOnlyHint": true,
+        "destructiveHint": false,
+        "idempotentHint": true,
+        "openWorldHint": true
+      },
+      "execution": {
+        "taskSupport": "forbidden"
+      }
+    },
     {
       "name": "gmail_send_message",
       "title": "Send Gmail Message",
@@ -9629,12 +9789,11 @@
           "proxyMode": {
             "type": "string",
             "enum": [
-              "location",
               "configured",
               "none"
             ],
             "default": "none",
-            "description": "Leave unset (clean egress). Do NOT set \"location\" just because a city was named — that comes from city-in-query wording. \"location\" forces residential geo-IP for rank-tracking fidelity, is frequently CAPTCHA-blocked, and accepts failures."
+            "description": "Leave unset for clean egress (the default). Country/region localization comes from gl/hl plus the city or region in the query — not from a proxy."
           },
           "proxyZip": {
             "type": "string",
@@ -12350,12 +12509,11 @@
           "proxyMode": {
             "type": "string",
             "enum": [
-              "location",
               "configured",
               "none"
             ],
             "default": "none",
-            "description": "Leave unset for the default route (stealth browser on the managed ISP proxy, retried on a fresh session when Google blocks). Localization comes from the city in the query plus gl/hl. location forces an explicit residential proxy — not recommended for Google."
+            "description": "Leave unset for the default route (stealth browser on the managed ISP proxy, retried on a fresh session when Google blocks). Country/region localization comes from the city or region in the query plus gl/hl — not from a proxy."
           },
           "proxyZip": {
             "type": "string",
@@ -17317,12 +17475,11 @@
           "proxyMode": {
             "type": "string",
             "enum": [
-              "location",
               "configured",
               "none"
             ],
             "default": "none",
-            "description": "Leave unset (clean egress). Do NOT set \"location\" just because a city was named — that comes from city-in-query wording. \"location\" forces residential geo-IP for rank-tracking fidelity, is frequently CAPTCHA-blocked, and accepts failures."
+            "description": "Leave unset for clean egress (the default). Country/region localization comes from gl/hl plus the city or region in the query — not from a proxy."
           },
           "proxyZip": {
             "type": "string",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mcp-scraper",
-  "version": "0.32.2",
+  "version": "0.33.0",
   "description": "MCP server for MCP Scraper web intelligence tools",
   "type": "module",
   "main": "./dist/index.cjs",