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..9646543 --- /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: fetch any public page as Markdown, HTML or text, pull structured fields from it as JSON, run batch jobs over many URLs, crawl a site from one start URL and drive a hosted browser for pages that need clicks, forms or pagination, with proxies, JavaScript rendering and anti-bot protection handled by Zenrows.", + "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..adb6fb4 --- /dev/null +++ b/dist/claude/README.md @@ -0,0 +1,53 @@ +# Zenrows for Claude + +Live web data: fetch any public page as Markdown, HTML or text, pull structured fields from it as JSON, run batch jobs over many URLs, crawl a site from one start URL and drive a hosted browser for pages that need clicks, forms or pagination, with proxies, JavaScript rendering and anti-bot protection handled by Zenrows. This plugin connects Claude to the Zenrows MCP server and 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. +- 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](https://docs.zenrows.com) +- MCP server documentation: [docs.zenrows.com/mcp/overview](https://docs.zenrows.com/mcp/overview) +- 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 0000000..a32dc12 Binary files /dev/null and b/dist/claude/assets/logo.png differ 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 `