@mrscraper/opencode 0.0.0-stage → 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,25 @@
+# Changelog
+
+All notable changes to the MrScraper OpenCode plugin are documented here. The
+project follows [Semantic Versioning](https://semver.org/).
+
+## 0.2.0 - 2026-10-12
+
+- Added OpenCode 2 support. OpenCode 2 does not run OpenCode 1 plugins; the
+  package now default-exports one object with an OpenCode 2 `setup()`, which
+  registers the `mrscraper` MCP server and the four skills through MCP and
+  skill transforms, and an OpenCode 1 `server()`, which keeps the existing
+  config hook.
+- OpenCode 1 now needs 1.18.29 or later (the first release that loads the
+  object form). On older releases, pin `@mrscraper/opencode@0.1.0`.
+- The `MrScraperPlugin` named export was removed; use the default export.
+- Documented OpenCode 2 install, sign-in, API-key configuration
+  (`mcp.servers`), and update commands.
+
+## 0.1.0 - 2026-10-05
+
+- Added the initial `@mrscraper/opencode` plugin: registers the hosted
+  MrScraper MCP server (`https://mcp.mrscraper.com/mcp`, OAuth 2.1) as
+  `mrscraper` unless the user already defines that server, and loads the
+  `mrscraper`, `mrscraper-fetch`, `mrscraper-scrape`, and `mrscraper-serp`
+  skills from the MrScraper Claude plugin 0.1.4.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 MrScraper
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# MrScraper for OpenCode
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+MrScraper connects [OpenCode](https://opencode.ai) to a hosted MCP server for
+fetching public web pages, managed structured extraction, Google discovery,
+saved scraper reruns, stored results, and account usage. The plugin also
+includes four focused skills that help OpenCode choose the right workflow and
+preserve raw page content.
+
+The same package works in OpenCode 2 and OpenCode 1.
+
+## What this plugin adds
+
+- An MCP server named `mrscraper` that points at the hosted Streamable HTTP
+  endpoint `https://mcp.mrscraper.com/mcp`.
+- OAuth 2.1 sign-in handled by OpenCode; no credential is stored in this
+  package.
+- The `mrscraper`, `mrscraper-fetch`, `mrscraper-scrape`, and `mrscraper-serp`
+  skills.
+- A fetch-first workflow that keeps raw page responses available for analysis,
+  verification, and follow-up transformations.
+
+If your configuration already defines a `mrscraper` MCP server, the plugin
+keeps your entry and only adds the skills. It also leaves any skill with the
+same name that you already have in place.
+
+## Requirements
+
+- OpenCode 2 (verified with 2.0.26), or OpenCode 1.18.29 or later (verified
+  with 1.18.29 and 1.19.0). On older OpenCode 1 releases, pin
+  `@mrscraper/opencode@0.1.0`.
+- A [MrScraper](https://app.mrscraper.com) account.
+- Permission to access and process the target content.
+
+## Install
+
+### OpenCode 2
+
+```bash
+opencode plugin add @mrscraper/opencode
+```
+
+This adds the package to `plugins` in your global configuration. To enable it
+for one project instead, add it to that project's `opencode.jsonc`:
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["@mrscraper/opencode"]
+}
+```
+
+### OpenCode 1
+
+```bash
+opencode plugin @mrscraper/opencode --global
+```
+
+Or add the package to the `plugin` list in `~/.config/opencode/opencode.json`
+(all projects) or a project's `opencode.json`:
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@mrscraper/opencode"]
+}
+```
+
+OpenCode installs npm plugins when it starts and caches them.
+
+## Sign in
+
+```bash
+opencode mcp auth mrscraper
+```
+
+In OpenCode 2 you can also run `/mcps` in a session, select `mrscraper`, and
+sign in there. OpenCode opens the MrScraper consent page in your browser,
+registers its own OAuth client, and stores the tokens outside your project
+configuration. Never paste OAuth tokens or API keys into chat.
+
+Check the connection:
+
+```bash
+opencode mcp list
+```
+
+`mrscraper` shows `needs authentication` before sign-in and `connected`
+afterwards.
+
+On a machine without a local browser, use an API key instead (next section).
+OpenCode 1 waits for the browser on `http://127.0.0.1:19876/mcp/oauth/callback`,
+so you can also forward that port, for example
+`ssh -L 19876:127.0.0.1:19876 <host>`.
+
+## Use an API key instead of OAuth
+
+Create a key at [app.mrscraper.com/api-tokens](https://app.mrscraper.com/api-tokens),
+export it as `MRSCRAPER_API_KEY` in the environment that starts OpenCode, and
+define the server yourself.
+
+OpenCode 2 (`opencode.jsonc`):
+
+```jsonc
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugins": ["@mrscraper/opencode"],
+  "mcp": {
+    "servers": {
+      "mrscraper": {
+        "type": "remote",
+        "url": "https://mcp.mrscraper.com/mcp",
+        "oauth": false,
+        "headers": { "Authorization": "Bearer {env:MRSCRAPER_API_KEY}" }
+      }
+    }
+  }
+}
+```
+
+OpenCode 1 (`opencode.json`):
+
+```json
+{
+  "$schema": "https://opencode.ai/config.json",
+  "plugin": ["@mrscraper/opencode"],
+  "mcp": {
+    "mrscraper": {
+      "type": "remote",
+      "url": "https://mcp.mrscraper.com/mcp",
+      "oauth": false,
+      "headers": {
+        "Authorization": "Bearer {env:MRSCRAPER_API_KEY}"
+      }
+    }
+  }
+}
+```
+
+OpenCode substitutes `{env:MRSCRAPER_API_KEY}` when it loads the configuration,
+so the key stays out of the file. In OpenCode 2 the substitution happens in the
+background service, so the variable must be set where the service starts; after
+setting it, run `opencode service restart` from that shell. An API key carries
+your full account authority; OAuth scopes do not apply to it.
+
+## Try it
+
+```text
+Fetch https://www.scrapethissite.com/pages/simple/ and summarize the page.
+```
+
+The server provides these tools. OpenCode 1 shows them as `mrscraper_<tool>`;
+OpenCode 2 reaches MCP tools through Code Mode by default.
+
+| Tool | Purpose |
+| --- | --- |
+| `fetch` | Retrieve and preserve a known page's raw response. |
+| `scrape` | Run managed structured extraction or bounded site mapping. |
+| `serp` | Discover public pages through Google. |
+| `rerun` | Reuse a saved AI or manual scraper configuration. |
+| `results` | Browse and filter stored result records. |
+| `result` | Retrieve one stored result or poll an asynchronous run. |
+| `status` | Inspect subscription usage and request outcomes. |
+
+## Fetch-first routing
+
+When a public URL is already known, the skills direct OpenCode to fetch it
+first and treat the raw response as the source of truth. The agent can read,
+summarize, compare, or derive structured output locally without losing details
+to an early extraction prompt.
+
+For roughly 100 known pages with a shared layout, the agent can fetch pages
+concurrently, retain every raw response, and apply one reusable local extractor
+instead of requesting 100 separate backend-LLM extractions. Use `scrape` when
+managed extraction is explicitly requested or has a clear benefit after the page
+structure and desired schema are understood.
+
+## Data and permissions
+
+The plugin sends MCP tool inputs, including target URLs and extraction
+instructions, to MrScraper's hosted service. Page responses and tool results are
+then available to OpenCode and its model provider for the requested task.
+Managed general and listing extraction sends page content and the extraction
+prompt to a backend language model and saves a reusable scraper configuration;
+reruns create new stored results. Use it only with public or otherwise
+authorized content, and follow the target site's requirements.
+
+Review MrScraper's [MCP documentation](https://docs.mrscraper.com/docs/getting-started/mcp-server),
+[Privacy Policy](https://mrscraper.com/privacy-policy),
+[Acceptable Use Policy](https://mrscraper.com/acceptable-use-policy), and
+[Terms of Use](https://mrscraper.com/terms-of-use) before use.
+
+## Update or remove
+
+OpenCode 2 checks unpinned npm plugins for updates without installing them.
+Update or remove the plugin with:
+
+```bash
+opencode plugin update @mrscraper/opencode
+opencode plugin remove @mrscraper/opencode
+```
+
+In OpenCode 1, an unpinned entry stays on the version OpenCode first cached.
+To control updates, pin a version and change it when you upgrade:
+
+```json
+{
+  "plugin": ["@mrscraper/opencode@0.2.0"]
+}
+```
+
+To remove it from OpenCode 1, delete the entry from `plugin`. In either
+version, remove the stored OAuth tokens afterwards:
+
+```bash
+opencode mcp logout mrscraper
+```
+
+You can also revoke access under Connected applications in your MrScraper
+account.
+
+## Support and security
+
+- Product help: [MrScraper MCP documentation](https://docs.mrscraper.com/docs/getting-started/mcp-server)
+- Bugs and feature requests: [GitHub Issues](https://github.com/mrscraper-com/mrscraper-opencode-plugin/issues)
+- Account help: [support@mrscraper.com](mailto:support@mrscraper.com)
+- Security reports: see [SECURITY.md](SECURITY.md)
+
+## Development
+
+```text
+index.ts        default export with an OpenCode 2 `setup()` and an OpenCode 1
+                `server()`; both register the MCP server and the skills
+skills/         MCP-oriented skills, copied verbatim from
+                mrscraper-com/mrscraper-claude-plugin (plugins/mrscraper/skills)
+```
+
+```bash
+npm install
+npm run check
+npm pack --dry-run
+```
+
+Test a local checkout in both majors before a release. In OpenCode 2, add the
+checkout's absolute path to `plugins`, then run `opencode mcp list` and
+`opencode api skill.list`. In OpenCode 1, add it to `plugin`, then run
+`opencode mcp list` and `opencode debug skill`. Record user-visible changes in
+[CHANGELOG.md](CHANGELOG.md) and follow [PUBLISHING.md](PUBLISHING.md) for
+releases.
+
+## License
+
+[MIT](LICENSE)

package/index.ts

@@ -0,0 +1,93 @@
+import type { Plugin as OpenCode1Plugin } from "@opencode-ai/plugin"
+import type { Plugin as OpenCode2, Skill } from "@opencode/plugin"
+import { readdir, readFile } from "node:fs/promises"
+import { dirname, join } from "node:path"
+import { fileURLToPath } from "node:url"
+
+const SERVER_NAME = "mrscraper"
+const MCP_URL = "https://mcp.mrscraper.com/mcp"
+const SKILLS_DIR = join(dirname(fileURLToPath(import.meta.url)), "skills")
+
+// OpenCode 1 reads `skills.paths` (see https://opencode.ai/config.json), but the
+// plugin SDK's Config type does not declare it yet.
+type SkillsConfig = { skills?: { paths?: string[]; urls?: string[] } }
+
+// OpenCode 1: add the server and the skills directory through the config hook.
+const server: OpenCode1Plugin = async () => ({
+  async config(input) {
+    input.mcp ??= {}
+    // Keep a user-defined entry, such as the API-key fallback or `enabled: false`.
+    input.mcp[SERVER_NAME] ??= { type: "remote", url: MCP_URL }
+
+    const config = input as typeof input & SkillsConfig
+    config.skills ??= {}
+    config.skills.paths ??= []
+    if (!config.skills.paths.includes(SKILLS_DIR)) config.skills.paths.push(SKILLS_DIR)
+  },
+})
+
+// OpenCode 2: register the same server and skills through domain transforms.
+const definition = {
+  id: "mrscraper",
+  async setup(ctx) {
+    const skills = await readSkills()
+    await ctx.mcp.transform((editor) => {
+      // Keep a user-defined `mcp.servers.mrscraper`, such as the API-key fallback.
+      if (!editor.get(SERVER_NAME)) editor.set(SERVER_NAME, { type: "remote", url: MCP_URL })
+    })
+    await ctx.skill.transform((editor) => {
+      for (const skill of skills) if (!editor.get(skill.id)) editor.add(skill)
+    })
+  },
+} satisfies OpenCode2.Plugin
+
+// Mirrors OpenCode 2's own SKILL.md loading: the folder name is the ID, the
+// frontmatter supplies `name` and `description`, and the body is the content.
+async function readSkills(): Promise<Skill.Info[]> {
+  const skills: Skill.Info[] = []
+  const folders = await readdir(SKILLS_DIR, { withFileTypes: true }).catch(() => [])
+  for (const folder of folders) {
+    if (!folder.isDirectory()) continue
+    const path = join(SKILLS_DIR, folder.name, "SKILL.md")
+    const text = await readFile(path, "utf8").catch(() => undefined)
+    const markdown = text === undefined ? undefined : parseMarkdown(text)
+    if (!markdown) continue
+    const { name, description } = markdown.frontmatter
+    skills.push({
+      id: folder.name as Skill.Info["id"],
+      name: (name || folder.name) as Skill.Info["name"],
+      ...(description ? { description } : {}),
+      path: path as Skill.Info["path"],
+      content: markdown.content,
+    })
+  }
+  return skills
+}
+
+// Reads the flat frontmatter these skills use: plain or quoted scalars and
+// `|` or `>` block scalars. Nested keys are ignored.
+function parseMarkdown(text: string) {
+  const match = /^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n|$)([\s\S]*)$/.exec(text)
+  if (!match) return undefined
+  const frontmatter: Record<string, string> = {}
+  const lines = match[1].split(/\r?\n/)
+  for (let i = 0; i < lines.length; i++) {
+    const field = /^([A-Za-z0-9_-]+):\s*(.*)$/.exec(lines[i])
+    if (!field) continue
+    const [, key, value] = field
+    if (!/^[|>][-+]?$/.test(value)) {
+      frontmatter[key] = value.replace(/^(["'])(.*)\1$/, "$2").trim()
+      continue
+    }
+    const block: string[] = []
+    while (i + 1 < lines.length && (lines[i + 1].trim() === "" || /^\s/.test(lines[i + 1]))) block.push(lines[++i])
+    const indent = Math.min(...block.filter((line) => line.trim()).map((line) => line.length - line.trimStart().length))
+    const literal = block.map((line) => line.slice(indent)).join("\n")
+    frontmatter[key] = (value.startsWith(">") ? literal.replace(/([^\n])\n(?=[^\n])/g, "$1 ") : literal).trim()
+  }
+  return { frontmatter, content: match[2] }
+}
+
+// One default export serves both majors: OpenCode 1 (1.18.29 or later) calls
+// `server()`, and OpenCode 2 reads `id` and `setup()` and ignores `server()`.
+export default { ...definition, server }

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@mrscraper/opencode",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "description": "MrScraper for OpenCode: the hosted MrScraper MCP server plus fetch-first skills for web scraping, structured data extraction, and Google search.",
+  "type": "module",
+  "main": "index.ts",
+  "exports": {
+    ".": "./index.ts"
+  },
+  "files": [
+    "index.ts",
+    "skills",
+    "CHANGELOG.md"
+  ],
+  "keywords": [
+    "opencode",
+    "opencode-plugin",
+    "mrscraper",
+    "web-scraping",
+    "data-extraction",
+    "scraping",
+    "google-search",
+    "serp",
+    "mcp",
+    "research"
+  ],
+  "license": "MIT",
+  "author": {
+    "name": "MrScraper",
+    "email": "support@mrscraper.com",
+    "url": "https://mrscraper.com"
+  },
+  "homepage": "https://github.com/mrscraper-com/mrscraper-opencode-plugin#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mrscraper-com/mrscraper-opencode-plugin.git"
+  },
+  "bugs": {
+    "url": "https://github.com/mrscraper-com/mrscraper-opencode-plugin/issues"
+  },
+  "scripts": {
+    "check": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@opencode-ai/plugin": "1.19.0",
+    "@opencode/plugin": "2.0.26",
+    "@types/node": "^22.20.5",
+    "typescript": "^5.9.3"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/skills/mrscraper/SKILL.md

@@ -0,0 +1,327 @@
+---
+name: mrscraper
+description: |
+  Connect, authenticate, route, and troubleshoot MrScraper MCP, and use saved scrapers, stored results, and account tools. For known public URLs, acquire and preserve raw content with mrscraper-fetch first; use mrscraper-scrape only for explicitly requested or clearly beneficial managed extraction, and mrscraper-serp for query-first discovery.
+---
+
+# MrScraper MCP
+
+Use this skill for connection and authentication checks, tool selection, shared
+response handling, saved reruns, stored results, account status, and
+troubleshooting. Load the focused fetch, scrape, or SERP skill for those
+workflows.
+
+## Step 1 — Verify or Connect MrScraper MCP
+
+Check whether the current client exposes these seven tools from the MrScraper
+MCP provider:
+
+    fetch  scrape  serp  status  rerun  results  result
+
+The client may display server-qualified names. Match the provider and
+unqualified tool name; do not assume a fixed namespace.
+
+If the tools are already available, use the existing connection. If they are
+missing, ask the user to enable the existing MrScraper connection or configure
+the managed Streamable HTTP endpoint:
+
+    https://mcp.mrscraper.com/mcp
+
+A self-managed deployment may expose the same tools over Streamable HTTP or
+stdio. Connection setup belongs to the MCP client. After setup or reconnection,
+list the available tools and confirm all seven names before claiming the
+integration is ready.
+
+## Step 2 — Authenticate
+
+MrScraper MCP authenticates through OAuth 2.1. Authentication belongs to the
+MCP connection and is never a tool argument.
+
+When the connection is not authorized, start the MCP client's authorization
+flow. Let the client discover the authorization metadata, open the MrScraper
+consent page, complete authorization, store the resulting credentials, and
+refresh access tokens. The user may need to approve access in a browser, but
+must not paste an authorization code, access token, refresh token, API key, or
+other credential into the conversation.
+
+Never place credentials in tool arguments, print them, write them into project
+artifacts, or manually reproduce the OAuth exchange. Do not configure an
+API-key or bearer-token fallback from these skills.
+
+Verify end-to-end access with one small fetch:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/"
+    }
+
+A successful page response confirms that the connection can authenticate and
+reach the web-data service. If it fails, report the error and do not claim
+setup is complete.
+
+## Step 3 — Route the Request
+
+| User outcome | MCP tool or skill |
+| --- | --- |
+| Acquire and preserve raw content from known public URLs for any downstream task | [mrscraper-fetch](../mrscraper-fetch/SKILL.md), preferably first |
+| Add managed extraction, repeated records, site mapping, schema guidance, or a reusable scraper | [mrscraper-scrape](../mrscraper-scrape/SKILL.md), normally after or alongside fetch |
+| Discover relevant pages from a Google query | [mrscraper-serp](../mrscraper-serp/SKILL.md), then fetch selected pages |
+| Reproduce a prior scrape or run an existing AI/manual scraper on new URLs | rerun |
+| List or retrieve stored results | results or result |
+| Check account usage or domain request outcomes | status |
+
+### Fetch-first principle
+
+For agent-led work, always use fetch for the first exploration of a known public
+URL. The raw response preserves complete page context for later questions,
+validation, and custom processing. Requesting JSON, a table, or named fields is
+not by itself a reason to use scrape; derive those outputs locally from the raw
+content when practical.
+
+The general and listing scrape modes send page content through a backend LLM.
+Their output is shaped by the extraction prompt and may omit information.
+Applying them across many pages also repeats model work that the agent can often
+replace with one reusable local extractor.
+
+Prefer this workflow for pages with a shared layout:
+
+1. Fetch representative pages and inspect their raw content.
+2. Understand the shared page structure and required fields.
+3. Define a stable output schema and reusable local extractor.
+4. Fetch the remaining pages, in parallel when safe.
+5. Apply the same extractor to every saved response.
+
+For roughly 100 same-layout pages, that means 100 fetches followed by one local
+batch extraction instead of 100 separate backend-LLM extractions. This is often
+faster, preserves every raw input, and allows fields to be recovered later if
+the schema changes.
+
+Use scrape only when the user explicitly requests managed extraction or when it
+still offers a clear benefit after fetch-led exploration. Even then, retain the
+fetched source and verify important values against it. The map agent is separate
+URL-discovery functionality; use it for bounded site mapping, then fetch the
+pages whose content matters.
+
+For discovery-first work, call serp, select relevant URLs, fetch those pages,
+and add managed extraction only when a derived structured view is useful.
+
+## Step 4 — Handle Output and Artifacts
+
+API-backed tools return the same response envelope in MCP structuredContent and
+in a formatted JSON text block:
+
+    {
+      "status_code": 200,
+      "data": {},
+      "headers": {}
+    }
+
+Prefer structuredContent when available. An API failure adds error and sets the
+MCP result's isError flag. An input-contract failure is returned as a tool
+error. Check those signals before trusting data.
+
+Credentials, cookies, and generated curl credentials are sanitized. Extracted
+scraper data is preserved even when it contains fields named token or password
+because those fields may be legitimate source values.
+
+MrScraper tools do not accept output paths. When the user requests an artifact,
+wait for a successful tool result, select the requested value, and save it with
+the environment's local file-writing capability. For scrape, the extracted
+value is normally at structuredContent.data.data.data. Keep the full envelope
+separately only when run metadata, headers, or diagnostics matter.
+
+Save substantial intermediate artifacts under the current project's
+.mrscraper directory unless the user specifies another location. This project
+artifact directory is unrelated to MCP connection credentials. Keep artifacts
+out of version control unless the user asks to commit them.
+
+## Step 5 — Rerun Saved Scrapers
+
+A successful scrape creates a saved AI scraper configuration. Read its UUID
+from structuredContent.data.data.scraperId and use rerun to apply the same
+configuration to the same or another URL. Prefer rerun over rebuilding a prompt
+when the user wants a repeatable version of an earlier extraction.
+
+The scraperId makes the configuration reusable but does not guarantee
+identical extracted values when the source page or model behavior changes.
+
+Choose scraper type and target count independently:
+
+1. Use type=ai for a saved AI scraper created by scrape.
+2. Use type=manual for a saved step-based workflow created in the MrScraper
+   dashboard. MCP can rerun but cannot create manual workflows.
+3. Leave bulk=false for one URL. Set bulk=true for a comma- or
+   newline-separated URL list submitted as one asynchronous job.
+
+| Mode | Required ID input | Target | Crawl controls |
+| --- | --- | --- | --- |
+| Single AI | scraper_id | One URL | Supported |
+| Single manual | scraper_id | One URL | Not accepted |
+| Bulk AI | bulk=true and id | Comma/newline-separated URLs | Not accepted |
+| Bulk manual | bulk=true and id | Comma/newline-separated URLs | Not accepted |
+
+Single AI example:
+
+    {
+      "target": "https://www.scrapethissite.com/pages/simple/",
+      "type": "ai",
+      "scraper_id": "SCRAPER_UUID"
+    }
+
+Single AI optionally accepts max_depth, max_pages, limit, include_patterns,
+exclude_patterns, proxy_country, max_retry, and timeout. Omit any control that
+the user did not request so the saved scraper or backend default remains in
+effect; the MCP server does not inject replacement defaults.
+
+Explicit-control example:
+
+    {
+      "target": "https://www.scrapethissite.com/pages/forms/?page_num=1",
+      "type": "ai",
+      "scraper_id": "SCRAPER_UUID",
+      "proxy_country": "ID",
+      "max_retry": 4,
+      "timeout": 120
+    }
+
+These controls are rejected by manual and bulk reruns.
+
+Bulk example:
+
+    {
+      "target": "https://www.scrapethissite.com/pages/simple/,https://www.scrapethissite.com/pages/forms/?page_num=1",
+      "type": "ai",
+      "bulk": true,
+      "id": "SCRAPER_UUID"
+    }
+
+Manual example, after the user accepts the warning below:
+
+    {
+      "target": "https://www.scrapethissite.com/pages/simple/",
+      "type": "manual",
+      "scraper_id": "SCRAPER_UUID",
+      "acknowledged": true
+    }
+
+Bulk rerun submits one asynchronous backend job. Retain
+structuredContent.data.data.bulkResultId and pass it to result as result_id.
+Inspect that record until it reaches a terminal state when the user asked to
+wait for completion. Do not resubmit the bulk rerun because its result is still
+running.
+
+Before the first rerun call with type=manual in a conversation, show the
+following warning exactly once and wait for the user's acknowledgment. Do not
+call the tool until the user accepts it, and do not repeat the warning on later
+manual reruns in the same conversation. After the user accepts, pass
+acknowledged=true on every manual rerun in that conversation; rerun refuses a
+manual rerun without it and returns this warning instead.
+
+> ### Compliance & Legal Risk
+>
+> WARNING
+>
+> **Scraping login-protected pages carries serious legal and compliance
+> risks.** Many websites explicitly prohibit automated access in their Terms
+> of Service, and bypassing authentication to scrape content may expose you to
+> legal action including lawsuits, account termination, and financial
+> penalties. By proceeding on scraping login-protected pages, you confirm that
+> you have read and understood the target website's Terms of Service, and you
+> **fully accept all legal, financial, and ethical responsibility** for your
+> actions.
+
+## Step 6 — Inspect Stored Results
+
+Use results when the exact result UUID is unknown:
+
+    {
+      "sort_field": "updatedAt",
+      "sort_order": "desc",
+      "page_size": 20,
+      "page": 1
+    }
+
+Apply exact backend filters when the user knows identifying result fields:
+
+    {
+      "scraper_id": "SCRAPER_UUID",
+      "status": "Finished",
+      "type": "Rerun-AI",
+      "url": "https://www.scrapethissite.com/pages/simple/"
+    }
+
+| Input | Default | Use |
+| --- | --- | --- |
+| sort_field | updatedAt | Stored-result sort key. |
+| sort_order | desc | Sort direction: asc or desc. |
+| page_size | 10 | Positive number of records per page. |
+| page | 1 | One-based page number. |
+| search | omitted | Free-text result filter. |
+| date_range_column | omitted | Date column used by start_at and end_at. |
+| start_at | omitted | Inclusive ISO 8601 range start. |
+| end_at | omitted | Inclusive ISO 8601 range end. |
+| scraper_id | omitted | Exact saved scraper UUID filter. |
+| status | omitted | Exact Draft, Finished, Running, Failed, or Cancelled filter. |
+| type | omitted | Exact result type filter, such as AI or Rerun-AI. |
+| url | omitted | Exact stored target URL filter. |
+
+Use result when the UUID is known:
+
+    {
+      "result_id": "RESULT_UUID",
+      "include_html": false
+    }
+
+A result_id may also be the bulkResultId returned by an asynchronous rerun.
+include_html defaults to true. Set it to false for a smaller response while
+polling status or when extracted data is sufficient.
+
+## Step 7 — Review Account Usage
+
+Call status with an empty object for subscription and token usage:
+
+    {}
+
+Add domain request outcomes and a time range only when needed:
+
+    {
+      "domain": "www.scrapethissite.com",
+      "from": "7d",
+      "to": "now"
+    }
+
+| Input | Default | Use |
+| --- | --- | --- |
+| domain | omitted | Add request outcomes for a normalized hostname. |
+| from | 24h | ISO start or relative duration such as 30m, 24h, or 7d. |
+| to | now | ISO end, now, or a relative duration. |
+| action | omitted | Exact request-action filter, used only with domain. |
+| api_token_name | omitted | API-token-name filter, used only with domain. |
+
+Domain outcomes describe MrScraper requests. They are not traffic, audience,
+SEO, or market analytics. status reports account and request health, not
+scrape-job progress; use result for a known asynchronous result ID.
+
+## Step 8 — Troubleshoot
+
+- Missing tools: enable or reconnect the MrScraper MCP connection, then confirm
+  all seven tools are exposed.
+- Unauthorized or expired authorization: reauthorize the OAuth 2.1 connection
+  through the MCP client.
+- Input-contract error: inspect the tool schema and omit inputs that do not
+  apply to the selected mode.
+- Page incomplete or missing dynamic content: load mrscraper-fetch and revise
+  page-loading inputs deliberately.
+- Extraction incomplete: load mrscraper-scrape and improve the prompt, agent,
+  or limits.
+- Search results weak: load mrscraper-serp and refine the query, locale, or
+  page.
+
+## Limits
+
+Use another tool for:
+
+- Clicking controls, completing forms, or authenticated browser sessions.
+- Parsing local PDFs, documents, spreadsheets, or other files.
+- Recurring monitoring, notifications, or scheduling.
+
+Explain the boundary and continue with any supported portion of the task.

package/skills/mrscraper-fetch/SKILL.md

@@ -0,0 +1,213 @@
+---
+name: mrscraper-fetch
+description: |
+  Retrieve raw HTML from a known public URL with MrScraper. Use for reading, inspecting, summarizing, archiving, or analyzing a page, and as the default content-acquisition step before agent-led or local extraction. Supports browser rendering, real-device Super Mode, and page-load controls; use mrscraper-serp when no target URL is known.
+---
+
+# Fetch Page Content with MrScraper MCP
+
+Use the fetch tool supplied by the MrScraper MCP server for the first exploration
+whenever the user already has a public URL. Keep using the raw response for
+summarization, comparison, transformation, and structured output instead of
+handing the page to another LLM by default. Use
+[mrscraper](../mrscraper/SKILL.md) for connection and authentication checks,
+saved runs, account status, or broader routing.
+
+## Page Retrieval Context
+
+fetch calls MrScraper's
+[page-fetching service](https://docs.mrscraper.com/docs/features/unblocker) once.
+Browser rendering executes page JavaScript, locale routing selects a
+geo-specific country, selector waits allow delayed content to appear, and
+homepage navigation establishes a normal navigation path before loading the
+target. Super Mode selects real-device routing independently of browser
+rendering.
+
+Use fetch only for content the user is authorized to access and in accordance
+with the site's requirements. Page-loading controls can help render a site that
+does not work with a basic request.
+
+Start with the URL alone and add only the controls the target needs. Plan-token
+usage is based on runtime and bandwidth: one token per 30 seconds and one token
+per 0.2 MB, rounded up per component. Resource blocking can reduce bandwidth
+for text-focused pages. Retries stop when the request succeeds, max_retries is
+reached, or the running token total reaches token_cap. The initial request
+always runs even when it exceeds that cap. See the
+[Token Plan](https://docs.mrscraper.com/docs/getting-started/api-token) for the
+maintained calculation.
+
+## Step 1 — Define the Outcome
+
+Confirm the target URL and what the user wants:
+
+- Preserve a raw source before extraction, transformation, or comparison.
+- Read, summarize, cite, or inspect the page.
+- Check whether specific text appears.
+- Archive the response.
+- Produce fields, JSON, tables, or other structured output with local logic.
+- Verify or supplement a managed scrape or saved result.
+- Load JavaScript-rendered or geo-sensitive content.
+
+Do not call scrape merely because the requested output is structured. Fetch the
+page, understand its layout, and transform the saved raw content locally. Use
+[mrscraper-scrape](../mrscraper-scrape/SKILL.md) only when the user explicitly
+requests managed extraction, or after fetch-led exploration has produced a
+stable output schema and managed extraction still offers a concrete benefit.
+Use [mrscraper-serp](../mrscraper-serp/SKILL.md) when discovery must happen
+first.
+
+### Prefer reusable local extraction
+
+When many pages share a layout:
+
+1. Fetch representative pages and inspect their raw content.
+2. Define one local extraction schema and implementation.
+3. Fetch the remaining pages, in parallel when safe and proportional.
+4. Apply the same local extractor to every saved response.
+
+For roughly 100 same-layout pages, concurrent fetches followed by one local
+batch extraction are often faster than 100 separate backend-LLM extractions.
+This also preserves every raw input for later recovery or schema changes.
+
+## Step 2 — Run the Fetch
+
+The client may namespace the tool name; select fetch from the MrScraper MCP
+provider. Start with one call containing only the required URL:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/"
+    }
+
+The result is available in MCP structuredContent and as formatted JSON text:
+
+    {
+      "status_code": 200,
+      "data": "<html>...</html>",
+      "headers": {
+        "content-type": "text/html"
+      }
+    }
+
+Prefer structuredContent. Check isError, error, and status_code before using
+data. Non-JSON page bodies are preserved exactly.
+
+## Step 3 — Choose Page-Loading Options
+
+browser_rendering and super_mode are independent axes. All four combinations
+can return different content or failures for the same URL:
+
+| browser_rendering | super_mode | Loading path |
+| --- | --- | --- |
+| false | false | Standard routing with the non-browser loader. |
+| true | false | Standard routing with browser loading and JavaScript. |
+| false | true | Real-device routing with the non-browser loader. |
+| true | true | Real-device routing with browser loading and JavaScript. |
+
+Use browser rendering when the page depends on JavaScript:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/ajax-javascript/#2015",
+      "browser_rendering": true
+    }
+
+Use Super Mode with the non-browser loader when routing may be the problem but
+browser loading is unnecessary or returns a worse response:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/",
+      "super_mode": true
+    }
+
+Use both controls for real-device browser loading:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/ajax-javascript/#2015",
+      "browser_rendering": true,
+      "super_mode": true
+    }
+
+Browser rendering is not a strictly stronger mode. Some sites fail or return
+worse content with browser_rendering=true but load successfully when it is
+false. Super Mode does not enable browser rendering.
+
+Wait for delayed content with a CSS selector:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/ajax-javascript/#2015",
+      "browser_rendering": true,
+      "wait_for_selector": ".film"
+    }
+
+Use geographic routing or homepage navigation when the target requires it:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/",
+      "browser_rendering": true,
+      "geo_code": "ID",
+      "home_page": true
+    }
+
+Use geographic routing for geo-specific content.
+
+Bound resource use for a browser-rendered page:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/ajax-javascript/#2015",
+      "browser_rendering": true,
+      "block_resources": true,
+      "max_retries": 3,
+      "token_cap": 10000,
+      "timeout": 60
+    }
+
+### Parameters
+
+| MCP input | Default | Request mapping | Use |
+| --- | --- | --- | --- |
+| url | required | Query url | Absolute HTTP or HTTPS target URL. |
+| browser_rendering | false | Query browserRendering | Execute page JavaScript. |
+| super_mode | false | Query super | Select real-device routing independently of browser rendering. |
+| geo_code | omitted | Query geoCode | Route through an ISO 3166-1 alpha-2 country. |
+| wait_for_selector | omitted | Query waitForSelector | Wait for a CSS selector; requires browser_rendering=true. |
+| home_page | false | Query homePage | Visit the site root before the target page. |
+| block_resources | false | Query blockResources | Block nonessential resources during loading. |
+| max_retries | 3 | Query maxRetries | Maximum retries after failure; zero disables retries. |
+| token_cap | omitted | Query tokenCap | Retry token budget; the initial request still runs. |
+| timeout | 30 | Query timeout | Page-load timeout in seconds; transport receives another 30 seconds. |
+
+Authentication is handled by the MCP client's OAuth 2.1 connection and is
+never a tool input.
+
+## Step 4 — Inspect and Retry Deliberately
+
+Start with both controls false unless the task already establishes a
+requirement. If the response fails, is blocked, incomplete, or missing dynamic
+content:
+
+1. Inspect the initial response.
+2. Change one axis at a time: browser_rendering for JavaScript, or super_mode
+   when routing may be the problem.
+3. If browser loading fails or returns worse content, retry the same super_mode
+   value with browser_rendering=false.
+4. Try the remaining untested combinations when the response is still unusable.
+5. Add wait_for_selector, geo_code, or home_page only when evidence shows that
+   the target requires it.
+6. Stop after a usable response unless the user requests a comparison.
+
+Do not repeat an identical combination. Treat wait_for_selector as a CSS
+selector, not a duration. Browser rendering loads a page; it does not click
+controls, submit forms, or provide an authenticated interactive browser
+session.
+
+## Step 5 — Deliver the Result
+
+Answer the user's request from data. Keep the full envelope when headers or
+diagnostics matter. When the user requests an archive, save the successful
+response or its data value with the environment's local file-writing
+capability; fetch itself has no output-path input.
+
+Keep fetched content as the source of truth for later steps. Build summaries,
+tables, JSON transformations, and extraction scripts from that raw content. If
+fetch fails and another MrScraper workflow can still complete the task, disclose
+that the raw response was not preserved and do not present the narrower result
+as exhaustive source content.

package/skills/mrscraper-scrape/SKILL.md

@@ -0,0 +1,206 @@
+---
+name: mrscraper-scrape
+description: |
+  Run MrScraper's general, listing, or map agents for managed structured extraction or bounded URL discovery within a known site. Use when managed output is explicitly requested or justified after source-page inspection; use mrscraper-fetch for initial acquisition of known pages and mrscraper-serp when no starting URL is known.
+---
+
+# Extract Structured Data with MrScraper MCP
+
+Do not use scrape for the first exploration of a known page. Start with
+[mrscraper-fetch](../mrscraper-fetch/SKILL.md), inspect the complete raw
+response, and prefer local analysis or a reusable extractor. Use scrape when
+the user explicitly wants MrScraper-managed extraction, or after the agent
+understands the website and has defined a stable output schema. Use
+[mrscraper](../mrscraper/SKILL.md) for connection troubleshooting, saved runs,
+account status, or broader routing.
+
+For general and listing, MrScraper retrieves page HTML and asks a backend LLM to
+interpret it according to prompt. This adds model-processing time, can narrow
+the result to the requested fields, and repeats model work across many pages.
+
+Before using general or listing, confirm all of the following:
+
+1. The target or representative pages have already been fetched and inspected.
+2. The site structure and required output fields are understood.
+3. A stable output schema has been defined.
+4. Managed extraction still offers a concrete benefit over local code, or the
+   user explicitly requested it.
+
+If these conditions are not met, return to fetch. Requiring JSON, a table, or
+named fields is not by itself a reason to call scrape. For large same-layout
+sets—even roughly 100 pages—safe concurrent fetches plus one reusable local
+extractor are often faster and preserve every raw response. The map agent is
+separate URL discovery functionality and does not require an extraction schema.
+
+## Step 1 — Choose an Agent
+
+| Agent | Use it for | Required input | Available controls |
+| --- | --- | --- | --- |
+| general | One detail page or one extraction task | prompt | proxy_country, schema_prompt |
+| listing | Repeated records or paginated listings | prompt | proxy_country, max_pages, schema_prompt |
+| map | Discovering URLs across a site | URL only | max_depth, max_pages, limit, include_patterns, exclude_patterns |
+
+The default agent is general. For map, omit prompt, schema_prompt, and
+proxy_country. For general and listing, omit map-only controls. max_pages is
+accepted by listing and map but not general.
+
+agent selects the extraction workflow. mode independently selects the backend
+execution tier: Cheap or Super. Omit mode to preserve the backend default, and
+select Super only when the extraction requires the stronger mode.
+
+## Step 2 — Define the Extraction
+
+The examples below assume the decision gate above has been satisfied. Write a
+prompt from the already-understood page structure and output schema, preserve
+source values, and do not ask the model to infer unavailable values.
+
+Detail-page example:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/",
+      "agent": "general",
+      "mode": "Super",
+      "prompt": "Extract each country's name, capital, population, and area. Preserve source values and omit unavailable fields."
+    }
+
+Repeated-listing example:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/forms/?page_num=1",
+      "agent": "listing",
+      "prompt": "Extract each hockey team's name, year, wins, losses, and win percentage.",
+      "max_pages": 5
+    }
+
+Site-map example:
+
+    {
+      "url": "https://www.scrapethissite.com/",
+      "agent": "map",
+      "max_depth": 2,
+      "max_pages": 50,
+      "limit": 1000,
+      "include_patterns": "/pages/"
+    }
+
+## Step 3 — Add Shape Guidance When Useful
+
+schema_prompt accepts a JSON object, not a file path. If the user supplies a
+local JSON Schema file, read and parse it with local file tools, confirm its
+root is an object, and pass that object:
+
+    {
+      "url": "https://www.scrapethissite.com/pages/simple/",
+      "agent": "general",
+      "prompt": "Extract every country's name, capital, population, and area.",
+      "schema_prompt": {
+        "type": "object",
+        "properties": {
+          "countries": {
+            "type": "array",
+            "items": {
+              "type": "object",
+              "properties": {
+                "name": { "type": "string" },
+                "capital": { "type": "string" },
+                "population": { "type": "string" },
+                "area": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+
+The MCP server appends this object to the extraction prompt as best-effort
+shape guidance. It does not validate the returned data against the schema.
+Validate locally when strict compliance is required.
+
+## Step 4 — Set Parameters
+
+| MCP input | Default | Request mapping | Use |
+| --- | --- | --- | --- |
+| url | required | Body url | Absolute HTTP or HTTPS starting URL. |
+| agent | general | Body agent | Select general, listing, or map. |
+| mode | service default | Body mode | Select Cheap or Super execution without changing the agent. |
+| prompt | required for general/listing | Body message | Describe the fields or records to extract. |
+| proxy_country | omitted | Body proxyCountry | Route general/listing through a country. |
+| max_pages | service default | Body maxPages | Bound listing or map pages. |
+| max_depth | service default | Body maxDepth | Bound map crawl depth. |
+| limit | service default | Body limit | Bound map URL results. |
+| include_patterns | omitted | Body includePatterns | Restrict map results to matching URLs. |
+| exclude_patterns | omitted | Body excludePatterns | Exclude matching map URLs. |
+| schema_prompt | omitted | Appended to message | JSON Schema object for general/listing guidance. |
+
+Authentication is handled by the MCP client's OAuth 2.1 connection. The scrape
+tool does not accept a credential or output-path input. Choose the smallest
+practical limits and omit optional values when the service default is
+appropriate.
+
+## Step 5 — Wait for Completion
+
+General and map usually finish quickly. Listing is synchronous and can take
+several minutes even for one page.
+
+Before starting a listing call, tell the user it may take several minutes. Keep
+waiting on the original MCP call within the environment's supported tool
+timeout. Do not submit a duplicate scrape because the first call is quiet or
+still running.
+
+## Step 6 — Use the Output
+
+The complete API envelope is returned in MCP structuredContent and as formatted
+JSON text. Prefer structuredContent and check isError, error, and status_code
+before trusting the response.
+
+A successful run normally stores its extracted value at:
+
+    structuredContent.data.data.data
+
+The saved scraper UUID is normally at:
+
+    structuredContent.data.data.scraperId
+
+When the user asks for a file, save the extracted value only after the tool
+succeeds. Use local file-writing capability and report the path. Preserve the
+full envelope separately when the scraper ID, response headers, or diagnostics
+also matter.
+
+Post-process only when the user requests filtering, merging, normalization,
+CSV, a table, or another deliverable. Extracted fields named token or password
+may be legitimate source data and are intentionally preserved.
+
+## Step 7 — Preserve the Reproducible Scraper
+
+Every successful scrape creates a saved AI scraper configuration by default.
+Report scraperId when it is available and the extraction may need to run again.
+
+Use the MrScraper rerun tool to apply the saved configuration to the same or
+another URL:
+
+    {
+      "target": "https://www.scrapethissite.com/pages/forms/?page_num=2",
+      "type": "ai",
+      "scraper_id": "SCRAPER_UUID"
+    }
+
+Prefer rerun over recreating the scrape definition when the user wants a
+repeatable extraction. Explain that this reproduces the saved configuration,
+not necessarily identical values when the page or model behavior changes.
+
+The rerun tool also handles dashboard-built manual workflows and asynchronous
+bulk jobs. Follow the full rerun workflow in
+[mrscraper](../mrscraper/SKILL.md), including the required acknowledgment
+before any manual rerun.
+
+## Step 8 — Handle Failures
+
+- Check isError, error, and status_code before using or saving output.
+- Tighten the prompt when fields are missing or grouped incorrectly.
+- Confirm the selected agent accepts every supplied input.
+- Validate locally when downstream code requires a strict schema.
+- Use [mrscraper-fetch](../mrscraper-fetch/SKILL.md) for page reading.
+- Use [mrscraper-serp](../mrscraper-serp/SKILL.md) when discovery must happen
+  first.
+- Never invent replacement fields or fill missing values with unsupported
+  assumptions.

package/skills/mrscraper-serp/SKILL.md

@@ -0,0 +1,123 @@
+---
+name: mrscraper-serp
+description: |
+  Discover public pages through Google with MrScraper using a search query or Google search URL. Use when no target URL is known or the user asks to inspect Google results. After discovery, preserve selected pages with mrscraper-fetch before adding managed extraction through mrscraper-scrape.
+---
+
+# Discover Pages with MrScraper MCP SERP
+
+Use the serp tool supplied by the MrScraper MCP server when a task begins with
+a search query rather than a known target URL. Use
+[mrscraper](../mrscraper/SKILL.md) for connection troubleshooting, saved runs,
+account status, or broader routing.
+
+## Step 1 — Build the Query
+
+Include the important entity, attribute, location, or date in query_or_url:
+
+    {
+      "query_or_url": "web scraping best practices"
+    }
+
+The input can also be a complete Google search URL:
+
+    {
+      "query_or_url": "https://www.google.com/search?q=web+scraping&gl=us&hl=en&start=20"
+    }
+
+For a Google URL, the tool reads q, gl, hl, and start. Explicit region,
+language, and page inputs take precedence.
+
+## Step 2 — Set Locale and Pagination
+
+Set both country and language when results must match a locale:
+
+    {
+      "query_or_url": "running shoes",
+      "region": "id",
+      "language": "id",
+      "page": 2
+    }
+
+Start with the first page unless the user requests broader coverage. Inspect
+the current page before requesting another.
+
+## Step 3 — Choose the Output
+
+Parsed JSON is the default and is suitable for selecting titles, URLs, and
+snippets:
+
+    {
+      "query_or_url": "iphone 17",
+      "format": "json"
+    }
+
+Request result-page HTML when the page itself is needed:
+
+    {
+      "query_or_url": "iphone 17",
+      "format": "html"
+    }
+
+Use JavaScript rendering for dynamic result features such as AI Overview:
+
+    {
+      "query_or_url": "what is web scraping",
+      "render_js": true
+    }
+
+### Parameters
+
+| MCP input | Default | Request mapping | Use |
+| --- | --- | --- | --- |
+| query_or_url | required | Body query | Search query or complete Google search URL. |
+| region | URL value or omitted | Body region | Google result country, such as us or id. |
+| language | URL value or omitted | Body language | Google result language, such as en or id. |
+| page | URL value or omitted | Body page | Positive, one-based results page. |
+| format | json | Body format | Return parsed JSON or result-page HTML. |
+| render_js | false | Body renderJs | Wait for JavaScript-rendered result features. |
+| raw | false | Body format=html | Deprecated compatibility alias; prefer format=html. |
+| client_timeout | 120 | MCP upstream deadline | Maximum wait in seconds; not sent in the SERP body. |
+
+Authentication is handled by the MCP client's OAuth 2.1 connection and is
+never a tool input.
+
+## Step 4 — Inspect the Results
+
+The complete response envelope is available in MCP structuredContent and as
+formatted JSON text. Prefer structuredContent. Check isError, error, and
+status_code before using data.
+
+For format=json, inspect data for the available titles, URLs, snippets, and
+other result fields. For format=html, data contains result-page HTML.
+
+When the user requests a search artifact, save the successful data or full
+envelope with local file-writing capability; serp has no output-path input.
+
+## Step 5 — Continue with Relevant URLs
+
+Select only URLs relevant to the user's goal, then:
+
+- Load [mrscraper-fetch](../mrscraper-fetch/SKILL.md) to preserve and inspect
+  each selected page before deriving answers, comparisons, or structured output.
+- Add [mrscraper-scrape](../mrscraper-scrape/SKILL.md) only when the user
+  explicitly requests managed extraction or it still offers a clear benefit
+  after the page structure and output schema are understood.
+
+Run independent follow-up URLs in parallel when the environment supports safe
+parallel execution. Keep the number of pages proportional to the requested
+coverage.
+
+## Step 6 — Handle Weak or Missing Results
+
+- Set both region and language when the locale is wrong.
+- Rewrite noisy queries around the important entity, attribute, and location.
+- Request another result page only after checking the current page.
+- Retry once with render_js=true when a dynamic result feature is required.
+- Increase client_timeout when the MCP request deadline is too short.
+- Use [mrscraper](../mrscraper/SKILL.md) when the connection or authentication
+  fails.
+
+SERP is for public Google discovery. Use the map agent in
+[mrscraper-scrape](../mrscraper-scrape/SKILL.md) to discover URLs within one
+known site.