diff --git a/.release-please-manifest.json b/.release-please-manifest.json index 9a9ceb4..5fc8373 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/openai": "0.1.8" } diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 0e0bb28..ef4aa0c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -14,10 +14,12 @@ platforms// skills//.md the host's text for a {{> slot}} in that skill readme/setup.md the host's Setup section of its README (readme/more.md: optional extra sections) overrides.lock whole-file overrides and the shared version each was copied from (only once one exists) + scripts/ the host's own tooling, never shipped; validate.mjs and package.sh are run by + npm run validate and npm run package -- , the rest by the host itself everything else the host's manifests, …, copied into dist// ({{version}} comes from release-please) dist// GENERATED: the plugin the host installs, or a code host's files .github/plugin/marketplace.json Copilot's marketplace catalog (see below) -scripts/ render, validate, override, new-host, mirror, test +scripts/ render, validate, override, new-host, package, mirror, test ``` ### Marketplace catalogs diff --git a/README.md b/README.md index 93c61ef..f71ab0e 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 | |---|---| +| ChatGPT and Codex | [dist/openai/README.md](dist/openai/README.md) | | GitHub Copilot | [dist/copilot/README.md](dist/copilot/README.md) | diff --git a/dist/openai/LICENSE b/dist/openai/LICENSE new file mode 100644 index 0000000..e7dd33a --- /dev/null +++ b/dist/openai/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/openai/README.md b/dist/openai/README.md new file mode 100644 index 0000000..af5aa80 --- /dev/null +++ b/dist/openai/README.md @@ -0,0 +1,64 @@ +# Zenrows for ChatGPT and Codex + +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 the model to the Zenrows MCP server and adds skills that tell the model 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 Zenrows from the plugins directory in ChatGPT or Codex, then sign in to your Zenrows account when the model first asks to use it. + +Then ask something like: "Use Zenrows to get the product names and prices from https://www.scrapingcourse.com/ecommerce/". + +## For maintainers + +The package follows OpenAI's [plugin package format](https://developers.openai.com/plugins/build/plugins): a root `plugin.json` (Agent Plugins schema, with the listing, review and publication fields under `extensions.com.openai`), a root `mcp.json`, `skills/` and `assets/`. + +``` +npm run validate # includes the submission limits, from platforms/openai/scripts/validate.mjs +npm run package -- openai # validates, then builds .cache/packages/openai-zenrows-.zip +``` + +`platforms/openai/scripts/validate.mjs` in [zenrows-integrations](https://github.com/ZenRows/zenrows-integrations) encodes the limits from OpenAI's [manifest field reference](https://developers.openai.com/plugins/deploy/submission#automatically-provide-submission-and-review-information) and [submission error reference](https://developers.openai.com/plugins/deploy/submission-errors). CI runs it on every push. + +Things to know before submitting: + +- **Reviewer credentials never go in this repo.** OpenAI rejects `test_credentials` and `reviewer_instructions` in the package; they are entered in the portal's Review details form. +- **Run the review test cases with the reviewer test account before submitting.** OpenAI asks for it. Update `expected_behavior` to match what actually happens. +- **`demo_recording_url` must open without signing in.** It is required for MCP review. +- **`mcp.json` declares OAuth under `extensions.com.openai.auth`**, as OpenAI's [authentication reference](https://developers.openai.com/plugins/build/plugins#configure-mcp-authentication) says. The generic Agent Plugins MCP schema doesn't list `extensions` on a server; OpenAI's own examples combine both, so this follows OpenAI. +- **The tool scan reads the live server.** Every tool on `mcp.zenrows.com` needs `readOnlyHint`, `destructiveHint` and `openWorldHint` before submission ([ZenRows/zenrows-mcp#43](https://github.com/ZenRows/zenrows-mcp/pull/43)). +- **Each upload needs a new `version`.** OpenAI requires it; release-please bumps it on every release. + +## Privacy + +The plugin sends the URLs and options you ask the model 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/openai/assets/logo.png b/dist/openai/assets/logo.png new file mode 100644 index 0000000..a32dc12 Binary files /dev/null and b/dist/openai/assets/logo.png differ diff --git a/dist/openai/mcp.json b/dist/openai/mcp.json new file mode 100644 index 0000000..2440854 --- /dev/null +++ b/dist/openai/mcp.json @@ -0,0 +1,19 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/mcp.schema.json", + "mcpServers": { + "zenrows": { + "type": "streamable-http", + "url": "https://mcp.zenrows.com/mcp", + "extensions": { + "com.openai": { + "auth": { + "type": "oauth", + "client": { + "mode": "dcr" + } + } + } + } + } + } +} diff --git a/dist/openai/plugin.json b/dist/openai/plugin.json new file mode 100644 index 0000000..8ed9e9b --- /dev/null +++ b/dist/openai/plugin.json @@ -0,0 +1,95 @@ +{ + "$schema": "https://agent-plugins.org/schemas/1.0.0/plugin.schema.json", + "name": "zenrows", + "version": "0.1.8", + "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", + "repository": "https://github.com/ZenRows/zenrows-integrations", + "license": "MIT", + "keywords": ["web-scraping", "data-extraction", "browser-automation", "crawl", "mcp", "zenrows"], + "extensions": { + "com.openai": { + "interface": { + "displayName": "Zenrows", + "shortDescription": "Live web data from any page", + "longDescription": "Zenrows lets ChatGPT and Codex read live web pages and turn them into usable data. Ask for a page's content and get clean markdown. Ask for products, prices, articles or tables and get structured fields. Hand over a list of URLs and get one result per page, or start from one page and collect the pages linked from it. For tasks that need clicking, scrolling or filling in a page, Zenrows runs a hosted browser session and reports what it finds.\n\nConnect your Zenrows account once with secure sign-in.", + "developerName": "Zenrows", + "category": "Developer Tools", + "capabilities": ["Read web pages", "Extract structured data", "Batch and crawl", "Browser automation"], + "websiteURL": "https://www.zenrows.com", + "supportURL": "https://www.zenrows.com/contact", + "privacyPolicyURL": "https://www.zenrows.com/legal/privacy", + "termsOfServiceURL": "https://www.zenrows.com/legal/terms", + "defaultPrompt": [ + "Use Zenrows to get the product names and prices shown on the first page of https://www.scrapingcourse.com/ecommerce/", + "Use Zenrows to find which products are out of stock on https://www.scrapingcourse.com/table-parsing", + "Use Zenrows to list the pages linked from https://www.scrapingcourse.com/ecommerce/" + ], + "composerIcon": "./assets/logo.png", + "logo": "./assets/logo.png" + }, + "onboardingSkill": "./skills/getting-started/SKILL.md", + "review": { + "demo_recording_url": "https://www.youtube.com/watch?v=4hDEUhIWlHo", + "test_cases": { + "positive": [ + { + "description": "Read one page and answer from its content", + "prompt": "Use Zenrows to read https://www.scrapingcourse.com/table-parsing and list the products that are out of stock.", + "tools_triggered": "scrape", + "expected_behavior": "Reads the product table and lists the four out-of-stock products: Headphones, Blender, Portable Speaker and Air Purifier." + }, + { + "description": "Structured fields from a listing page", + "prompt": "Use Zenrows to get the product names and prices shown on the first page of https://www.scrapingcourse.com/ecommerce/.", + "tools_triggered": "extract", + "expected_behavior": "Calls extract on that URL and returns the 16 products on the first page, each with its name and price, from Abominable Hoodie ($69.00) to Artemis Running Short ($45.00). It does not fetch the other catalog pages." + }, + { + "description": "Several URLs as one batch job", + "prompt": "Use Zenrows to fetch these five pages as one batch job and tell me which ones succeeded: https://www.scrapingcourse.com/ecommerce/, https://www.scrapingcourse.com/ecommerce/page/2/, https://www.scrapingcourse.com/pagination, https://www.scrapingcourse.com/table-parsing, https://www.scrapingcourse.com/javascript-rendering/", + "tools_triggered": "batch_create", + "expected_behavior": "Submits one Batch job with five tasks and reports one result per URL: five successful, zero failed. batch_create can wait for the job to finish and return its counts, so batch_status, batch_wait or batch_results may or may not follow." + }, + { + "description": "Multi-step browsing that needs a click", + "prompt": "Use Zenrows to open https://www.scrapingcourse.com/button-click in a browser session, click the Load more button once, and tell me the price of the Kenobi Trail Jacket.", + "tools_triggered": "browser_navigate, browser_click or browser_batch, browser_close", + "expected_behavior": "Opens a browser session, clicks Load more and answers $47. The Kenobi Trail Jacket is not on the page before the click, so the answer needs it. Then closes the browser session." + }, + { + "description": "Check account usage", + "prompt": "Use Zenrows to check how much of my Zenrows usage I have spent this period.", + "tools_triggered": "account_usage", + "expected_behavior": "Reports the connected account's credits used and remaining for the current period, without changing anything and without purchase or upgrade links." + } + ], + "negative": [ + { + "description": "Request unrelated to web data: the plugin should not be called", + "prompt": "Write a short poem about autumn." + }, + { + "description": "Purchase with card details: the plugin should decline to buy or to enter payment data", + "prompt": "Buy the first product on https://www.scrapingcourse.com/ecommerce/ and pay with my card 4111 1111 1111 1111." + }, + { + "description": "No target URL: the plugin should ask which page to read before calling any tool", + "prompt": "Scrape the website." + } + ] + }, + "commerce": false, + "commerce_description": "This plugin does not sell products or process payments. Requests use credits on the user's existing Zenrows plan." + }, + "publication": { + "release_notes": "First release. Read live web pages, extract structured data, run batch jobs and site crawls, and drive hosted browser sessions through the Zenrows MCP server." + } + } + } +} diff --git a/dist/openai/skills/batch/SKILL.md b/dist/openai/skills/batch/SKILL.md new file mode 100644 index 0000000..daa4126 --- /dev/null +++ b/dist/openai/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 Codex), 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/openai/skills/browser-automation/SKILL.md b/dist/openai/skills/browser-automation/SKILL.md new file mode 100644 index 0000000..34d815f --- /dev/null +++ b/dist/openai/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/openai/skills/capture-api-calls/SKILL.md b/dist/openai/skills/capture-api-calls/SKILL.md new file mode 100644 index 0000000..2b0aa56 --- /dev/null +++ b/dist/openai/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 `