alterlab-mcp-server 1.7.0 → 1.9.0

package/README.md

@@ -26,7 +26,7 @@
 ### Claude Code
 
 ```bash
-claude mcp add alterlab -- npx -y alterlab-mcp-server
+claude mcp add alterlab -- npx -y alterlab-mcp-server@latest
 ```
 
 Then set your API key: `export ALTERLAB_API_KEY=sk_live_...` or add it to `.claude.json` (see [full setup](#install-in-claude-desktop--claude-code) below).
@@ -68,9 +68,9 @@ AlterLab uses a multi-tier scraping architecture. It automatically selects the c
 
 1. **Curl** ($0.0002/req) — Direct HTTP for static pages, RSS feeds, public APIs
 2. **HTTP** ($0.0003/req) — TLS fingerprint rotation for moderately protected sites
-3. **Stealth** ($0.0005/req) — Browser impersonation for Cloudflare/DataDome-protected sites
-4. **Light JS** ($0.0007/req) — Lightweight JS extraction from server-rendered HTML
-5. **Browser** ($0.001/req) — Full headless Chromium for JavaScript-heavy SPAs
+3. **Stealth** ($0.002/req) — Browser impersonation for Cloudflare/DataDome-protected sites
+4. **Light JS** ($0.0025/req) — Lightweight JS extraction from server-rendered HTML
+5. **Browser** ($0.004/req) — Full headless Chromium for JavaScript-heavy SPAs
 
 Auto mode starts at Tier 1 and escalates only when blocked. Most websites resolve at Tiers 1-2, so **$1 gets you 1,000 to 5,000 scrapes** depending on the sites you target.
 
@@ -87,7 +87,7 @@ Add to your Claude config file (`~/.claude.json` for Claude Code, or Settings fo
   "mcpServers": {
     "alterlab": {
       "command": "npx",
-      "args": ["-y", "alterlab-mcp-server"],
+      "args": ["-y", "alterlab-mcp-server@latest"],
       "env": {
         "ALTERLAB_API_KEY": "sk_live_your_key_here"
       }
@@ -105,7 +105,7 @@ Add to `.cursor/mcp.json` in your project root:
   "mcpServers": {
     "alterlab": {
       "command": "npx",
-      "args": ["-y", "alterlab-mcp-server"],
+      "args": ["-y", "alterlab-mcp-server@latest"],
       "env": {
         "ALTERLAB_API_KEY": "sk_live_your_key_here"
       }
@@ -123,7 +123,7 @@ Add to Windsurf MCP settings (`~/.codeium/windsurf/mcp_config.json`):
   "mcpServers": {
     "alterlab": {
       "command": "npx",
-      "args": ["-y", "alterlab-mcp-server"],
+      "args": ["-y", "alterlab-mcp-server@latest"],
       "env": {
         "ALTERLAB_API_KEY": "sk_live_your_key_here"
       }
@@ -160,19 +160,37 @@ Scrape a URL and return its content as markdown, text, HTML, or JSON. Automatica
 |---|---|---|---|
 | `url` | string | required | URL to scrape |
 | `mode` | `auto` \| `html` \| `js` \| `pdf` \| `ocr` | `auto` | Scraping mode |
-| `formats` | `(text\|json\|html\|markdown)[]` | `["markdown"]` | Output formats |
-| `render_js` | boolean | `false` | Use headless browser (+3 credits) |
-| `use_proxy` | boolean | `false` | Premium proxy (+1 credit) |
-| `proxy_country` | string | — | ISO country code for geo-targeting (e.g., `US`, `DE`) |
-| `wait_for` | string | — | CSS selector to wait for before extraction |
-| `timeout` | number | `90` | Timeout in seconds (1-300) |
-| `include_raw_html` | boolean | `false` | Include raw HTML alongside formatted content |
-| `session_id` | string (UUID) | — | Stored session ID for authenticated scraping |
-| `cookies` | `Record<string, string>` | &mdash; | Inline cookies for one-off authenticated requests |
+| `method` / `body` / `content_type` / `headers` | enum / string / enum / object | `GET` | POST support (1.5x cost) and custom target headers |
+| `formats` | `(text\|json\|json_v2\|html\|markdown\|rag\|content\|raw)[]` | `["markdown"]` | Output formats |
+| `extraction_schema` / `extraction_prompt` | object / string | &mdash; | LLM extraction (+$0.001) |
+| `extraction_profile` / `extraction_template` | enum | &mdash; | `auto`, `product`, `article`, `job_posting`, `faq`, `recipe`, `event`, `ecommerce_homepage`, `directory_listing` (`template` is a deprecated alias) |
+| `extraction_provider` / `extraction_model` | enum / string | &mdash; | BYOK LLM selection |
+| `evidence`, `promote_schema_org`, `filter_content` | boolean | &mdash; | Extraction behaviour |
+| `cache`, `cache_ttl`, `force_refresh` | boolean / number / boolean | &mdash; | Response caching (`cache_ttl` 60-86400) |
+| `render_js` | boolean \| `"auto"` | API default | Headless browser (forces Browser tier, $0.004) |
+| `use_proxy`, `proxy_country` | boolean, string | &mdash; | Premium proxy (+$0.0002) and geo-targeting |
+| `use_own_proxy`, `use_system_proxy`, `proxy_integration_id` | boolean, boolean, string | &mdash; | Bring-your-own-proxy selection |
+| `skip_tls_verification` | boolean | &mdash; | Omit (recommended) = verify, fall back on invalid certs; `true` skip, `false` require valid cert |
+| `wait_for`, `wait_until`, `wait_condition` | string | &mdash; | Selector / load-event waits |
+| `actions` | object[] (max 20) | &mdash; | Browser actions: `wait`, `wait_for`, `click`, `fill`, `press`, `scroll`, `infinite_scroll`, `screenshot`, `evaluate` |
+| `screenshot`, `generate_pdf`, `ocr` | boolean | &mdash; | Add-ons (+$0.0002 / +$0.0004 / +$0.001) |
+| `scroll_to_load`, `scroll_count`, `enable_scroll` | boolean / 1-10 / boolean | &mdash; | Lazy-load handling |
+| `include_iframes`, `flatten_shadow_dom`, `block_images`, `remove_cookie_banners` | boolean | &mdash; | Rendering options |
+| `section_filter` | object | &mdash; | Filter for `json_v2` sections |
+| `session_id`, `cookies`, `session_headers` | UUID, object, object | &mdash; | Authenticated scraping |
+| `sticky_session`, `sticky_session_ttl` | string, 300-7200 | &mdash; | Reuse cookies and exit IP across calls (paid plans) |
+| `location` | `{country, language}` | &mdash; | Geo-targeting |
+| `cost_controls` | object | &mdash; | `force_tier`, `max_tier`, `max_credits`, `prefer_cost`, `prefer_speed`, `fail_fast`, `time_budget` (`prefer_cost`, `prefer_speed`, `fail_fast` also accepted at top level) |
+| `embeddings` | object | &mdash; | `enabled`, `model`, `chunk_size`, `chunk_overlap` (+$0.001/page) |
+| `sync_policy` | `auto` \| `wait_until_deadline` | `auto` | Wait behaviour for long scrapes |
+| `timeout`, `max_response_bytes`, `include_raw_html` | number, number, boolean | `90`, 5 MB, `false` | Limits and raw output |
+| `estimate_first` | boolean | `false` | Run a free cost estimate first |
+
+Not exposed: `source` (dashboard tracking tag), `sync` (the tool is always synchronous), `webhook_url` (use `alterlab_batch`/`alterlab_crawl` webhooks). If a scrape outlives the ~85s synchronous window the tool returns a `job_id`; fetch it with `alterlab_get_job`.
 
 ### `alterlab_extract` &mdash; Extract Structured Data
 
-Extract structured fields from any webpage using pre-built profiles or custom JSON Schema. Returns clean JSON &mdash; ready for databases, spreadsheets, or downstream processing.
+Extract structured fields from HTML, text or markdown content using pre-built profiles or custom JSON Schema. Returns clean JSON &mdash; ready for databases, spreadsheets, or downstream processing.
 
 ```
 "Extract the product name, price, and rating from this Amazon page"
@@ -180,12 +198,17 @@ Extract structured fields from any webpage using pre-built profiles or custom JS
 
 | Parameter | Type | Default | Description |
 |---|---|---|---|
-| `url` | string | required | URL to extract from |
-| `extraction_profile` | enum | `auto` | Profile: `product`, `article`, `job_posting`, `faq`, `recipe`, `event` |
+| `content` | string (max 500,000) | required | HTML, text or markdown you already have (this tool does not fetch a URL) |
+| `content_type` | `html` \| `text` \| `markdown` | `html` | Type of `content` |
+| `extraction_profile` / `extraction_template` | enum | &mdash; | Profile: `auto`, `product`, `article`, `job_posting`, `faq`, `recipe`, `event`, `ecommerce_homepage`, `directory_listing` |
 | `extraction_schema` | object | &mdash; | Custom JSON Schema for structured output |
 | `extraction_prompt` | string | &mdash; | Natural language extraction instructions |
-| `render_js` | boolean | `false` | Use headless browser |
-| `use_proxy` | boolean | `false` | Premium proxy |
+| `extraction_provider` / `extraction_model` | enum / string | &mdash; | BYOK LLM selection |
+| `formats` | enum[] | `["json"]` | Output formats |
+| `source_url`, `evidence` | string, boolean | &mdash; | Context URL and provenance |
+| `cache`, `cache_ttl` | `auto` \| `skip` \| `only`, number | `auto` | Extraction result cache |
+
+To scrape and extract in one step, use `alterlab_scrape` with `extraction_schema`.
 
 **Extraction profiles:**
 
@@ -209,6 +232,10 @@ Take a full-page screenshot of any URL. Returns a PNG image directly in the conv
 | `url` | string | required | URL to screenshot |
 | `wait_for` | string | &mdash; | CSS selector to wait for before capture |
 | `wait_until` | enum | `networkidle` | `networkidle`, `domcontentloaded`, or `load` |
+| `timeout` | number | `90` | Timeout in seconds (1-300) |
+| `use_proxy`, `proxy_country` | boolean, string | &mdash; | Premium proxy and geo-targeting |
+| `session_id`, `cookies` | UUID, object | &mdash; | Screenshot pages behind a login |
+| `location` | `{country, language}` | &mdash; | Geo-targeting |
 
 ### `alterlab_estimate_cost` &mdash; Estimate Before You Scrape
 
@@ -222,8 +249,14 @@ Check how much a scrape will cost before running it. Returns the predicted tier,
 |---|---|---|---|
 | `url` | string | required | URL to estimate |
 | `mode` | enum | `auto` | Scraping mode |
-| `render_js` | boolean | `false` | Include JS rendering cost |
-| `use_proxy` | boolean | `false` | Include proxy cost |
+| `method` | `GET` \| `POST` | `GET` | POST costs 1.5x |
+| `render_js` | boolean \| `"auto"` | `false` | Include JS rendering cost |
+| `use_proxy`, `use_own_proxy` | boolean | `false` | Include proxy cost / BYOP discount |
+| `screenshot`, `generate_pdf`, `ocr` | boolean | &mdash; | Include add-on cost |
+
+### `alterlab_get_job` &mdash; Fetch an Async Job
+
+Fetch the status and result of a scrape that returned a `job_id` (a scrape that outlived the synchronous wait window). Parameter: `job_id` (string, required).
 
 ### `alterlab_check_balance` &mdash; Check Your Credits
 
@@ -253,8 +286,12 @@ Create a new stored session with cookies from a logged-in browser. The session i
 |---|---|---|---|
 | `name` | string | required | Human-readable name (e.g., "My Amazon Account") |
 | `domain` | string | required | Domain (e.g., "amazon.com") |
-| `cookies` | `Record<string, string>` | required | Cookie key-value pairs |
-| `user_agent` | string | &mdash; | Browser User-Agent to use with this session |
+| `consent` | boolean | required | Must be `true`: explicit GDPR consent to store the cookies (the API rejects creation otherwise) |
+| `cookies` | `Record<string,string>` \| cookie objects[] | &mdash; | Cookies as key-value pairs or `{name, value, domain, path, ...}` objects |
+| `headers` | `Record<string,string>` | &mdash; | Custom headers (e.g. a User-Agent) |
+| `expires_at`, `notes` | string | &mdash; | Expiry (ISO 8601) and notes |
+| `auto_refresh_enabled`, `notify_before_expiry`, `notify_on_failure` | boolean | `true` | Health checks and notifications |
+| `organization_id`, `shared` | UUID, boolean | &mdash; | Organization sharing |
 
 ### `alterlab_validate_session` &mdash; Validate a Session
 
@@ -355,15 +392,20 @@ No subscriptions. No monthly minimums. Add balance and use it whenever you need
 |---|---|---|---|
 | Curl | Direct HTTP | $0.0002 | Static pages, RSS feeds, public APIs |
 | HTTP | TLS fingerprinting | $0.0003 | Sites with basic bot detection |
-| Stealth | Browser impersonation | $0.0005 | Cloudflare, DataDome, PerimeterX protected sites |
-| Light JS | JSON extraction | $0.0007 | Server-rendered pages needing structured data |
-| Browser | Headless Chromium | $0.001 | Full JavaScript SPAs (React, Angular, Vue) |
+| Stealth | Browser impersonation | $0.002 | Cloudflare, DataDome, PerimeterX protected sites |
+| Light JS | JSON extraction | $0.0025 | Server-rendered pages needing structured data |
+| Browser | Headless Chromium | $0.004 | Full JavaScript SPAs (React, Angular, Vue) |
 
 ### Optional Add-Ons
 
 | Add-On | Extra Cost | Description |
 |---|---|---|
-| JavaScript Rendering | +$0.0006 | Headless Chromium for dynamic content |
+| JavaScript Rendering | forces Browser tier | No separate add-on: `render_js` bills the Browser tier ($0.004) |
+| PDF Generation | +$0.0004 | PDF of the rendered page |
+| LLM Extraction / Embeddings | +$0.001 | `extraction_schema` / `extraction_prompt`, `embeddings` |
+| POST requests | x1.5 | `method: "POST"` costs 1.5x the tier price |
+| Own proxy (BYOP) | -20% | `use_own_proxy` discount on the tier price |
+| Search | $0.001 / $0.004 | duckduckgo / google and bing engines |
 | Screenshot Capture | +$0.0002 | Full-page PNG screenshot |
 | Premium Proxy | +$0.0002 | Geo-targeted residential proxy (195+ countries) |
 | OCR Text Extraction | +$0.001 | Extract text from images on the page |
@@ -385,7 +427,7 @@ No subscriptions. No monthly minimums. Add balance and use it whenever you need
 
 ### How do I add web scraping to Claude, Cursor, or Windsurf?
 
-Install the AlterLab MCP server. For Claude Code, run `claude mcp add alterlab -- npx -y alterlab-mcp-server` and set your `ALTERLAB_API_KEY`. For Claude Desktop, Cursor, or Windsurf, add the JSON config block to your MCP settings file. Once configured, your AI assistant can scrape any URL, extract structured data, and take screenshots directly in conversation.
+Install the AlterLab MCP server. For Claude Code, run `claude mcp add alterlab -- npx -y alterlab-mcp-server@latest` and set your `ALTERLAB_API_KEY`. For Claude Desktop, Cursor, or Windsurf, add the JSON config block to your MCP settings file. Once configured, your AI assistant can scrape any URL, extract structured data, and take screenshots directly in conversation.
 
 ### Can Claude scrape websites that are behind Cloudflare or anti-bot protection?
 
@@ -393,11 +435,11 @@ Yes. AlterLab automatically handles Cloudflare, DataDome, PerimeterX, Akamai, an
 
 ### What is an MCP server and how does it work with Claude?
 
-MCP (Model Context Protocol) is Anthropic's open standard for connecting AI assistants to external tools and data sources. An MCP server is a small program that exposes tools &mdash; like web scraping &mdash; that Claude, Cursor, or Windsurf can call during a conversation. The AlterLab MCP server gives your AI assistant 5 tools: scrape, extract, screenshot, estimate cost, and check balance.
+MCP (Model Context Protocol) is Anthropic's open standard for connecting AI assistants to external tools and data sources. An MCP server is a small program that exposes tools &mdash; like web scraping &mdash; that Claude, Cursor, or Windsurf can call during a conversation. The AlterLab MCP server gives your AI assistant 23 tools: scrape, extract, screenshot, crawl, search, map, batch scraping, session management, beta features, and more.
 
 ### How is AlterLab different from Firecrawl, ScrapingBee, or Apify MCP servers?
 
-AlterLab starts at $0.0002 per request &mdash; 5-20x cheaper than most scraping APIs &mdash; because it only uses expensive browser rendering when a site actually requires it. Smart tier escalation means you pay for what each site needs, not the maximum. AlterLab also includes built-in structured data extraction with pre-built profiles (product, article, job posting, etc.) at no extra cost.
+AlterLab starts at $0.0002 per request &mdash; 5-20x cheaper than most scraping APIs &mdash; because it only uses expensive browser rendering when a site actually requires it. Smart tier escalation means you pay for what each site needs, not the maximum. AlterLab also includes built-in structured data extraction with pre-built profiles (product, article, job posting, etc.).
 
 ### Can I scrape Amazon, Walmart, and other e-commerce sites from Claude?
 
@@ -421,7 +463,7 @@ Free-tier accounts have rate limits. Adding any balance removes rate limits. The
 
 ### Can I use this MCP server for large-scale scraping?
 
-Yes. The MCP server processes one request at a time through the conversation interface, but you can build agentic workflows that scrape many URLs sequentially. For batch processing, use the AlterLab API directly or the [n8n integration](https://www.npmjs.com/package/n8n-nodes-alterlab).
+Yes. For parallel scraping, use `alterlab_batch` to scrape up to 100 URLs in a single request — much faster than sequential calls. For crawling entire domains, use `alterlab_crawl`. You can also build agentic workflows that scrape many URLs sequentially, or use the [n8n integration](https://www.npmjs.com/package/n8n-nodes-alterlab) for workflow automation.
 
 ---
 

package/dist/auth.d.ts

@@ -0,0 +1,30 @@
+/**
+ * OAuth 2.0 Device Authorization Grant (RFC 8628) client-side flow.
+ *
+ * Authentication priority chain:
+ *   1. ALTERLAB_API_KEY environment variable
+ *   2. ~/.alterlab/config.json
+ *   3. Interactive auth (TTY only):
+ *      a. 5-second countdown — press any key to switch to manual paste
+ *      b. Device flow (POST /auth/device → open browser → poll /auth/token)
+ *      c. Fallback: manual API key paste
+ *
+ * All user-facing output goes to stderr — stdout is reserved for MCP protocol.
+ */
+import { type Config } from "./config.js";
+/**
+ * Ensure a valid AlterLab API key is available and return a Config object.
+ *
+ * Resolution order:
+ *   1. ALTERLAB_API_KEY environment variable
+ *   2. ~/.alterlab/config.json
+ *   3. Interactive auth (only when running in a TTY):
+ *      a. 5-second countdown — press any key to switch to manual paste
+ *      b. OAuth 2.0 Device Authorization Grant flow (if countdown expires)
+ *      c. Manual API key paste (if keypress during countdown, or device flow fails)
+ *
+ * When not running in a TTY (e.g., as an MCP server subprocess), emits a
+ * helpful error on stderr and exits with code 1 if no key is found.
+ */
+export declare function ensureAuth(): Promise<Config>;
+//# sourceMappingURL=auth.d.ts.map

package/dist/auth.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auth.d.ts","sourceRoot":"","sources":["../src/auth.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAMH,OAAO,EACL,KAAK,MAAM,EAKZ,MAAM,aAAa,CAAC;AAuXrB;;;;;;;;;;;;;GAaG;AACH,wBAAsB,UAAU,IAAI,OAAO,CAAC,MAAM,CAAC,CA0FlD"}