From 9f4ac8988a0857162a8d2f94d763e8f8a109ef3b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?In=C3=AAs=20Moital?= Date: Mon, 2 Nov 2026 17:23:15 +0000 Subject: [PATCH 1/4] feat(claude): plugin for Claude in the shared skills layout Moves claude-zenrows (v0.1.6) into platforms/claude: the Claude names, the "Zenrows connector" wording and the sign-in steps become vars and the getting-started slot, so no skill is overridden. Claude now gets the shared skill text Copilot already has: the user-precedence line, account_usage, the no-payment rule and the newer AUTH004/AUTH014 wording. Adds the top-level .claude-plugin/marketplace.json catalog pointing at dist/claude and a release-please package starting at 0.1.6. Contact email is integrations@zenrows.com. --- .claude-plugin/marketplace.json | 19 ++++ .release-please-manifest.json | 3 +- README.md | 1 + dist/claude/.claude-plugin/plugin.json | 21 ++++ dist/claude/.mcp.json | 8 ++ dist/claude/LICENSE | 21 ++++ dist/claude/README.md | 52 ++++++++++ dist/claude/assets/logo.png | Bin 0 -> 4959 bytes dist/claude/skills/batch/SKILL.md | 45 +++++++++ .../claude/skills/browser-automation/SKILL.md | 60 +++++++++++ dist/claude/skills/capture-api-calls/SKILL.md | 35 +++++++ dist/claude/skills/crawl/SKILL.md | 30 ++++++ .../skills/extract-structured-data/SKILL.md | 44 ++++++++ dist/claude/skills/getting-started/SKILL.md | 40 ++++++++ dist/claude/skills/map/SKILL.md | 22 ++++ dist/claude/skills/scrape-webpage/SKILL.md | 17 ++++ dist/claude/skills/using-zenrows/SKILL.md | 95 ++++++++++++++++++ platforms/claude/.claude-plugin/plugin.json | 21 ++++ platforms/claude/.mcp.json | 8 ++ platforms/claude/README.md | 52 ++++++++++ .../claude/skills/getting-started/connect.md | 3 + platforms/claude/vars.yaml | 18 ++++ release-please-config.json | 21 ++++ 23 files changed, 635 insertions(+), 1 deletion(-) create mode 100644 .claude-plugin/marketplace.json create mode 100644 dist/claude/.claude-plugin/plugin.json create mode 100644 dist/claude/.mcp.json create mode 100644 dist/claude/LICENSE create mode 100644 dist/claude/README.md create mode 100644 dist/claude/assets/logo.png create mode 100644 dist/claude/skills/batch/SKILL.md create mode 100644 dist/claude/skills/browser-automation/SKILL.md create mode 100644 dist/claude/skills/capture-api-calls/SKILL.md create mode 100644 dist/claude/skills/crawl/SKILL.md create mode 100644 dist/claude/skills/extract-structured-data/SKILL.md create mode 100644 dist/claude/skills/getting-started/SKILL.md create mode 100644 dist/claude/skills/map/SKILL.md create mode 100644 dist/claude/skills/scrape-webpage/SKILL.md create mode 100644 dist/claude/skills/using-zenrows/SKILL.md create mode 100644 platforms/claude/.claude-plugin/plugin.json create mode 100644 platforms/claude/.mcp.json create mode 100644 platforms/claude/README.md create mode 100644 platforms/claude/skills/getting-started/connect.md create mode 100644 platforms/claude/vars.yaml diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json new file mode 100644 index 0000000..07cedfc --- /dev/null +++ b/.claude-plugin/marketplace.json @@ -0,0 +1,19 @@ +{ + "name": "zenrows", + "owner": { + "name": "Zenrows", + "email": "integrations@zenrows.com" + }, + "metadata": { + "description": "Zenrows for Claude: live web data through the Zenrows MCP server.", + "version": "0.1.6" + }, + "plugins": [ + { + "name": "zenrows", + "description": "Live web data for Claude: fetch pages, extract structured data, crawl sites, run batch jobs and drive hosted browser sessions through the Zenrows MCP server.", + "version": "0.1.6", + "source": "./dist/claude" + } + ] +} diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a9ceb4..948fa62 100644 --- a/.release-please-manifest.json +++ b/.release-please-manifest.json @@ -1,3 +1,4 @@ { - "dist/copilot": "0.1.1" + "dist/copilot": "0.1.1", + "dist/claude": "0.1.6" } diff --git a/README.md b/README.md index 93c61ef..649e4de 100644 --- a/README.md +++ b/README.md @@ -9,6 +9,7 @@ Each host's guide covers installing the plugin and signing in to Zenrows. You si | Host | Setup guide | |---|---| +| Claude | [dist/claude/README.md](dist/claude/README.md) | | GitHub Copilot | [dist/copilot/README.md](dist/copilot/README.md) | diff --git a/dist/claude/.claude-plugin/plugin.json b/dist/claude/.claude-plugin/plugin.json new file mode 100644 index 0000000..4617e99 --- /dev/null +++ b/dist/claude/.claude-plugin/plugin.json @@ -0,0 +1,21 @@ +{ + "name": "zenrows", + "displayName": "Zenrows", + "version": "0.1.6", + "description": "Live web data for Claude: fetch pages, extract structured data, crawl sites, run batch jobs and drive hosted browser sessions through the Zenrows MCP server.", + "author": { + "name": "Zenrows", + "email": "integrations@zenrows.com", + "url": "https://www.zenrows.com" + }, + "homepage": "https://docs.zenrows.com", + "documentationUrl": "https://docs.zenrows.com/integrations/claude", + "supportUrl": "https://www.zenrows.com/contact", + "privacyPolicyUrl": "https://www.zenrows.com/legal/privacy", + "termsOfServiceUrl": "https://www.zenrows.com/legal/terms", + "repository": "https://github.com/ZenRows/zenrows-integrations", + "license": "MIT", + "keywords": ["web-scraping", "data-extraction", "browser-automation", "mcp", "zenrows"], + "icon": "./assets/logo.png", + "mcpServers": "./.mcp.json" +} diff --git a/dist/claude/.mcp.json b/dist/claude/.mcp.json new file mode 100644 index 0000000..2fe7242 --- /dev/null +++ b/dist/claude/.mcp.json @@ -0,0 +1,8 @@ +{ + "mcpServers": { + "zenrows": { + "type": "http", + "url": "https://mcp.zenrows.com/mcp" + } + } +} diff --git a/dist/claude/LICENSE b/dist/claude/LICENSE new file mode 100644 index 0000000..e7dd33a --- /dev/null +++ b/dist/claude/LICENSE @@ -0,0 +1,21 @@ +MIT License + +Copyright (c) 2026 Zenrows + +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. diff --git a/dist/claude/README.md b/dist/claude/README.md new file mode 100644 index 0000000..58d45bb --- /dev/null +++ b/dist/claude/README.md @@ -0,0 +1,52 @@ +# Zenrows for Claude + +Live web data for Claude. This plugin connects Claude to the Zenrows MCP server, so Claude can fetch the current content of any public page, pull structured fields from it, crawl a site from one start URL, run batch jobs over many URLs, and drive a hosted browser for pages that need clicks, forms or pagination. It also adds skills that tell Claude which Zenrows tool fits each task and how to keep requests efficient. + +## What you get + +- The Zenrows MCP server (`https://mcp.zenrows.com/mcp`). You sign in to your Zenrows account with OAuth; there is no API key to copy. +- Nine skills: + +| Skill | Use it for | +|---|---| +| `using-zenrows` | Overview: tools, defaults, errors and plan limits | +| `getting-started` | First-run checks and troubleshooting | +| `scrape-webpage` | Reading one page | +| `extract-structured-data` | Named fields or JSON from one page | +| `batch` | A list of five or more URLs as one job | +| `crawl` | Many pages under one site section | +| `map` | Listing a site's URLs without fetching them | +| `browser-automation` | Clicks, forms, pagination and multi-step flows | +| `capture-api-calls` | Finding the API calls a page makes | + +## Requirements + +A Zenrows account. Requests use credits on your Zenrows plan. You can [sign up here](https://app.zenrows.com/register). + +## Setup + +Install the plugin. In Claude Code: + +``` +/plugin install zenrows --marketplace ZenRows/zenrows-integrations +``` + +Then sign in to Zenrows when Claude asks you to connect: + +- **Claude (web or desktop):** Customize → Connectors → Zenrows → Connect. +- **Claude Code:** run `/mcp`, select `zenrows` and authenticate. + +Then ask Claude something like: "Use Zenrows to get the product names and prices from https://www.scrapingcourse.com/ecommerce/". + +## Privacy + +The plugin sends the URLs and options you ask Claude to fetch to Zenrows, which processes them under the [Zenrows privacy policy](https://www.zenrows.com/legal/privacy). + +## Support + +- Documentation: [docs.zenrows.com/integrations/claude](https://docs.zenrows.com/integrations/claude) +- Contact: [integrations@zenrows.com](mailto:integrations@zenrows.com) + +## License + +MIT diff --git a/dist/claude/assets/logo.png b/dist/claude/assets/logo.png new file mode 100644 index 0000000000000000000000000000000000000000..a32dc121e6d08ae56c36b82382e4671ae5cc7233 GIT binary patch literal 4959 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 R^YTU*3sdV0^(LNC{|k;`(4+tW literal 0 HcmV?d00001 diff --git a/dist/claude/skills/batch/SKILL.md b/dist/claude/skills/batch/SKILL.md new file mode 100644 index 0000000..5b398d5 --- /dev/null +++ b/dist/claude/skills/batch/SKILL.md @@ -0,0 +1,45 @@ +--- +name: batch +description: Fetch a list of URLs the user already has as one managed Zenrows job, with retries and per-task results. Use when the user supplies or points at roughly five or more URLs (a file, a pasted list, the output of map) and wants their content or extracted fields. Not for discovering URLs by following links (use crawl), not for listing a site's URLs (use map), and not for a single page (use scrape-webpage). +--- + +# Batch + +The user's instructions take precedence over this skill. If they conflict, follow the user. + +Zenrows Batch queues many URLs as one server-side job, retries transient failures, and stores the results. + +## When to use this instead of `scrape` + +Use batch at roughly five URLs or more. Below that, parallel `scrape` calls are faster and simpler, since a job costs a create, a wait and a results fetch. Above it, batch wins: one job instead of N round trips, server-side retries, and no plan-concurrency 429s (the Developer plan allows 5 concurrent requests). + +## Instructions + +1. Confirm the URL list and its size with the user before submitting. A batch bills per URL, so an unintended 5,000-URL job is expensive. +2. Submit the job: + - Same options for every URL: `batch_create(urls=[...], response_type='markdown')`. + - Different options per URL, or you need ids echoed back: `batch_create(tasks=[{url, external_id, metadata, zenrows_params}, ...])`. + - `urls` is ignored when `tasks` is provided. Do not pass both. +3. Wait for completion: + - Small jobs: pass `wait=true` to `batch_create` and get a terminal state in one call. + - Larger jobs: let `batch_create` return, then call `batch_wait(job_id)`. Default timeout is 600000 ms; raise `timeout_ms` (max 3600000) for big jobs. + - Report progress from `batch_status(job_id)` if the user asks mid-job. +4. Collect results with `batch_results(job_id)`. Use `status='successful'` or `status='failed'` to split them when reporting. +5. If you can write files (for example in Claude Code), save results to `./.zenrows/batch-.jsonl`, one JSON object per line, and summarize instead of reading the whole file back. Otherwise, summarize the results directly. +6. If the user stops the task, call `batch_cancel(job_id)`. The job keeps consuming credits until cancelled. + +## Options + +| Need | Where | Note | +|------|-------|------| +| Same settings for all URLs | job level: `js_render`, `premium_proxy`, `proxy_country`, `response_type` | Simplest form | +| Different settings per URL | `tasks[].zenrows_params` | Accepts `js_render`, `premium_proxy`, `extract`, `autoparse`, and other scrape params | +| Structured fields, not page content | `tasks[].zenrows_params` with `extract` or `autoparse` | Batch and Extract compose | +| Track which result is which | `tasks[].external_id` and `tasks[].metadata` | Echoed back on results | +| Geo-restricted pages | `proxy_country` | Works with the default settings | + +## Notes + +- `batch_create` has no required field, but a job with neither `tasks` nor `urls` does nothing. Always supply one. +- Always report the failed count alongside the successful one. Batch retries transient failures itself, so a URL in the failed set has genuinely not worked. +- `browser_batch` is unrelated: it batches actions inside one browser session. It is not this. diff --git a/dist/claude/skills/browser-automation/SKILL.md b/dist/claude/skills/browser-automation/SKILL.md new file mode 100644 index 0000000..34d815f --- /dev/null +++ b/dist/claude/skills/browser-automation/SKILL.md @@ -0,0 +1,60 @@ +--- +name: browser-automation +description: 'Drive a page through steps before its content is available: clicking, filling forms, logging in, paginating, or multi-step navigation that a single fetch cannot do. Use when interaction is required to reach the content. Not for static page reads (use scrape-webpage), and not for passively listing the network or API calls a page makes (use capture-api-calls).' +--- + +# Browser automation + +The user's instructions take precedence over this skill. If they conflict, follow the user. + +## Instructions + +1. Open a session with `browser_navigate(url)`. Save the returned `session_id` and pass it to every later call. +2. Find the selectors you need with `browser_get_accessibility_tree` or `browser_query_selector_all`. Both are cheaper and more precise than a screenshot. Take `browser_screenshot` only when the page state is unclear or the user asked to see it. +3. Run the interaction as one `browser_batch` call whenever the steps are known in advance. Every round trip to the hosted browser costs seconds; a login sent as six separate calls is six times slower than it needs to be. +4. Fall back to individual `browser_*` calls only when a later step depends on reading an earlier result. +5. Always call `browser_close(session_id)` when done, to free a concurrency slot. + +## browser_batch + +`browser_batch(session_id, actions, stop_on_error)` runs 1 to 50 ordered actions in one call, reads included. A login and its result: + +```json +{ + "session_id": "", + "actions": [ + { "type": "wait_for_selector", "selector": "#email" }, + { "type": "fill", "selector": "#email", "value": "user@example.com" }, + { "type": "fill", "selector": "#password", "value": "secret" }, + { "type": "click", "selector": "button[type=submit]" }, + { "type": "wait_for_navigation" }, + { "type": "get_text" } + ] +} +``` + +Action names inside `actions` drop the `browser_` prefix: `navigate`, `go_back`, `go_forward`, `reload`, `click`, `hover`, `type`, `fill`, `select`, `check`, `uncheck`, `focus`, `press_key`, `scroll`, `drag`, `wait`, `wait_for_selector`, `wait_for_navigation`, `evaluate`, `screenshot`, `get_text`, `get_html`, `get_url`, `get_title`, `get_attribute`, `get_accessibility_tree`, `query_selector_all`. + +Three traps: + +- The action is `select`, not `select_option`. +- `fill` takes `value`. `type` takes `text`. +- `stop_on_error` defaults to `true`, so one bad selector halts the rest of the list. Set it to `false` only when the later actions do not depend on the earlier ones. + +`browser_batch` batches actions inside one browser session. It is unrelated to the Batch product and its `batch_*` tools. + +## Session management + +- Pass `session_id` to every subsequent `browser_*` call. +- Do not open multiple sessions unless the task requires it. +- Browser sessions hold concurrency slots on the user's plan. Close them promptly. +- Geo-targeting is set when the session is created. Pass `proxy_country` (ISO 3166-1 alpha-2, for example `de`) or `proxy_region` (`eu`, `na`, `ap`, `sa`, `af`, `me`) to `browser_navigate`. Later `browser_*` calls do not accept either, so set it on the first call or start a new session. + +## When to prefer browser over scrape + +| Scenario | Tool | +|----------|------| +| Read a static docs page | `scrape` | +| Log in, then navigate | `browser_*` | +| Click "Load more" pagination | `browser_*` | +| Fill a search form and read results | `browser_*` | diff --git a/dist/claude/skills/capture-api-calls/SKILL.md b/dist/claude/skills/capture-api-calls/SKILL.md new file mode 100644 index 0000000..2b0aa56 --- /dev/null +++ b/dist/claude/skills/capture-api-calls/SKILL.md @@ -0,0 +1,35 @@ +--- +name: capture-api-calls +description: Discover the background API or XHR endpoints a page calls, or reverse-engineer how it loads its data. Use when the user wants the underlying request a site makes, not the rendered page. Not for interacting with the page UI (use browser-automation), and not for reading rendered content (use scrape-webpage). +--- + +# Capture API calls + +The user's instructions take precedence over this skill. If they conflict, follow the user. + +## Instructions + +1. Open a session with `browser_navigate(url)` and save the `session_id`. +2. Let the page finish loading: `browser_wait(session_id, ms=3000)`. Do not use `browser_wait_for_navigation` here; that must run before a navigation-triggering action, not after `browser_navigate`. +3. Collect network resource URLs with `browser_evaluate`: + + ```javascript + JSON.stringify( + performance.getEntriesByType('resource') + .filter(r => r.initiatorType === 'fetch' || r.initiatorType === 'xmlhttprequest' || r.name.includes('/api/')) + .map(r => ({ url: r.name, type: r.initiatorType })) + ) + ``` + +4. Identify the endpoint(s) most likely returning the target data (JSON paths, `/api/` URLs, GraphQL endpoints). +5. Present the endpoint URL, the method if inferable, and a sample response shape. +6. Optionally call the endpoint directly with `scrape(url=, response_type='html')` to get the raw response body. +7. Always call `browser_close(session_id)` when done. + +## Fallback + +If `performance.getEntriesByType` returns nothing (a single-page app with deferred loads), interact with the page (scroll, click load triggers) and re-run the evaluate script, or inspect inline `