diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a9ceb4..a0d8bcd 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/cursor": "0.2.2" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e0bb28..776c0b0 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -82,7 +82,7 @@ Each host is its own release-please package (`dist/`), with its own versio ### Mirror repos -Some installs name a repo of their own instead of a folder here: `copilot plugin marketplace add ZenRows/copilot-zenrows` reads that repo's root. Such a repo is a mirror: `mirror: ZenRows/copilot-zenrows` in the host's `vars.yaml` makes each release of the host replace the mirror's contents with `dist//`, plus the host's marketplace catalogs at the same paths, listing only that host with `source` set to `./` (the mirror's root), and a banner in its README pointing here. So the catalog is edited in one place, and `npm run validate` fails if a mirrored host has none. Nobody edits a mirror by hand; only its deploy key can push to it. +Some installs name a repo of their own instead of a folder here: `copilot plugin marketplace add ZenRows/copilot-zenrows` reads that repo's root, and so do the Cursor Marketplace and ClawHub. Such a repo is a mirror: `mirror: ZenRows/copilot-zenrows` in the host's `vars.yaml` makes each release of the host replace the mirror's contents with `dist//`, plus a banner in its README pointing here. If the host has marketplace catalogs, the mirror gets them at the same paths, listing only that host with `source` set to `./` (the mirror's root), so the catalog is edited in one place. A host that reads its plugin from the repo root, like Cursor or OpenClaw, needs no catalog. Nobody edits a mirror by hand; only its deploy key can push to it. - The release workflow runs `.github/workflows/mirror.yml` for each released host. It makes one normal commit (`release copilot-v0.1.2 from ZenRows/zenrows-integrations@`), never a force-push, and tags the mirror `v`. No commit is made when nothing changed, so a re-run is safe. - It pushes with the deploy key in the `MIRROR_KEY_` secret of the `release` environment. The key, the mirror's branch protection and its settings are in [iac-bootstrap](https://github.com/ZenRows/iac-bootstrap). diff --git a/README.md b/README.md index 93c61ef..1a00553 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 | |---|---| +| Cursor | [dist/cursor/README.md](dist/cursor/README.md) | | GitHub Copilot | [dist/copilot/README.md](dist/copilot/README.md) | diff --git a/dist/cursor/.cursor-plugin/plugin.json b/dist/cursor/.cursor-plugin/plugin.json new file mode 100644 index 0000000..fc0973d --- /dev/null +++ b/dist/cursor/.cursor-plugin/plugin.json @@ -0,0 +1,30 @@ +{ + "name": "zenrows", + "displayName": "Zenrows", + "version": "0.2.2", + "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" + }, + "homepage": "https://www.zenrows.com", + "repository": "https://github.com/ZenRows/zenrows-integrations", + "license": "MIT", + "keywords": [ + "web-scraping", + "crawler", + "site-map", + "browser-automation", + "data-extraction", + "anti-bot", + "mcp", + "scraping-api", + "zenrows" + ], + "category": "data-and-analytics", + "tags": ["web-scraping", "crawling", "browser-automation", "mcp"], + "logo": "assets/logo.png", + "skills": "skills", + "commands": "commands", + "mcpServers": "mcp.json" +} diff --git a/dist/cursor/LICENSE b/dist/cursor/LICENSE new file mode 100644 index 0000000..e7dd33a --- /dev/null +++ b/dist/cursor/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/cursor/README.md b/dist/cursor/README.md new file mode 100644 index 0000000..9cff80f --- /dev/null +++ b/dist/cursor/README.md @@ -0,0 +1,67 @@ +# Zenrows for Cursor + +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 Cursor to the Zenrows MCP server and adds skills that tell Cursor 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 + +### 1. Install the plugin + +Install Zenrows from the Cursor Marketplace. + +### 2. Authorize + +The plugin adds the hosted Zenrows MCP server. After installing, open Settings, Tools and MCP, find the `zenrows` server, click “Connect”, and complete the Zenrows authorization in your browser. Cursor stores and refreshes the token for you. + +### 3. Verify + +Run `/zenrows-doctor` in a chat to confirm the connection is live and authorized, or just ask the agent “fetch https://httpbin.io/get” and watch it scrape. If the connection looks stuck, open the command palette (Cmd+Shift+P), run “Cursor: Clear All MCP Tokens”, restart Cursor, and re-authorize. + +## Usage examples + +| Prompt | What the agent does | +|--------|---------------------| +| Fetch the OpenAI streaming docs and tell me how to stream responses. | Scrapes the page and summarizes the streaming section. | +| Scrape competitor.com/pricing and compare it to ours. | Scrapes and parses the pricing into a comparison. | +| Get all the product links from shop.example.com/phones. | Extracts links from the page. | +| Map the URLs on docs.example.com. | Lists the site's URLs from its sitemap. | +| Crawl all the pages under example.com/guide. | Follows internal links and collects each page. | +| Extract every email address from dir.example.com. | Returns a deduplicated email list. | +| Log into this site, open the first result, and give me its content. | Runs a browser session through the steps. | +| What internal API does this page use to load its data? | Inspects the page's network calls and surfaces the endpoint. | + +The plugin also adds `/zenrows-doctor`, which checks that the Zenrows connection is live and authorized. + +## Privacy + +The plugin sends the URLs and options you ask Cursor 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/cursor/assets/logo.png b/dist/cursor/assets/logo.png new file mode 100644 index 0000000..a32dc12 Binary files /dev/null and b/dist/cursor/assets/logo.png differ diff --git a/dist/cursor/commands/zenrows-doctor.md b/dist/cursor/commands/zenrows-doctor.md new file mode 100644 index 0000000..b53e5df --- /dev/null +++ b/dist/cursor/commands/zenrows-doctor.md @@ -0,0 +1,16 @@ +--- +name: zenrows-doctor +description: Check that the Zenrows MCP connection is live and authorized, and confirm scraping works. +--- + +# /zenrows-doctor + +Report whether Zenrows is connected, authorized, and able to scrape. Steps: + +1. Check which Zenrows MCP tools are available and report them by primitive: Fetch (`scrape`), Extract (`extract`), Batch (`batch_*`), Crawl (`crawl_*`) and Browser Sessions (`browser_*`). Name any that are missing. If no Zenrows tools are present at all, the plugin is not connected: confirm it is installed and enabled, fully restart Cursor, and check Settings, MCPs for a `zenrows` entry. +2. Run a probe: `scrape(url='https://httpbin.io/get', response_type='plaintext')`. + - Returns content: Zenrows is connected, authorized, and scraping works. Report success. + - Returns a 401 or `AUTH003`: the OAuth login is missing or expired. Tell the user to complete the Zenrows authorization when Cursor shows "Needs login", or, if it is stuck, run "Cursor: Clear All MCP Tokens" from the command palette (Cmd+Shift+P) and re-authorize. + - Returns `AUTH004` or `AUTH014`: Zenrows is connected, but the account's credits or this API key's credit cap are used up. Reconnecting won't help. Tell the user to check their usage and plan in the Zenrows dashboard. +3. Call `account_usage` (it is free and changes nothing) to report the plan's usage. +4. Keep the output to a few lines: connection status, the tools found by primitive, auth status and usage. diff --git a/dist/cursor/mcp.json b/dist/cursor/mcp.json new file mode 100644 index 0000000..f14af5f --- /dev/null +++ b/dist/cursor/mcp.json @@ -0,0 +1,7 @@ +{ + "mcpServers": { + "zenrows": { + "url": "https://mcp.zenrows.com/mcp" + } + } +} diff --git a/dist/cursor/skills/batch/SKILL.md b/dist/cursor/skills/batch/SKILL.md new file mode 100644 index 0000000..0fd2205 --- /dev/null +++ b/dist/cursor/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 Cursor's agent), 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/cursor/skills/browser-automation/SKILL.md b/dist/cursor/skills/browser-automation/SKILL.md new file mode 100644 index 0000000..34d815f --- /dev/null +++ b/dist/cursor/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/cursor/skills/capture-api-calls/SKILL.md b/dist/cursor/skills/capture-api-calls/SKILL.md new file mode 100644 index 0000000..2b0aa56 --- /dev/null +++ b/dist/cursor/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 `