{
  "markdown": "<h1 align=\"center\">Novada Proxy</h1>\n\n<p align=\"center\"><strong>The agent-first residential proxy MCP — works with any provider.</strong></p>\n\n<p align=\"center\">\nRoute any HTTP request through 2M+ real home devices — Android phones, Windows PCs, Macs — to bypass anti-bot systems, geo-target by country or city, and maintain sticky sessions across multi-step workflows. Powered by <a href=\"https://www.novada.com\">Novada</a>.\n</p>\n\n<p align=\"center\">\n  <a href=\"https://npmjs.com/package/novada-proxy-mcp\"><img src=\"https://img.shields.io/npm/v/novada-proxy-mcp?label=npm&color=CB3837&style=flat-square\" alt=\"npm version\"></a>\n  <a href=\"https://npmjs.com/package/novada-proxy-mcp\"><img src=\"https://img.shields.io/npm/dw/novada-proxy-mcp?label=downloads&color=blue&style=flat-square\" alt=\"npm downloads\"></a>\n  <a href=\"LICENSE\"><img src=\"https://img.shields.io/badge/license-MIT-green?style=flat-square\" alt=\"License: MIT\"></a>\n  <a href=\"https://github.com/NovadaLabs/Novada-proxy/actions\"><img src=\"https://github.com/NovadaLabs/Novada-proxy/actions/workflows/ci.yml/badge.svg\" alt=\"CI\"></a>\n  <a href=\"https://nodejs.org\"><img src=\"https://img.shields.io/badge/node-%3E%3D18-brightgreen?style=flat-square\" alt=\"Node.js\"></a>\n</p>\n\n<p align=\"center\">\n  <img src=\"https://img.shields.io/badge/tools-10-orange?style=flat-square\" alt=\"10 tools\">\n  <img src=\"https://img.shields.io/badge/prompts-5-blue?style=flat-square\" alt=\"5 prompts\">\n  <img src=\"https://img.shields.io/badge/resources-5-green?style=flat-square\" alt=\"5 resources\">\n  <img src=\"https://img.shields.io/badge/tests-430-brightgreen?style=flat-square\" alt=\"430 tests\">\n  <img src=\"https://img.shields.io/badge/providers-5-purple?style=flat-square\" alt=\"5 providers\">\n</p>\n\n<p align=\"center\">\n  <a href=\"https://lobehub.com/mcp/novadalabs-novada-proxy\"><img src=\"https://lobehub.com/badge/mcp/novadalabs-novada-proxy\" alt=\"LobeHub MCP\"></a>\n  <a href=\"https://lobehub.com/mcp/novadalabs-novada-proxy\"><img src=\"https://lobehub.com/badge/mcp-full/novadalabs-novada-proxy?theme=light\" alt=\"LobeHub MCP Full\"></a>\n  <a href=\"https://smithery.ai/server/novada-proxy-mcp\"><img src=\"https://smithery.ai/badge/novada-proxy-mcp\" alt=\"Smithery\"></a>\n  <a href=\"https://mcp.run\"><img src=\"https://img.shields.io/badge/MCP-Registry-blueviolet?style=flat-square\" alt=\"MCP Registry\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#novada-proxy\"><img src=\"https://img.shields.io/badge/lang-English-blue?style=flat-square\" alt=\"English\"></a>\n  <a href=\"#novada-proxy中文文档\"><img src=\"https://img.shields.io/badge/lang-中文文档-red?style=flat-square\" alt=\"中文文档\"></a>\n</p>\n\n<p align=\"center\">\n  <a href=\"#why-novada-proxy\">Why</a> &middot;\n  <a href=\"#quick-install\">Install</a> &middot;\n  <a href=\"#10-tools-at-a-glance\">Tools</a> &middot;\n  <a href=\"#5-prompts\">Prompts</a> &middot;\n  <a href=\"#5-resources\">Resources</a> &middot;\n  <a href=\"#providers\">Providers</a> &middot;\n  <a href=\"#agent-first-design\">Agent-First</a>\n</p>\n\n---\n\nWorks with **Claude Code**, **Cursor**, **Windsurf**, **Cline**, **Continue**, and any MCP-compatible AI agent.\n\n> [!TIP]\n> **Free tier available** — sign up at [novada.com](https://www.novada.com), no credit card required. Get free access to Scraper API, Web Unblocker, and residential proxies to start building immediately.\n\n---\n\n## Getting Started\n\n<p align=\"center\">\n  <a href=\"https://www.novada.com\"><img src=\"https://img.shields.io/badge/1-Sign_Up_at_novada.com-5D34F2?style=for-the-badge\" alt=\"Step 1\"></a>\n  <a href=\"https://dashboard.novada.com/overview/res/endpoint-generator/\"><img src=\"https://img.shields.io/badge/2-Get_Proxy_Credentials-0EA5E9?style=for-the-badge\" alt=\"Step 2\"></a>\n  <a href=\"#quick-install\"><img src=\"https://img.shields.io/badge/3-Install_&_Run-10B981?style=for-the-badge\" alt=\"Step 3\"></a>\n</p>\n\n### For Humans\n\n1. **Create a free account** at [novada.com](https://www.novada.com) — no credit card required\n2. **Get your credentials** at [Dashboard → Residential Proxies → Endpoint Generator](https://dashboard.novada.com/overview/res/endpoint-generator/) — copy your username and password\n3. **Install and run:**\n\n```bash\n# Claude Code\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_PROXY_USER=your_username \\\n  -e NOVADA_PROXY_PASS=your_password \\\n  -- npx -y novada-proxy-mcp\n\n# Or use the CLI directly\nnpx novada-proxy-mcp status\nnpx novada-proxy fetch https://example.com\n```\n\n### For Agents\n\n> [!NOTE]\n> **Agents:** Tell your human to complete steps 1-2 above. Once credentials are set as environment variables, all 10 tools are available immediately. No API key rotation, no token refresh — proxy credentials are persistent.\n\n```\nRequired env vars:\n  NOVADA_PROXY_USER   — from novada.com dashboard\n  NOVADA_PROXY_PASS   — from novada.com dashboard\n\nOptional (for extra features):\n  NOVADA_API_KEY      — enables novada_proxy_search (Google search)\n  NOVADA_BROWSER_WS   — enables novada_proxy_render (JS rendering)\n  NOVADA_PROXY_ZONE   — \"res\" (default), \"isp\", or \"dcp\"\n```\n\n**Need help?** Contact [support@novada.com](mailto:support@novada.com)\n\n---\n\n## Why Novada Proxy\n\nAI agents get blocked on 60–70% of commercial websites. Standard HTTP requests are detected and rejected by Cloudflare, Akamai, DataDome, and PerimeterX. Novada Proxy routes your agent through real residential IPs — indistinguishable from a human browser.\n\n| Problem | Solution |\n|---------|----------|\n| Amazon, LinkedIn, Cloudflare block your agent | 2M+ residential IPs from real home devices |\n| Bot challenges return 403 / CAPTCHA | Real device fingerprints bypass detection |\n| JS-rendered pages return blank content | `novada_proxy_render` runs real Chromium |\n| Geo-restricted or localized content | 195+ countries, city-level targeting |\n| Multi-step workflows need the same IP | Sticky sessions — consistent IP across calls |\n| Scraping 10+ URLs wastes time | `novada_proxy_batch_fetch` — concurrent, parallel |\n| Need structured fields, not raw HTML | `novada_proxy_extract` — title, price, rating, etc. |\n| Finding URLs before scraping | `novada_proxy_map` — discover all internal links |\n| Need clean search results | `novada_proxy_search` — Google results as JSON |\n\n---\n\n## 10 Tools at a Glance\n\n| Tool | What It Does | Requires |\n|------|-------------|---------|\n| `novada_proxy_fetch` | Fetch any URL through residential proxy | Proxy credentials |\n| `novada_proxy_batch_fetch` | Fetch 2–20 URLs concurrently (up to 5x parallel) | Proxy credentials |\n| `novada_proxy_extract` | Extract structured fields — heuristic mode (fields) or LLM mode (schema) | Proxy credentials |\n| `novada_proxy_map` | Crawl a URL and return all internal links as JSON array | Proxy credentials |\n| `novada_proxy_crawl` | Recursively crawl a site (BFS, depth 1-5) with URL discovery | Proxy credentials |\n| `novada_proxy_session` | Sticky session — same IP across every call | Proxy credentials |\n| `novada_proxy_search` | Google search -> structured JSON (title, url, snippet) | `NOVADA_API_KEY` |\n| `novada_proxy_render` | Render JS-heavy pages with real Chromium [BETA] | `NOVADA_BROWSER_WS` |\n| `novada_proxy_research` | One-shot deep research — search + fetch + synthesize | `NOVADA_API_KEY` + Proxy |\n| `novada_proxy_status` | Check proxy network health + version | _(none)_ |\n\n---\n\n## Quick Decision Guide\n\n| I want to... | Use this tool |\n|--------------|---------------|\n| Fetch a single URL | `novada_proxy_fetch` |\n| Fetch 2–20 URLs at once | `novada_proxy_batch_fetch` |\n| Extract specific fields (title, price...) | `novada_proxy_extract` with `fields` |\n| Extract ANY field via schema | `novada_proxy_extract` with `schema` |\n| Find all links on a page | `novada_proxy_map` |\n| Crawl an entire site | `novada_proxy_crawl` |\n| Research a topic | `novada_proxy_research` |\n| Search Google | `novada_proxy_search` |\n| Render a JS-heavy page | `novada_proxy_render` |\n| Keep same IP across calls | `novada_proxy_session` |\n| Check if proxy works | `novada_proxy_status` |\n\n## When To Use Which Tool\n\n```\nGoal: \"Scrape a single URL\"\n  └─ Static HTML page?          → novada_proxy_fetch\n  └─ Need specific fields?      → novada_proxy_extract (fields or schema mode)\n  └─ React/Vue SPA / blank page? → novada_proxy_render\n\nGoal: \"Scrape multiple URLs\"\n  └─ You have the URLs already  → novada_proxy_batch_fetch\n  └─ You need links from one page → novada_proxy_map → novada_proxy_batch_fetch\n  └─ You need to crawl a whole site → novada_proxy_crawl → novada_proxy_batch_fetch\n\nGoal: \"Research a topic\"        → novada_proxy_research (search + fetch + findings in one call)\n\nGoal: \"Search the web\"          → novada_proxy_search → novada_proxy_batch_fetch\n\nGoal: \"Login + multi-page flow\" → novada_proxy_session (same session_id)\n\nGoal: \"Check if proxy works\"    → novada_proxy_status\n```\n\n---\n\n## 5 Prompts\n\nPre-built agent workflows that chain multiple tools together. Call these from any MCP client to execute common patterns in one step.\n\n| Prompt | Description | Key Arguments |\n|--------|-------------|---------------|\n| `fetch_url` | Fetch a URL through residential proxy with anti-bot bypass | `url`, `country`, `format` |\n| `research_topic` | Search + batch read workflow — find and read top pages on a topic | `query`, `num_results`, `country` |\n| `extract_product` | Extract structured product data from any e-commerce URL | `url`, `fields` |\n| `crawl_site` | Discover all pages on a site, then fetch them in parallel | `url`, `limit`, `country` |\n| `troubleshoot` | Step-by-step proxy diagnosis when things go wrong | `error_message` |\n\n> [!NOTE]\n> Prompts orchestrate multi-tool workflows automatically. For example, `research_topic` runs `novada_proxy_search` then `novada_proxy_batch_fetch` in sequence — the agent doesn't need to figure out the pipeline.\n\n---\n\n## 5 Resources\n\nAlways-accessible reference data that agents can read at any time, without making proxy calls.\n\n| Resource URI | Description |\n|-------------|-------------|\n| `proxy://countries` | Complete list of 195+ country codes with city-level targeting |\n| `proxy://error-codes` | All typed error codes with recovery instructions |\n| `proxy://workflows` | Common agent workflow patterns (crawl, research, monitoring) |\n| `proxy://supported-fields` | All fields `novada_proxy_extract` can extract with strategies |\n| `proxy://cost-guide` | Credits per tool, caching behavior, cost optimization tips |\n\n---\n\n## Quick Install\n\n**Core — fetch any URL through residential proxy:**\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_PROXY_USER=your_username \\\n  -e NOVADA_PROXY_PASS=your_password \\\n  -- npx -y novada-proxy-mcp\n```\n\n**Search only:**\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_API_KEY=your_key \\\n  -- npx -y novada-proxy-mcp\n```\n\n**All tools (proxy + search + browser render):**\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_PROXY_USER=your_username \\\n  -e NOVADA_PROXY_PASS=your_password \\\n  -e NOVADA_API_KEY=your_key \\\n  -e NOVADA_BROWSER_WS=your_browser_ws_url \\\n  -- npx -y novada-proxy-mcp\n```\n\n**Cursor / Windsurf / Cline — add to MCP config:**\n```json\n{\n  \"mcpServers\": {\n    \"novada-proxy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"novada-proxy-mcp\"],\n      \"env\": {\n        \"NOVADA_PROXY_USER\": \"your_username\",\n        \"NOVADA_PROXY_PASS\": \"your_password\"\n      }\n    }\n  }\n}\n```\n\nGet credentials: **[novada.com](https://www.novada.com)** -> Dashboard -> Residential Proxies -> Endpoint Generator\n\n---\n\n## Providers\n\nNovada Proxy works with **any HTTP proxy provider**. Novada is the built-in default with the deepest integration.\n\n**Priority:** Novada -> BrightData -> Smartproxy -> Oxylabs -> Generic. First configured provider wins.\n\n| Feature | Novada | BrightData | Smartproxy | Oxylabs | Generic HTTP |\n|---------|--------|------------|------------|---------|-------------|\n| Auto country targeting | ✓ | ✓ | ✓ | ✓ | manual |\n| Auto city targeting | ✓ | ✓ | ✓ | ✓ | manual |\n| Sticky sessions | ✓ | ✓ | ✓ | ✓ | manual |\n| Built-in search API | ✓ | — | — | — | — |\n| Browser API (JS render) | ✓ | — | — | — | — |\n\n<details>\n<summary>BrightData setup</summary>\n\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e BRIGHTDATA_USER=\"brd-customer-abc123-zone-residential\" \\\n  -e BRIGHTDATA_PASS=your_password \\\n  -- npx -y novada-proxy-mcp\n```\n`BRIGHTDATA_USER` is your full username including zone. Optional: `BRIGHTDATA_HOST`, `BRIGHTDATA_PORT` (default `zproxy.lum-superproxy.io:22225`).\n</details>\n\n<details>\n<summary>Smartproxy setup</summary>\n\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e SMARTPROXY_USER=your_username \\\n  -e SMARTPROXY_PASS=your_password \\\n  -- npx -y novada-proxy-mcp\n```\nOptional: `SMARTPROXY_HOST`, `SMARTPROXY_PORT` (default `gate.smartproxy.com:10001`).\n</details>\n\n<details>\n<summary>Oxylabs setup</summary>\n\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e OXYLABS_USER=your_username \\\n  -e OXYLABS_PASS=your_password \\\n  -- npx -y novada-proxy-mcp\n```\nOptional: `OXYLABS_HOST`, `OXYLABS_PORT` (default `pr.oxylabs.io:7777`).\n</details>\n\n<details>\n<summary>Generic HTTP proxy (IPRoyal, any provider)</summary>\n\n```bash\nclaude mcp add novada-proxy-mcp \\\n  -e PROXY_URL=\"http://username:password@geo.iproyal.com:12321\" \\\n  -- npx -y novada-proxy-mcp\n```\n`country`, `city`, `session_id` params are ignored with Generic — encode targeting directly in your proxy URL.\n</details>\n\n---\n\n## Agent-First Design\n\n> [!NOTE]\n> Novada Proxy is the only proxy MCP designed specifically for autonomous AI agents. Every response, error, and description is optimized for machine consumption.\n\n| Feature | What It Means |\n|---------|--------------|\n| `agent_instruction` in errors | Every error tells the agent exactly what to do next |\n| Decision trees in descriptions | WHEN TO USE / USE INSTEAD guides in every tool |\n| `cache_hit` metadata | Agent knows when 0 credits were used (cached response) |\n| `credits_estimated` per call | Cost tracking built into every response |\n| Typed error codes | Machine-readable: `BOT_DETECTION_SUSPECTED`, `PAGE_NOT_FOUND`, etc. |\n| 5 workflow prompts | Pre-built agent workflows: research, crawl, extract, diagnose |\n| 5 reference resources | Countries, error codes, cost guide — always accessible |\n\n---\n\n## Tools\n\n### `novada_proxy_fetch`\nFetch any URL through a residential proxy. Returns structured JSON with content, status code, and metadata. Auto-retry on network errors. Caches repeated calls (default 300s TTL — `meta.cache_hit: true` means no proxy credit used).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Target URL (`http://` or `https://`) |\n| `country` | string | — | 2-letter ISO code: `US`, `DE`, `JP`, `GB`, `BR`... (195+ options) |\n| `city` | string | — | City: `newyork`, `london`, `tokyo`, `paris`, `berlin`... |\n| `session_id` | string | — | Reuse same ID for same IP across calls (no hyphens, max 64 chars) |\n| `format` | string | `markdown` | `markdown` strips HTML / `raw` returns full HTML |\n| `timeout` | number | `60` | Timeout in seconds (1–120) |\n\n**Response:**\n```json\n{\n  \"ok\": true,\n  \"tool\": \"novada_proxy_fetch\",\n  \"data\": { \"url\": \"...\", \"status_code\": 200, \"content\": \"...\", \"size_bytes\": 34000 },\n  \"meta\": { \"latency_ms\": 1800, \"cache_hit\": false, \"quota\": { \"credits_estimated\": 1 } }\n}\n```\n\n---\n\n### `novada_proxy_batch_fetch`\nFetch 2–20 URLs concurrently through residential proxy. Up to 5x faster than sequential fetches. Per-URL errors are captured individually — the batch itself succeeds even if some URLs fail. Reuses response cache for URLs already fetched.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `urls` | string[] | required | 2–20 URLs to fetch |\n| `concurrency` | number | `3` | Parallel requests (1–5) |\n| `country` | string | — | Same country for all URLs |\n| `format` | string | `markdown` | `markdown` or `raw` |\n| `timeout` | number | `60` | Per-URL timeout in seconds |\n\n**Response:**\n```json\n{\n  \"ok\": true,\n  \"tool\": \"novada_proxy_batch_fetch\",\n  \"data\": {\n    \"requested\": 3,\n    \"succeeded\": 3,\n    \"failed\": 0,\n    \"results\": [\n      { \"url\": \"https://...\", \"ok\": true, \"content\": \"...\", \"cache_hit\": false, \"latency_ms\": 1200 },\n      { \"url\": \"https://...\", \"ok\": true, \"content\": \"...\", \"cache_hit\": true,  \"latency_ms\": 0 },\n      { \"url\": \"https://...\", \"ok\": false, \"error\": { \"code\": \"TLS_ERROR\", \"message\": \"...\" } }\n    ]\n  },\n  \"meta\": { \"latency_ms\": 4100, \"quota\": { \"credits_estimated\": 3 } }\n}\n```\n\n---\n\n### `novada_proxy_extract`\nExtract structured fields from any URL using heuristic pattern matching (meta tags, Open Graph, JSON-LD, Schema.org). Lightweight — no LLM needed. Set `render_fallback: true` to automatically retry via real Chromium if the proxy fetch fails.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Target URL |\n| `fields` | string[] | required | Fields to extract: `title`, `price`, `description`, `rating`, `image`, `author`, `date`... |\n| `render_fallback` | boolean | `false` | Auto-retry via `novada_proxy_render` on TLS/bot block |\n| `country` | string | — | Geo-target the fetch |\n| `timeout` | number | `60` | Timeout in seconds |\n\n**Response:**\n```json\n{\n  \"ok\": true,\n  \"tool\": \"novada_proxy_extract\",\n  \"data\": {\n    \"url\": \"https://books.toscrape.com/...\",\n    \"fields\": { \"title\": \"A Light in the Attic\", \"price\": \"£51.77\", \"description\": null },\n    \"extracted_via\": \"proxy_fetch\"\n  },\n  \"meta\": { \"latency_ms\": 2100, \"quota\": { \"credits_estimated\": 1 } }\n}\n```\n\n---\n\n### `novada_proxy_map`\nCrawl a URL and return all internal links as a structured JSON array. Use as the discovery step before `novada_proxy_batch_fetch` to crawl an entire site without guessing URLs.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Starting URL to crawl |\n| `limit` | number | `50` | Max URLs to return (10–200) |\n| `include_external` | boolean | `false` | Include off-domain links |\n| `country` | string | — | Geo-target the fetch |\n| `timeout` | number | `60` | Timeout in seconds |\n\n**Response:**\n```json\n{\n  \"ok\": true,\n  \"tool\": \"novada_proxy_map\",\n  \"data\": {\n    \"domain\": \"books.toscrape.com\",\n    \"internal_url_count\": 20,\n    \"internal_urls\": [\"https://books.toscrape.com/catalogue/...\", \"...\"],\n    \"sitemap_hint\": \"https://books.toscrape.com/sitemap.xml (check manually)\"\n  },\n  \"meta\": { \"latency_ms\": 3800, \"quota\": { \"credits_estimated\": 1 } }\n}\n```\n\n---\n\n### `novada_proxy_session`\nSticky session fetch — every call with the same `session_id` uses the same residential IP. Essential for login flows, paginated scraping, and price monitoring. Supports `verify_sticky: true` to confirm IP consistency before relying on it.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `session_id` | string | required | Unique ID — reuse to keep same IP (no hyphens, max 64 chars) |\n| `url` | string | required | Target URL |\n| `country` | string | — | 2-letter country code |\n| `city` | string | — | City-level targeting |\n| `verify_sticky` | boolean | `false` | Make 3 proxy calls to confirm IP consistency (adds ~15–25s) |\n| `format` | string | `markdown` | `markdown` or `raw` |\n| `timeout` | number | `60` | Timeout in seconds |\n\n---\n\n### `novada_proxy_search`\nStructured Google search via Novada Scraper API. Returns titles, URLs, and snippets as clean JSON — no HTML parsing needed.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | required | Search query |\n| `num` | number | `10` | Results (1–20) |\n| `country` | string | — | Localize: `us`, `uk`, `de`, `jp`... |\n| `language` | string | — | Language: `en`, `zh`, `de`, `ja`... |\n\n---\n\n### `novada_proxy_render` [BETA]\nRender JavaScript-heavy pages using Novada's Browser API (real Chromium, full JS execution). Use for SPAs, React/Vue apps, and pages that return blank with a standard HTTP fetch.\n\n**Requires:** `NOVADA_BROWSER_WS` — copy the Puppeteer URL from Dashboard -> Browser API -> Playground\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Target URL |\n| `format` | string | `markdown` | `markdown` / `html` / `text` |\n| `wait_for` | string | — | CSS selector to wait for before extracting (e.g. `.product-title`) |\n| `timeout` | number | `60` | Timeout in seconds (5–120) |\n\n> Costs ~5 proxy credits per call vs 1 for `novada_proxy_fetch`. Use `novada_proxy_extract` with `render_fallback: true` for automatic escalation when needed.\n\n---\n\n### `novada_proxy_crawl`\nRecursively crawl a website via BFS traversal. Starts from a URL, discovers links at each depth level, and returns the full URL tree with metadata.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Starting URL to crawl |\n| `depth` | number | `2` | BFS depth (1–5) |\n| `limit` | number | `50` | Max pages to crawl (10–200) |\n| `include_content` | boolean | `false` | Also return page content for each URL |\n| `country` | string | — | Geo-target all fetches |\n| `format` | string | `markdown` | Content format when `include_content: true` |\n| `timeout` | number | `60` | Per-page timeout in seconds |\n\n**When to use:** Full-site scraping, sitemap generation, content indexing — when you need MORE than a single page.\n\n**Use `novada_proxy_map` instead if:** You only need links from ONE page (one level deep). Map is faster and cheaper for single-page link discovery.\n\n**Chain with:** `novada_proxy_batch_fetch` to scrape specific pages from the URL tree.\n\n**Example:**\n```json\n{\n  \"url\": \"https://example.com\",\n  \"depth\": 2,\n  \"limit\": 50,\n  \"include_content\": false\n}\n```\n\n**Response:** `data.pages[]` (url, depth, status_code, total_links), `data.urls[]` (flat array for chaining into `novada_proxy_batch_fetch`)\n\n---\n\n### `novada_proxy_research`\nOne-shot research tool — searches the web, fetches top results, and returns structured findings with source previews. The agent can analyze the findings for deeper synthesis.\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `query` | string | required | Research question or topic |\n| `depth` | string | `\"standard\"` | `\"quick\"` (3 sources), `\"standard\"` (5 sources), `\"deep\"` (10 sources) |\n| `country` | string | — | Localize search results |\n| `timeout` | number | `60` | Timeout in seconds |\n\n**Requires:** `NOVADA_API_KEY` (for Google search) + Proxy credentials (for fetching sources)\n\n**When to use:** Research questions, topic investigation, competitive analysis, fact-finding — when you need content from multiple sources in one call.\n\n**Use `novada_proxy_search` instead if:** You just need search result URLs, not full page content.\n\n**Chain with:** `novada_proxy_fetch` on specific `urls[]` for deeper reading of individual sources.\n\n**Note:** `findings_summary` is a concatenated preview of sources — your agent should analyze `findings[]` for actual synthesis.\n\n**Example:**\n```json\n{\n  \"query\": \"best residential proxy providers 2026\",\n  \"depth\": \"standard\"\n}\n```\n\n**Response:** `data.findings[]` (title, url, snippet, content_preview), `data.urls[]` (for chaining), `data.findings_summary`\n\n---\n\n### `novada_proxy_extract` — Schema Mode\n\nIn addition to `fields` (heuristic extraction), `novada_proxy_extract` supports a `schema` parameter for extracting any arbitrary field via your agent's LLM — zero additional API cost.\n\n#### Schema Mode (LLM Extraction)\nPass `schema` instead of `fields` for arbitrary field extraction. The tool returns cleaned page content + an extraction prompt — your agent does the extraction (zero additional API cost).\n\n| Parameter | Type | Default | Description |\n|-----------|------|---------|-------------|\n| `url` | string | required | Target URL |\n| `schema` | object | — | Keys = field names, values = field descriptions. Use instead of `fields`. |\n| `render_fallback` | boolean | `false` | Auto-retry via `novada_proxy_render` on TLS/bot block |\n| `country` | string | — | Geo-target the fetch |\n| `timeout` | number | `60` | Timeout in seconds |\n\n**Example:**\n```json\n{\n  \"url\": \"https://example.com/product\",\n  \"schema\": {\n    \"product_name\": \"The full product name\",\n    \"price\": \"Current price with currency\",\n    \"warranty\": \"Warranty terms and duration\",\n    \"return_policy\": \"Return policy summary\"\n  }\n}\n```\n\n**Response:** `data.mode = \"llm_extract\"`, `data.content` (cleaned markdown), `data.extraction_prompt` (instructions for your agent to follow and extract the fields)\n\n**Security:** Schema keys must be alphanumeric/underscore (a-z, 0-9, _), max 50 chars. Values max 200 chars.\n\n---\n\n### `novada_proxy_status`\nCheck proxy network connectivity and version. Makes a live proxy call to verify the connection is working. No credentials required.\n\n---\n\n## Agent Workflows\n\n### Site crawl pipeline (map -> batch)\n```\n# Agent task: \"Read all products on this catalogue\"\n1. novada_proxy_map(url=\"https://books.toscrape.com\", limit=50)\n   → returns 20–50 internal URLs in 4s, 1 credit\n\n2. novada_proxy_batch_fetch(urls=[...20 URLs], concurrency=5)\n   → fetches all 20 pages in parallel, ~4s wall time, 20 credits\n   (vs ~60s sequential = 15x speedup)\n```\n\n### Research pipeline (search -> batch)\n```\n# Agent task: \"Find and read top 5 pages about X\"\n1. novada_proxy_search(query=\"residential proxy MCP\", num=5)\n   → structured JSON: titles, URLs, snippets\n\n2. novada_proxy_batch_fetch(urls=[...5 URLs], format=\"markdown\")\n   → full content of all 5 pages in parallel\n```\n\n### Sticky session — login + multi-page scrape\n```\n# Same IP across all calls\nnovada_proxy_session(session_id=\"job_001\", url=\"https://example.com/login\")\nnovada_proxy_session(session_id=\"job_001\", url=\"https://example.com/dashboard\")\nnovada_proxy_session(session_id=\"job_001\", url=\"https://example.com/data/page/1\")\nnovada_proxy_session(session_id=\"job_001\", url=\"https://example.com/data/page/2\")\n```\n\n### Price monitoring — same product, three markets\n```\nnovada_proxy_fetch(url=\"https://amazon.com/dp/B0BSHF7WHW\", country=\"US\")\nnovada_proxy_fetch(url=\"https://amazon.com/dp/B0BSHF7WHW\", country=\"DE\")\nnovada_proxy_fetch(url=\"https://amazon.com/dp/B0BSHF7WHW\", country=\"JP\")\n# Second call per URL is a cache hit (0ms, 0 credits) if within 300s TTL\n```\n\n### Extract structured data\n```\n# Agent task: \"Get product details without parsing HTML\"\nnovada_proxy_extract(\n  url=\"https://books.toscrape.com/catalogue/a-light-in-the-attic_1000/index.html\",\n  fields=[\"title\", \"price\", \"description\", \"rating\"],\n  render_fallback=true  # auto-retry via Chromium if proxy gets blocked\n)\n```\n\n---\n\n## Response Cache\n\nAll `novada_proxy_fetch` and `novada_proxy_batch_fetch` calls are cached in-process. Repeated fetches to the same URL within the TTL window consume **zero proxy credits**.\n\n| Behavior | Detail |\n|----------|--------|\n| Default TTL | 300 seconds (5 minutes) |\n| Cache key | `url + format + country` |\n| Session bypass | `session_id` present -> never cached (sticky routing requires live calls) |\n| Disable | Set `PROXY4AGENT_CACHE_TTL_SECONDS=0` |\n| Max entries | 200 (oldest evicted when full) |\n\n**Reading cache status from response:**\n```json\n\"meta\": {\n  \"cache_hit\": true,          // served from cache — no proxy credit used\n  \"cache_age_seconds\": 12,    // seconds since the entry was stored\n  \"latency_ms\": 0             // ~0ms for cache hits\n}\n```\n\n---\n\n## Typed Error Codes\n\nEvery error response includes a typed `error.code`, `recoverable` flag, and `agent_instruction` with the correct next step. Agents never need to parse error messages.\n\n| Code | Meaning | Recoverable | Agent Action |\n|------|---------|-------------|--------------|\n| `BOT_DETECTION_SUSPECTED` | HTTP 4xx — target blocked the request | ✓ | Retry with `novada_proxy_render` or different `country` |\n| `TLS_ERROR` | TLS/SSL connection failed through proxy | ✓ | Retry with a different `country` parameter |\n| `TIMEOUT` | Request exceeded timeout limit | ✓ | Increase `timeout` or retry |\n| `RATE_LIMITED` | HTTP 429 — too many requests | ✓ | Wait 5s and retry |\n| `NETWORK_ERROR` | DNS failure — hostname not found | ✗ | Verify the URL is correct |\n| `SESSION_STICKINESS_FAILED` | Same IP not maintained | ✓ | Retry `verify_sticky: true` to confirm |\n| `INVALID_INPUT` | Bad parameter value | ✗ | Fix the parameter and retry |\n| `PROVIDER_NOT_CONFIGURED` | Missing env vars | ✗ | Set credentials and restart MCP |\n| `UNKNOWN_ERROR` | Unexpected error | ✓ | Check `novada_proxy_status`, retry |\n\n**Error response format:**\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"BOT_DETECTION_SUSPECTED\",\n    \"message\": \"HTTP 403 — request blocked by target\",\n    \"recoverable\": true,\n    \"agent_instruction\": \"Try novada_proxy_render (real browser). Or retry with a different country/session_id.\"\n  }\n}\n```\n\n---\n\n## Geo Coverage\n\n**195+ countries** including:\n\n`US` `GB` `DE` `FR` `JP` `CA` `AU` `BR` `IN` `KR` `SG` `NL` `IT` `ES` `MX` `RU` `PL` `SE` `NO` `DK` `FI` `CH` `AT` `BE` `PT` `CZ` `HU` `RO` `UA` `TR` `IL` `ZA` `NG` `EG` `AR` `CL` `CO` `PE` `VN` `TH` `ID` `MY` `PH` `TW` `HK` `NZ` + [148 more](https://www.novada.com)\n\n**City-level targeting:** `newyork` · `losangeles` · `chicago` · `london` · `paris` · `berlin` · `tokyo` · `seoul` · `sydney` · `toronto` · `singapore` · `dubai` · `mumbai` · `saopaulo`\n\n---\n\n## Compatible With\n\n| Client | Install method |\n|--------|---------------|\n| **Claude Code** | `claude mcp add novada-proxy-mcp -e ... -- npx -y novada-proxy-mcp` |\n| **Cursor** | Settings -> MCP -> Add server -> `npx -y novada-proxy-mcp` |\n| **Windsurf** | MCP config -> `npx -y novada-proxy-mcp` |\n| **Cline** | MCP settings -> command: `npx`, args: `[\"-y\", \"novada-proxy-mcp\"]` |\n| **Continue** | `.continue/config.json` -> mcpServers |\n| **Smithery** | [smithery.ai/server/novada-proxy-mcp](https://smithery.ai/server/novada-proxy-mcp) |\n| **Any MCP client** | stdio transport / `npx -y novada-proxy-mcp` |\n\n---\n\n## Network\n\n| Metric | Value |\n|--------|-------|\n| Residential IPs | 2,000,000+ |\n| Live nodes | 7,000+ |\n| Countries | 195+ |\n| Device types | Android, Windows, Mac |\n| Uptime | 99.9% |\n\n---\n\n## Confirmed Working\n\n**E-commerce:** Amazon, eBay, Walmart, Etsy, Shopify stores  \n**Professional:** LinkedIn  \n**Anti-bot protected:** Cloudflare, Akamai, DataDome  \n**News & content:** HackerNews, Reddit, BBC, CNN, NYTimes  \n**Tech:** GitHub, Wikipedia, Stack Overflow, IMDB\n\n---\n\n## Real-World Test Results\n\nTested across 3 Novada proxy types with 33 real-world tests (2026-04-28):\n\n| Proxy Type | Tests | Pass | Notes |\n|-----------|:-----:|:----:|-------|\n| Residential | 11 | 9 | Wikipedia, Shopify, HackerNews, geo-targeting work. Sticky sessions require endpoint config. |\n| ISP | 7 | 7 | All tools work including sticky sessions (`session_verified: true`). |\n| Datacenter | 8 | 8 | Fast, cost-effective. Anti-bot sites (Amazon, CNN) may block datacenter IPs — use residential for those. |\n| Error handling | 7 | 7 | All error codes return structured JSON with `agent_instruction`. |\n\n**Success rate: 94% (31/33 pass)**. Failures are proxy-type limitations (datacenter on anti-bot sites), not code bugs.\n\n### Proxy Type Guide\n\n| Use Case | Recommended Proxy | Why |\n|----------|------------------|-----|\n| Anti-bot sites (Amazon, LinkedIn, CNN) | Residential | Real home IPs, hardest to detect |\n| Fast bulk scraping | Datacenter | Lowest latency, cheapest per GB |\n| Sticky sessions (login flows) | ISP | 6-hour sticky, stable IPs |\n| General scraping | Any | All types handle most sites |\n\n---\n\n## Known Limitations\n\n| Limitation | Workaround |\n|-----------|-----------|\n| Datacenter IPs blocked on anti-bot sites | Use residential or ISP proxy type (`NOVADA_PROXY_ZONE=res`) |\n| Proxy-side DNS errors surface as `TLS_ERROR` | Check if domain exists before retrying with different country |\n| CLI is stateless (no cross-invocation cache) | Use MCP server for cache benefits, or re-fetch same URLs within one CLI batch |\n| `novada_proxy_render` requires Browser API key | Set `NOVADA_BROWSER_WS` env var — get it from novada.com dashboard |\n| Heuristic extraction misses a field | Use `schema` mode: pass `schema:{\"field\":\"description\"}` — returns cleaned content + extraction prompt for your agent to extract any field (zero-cost LLM extraction) |\n\n---\n\n## Feedback & Support\n\n- **Email:** [support@novada.com](mailto:support@novada.com)\n- **GitHub Issues:** [github.com/NovadaLabs/Novada-proxy/issues](https://github.com/NovadaLabs/Novada-proxy/issues)\n- **Website:** [novada.com](https://www.novada.com)\n\n---\n\n## License\n\nMIT © [Novada](https://www.novada.com) — see [LICENSE](LICENSE)\n\n---\n\n---\n\n# Novada Proxy（中文文档）\n\n<p align=\"center\"><strong>AI 智能体专属住宅代理 MCP — 支持任意供应商。</strong></p>\n\n<p align=\"center\">\n通过 200 万+ 真实家庭设备（Android 手机、Windows 电脑、Mac）路由 HTTP 请求，绕过反机器人系统，按国家/城市精准定位，跨请求保持同一 IP。\n</p>\n\n<p align=\"center\">\n  <a href=\"#novada-proxy\"><img src=\"https://img.shields.io/badge/lang-English-blue?style=flat-square\" alt=\"返回英文\"></a>\n  <img src=\"https://img.shields.io/badge/工具-10个-orange?style=flat-square\" alt=\"10 个工具\">\n  <img src=\"https://img.shields.io/badge/提示词-5个-blue?style=flat-square\" alt=\"5 个提示词\">\n  <img src=\"https://img.shields.io/badge/资源-5个-green?style=flat-square\" alt=\"5 个资源\">\n  <img src=\"https://img.shields.io/badge/测试-430个-brightgreen?style=flat-square\" alt=\"430 个测试\">\n</p>\n\n<p align=\"center\">\n  <a href=\"#10-个工具\">工具</a> &middot;\n  <a href=\"#5-个提示词\">提示词</a> &middot;\n  <a href=\"#5-个资源\">资源</a> &middot;\n  <a href=\"#快速安装\">安装</a> &middot;\n  <a href=\"#智能体优先设计\">智能体优先</a> &middot;\n  <a href=\"#多供应商支持\">供应商</a>\n</p>\n\n---\n\n支持 **Claude Code**、**Cursor**、**Windsurf**、**Cline**、**Continue** 及所有 MCP 兼容智能体。由 **[Novada](https://www.novada.com)** 提供支持。\n\n> [!TIP]\n> **免费套餐** — 在 [novada.com](https://www.novada.com) 注册，无需信用卡。免费使用 Scraper API、Web Unblocker 和住宅代理。\n\n---\n\n## 10 个工具\n\n```\nnovada_proxy_fetch       → 通过住宅代理抓取任意 URL\nnovada_proxy_batch_fetch → 并发抓取 2-20 个 URL（最高 5 倍加速）\nnovada_proxy_extract     → 从页面提取结构化字段（标题、价格、评分…）\nnovada_proxy_map         → 爬取页面，返回所有内部链接 JSON 数组\nnovada_proxy_crawl       → 递归爬取站点（BFS，深度 1-5），自动发现 URL\nnovada_proxy_session     → 粘性会话 — 同一 session_id 始终同一 IP\nnovada_proxy_search      → Google 搜索，返回结构化 JSON（无需解析 HTML）\nnovada_proxy_render      → 真实 Chromium 渲染 JS 页面 [BETA]\nnovada_proxy_research    → 一键深度研究 — 搜索 + 抓取 + 综合分析\nnovada_proxy_status      → 检查代理网络健康状态\n```\n\n---\n\n## 5 个提示词\n\n预构建的智能体工作流，将多个工具链式组合。\n\n| 提示词 | 描述 | 主要参数 |\n|--------|------|---------|\n| `fetch_url` | 通过住宅代理抓取 URL，自动绕过反机器人 | `url`, `country`, `format` |\n| `research_topic` | 搜索 + 批量阅读工作流 — 搜索主题并阅读排名靠前的页面 | `query`, `num_results`, `country` |\n| `extract_product` | 从任意电商 URL 提取结构化产品数据 | `url`, `fields` |\n| `crawl_site` | 发现站点所有页面，然后并行抓取 | `url`, `limit`, `country` |\n| `troubleshoot` | 代理故障逐步诊断 | `error_message` |\n\n---\n\n## 5 个资源\n\n智能体可随时读取的参考数据，无需消耗代理额度。\n\n| 资源 URI | 描述 |\n|----------|------|\n| `proxy://countries` | 195+ 国家代码完整列表，含城市级定位 |\n| `proxy://error-codes` | 所有类型化错误码及恢复指令 |\n| `proxy://workflows` | 常用智能体工作流模式（爬取、研究、监控） |\n| `proxy://supported-fields` | `novada_proxy_extract` 支持的所有提取字段及策略 |\n| `proxy://cost-guide` | 每个工具的额度消耗、缓存行为、成本优化技巧 |\n\n---\n\n## 快速决策指南\n\n| 我想要... | 使用工具 |\n|-----------|---------|\n| 抓取单个 URL | `novada_proxy_fetch` |\n| 同时抓取 2-20 个 URL | `novada_proxy_batch_fetch` |\n| 提取特定字段（标题、价格…） | `novada_proxy_extract` 使用 `fields` |\n| 提取任意字段（Schema 模式） | `novada_proxy_extract` 使用 `schema` |\n| 获取页面上的所有链接 | `novada_proxy_map` |\n| 爬取整个站点 | `novada_proxy_crawl` |\n| 研究某个主题 | `novada_proxy_research` |\n| 搜索 Google | `novada_proxy_search` |\n| 渲染 JS 重型页面 | `novada_proxy_render` |\n| 跨请求保持同一 IP | `novada_proxy_session` |\n| 检查代理是否正常 | `novada_proxy_status` |\n\n## 工具选择决策树\n\n```\n目标：抓取单个 URL\n  ├─ 静态 HTML 页面？                    → novada_proxy_fetch\n  ├─ 需要特定字段（价格/标题）？          → novada_proxy_extract（fields 或 schema 模式）\n  └─ React/Vue SPA / 内容为空？          → novada_proxy_render\n\n目标：批量抓取多个 URL\n  ├─ 已有 URL 列表？                     → novada_proxy_batch_fetch\n  ├─ 需要获取单页链接？                  → novada_proxy_map → novada_proxy_batch_fetch\n  └─ 需要爬取整个站点？                  → novada_proxy_crawl → novada_proxy_batch_fetch\n\n目标：研究某个主题                       → novada_proxy_research（一次调用搜索 + 抓取 + 分析）\n\n目标：网页搜索                          → novada_proxy_search → novada_proxy_batch_fetch\n\n目标：登录 + 多步骤流程                  → novada_proxy_session（相同 session_id）\n\n目标：验证代理是否正常工作               → novada_proxy_status\n```\n\n---\n\n## 三大流水线模式\n\n### 全站爬取流水线（推荐）\n\n```\nnovada_proxy_map(url, limit=50)\n        │\n        ▼\n  返回 20-50 个内部链接（1 credit，4 秒）\n        │\n        ▼\nnovada_proxy_batch_fetch(urls, concurrency=5)\n        │\n        ▼\n  并发抓取所有页面（N credits，~4 秒，比串行快 15x）\n```\n\n### 搜索研究流水线\n\n```\nnovada_proxy_search(query, num=10)\n        │\n        ▼\n  结构化 JSON：标题 + URL + 摘要\n        │\n        ▼\nnovada_proxy_batch_fetch(urls, format=\"markdown\")\n        │\n        ▼\n  全部页面内容并行返回\n```\n\n### 粘性会话 — 登录 + 多页抓取\n\n```\nsession_id = \"job_001\"\n\nnovada_proxy_session(session_id, url=\"/login\")    → 同一 IP\nnovada_proxy_session(session_id, url=\"/dashboard\") → 同一 IP\nnovada_proxy_session(session_id, url=\"/data/1\")    → 同一 IP\nnovada_proxy_session(session_id, url=\"/data/2\")    → 同一 IP\n```\n\n---\n\n## 智能体优先设计\n\n> [!NOTE]\n> Novada Proxy 是唯一专为自主 AI 智能体设计的代理 MCP。每个响应、错误和描述都为机器消费而优化。\n\n| 特性 | 含义 |\n|------|------|\n| 错误中的 `agent_instruction` | 每个错误都告诉智能体下一步该做什么 |\n| 描述中的决策树 | 每个工具都有 WHEN TO USE / USE INSTEAD 指引 |\n| `cache_hit` 元数据 | 智能体知道是否消耗了 0 额度（缓存命中） |\n| `credits_estimated` | 每个响应都内置成本追踪 |\n| 类型化错误码 | 机器可读：`BOT_DETECTION_SUSPECTED`、`PAGE_NOT_FOUND` 等 |\n| 5 个工作流提示词 | 预构建工作流：研究、爬取、提取、诊断 |\n| 5 个参考资源 | 国家、错误码、成本指南 — 随时可访问 |\n\n---\n\n## 核心特性\n\n### 1. 住宅 IP 网络\n- **200 万+ 真实设备**：Android 手机、Windows 电脑、Mac\n- **7,000+ 活跃节点**，99.9% 在线率\n- 真实家庭 IP 指纹，绕过 Cloudflare、Akamai、DataDome 检测\n\n### 2. 地理定向\n- **195+ 国家**，两字母 ISO 代码（`US`、`DE`、`JP`、`BR`...）\n- **城市级定位**：`newyork`、`london`、`tokyo`、`singapore`...\n- 同一 URL 不同国家 = 独立缓存键，互不干扰\n\n### 3. 响应缓存\n重复抓取相同 URL 不消耗代理额度：\n\n```json\n// 第一次调用（live fetch）\n\"meta\": { \"cache_hit\": false, \"latency_ms\": 1800, \"quota\": { \"credits_estimated\": 1 } }\n\n// 第二次调用（cache hit）\n\"meta\": { \"cache_hit\": true, \"cache_age_seconds\": 5, \"latency_ms\": 0 }\n```\n\n| 配置项 | 说明 |\n|--------|------|\n| 默认 TTL | 300 秒（5 分钟） |\n| 缓存键 | `url + format + country` |\n| 禁用缓存 | `PROXY4AGENT_CACHE_TTL_SECONDS=0` |\n| session_id | 有 session_id 的请求永不缓存（粘性路由需要实时调用） |\n\n### 4. 智能体优先的 JSON 输出\n所有工具返回统一结构：\n\n```json\n{\n  \"ok\": true / false,\n  \"tool\": \"工具名称\",\n  \"data\": { ... },\n  \"meta\": {\n    \"latency_ms\": 1800,\n    \"cache_hit\": false,\n    \"quota\": { \"credits_estimated\": 1 }\n  }\n}\n```\n\n### 5. 类型化错误码 + 恢复指令\n每个错误都包含 `code`（枚举）、`recoverable`（布尔）、`agent_instruction`（下一步操作）：\n\n```json\n{\n  \"ok\": false,\n  \"error\": {\n    \"code\": \"BOT_DETECTION_SUSPECTED\",\n    \"recoverable\": true,\n    \"agent_instruction\": \"Try novada_proxy_render (real browser). Or retry with a different country/session_id.\"\n  }\n}\n```\n\n| 错误码 | 含义 | 可恢复 |\n|--------|------|--------|\n| `BOT_DETECTION_SUSPECTED` | 被目标站点封锁（403） | ✓ |\n| `TLS_ERROR` | TLS/SSL 连接失败 | ✓ |\n| `TIMEOUT` | 请求超时 | ✓ |\n| `RATE_LIMITED` | HTTP 429 限速 | ✓ |\n| `NETWORK_ERROR` | DNS 解析失败 | ✗ |\n| `INVALID_INPUT` | 参数错误 | ✗ |\n| `PROVIDER_NOT_CONFIGURED` | 缺少凭证 | ✗ |\n\n### 6. 批量并发抓取\n`novada_proxy_batch_fetch` 内置信号量并发控制：\n\n```json\n// 10 个 URL，concurrency=5，wall time = ~8.8s（串行估计 ~50s）\n{\n  \"data\": {\n    \"results\": [\n      { \"url\": \"...\", \"ok\": true, \"cache_hit\": false, \"latency_ms\": 1200 },\n      { \"url\": \"...\", \"ok\": true, \"cache_hit\": true,  \"latency_ms\": 0 },\n      { \"url\": \"...\", \"ok\": false, \"error\": { \"code\": \"TLS_ERROR\" } }\n    ]\n  },\n  \"meta\": { \"latency_ms\": 8800, \"quota\": { \"credits_estimated\": 10 } }\n}\n```\n\n### 7. 多供应商支持\n\n| 供应商 | 环境变量 | 说明 |\n|--------|---------|------|\n| **Novada**（推荐） | `NOVADA_PROXY_USER` + `NOVADA_PROXY_PASS` | 最深度集成，含搜索 + 浏览器 API |\n| BrightData | `BRIGHTDATA_USER` + `BRIGHTDATA_PASS` | 完整自动定位 |\n| Smartproxy | `SMARTPROXY_USER` + `SMARTPROXY_PASS` | 完整自动定位 |\n| Oxylabs | `OXYLABS_USER` + `OXYLABS_PASS` | 完整自动定位 |\n| 通用 HTTP | `PROXY_URL=http://user:pass@host:port` | 任意代理服务商 |\n\n### 8. 渐进式降级（render_fallback）\n`novada_proxy_extract` 支持自动升级到浏览器渲染：\n\n```\n代理抓取失败（TLS / Bot检测）\n        │\n        ▼ render_fallback=true\nnovada_proxy_render（真实 Chromium）\n        │\n        ▼\ndata.extracted_via = \"render\"  （agent 知道走了哪条路径）\ndata.fetch_warning = \"Proxy fetch failed... escalated to render\"\n```\n\n---\n\n## 快速安装\n\n```bash\n# 核心（住宅代理抓取）\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_PROXY_USER=你的用户名 \\\n  -e NOVADA_PROXY_PASS=你的密码 \\\n  -- npx -y novada-proxy-mcp\n\n# 仅搜索\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_API_KEY=你的_API_Key \\\n  -- npx -y novada-proxy-mcp\n\n# 全功能（代理 + 搜索 + 浏览器渲染）\nclaude mcp add novada-proxy-mcp \\\n  -e NOVADA_PROXY_USER=你的用户名 \\\n  -e NOVADA_PROXY_PASS=你的密码 \\\n  -e NOVADA_API_KEY=你的_API_Key \\\n  -e NOVADA_BROWSER_WS=你的_Browser_WS_URL \\\n  -- npx -y novada-proxy-mcp\n```\n\n获取凭证：**[novada.com](https://www.novada.com)** -> 仪表盘 -> 住宅代理 -> 端点生成器\n\n**Cursor / Windsurf / Cline** 配置：\n```json\n{\n  \"mcpServers\": {\n    \"novada-proxy-mcp\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"novada-proxy-mcp\"],\n      \"env\": {\n        \"NOVADA_PROXY_USER\": \"你的用户名\",\n        \"NOVADA_PROXY_PASS\": \"你的密码\"\n      }\n    }\n  }\n}\n```\n\n---\n\n## 工具参数速查\n\n### novada_proxy_fetch\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 目标 URL |\n| `country` | string | — | 国家代码（`US`、`DE`、`JP`...） |\n| `city` | string | — | 城市（`newyork`、`london`...） |\n| `session_id` | string | — | 复用同一 IP（不含连字符，最多 64 字符） |\n| `format` | string | `markdown` | `markdown`（去 HTML）或 `raw`（原始 HTML） |\n| `timeout` | number | `60` | 超时秒数（1-120） |\n\n### novada_proxy_batch_fetch\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `urls` | string[] | 必填 | 2-20 个 URL |\n| `concurrency` | number | `3` | 并发数（1-5） |\n| `country` | string | — | 对所有 URL 使用相同国家 |\n| `format` | string | `markdown` | `markdown` 或 `raw` |\n\n### novada_proxy_extract\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 目标 URL |\n| `fields` | string[] | 必填 | 要提取的字段（`title`、`price`、`description`、`rating`...） |\n| `render_fallback` | boolean | `false` | 代理失败时自动切换到浏览器渲染 |\n| `country` | string | — | 地理定向 |\n\n### novada_proxy_map\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 起始 URL |\n| `limit` | number | `50` | 最多返回 URL 数（10-200） |\n| `include_external` | boolean | `false` | 包含站外链接 |\n\n### novada_proxy_session\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `session_id` | string | 必填 | 会话 ID（不含连字符，最多 64 字符） |\n| `url` | string | 必填 | 目标 URL |\n| `verify_sticky` | boolean | `false` | 验证 IP 一致性（需额外 15-25 秒） |\n| `country` | string | — | 国家代码 |\n\n### novada_proxy_search\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `query` | string | 必填 | 搜索关键词 |\n| `num` | number | `10` | 结果数量（1-20） |\n| `country` | string | — | 本地化结果（`us`、`de`、`jp`...） |\n| `language` | string | — | 语言（`en`、`zh`、`de`...） |\n\n### novada_proxy_render [BETA]\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 目标 URL |\n| `format` | string | `markdown` | `markdown` · `html` · `text` |\n| `wait_for` | string | — | 等待 CSS 选择器后再提取（如 `.product-title`） |\n| `timeout` | number | `60` | 超时秒数（5-120） |\n\n### novada_proxy_crawl\n递归 BFS 爬取站点，从起始 URL 出发，按深度逐层发现链接，返回完整 URL 树及元数据。\n\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 起始 URL |\n| `depth` | number | `2` | BFS 深度（1-5） |\n| `limit` | number | `50` | 最大爬取页数（10-200） |\n| `include_content` | boolean | `false` | 同时返回每个页面的内容 |\n| `country` | string | — | 地理定向所有请求 |\n| `format` | string | `markdown` | `include_content: true` 时的内容格式 |\n| `timeout` | number | `60` | 每页超时秒数 |\n\n**适用场景：** 全站抓取、站点地图生成、内容索引 — 需要抓取**多个页面**时使用。\n\n**改用 `novada_proxy_map` 的情况：** 只需要**单页**链接（一层深度）。Map 更快、更省额度。\n\n**组合使用：** 将 `data.urls[]` 传入 `novada_proxy_batch_fetch` 并发抓取。\n\n**请求示例：**\n```json\n{\n  \"url\": \"https://example.com\",\n  \"depth\": 2,\n  \"limit\": 50,\n  \"include_content\": false\n}\n```\n\n**响应：** `data.pages[]`（url、depth、status_code、total_links），`data.urls[]`（扁平数组，可直接传给 `novada_proxy_batch_fetch`）\n\n---\n\n### novada_proxy_research\n一键深度研究工具 — 搜索网络、抓取排名靠前的结果，返回含来源预览的结构化分析。智能体可对 findings 进行进一步综合分析。\n\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `query` | string | 必填 | 研究问题或主题 |\n| `depth` | string | `\"standard\"` | `\"quick\"`（3 个来源）、`\"standard\"`（5 个）、`\"deep\"`（10 个） |\n| `country` | string | — | 本地化搜索结果 |\n| `timeout` | number | `60` | 超时秒数 |\n\n**需要：** `NOVADA_API_KEY`（Google 搜索）+ 代理凭证（抓取来源页面）\n\n**适用场景：** 研究问题、主题调研、竞品分析、事实核查 — 需要一次调用获取多个来源内容时。\n\n**改用 `novada_proxy_search` 的情况：** 只需要搜索结果 URL，不需要完整页面内容。\n\n**组合使用：** 对 `data.urls[]` 中的特定 URL 调用 `novada_proxy_fetch` 进行深度阅读。\n\n**注意：** `findings_summary` 是各来源内容的拼接预览 — 智能体应分析 `findings[]` 进行实质性综合。\n\n**请求示例：**\n```json\n{\n  \"query\": \"2026年最佳住宅代理服务商\",\n  \"depth\": \"standard\"\n}\n```\n\n**响应：** `data.findings[]`（title、url、snippet、content_preview），`data.urls[]`（可链式传给其他工具），`data.findings_summary`\n\n---\n\n### novada_proxy_extract — Schema 模式（LLM 提取）\n\n除 `fields`（启发式提取）外，`novada_proxy_extract` 还支持 `schema` 参数，通过智能体自身的 LLM 提取任意字段 — **零额外 API 费用**。\n\n传入 `schema` 替代 `fields`，工具返回清洗后的页面内容 + 提取提示词 — 由你的智能体完成提取。\n\n| 参数 | 类型 | 默认 | 说明 |\n|------|------|------|------|\n| `url` | string | 必填 | 目标 URL |\n| `schema` | object | — | 键 = 字段名，值 = 字段描述。替代 `fields` 使用。 |\n| `render_fallback` | boolean | `false` | 代理失败时自动切换到浏览器渲染 |\n| `country` | string | — | 地理定向 |\n| `timeout` | number | `60` | 超时秒数 |\n\n**请求示例：**\n```json\n{\n  \"url\": \"https://example.com/product\",\n  \"schema\": {\n    \"product_name\": \"完整的产品名称\",\n    \"price\": \"当前价格（含货币符号）\",\n    \"warranty\": \"保修条款和期限\",\n    \"return_policy\": \"退货政策摘要\"\n  }\n}\n```\n\n**响应：** `data.mode = \"llm_extract\"`，`data.content`（清洗后的 Markdown 内容），`data.extraction_prompt`（供智能体遵循并提取字段的指令）\n\n**安全限制：** Schema 键名只能包含字母、数字、下划线（a-z、0-9、_），最多 50 字符；值最多 200 字符。\n\n---\n\n## 使用场景\n\n**AI 智能体需要：**\n- 抓取电商网站（Amazon、eBay、Walmart）不被封锁\n- 跨国家监控价格变动\n- 访问 195+ 国家的地区限制内容\n- 对 Cloudflare/Akamai 保护站点进行竞争情报收集\n- 执行多步登录流程并保持同一 IP\n- 渲染无真实浏览器就返回空白的 JS 页面\n- Google 搜索返回结构化 JSON 结果\n\n**开发者构建：**\n- AI 驱动的网页研究工具\n- 价格比较智能体\n- 全站内容爬取管道\n- SEO 监控仪表盘\n- 市场调研自动化\n\n---\n\n## 已验证可用\n\n**电商：** Amazon、eBay、Walmart、Etsy、Shopify  \n**职业网络：** LinkedIn  \n**反机器人保护：** Cloudflare 站点、Akamai、DataDome  \n**新闻内容：** HackerNews、Reddit、BBC、CNN、NYTimes  \n**科技：** GitHub、Wikipedia、Stack Overflow、IMDB\n\n---\n\n## 反馈与支持\n\n- **邮箱：** [support@novada.com](mailto:support@novada.com)\n- **GitHub Issues：** [github.com/NovadaLabs/Novada-proxy/issues](https://github.com/NovadaLabs/Novada-proxy/issues)\n- **官网：** [novada.com](https://www.novada.com)\n\n---\n\n## 许可证\n\nMIT © [Novada](https://www.novada.com)\n",
  "bytes": 46493,
  "sha": "fc7021ddfcadf1a9c02776977ab00e991844181c4f277ed617049b09daea6c2f",
  "repo_slug": "novadalabs/proxy4agent",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_novadalabs_proxy4agents_mcp_336c4f63/readme"
}