@spicrawl/mcp 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+All notable changes to `@spicrawl/mcp` are documented here. This project follows
+[Semantic Versioning](https://semver.org/).
+
+## 0.1.0 — 2026-10-01
+
+First public release of the Spicrawl MCP server, published to npm as `@spicrawl/mcp` from https://github.com/Spicrawl/mcp with an npm provenance attestation.
+
+- `npx -y @spicrawl/mcp` runs the stdio server for any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, Codex, …), keyed by `SPICRAWL_API_KEY`. Installed globally, the command is `spicrawl-mcp` (`spicrawl-mcp-server` is an alias).
+- `spicrawl-mcp --http` (or `node dist/http.js`) runs the Streamable HTTP server behind the hosted endpoint at https://mcp.spicrawl.com/mcp: per-caller bearer-token auth validated against the API, sessions pinned to the key that opened them, idle-session eviction and a `/healthz` liveness route.
+- 25 tools: `spicrawl_scrape`; batch jobs (`spicrawl_batch_submit`, `_list`, `_status`, `_results`, `_task_content`, `_cancel`, `_retry`, `_add_items`, `_close`); browser sessions (`spicrawl_session_create`, `_list`, `_get`, `_context`, `_release`, `_delete`); usage and request history (`spicrawl_usage`, `_usage_summary`, `_usage_reconciliation`, `spicrawl_requests_list`, `spicrawl_request_get`); `spicrawl_browser_connect_url` (coming soon); and the docs (`spicrawl_docs_search`, `_read`, `_index`).
+- Tools refuse unknown arguments instead of dropping them, and surface the platform's error codes and guidance.
+- Screenshots come back as MCP image blocks and printed pages (`format: "pdf"`) as PDF resource blocks.
+- `--version` and `--help`. The version reported to MCP clients and in the `User-Agent` (`spicrawl-mcp/<version>`) is read from package.json.
+
+Previously developed in Spicrawl's private repository as the unpublished `spicrawl-mcp-server` 0.2.0; this is the same server under its public name.

package/LICENSE

@@ -0,0 +1,61 @@
+Apache License
+
+Version 2.0, January 2004
+
+http://www.apache.org/licenses/
+
+TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+1. Definitions.
+
+"License" shall mean the terms and conditions for use, reproduction, and distribution as defined by Sections 1 through 9 of this document.
+
+"Licensor" shall mean the copyright owner or entity authorized by the copyright owner that is granting the License.
+
+"Legal Entity" shall mean the union of the acting entity and all other entities that control, are controlled by, or are under common control with that entity. For the purposes of this definition, "control" means (i) the power, direct or indirect, to cause the direction or management of such entity, whether by contract or otherwise, or (ii) ownership of fifty percent (50%) or more of the outstanding shares, or (iii) beneficial ownership of such entity.
+
+"You" (or "Your") shall mean an individual or Legal Entity exercising permissions granted by this License.
+
+"Source" form shall mean the preferred form for making modifications, including but not limited to software source code, documentation source, and configuration files.
+
+"Object" form shall mean any form resulting from mechanical transformation or translation of a Source form, including but not limited to compiled object code, generated documentation, and conversions to other media types.
+
+"Work" shall mean the work of authorship, whether in Source or Object form, made available under the License, as indicated by a copyright notice that is included in or attached to the work (an example is provided in the Appendix below).
+
+"Derivative Works" shall mean any work, whether in Source or Object form, that is based on (or derived from) the Work and for which the editorial revisions, annotations, elaborations, or other modifications represent, as a whole, an original work of authorship. For the purposes of this License, Derivative Works shall not include works that remain separable from, or merely link (or bind by name) to the interfaces of, the Work and Derivative Works thereof.
+
+"Contribution" shall mean any work of authorship, including the original version of the Work and any modifications or additions to that Work or Derivative Works thereof, that is intentionally submitted to Licensor for inclusion in the Work by the copyright owner or by an individual or Legal Entity authorized to submit on behalf of the copyright owner. For the purposes of this definition, "submitted" means any form of electronic, verbal, or written communication sent to the Licensor or its representatives, including but not limited to communication on electronic mailing lists, source code control systems, and issue tracking systems that are managed by, or on behalf of, the Licensor for the purpose of discussing and improving the Work, but excluding communication that is conspicuously marked or otherwise designated in writing by the copyright owner as "Not a Contribution."
+
+"Contributor" shall mean Licensor and any individual or Legal Entity on behalf of whom a Contribution has been received by Licensor and subsequently incorporated within the Work.
+
+2. Grant of Copyright License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable copyright license to reproduce, prepare Derivative Works of, publicly display, publicly perform, sublicense, and distribute the Work and such Derivative Works in Source or Object form.
+
+3. Grant of Patent License. Subject to the terms and conditions of this License, each Contributor hereby grants to You a perpetual, worldwide, non-exclusive, no-charge, royalty-free, irrevocable (except as stated in this section) patent license to make, have made, use, offer to sell, sell, import, and otherwise transfer the Work, where such license applies only to those patent claims licensable by such Contributor that are necessarily infringed by their Contribution(s) alone or by combination of their Contribution(s) with the Work to which such Contribution(s) was submitted. If You institute patent litigation against any entity (including a cross-claim or counterclaim in a lawsuit) alleging that the Work or a Contribution incorporated within the Work constitutes direct or contributory patent infringement, then any patent licenses granted to You under this License for that Work shall terminate as of the date such litigation is filed.
+
+4. Redistribution. You may reproduce and distribute copies of the Work or Derivative Works thereof in any medium, with or without modifications, and in Source or Object form, provided that You meet the following conditions:
+
+You must give any other recipients of the Work or Derivative Works a copy of this License; and
+
+You must cause any modified files to carry prominent notices stating that You changed the files; and
+
+You must retain, in the Source form of any Derivative Works that You distribute, all copyright, patent, trademark, and attribution notices from the Source form of the Work, excluding those notices that do not pertain to any part of the Derivative Works; and
+
+If the Work includes a "NOTICE" text file as part of its distribution, then any Derivative Works that You distribute must include a readable copy of the attribution notices contained within such NOTICE file, excluding those notices that do not pertain to any part of the Derivative Works, in at least one of the following places: within a NOTICE text file distributed as part of the Derivative Works; within the Source form or documentation, if provided along with the Derivative Works; or, within a display generated by the Derivative Works, if and wherever such third-party notices normally appear. The contents of the NOTICE file are for informational purposes only and do not modify the License. You may add Your own attribution notices within Derivative Works that You distribute, alongside or as an addendum to the NOTICE text from the Work, provided that such additional attribution notices cannot be construed as modifying the License. You may add Your own copyright statement to Your modifications and may provide additional or different license terms and conditions for use, reproduction, or distribution of Your modifications, or for any such Derivative Works as a whole, provided Your use, reproduction, and distribution of the Work otherwise complies with the conditions stated in this License.
+
+5. Submission of Contributions. Unless You explicitly state otherwise, any Contribution intentionally submitted for inclusion in the Work by You to the Licensor shall be under the terms and conditions of this License, without any additional terms or conditions. Notwithstanding the above, nothing herein shall supersede or modify the terms of any separate license agreement you may have executed with Licensor regarding such Contributions.
+
+6. Trademarks. This License does not grant permission to use the trade names, trademarks, service marks, or product names of the Licensor, except as required for reasonable and customary use in describing the origin of the Work and reproducing the content of the NOTICE file.
+
+7. Disclaimer of Warranty. Unless required by applicable law or agreed to in writing, Licensor provides the Work (and each Contributor provides its Contributions) on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of using or redistributing the Work and assume any risks associated with Your exercise of permissions under this License.
+
+8. Limitation of Liability. In no event and under no legal theory, whether in tort (including negligence), contract, or otherwise, unless required by applicable law (such as deliberate and grossly negligent acts) or agreed to in writing, shall any Contributor be liable to You for damages, including any direct, indirect, special, incidental, or consequential damages of any character arising as a result of this License or out of the use or inability to use the Work (including but not limited to damages for loss of goodwill, work stoppage, computer failure or malfunction, or any and all other commercial damages or losses), even if such Contributor has been advised of the possibility of such damages.
+
+9. Accepting Warranty or Additional Liability. While redistributing the Work or Derivative Works thereof, You may choose to offer, and charge a fee for, acceptance of support, warranty, indemnity, or other liability obligations and/or rights consistent with this License. However, in accepting such obligations, You may act only on Your own behalf and on Your sole responsibility, not on behalf of any other Contributor, and only if You agree to indemnify, defend, and hold each Contributor harmless for any liability incurred by, or claims asserted against, such Contributor by reason of your accepting any such warranty or additional liability.
+
+END OF TERMS AND CONDITIONS
+
+Copyright 2026 Spicrawl
+
+Licensed under the Apache License, Version 2.0 (the "License"); you may not use
+this file except in compliance with the License. You may obtain a copy of the
+License at http://www.apache.org/licenses/LICENSE-2.0

package/README.md

@@ -1,3 +1,252 @@
-# Temporary Holding Version
+# Spicrawl MCP Server: Web Scraping Tools for AI Agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The official [Model Context Protocol](https://modelcontextprotocol.io) server for [Spicrawl](https://spicrawl.com), the web scraping API for AI agents and LLMs. Connect it to Claude Code, Claude Desktop, Cursor, VS Code, Codex or any MCP client, and your agent can scrape pages to Markdown, extract structured data, run batch jobs over thousands of URLs, keep browser sessions and read the Spicrawl docs, all as native tools.
+
+[![npm version](https://img.shields.io/npm/v/@spicrawl/mcp.svg)](https://www.npmjs.com/package/@spicrawl/mcp)
+[![license](https://img.shields.io/npm/l/@spicrawl/mcp.svg)](https://www.npmjs.com/package/@spicrawl/mcp)
+[![CI](https://github.com/Spicrawl/mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/Spicrawl/mcp/actions/workflows/ci.yml)
+[![docs](https://img.shields.io/badge/docs-docs.spicrawl.com-blue.svg)](https://docs.spicrawl.com/agents/mcp)
+
+**[Docs](https://docs.spicrawl.com/agents/mcp)** · **[Get an API key](https://app.spicrawl.com/signup)** · **[GitHub](https://github.com/Spicrawl/mcp)** · **[SDK](https://github.com/Spicrawl/sdk)** · **[CLI](https://github.com/Spicrawl/cli)** · **[Changelog](https://github.com/Spicrawl/mcp/blob/main/CHANGELOG.md)**
+
+## Two ways to connect
+
+| | Hosted endpoint | Local (stdio) |
+|---|---|---|
+| What | `https://mcp.spicrawl.com/mcp`, MCP Streamable HTTP | `npx -y @spicrawl/mcp`, a subprocess of your MCP client |
+| Install | nothing | Node.js 20 or later |
+| Auth | `Authorization: Bearer <API key>` header | `SPICRAWL_API_KEY` environment variable |
+| Use when | your client supports remote MCP servers (most do) | your client only launches local servers, or you want to pin a version |
+
+Both serve the same 25 `spicrawl_*` tools. [Create an API key](https://app.spicrawl.com/signup) in the dashboard first; keys start with `spicrawl_live_` or `spicrawl_test_`.
+
+## Hosted endpoint
+
+Each tool call runs under your key, exactly as if you had called the API yourself, and a session is bound to the key that opened it. The key is checked when a session opens: an unknown or revoked key gets `401`, and if the API cannot be reached to check it the endpoint answers `503` with `Retry-After` (retry rather than rotating the key).
+
+**Claude Code:**
+
+```bash
+claude mcp add --transport http spicrawl https://mcp.spicrawl.com/mcp \
+  --header "Authorization: Bearer spicrawl_live_..."
+```
+
+or in a project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "spicrawl": {
+      "type": "http",
+      "url": "https://mcp.spicrawl.com/mcp",
+      "headers": { "Authorization": "Bearer spicrawl_live_..." }
+    }
+  }
+}
+```
+
+**Cursor** (`.cursor/mcp.json` or `~/.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "spicrawl": {
+      "url": "https://mcp.spicrawl.com/mcp",
+      "headers": { "Authorization": "Bearer spicrawl_live_..." }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`; VS Code uses the `servers` key). The `inputs` entry makes VS Code ask for the key once and store it, so the file is safe to commit:
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "spicrawl-api-key", "description": "Spicrawl API key", "password": true }
+  ],
+  "servers": {
+    "spicrawl": {
+      "type": "http",
+      "url": "https://mcp.spicrawl.com/mcp",
+      "headers": { "Authorization": "Bearer ${input:spicrawl-api-key}" }
+    }
+  }
+}
+```
+
+**Codex** reads the key from the environment each time it connects, so the key never lands in a file:
+
+```bash
+export SPICRAWL_API_KEY=spicrawl_live_...
+codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY
+```
+
+The equivalent `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.spicrawl]
+url = "https://mcp.spicrawl.com/mcp"
+bearer_token_env_var = "SPICRAWL_API_KEY"
+```
+
+**Claude Desktop** only launches local servers from `claude_desktop_config.json`, and custom connectors cannot send an `Authorization` header, so use the [local server](#local-server-stdio) below.
+
+## Local server (stdio)
+
+`npx -y @spicrawl/mcp` downloads the package and runs the stdio server. The client starts it and passes your key in its environment.
+
+**Claude Code:**
+
+```bash
+claude mcp add spicrawl --env SPICRAWL_API_KEY=spicrawl_live_... -- npx -y @spicrawl/mcp
+```
+
+**Claude Desktop** (`claude_desktop_config.json`) and **Cursor** (`.cursor/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "spicrawl": {
+      "command": "npx",
+      "args": ["-y", "@spicrawl/mcp"],
+      "env": { "SPICRAWL_API_KEY": "spicrawl_live_..." }
+    }
+  }
+}
+```
+
+**VS Code** (`.vscode/mcp.json`):
+
+```json
+{
+  "inputs": [
+    { "type": "promptString", "id": "spicrawl-api-key", "description": "Spicrawl API key", "password": true }
+  ],
+  "servers": {
+    "spicrawl": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@spicrawl/mcp"],
+      "env": { "SPICRAWL_API_KEY": "${input:spicrawl-api-key}" }
+    }
+  }
+}
+```
+
+**Codex** (`~/.codex/config.toml`):
+
+```toml
+[mcp_servers.spicrawl]
+command = "npx"
+args = ["-y", "@spicrawl/mcp"]
+env = { SPICRAWL_API_KEY = "spicrawl_live_..." }
+```
+
+Restart the client; the `spicrawl_*` tools appear. To install it once instead of fetching it on each start, run `npm install -g @spicrawl/mcp` and use the command `spicrawl-mcp` (`spicrawl-mcp-server` is an alias).
+
+### Environment variables
+
+| Variable | Required | Default | Notes |
+|---|---|---|---|
+| `SPICRAWL_API_KEY` | yes (stdio) | — | Your Spicrawl API key. The HTTP server ignores it and uses each caller's bearer token instead. |
+| `SPICRAWL_BASE_URL` | no | `https://api.spicrawl.com` (stdio), `http://127.0.0.1:8080` (HTTP server) | The Spicrawl API base URL. Set it for a self-hosted or local stack, and always when you run the HTTP server against the public API. |
+| `SPICRAWL_PUBLIC_BASE_URL` | no | `SPICRAWL_BASE_URL` | The API as the end user reaches it, used only for URLs handed back (`spicrawl_browser_connect_url`). Set it when the server talks to the API over a private address. |
+| `SPICRAWL_DOCS_URL` | no | see below | The docs base URL, no trailing slash. The docs tools read `<base>/api/search`, `<base>/<page>.md` and `<base>/llms.txt`. The docs are public: your API key is never sent there. |
+| `SPICRAWL_DOCS_HOST` | no | — | Legacy: an origin whose docs are at `/docs`. Read only when `SPICRAWL_DOCS_URL` is unset. |
+| `SPICRAWL_MCP_ADDR` | no | `127.0.0.1:8090` | HTTP server only: the listen address, `host:port`. |
+| `SPICRAWL_MCP_SESSION_IDLE_MS` | no | `1800000` (30 min) | HTTP server only: idle sessions are dropped after this long. |
+
+Without `SPICRAWL_DOCS_URL` or `SPICRAWL_DOCS_HOST`, the docs tools read a self-hosted API's own docs (`SPICRAWL_PUBLIC_BASE_URL`, else `SPICRAWL_BASE_URL`, plus `/docs`), and otherwise `https://docs.spicrawl.com`.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| **Scrape** | |
+| `spicrawl_scrape` | Retrieve a URL as markdown/text/html/json, or print it to a PDF. Optional browser render, selector or AI extraction, links, screenshot, DOM scoping, proxy control, caching, browser actions, network capture. |
+| **Batch** | |
+| `spicrawl_batch_submit` | Scrape many URLs as one async job with shared settings. Output is markdown unless `format` says otherwise, the same default as `spicrawl_scrape`. Returns the job object. |
+| `spicrawl_batch_list` | List the project's batch jobs, newest first, with status and progress. |
+| `spicrawl_batch_status` | Poll one batch job's status and progress. |
+| `spicrawl_batch_results` | Read a page of a job's finished items (content, or a `result_url` API content path per item). |
+| `spicrawl_batch_task_content` | Read the full payload of one item by its `seq`. |
+| `spicrawl_batch_cancel` | Cancel a job: unstarted items never run, finished ones keep their results. |
+| `spicrawl_batch_retry` | Re-queue every failed item of a job. |
+| `spicrawl_batch_add_items` | Append URLs to a job submitted with `open: true`. |
+| `spicrawl_batch_close` | Stop an open job accepting items so it can complete. |
+| **Sessions** | |
+| `spicrawl_session_create` | Create a persistent browser identity (cookies, storage, pinned engine, sticky exit IP) to reuse across scrapes. |
+| `spicrawl_session_list` | List the project's sessions, newest first. |
+| `spicrawl_session_get` | One session's metadata (status, engine, exit, usage, expiry). |
+| `spicrawl_session_context` | Dump a live session's stored state (cookies, storage). It contains secrets, and can clone a session. |
+| `spicrawl_session_release` | End a session; its record stays visible as `released`. |
+| `spicrawl_session_delete` | Permanently delete a session and its stored state. |
+| **Usage and request history** | |
+| `spicrawl_usage` | Billing-grade usage over a date window, grouped by day, project, engine or feature (needs the `read` scope). |
+| `spicrawl_usage_summary` | Current-period usage totals (needs the `read` scope). |
+| `spicrawl_usage_reconciliation` | One day's drift between the request log and the billed rollup (needs the `read` scope). |
+| `spicrawl_requests_list` | Recent API calls in the key's project with status, errors, engine, proxy, latency and credits; `all_projects: true` lists every project in the organization (needs the `read` scope). |
+| `spicrawl_request_get` | The full log record of one call by its request id, for debugging a failed or slow scrape. |
+| **Browser** | |
+| `spicrawl_browser_connect_url` | Coming soon: remote browsers are not available yet. Mints a single-use CDP WebSocket URL for driving Spicrawl's remote browser from your own Puppeteer or Playwright. |
+| **Docs** | |
+| `spicrawl_docs_search` | Search the Spicrawl docs (`query`, optional `limit` 1-20, default 8). Results are grouped by page, with matching sections, snippets and the `.md` URL to read next. An error code (`ERR::FAMILY::NAME`) also gets a link to its entry on the errors page. |
+| `spicrawl_docs_read` | Read one docs page as Markdown by path (`guides/anti-bot`) or docs URL, optionally with `#anchor`. Pages over 60k characters are truncated and say so; other hosts and `..` are refused. |
+| `spicrawl_docs_index` | The docs' `llms.txt`: every page with its title, description and `.md` link. |
+
+See the [MCP server docs](https://docs.spicrawl.com/agents/mcp) for each tool's arguments.
+
+## Example prompts
+
+Once connected, an agent can act on requests like:
+
+- *"Scrape https://example.com/pricing as markdown and summarise the plans."*
+- *"Get the product name, price and stock status from this URL."* The agent calls `spicrawl_scrape` with `autoparse` or an `extract` map.
+- *"Scrape these 50 URLs and give me the titles."* The agent calls `spicrawl_batch_submit`, then `spicrawl_batch_status` and `spicrawl_batch_results`.
+
+## Behaviour worth knowing
+
+- Tools reject unknown arguments rather than ignoring them. A misspelt or unsupported field (e.g. `js_render` on `spicrawl_scrape`, whose argument is `render`) fails the call with an error naming it, so a setting the agent believes it applied is never dropped.
+- Errors carry the platform's own code and guidance (e.g. `ERR::UPSTREAM::CHALLENGE` when a site served a bot wall), so the agent can decide whether to retry or change parameters.
+- `spicrawl_scrape` screenshots come back as MCP image content blocks the model can see. In the JSON, each `screenshots` entry keeps its metadata but its base64 is replaced by a pointer to its block. An image over 5 MB of base64 is not attached, and its entry says how to get a smaller one.
+- `spicrawl_scrape` with `format: "pdf"` (plus `render` or `engine: "chromium"`) returns the printed page as an MCP resource block (`application/pdf`). A PDF over 10 MB of base64 is not attached; `pdf.not_attached` says so.
+- Coming soon, and marked so in the tool descriptions: `ai_extract`, stealth mode (`stealth`, engine `camoufox`), `extract_preset`, the managed proxy pool (`premium_proxy`, `proxy_country`, `sticky_key`, session `rotate_ip`/`region_pool`) and `spicrawl_browser_connect_url`. The schemas already accept them so nothing changes the day they ship; until then agents should not send them.
+
+## Self-hosting the HTTP server
+
+The hosted endpoint is this package's Streamable HTTP server. To run your own, for example beside a self-hosted Spicrawl deployment:
+
+```bash
+SPICRAWL_MCP_ADDR=127.0.0.1:8090 \
+SPICRAWL_BASE_URL=https://api.spicrawl.com \
+npx -y @spicrawl/mcp --http
+```
+
+or, from an installed copy, `node node_modules/@spicrawl/mcp/dist/http.js` with the same environment.
+
+- It serves MCP at `POST/GET/DELETE /mcp` and liveness at `GET /healthz` (no auth): `curl http://127.0.0.1:8090/healthz`.
+- **`SPICRAWL_BASE_URL` defaults to `http://127.0.0.1:8080`** for the HTTP server (a Spicrawl API on the same host), not to the public API. Set it to `https://api.spicrawl.com` to front the public API.
+- Each caller authenticates with their own key as `Authorization: Bearer spicrawl_live_...`. The key is validated against the API before a session opens, and a session is pinned to the key that created it.
+- The server speaks plain HTTP. Put it behind TLS (a reverse proxy) before sending keys across a network.
+
+## Development
+
+```bash
+git clone https://github.com/Spicrawl/mcp.git && cd mcp
+npm ci
+npm run typecheck
+npm test
+```
+
+`npm test` builds the package, then runs the `node:test` suite in `test/` against the real `dist/http.js`, pointed at a fake Spicrawl API on loopback. It needs no deployment, no network and no real API key, and finishes in a few seconds.
+
+`npm run build` writes `dist/index.js` (the `spicrawl-mcp` command: stdio, or HTTP with `--http`) and `dist/http.js` (the HTTP server). Run the stdio server from a checkout with `SPICRAWL_API_KEY=... node dist/index.js`.
+
+## Security
+
+See [SECURITY.md](SECURITY.md). Never commit an API key; if one leaks, revoke it at https://app.spicrawl.com.
+
+## License
+
+[Apache-2.0](LICENSE)

package/dist/client.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Thin client over the Spicrawl REST API.
+ *
+ * Every MCP tool ultimately calls one of these methods. The client owns three
+ * things the tools should not each re-implement: authentication (the caller's
+ * API key as a bearer token), the base URL, and turning the platform's RFC 7807
+ * problem envelope into an actionable Error the agent can act on rather than a
+ * bare HTTP status.
+ */
+/**
+ * This package's version, read from package.json so the User-Agent, the MCP
+ * server's advertised version and the published package cannot drift. The
+ * path is relative to the compiled file (dist/client.js), and package.json
+ * ships with every npm package regardless of `files`.
+ */
+export declare const PACKAGE_VERSION: string;
+/**
+ * Sent on every API call. The API classifies the client surface from it
+ * (cli / mcp / sdk / other) and records it on each request-log row, so MCP
+ * traffic is countable. The product token must stay `spicrawl-mcp/`.
+ */
+export declare const USER_AGENT: string;
+/**
+ * The docs base URL from the environment, no trailing slash; page paths are
+ * appended to it directly (`<base>/errors`, `<base>/llms.txt`):
+ *
+ *   1. SPICRAWL_DOCS_URL, the full base (`https://docs.spicrawl.com`, or
+ *      `http://host:8080/docs` on a self-hosted deployment);
+ *   2. SPICRAWL_DOCS_HOST + `/docs`, the legacy origin-only setting, which keeps
+ *      its old meaning so an existing env file does not silently change;
+ *   3. a self-hosted API (SPICRAWL_PUBLIC_BASE_URL, else SPICRAWL_BASE_URL) +
+ *      `/docs`, where every deployment serves its own docs;
+ *   4. https://docs.spicrawl.com, also when that API is the public one.
+ *
+ * Read from the raw environment, not the client's baseURL, so a stdio server
+ * with no base URL set points at the public docs rather than localhost.
+ */
+export declare function docsBaseFromEnv(env?: NodeJS.ProcessEnv): string;
+/** The RFC 7807 problem shape every Spicrawl error uses. */
+interface Problem {
+    code?: string;
+    title?: string;
+    detail?: string;
+    status?: number;
+    retryable?: boolean;
+    target_status?: number | null;
+    doc_url?: string;
+}
+/** A failed request, carrying the platform's own error code and guidance. */
+export declare class ILayerError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly retryable: boolean;
+    readonly docUrl?: string;
+    constructor(status: number, problem: Problem, fallback: string);
+}
+export interface ClientConfig {
+    baseURL?: string;
+    /**
+     * The API base URL as the MCP's USERS reach it, for URLs handed back to them
+     * (the browser tool's CDP URL). Differs from baseURL when the MCP talks to
+     * the API over loopback. Defaults to baseURL.
+     */
+    publicBaseURL?: string;
+    apiKey: string;
+    timeoutMs?: number;
+    /**
+     * The public docs base (`https://docs.spicrawl.com`, `http://host:8080/docs`)
+     * the docs tools read from. Defaults to docsBaseFromEnv(). The API key is
+     * never sent there.
+     */
+    docsBaseURL?: string;
+}
+export declare class ILayerClient {
+    readonly baseURL: string;
+    /** Base URL for URLs returned to the caller; never used for upstream calls. */
+    readonly publicBaseURL: string;
+    /** The caller's key. Read by tools that hand out URLs carrying it (browser). */
+    readonly apiKey: string;
+    /** Public docs base, e.g. https://docs.spicrawl.com; no trailing slash. */
+    readonly docsBaseURL: string;
+    private readonly timeoutMs;
+    constructor(config: ClientConfig);
+    /** POST /v1/scrape — retrieve, render, and extract one URL. */
+    scrape(params: Record<string, unknown>): Promise<unknown>;
+    /** Any REST call. Tools for newer endpoints use this directly. */
+    request(method: string, path: string, body?: Record<string, unknown>): Promise<unknown>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,187 @@
+/**
+ * Thin client over the Spicrawl REST API.
+ *
+ * Every MCP tool ultimately calls one of these methods. The client owns three
+ * things the tools should not each re-implement: authentication (the caller's
+ * API key as a bearer token), the base URL, and turning the platform's RFC 7807
+ * problem envelope into an actionable Error the agent can act on rather than a
+ * bare HTTP status.
+ */
+import { createRequire } from "node:module";
+/**
+ * This package's version, read from package.json so the User-Agent, the MCP
+ * server's advertised version and the published package cannot drift. The
+ * path is relative to the compiled file (dist/client.js), and package.json
+ * ships with every npm package regardless of `files`.
+ */
+export const PACKAGE_VERSION = createRequire(import.meta.url)("../package.json").version;
+/**
+ * Sent on every API call. The API classifies the client surface from it
+ * (cli / mcp / sdk / other) and records it on each request-log row, so MCP
+ * traffic is countable. The product token must stay `spicrawl-mcp/`.
+ */
+export const USER_AGENT = `spicrawl-mcp/${PACKAGE_VERSION}`;
+/** The public Spicrawl API; set SPICRAWL_BASE_URL for a self-hosted or local stack. */
+const DEFAULT_BASE_URL = "https://api.spicrawl.com";
+const DEFAULT_TIMEOUT_MS = 120_000;
+/**
+ * Where the public docs live when nothing in the environment says otherwise:
+ * the root of their own host. llms.txt and the API's error doc_url links point
+ * here, and spicrawl_docs_read only reads URLs on the docs origin.
+ */
+const DEFAULT_DOCS_URL = "https://docs.spicrawl.com";
+const trimURL = (s) => (s ?? "").trim().replace(/\/+$/, "");
+/** An origin that serves the docs under /docs (a self-hosted API, the legacy SPICRAWL_DOCS_HOST). */
+const underDocs = (origin) => (origin.endsWith("/docs") ? origin : `${origin}/docs`);
+/**
+ * The docs base URL from the environment, no trailing slash; page paths are
+ * appended to it directly (`<base>/errors`, `<base>/llms.txt`):
+ *
+ *   1. SPICRAWL_DOCS_URL, the full base (`https://docs.spicrawl.com`, or
+ *      `http://host:8080/docs` on a self-hosted deployment);
+ *   2. SPICRAWL_DOCS_HOST + `/docs`, the legacy origin-only setting, which keeps
+ *      its old meaning so an existing env file does not silently change;
+ *   3. a self-hosted API (SPICRAWL_PUBLIC_BASE_URL, else SPICRAWL_BASE_URL) +
+ *      `/docs`, where every deployment serves its own docs;
+ *   4. https://docs.spicrawl.com, also when that API is the public one.
+ *
+ * Read from the raw environment, not the client's baseURL, so a stdio server
+ * with no base URL set points at the public docs rather than localhost.
+ */
+export function docsBaseFromEnv(env = process.env) {
+    const url = trimURL(env.SPICRAWL_DOCS_URL);
+    if (url)
+        return url;
+    const host = trimURL(env.SPICRAWL_DOCS_HOST);
+    if (host)
+        return underDocs(host);
+    const api = trimURL(env.SPICRAWL_PUBLIC_BASE_URL || env.SPICRAWL_BASE_URL);
+    if (api && api.toLowerCase() !== DEFAULT_BASE_URL)
+        return underDocs(api);
+    return DEFAULT_DOCS_URL;
+}
+/** A failed request, carrying the platform's own error code and guidance. */
+export class ILayerError extends Error {
+    code;
+    status;
+    retryable;
+    docUrl;
+    constructor(status, problem, fallback) {
+        const detail = problem.detail || problem.title || fallback;
+        super(detail);
+        this.name = "ILayerError";
+        this.code = problem.code || `HTTP_${status}`;
+        this.status = problem.status ?? status;
+        this.retryable = problem.retryable ?? status >= 500;
+        this.docUrl = problem.doc_url;
+    }
+}
+export class ILayerClient {
+    baseURL;
+    /** Base URL for URLs returned to the caller; never used for upstream calls. */
+    publicBaseURL;
+    /** The caller's key. Read by tools that hand out URLs carrying it (browser). */
+    apiKey;
+    /** Public docs base, e.g. https://docs.spicrawl.com; no trailing slash. */
+    docsBaseURL;
+    timeoutMs;
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new Error("SPICRAWL_API_KEY is required. Set it to an Spicrawl API key (spicrawl_live_...) in the MCP server's environment.");
+        }
+        this.baseURL = (config.baseURL || DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this.publicBaseURL = (config.publicBaseURL || this.baseURL).replace(/\/+$/, "");
+        this.apiKey = config.apiKey;
+        this.docsBaseURL = (config.docsBaseURL || docsBaseFromEnv()).replace(/\/+$/, "");
+        this.timeoutMs = config.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /** POST /v1/scrape — retrieve, render, and extract one URL. */
+    async scrape(params) {
+        return this.request("POST", "/v1/scrape", params);
+    }
+    /** Any REST call. Tools for newer endpoints use this directly. */
+    async request(method, path, body) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+        let response;
+        try {
+            response = await fetch(`${this.baseURL}${path}`, {
+                method,
+                headers: {
+                    Authorization: `Bearer ${this.apiKey}`,
+                    Accept: "application/json",
+                    "User-Agent": USER_AGENT,
+                    ...(body ? { "Content-Type": "application/json" } : {}),
+                },
+                body: body ? JSON.stringify(body) : undefined,
+                signal: controller.signal,
+            });
+        }
+        catch (err) {
+            if (err instanceof Error && err.name === "AbortError") {
+                throw new Error(`Request to ${path} timed out after ${this.timeoutMs} ms. A render or batch may need a longer timeout, or the API at ${this.baseURL} is unreachable.`);
+            }
+            throw new Error(`Could not reach the Spicrawl API at ${this.baseURL}${path}: ${err instanceof Error ? err.message : String(err)}. Check SPICRAWL_BASE_URL and that the server is running.`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+        // A PDF (`response_format=pdf`) is bytes: read as text it would be corrupted.
+        if (response.ok && mediaType(response) === "application/pdf")
+            return pdfPayload(response);
+        const text = await response.text();
+        let parsed;
+        try {
+            parsed = text ? JSON.parse(text) : {};
+        }
+        catch {
+            // Not JSON: a scrape body (markdown/text/html) — or, on an error, a
+            // gateway's page, which the check below still reports as a failure.
+            parsed = response.ok || response.headers.get("x-engine") !== null ? { content: text } : { detail: text };
+        }
+        // A non-2xx status is only an error when the body is a platform problem.
+        // With `original_status` the API relays the target's own status (a 404
+        // page the caller allowed via `allowed_status_codes`) on a SUCCESSFUL
+        // scrape, and that content must reach the agent, not be reported as a
+        // failure.
+        // A completed scrape always carries X-Engine; a gateway's error page does not.
+        const relayedTargetStatus = response.headers.get("x-engine") !== null;
+        const isProblem = typeof parsed === "object" && parsed !== null && typeof parsed.code === "string";
+        if (!response.ok && (isProblem || !relayedTargetStatus)) {
+            throw new ILayerError(response.status, parsed, `Request failed with HTTP ${response.status}`);
+        }
+        return parsed;
+    }
+}
+/** The response's media type, lowercase, without parameters. */
+function mediaType(response) {
+    return (response.headers.get("content-type") ?? "").split(";")[0].trim().toLowerCase();
+}
+/**
+ * A `response_format=pdf` scrape answers with the file itself, and the envelope's
+ * fields as headers. The bytes come back base64 under `pdf`, with those fields
+ * beside it, for the scrape tool to hand over as a resource block (tools/pdf.ts).
+ */
+async function pdfPayload(response) {
+    const bytes = Buffer.from(await response.arrayBuffer());
+    const header = (name) => response.headers.get(name) ?? undefined;
+    const number = (name) => {
+        const v = header(name);
+        return v !== undefined && v !== "" && Number.isFinite(Number(v)) ? Number(v) : undefined;
+    };
+    const out = {
+        pdf: { content_type: "application/pdf", size_bytes: bytes.length, encoding: "base64", data: bytes.toString("base64") },
+    };
+    const fields = {
+        engine: header("x-engine"),
+        status: number("x-target-status"),
+        credits: number("x-credits-charged"),
+        final_url: header("x-final-url"),
+        request_id: header("x-request-id"),
+    };
+    for (const [k, v] of Object.entries(fields))
+        if (v !== undefined)
+            out[k] = v;
+    return out;
+}
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;GAKG;AACH,MAAM,CAAC,MAAM,eAAe,GAC1B,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC,iBAAiB,CACjD,CAAC,OAAO,CAAC;AAEV;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,eAAe,EAAE,CAAC;AAE5D,uFAAuF;AACvF,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AACpD,MAAM,kBAAkB,GAAG,OAAO,CAAC;AACnC;;;;GAIG;AACH,MAAM,gBAAgB,GAAG,2BAA2B,CAAC;AAErD,MAAM,OAAO,GAAG,CAAC,CAAqB,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,IAAI,EAAE,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;AAChF,qGAAqG;AACrG,MAAM,SAAS,GAAG,CAAC,MAAc,EAAE,EAAE,CAAC,CAAC,MAAM,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,GAAG,MAAM,OAAO,CAAC,CAAC;AAE7F;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,eAAe,CAAC,MAAyB,OAAO,CAAC,GAAG;IAClE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3C,IAAI,GAAG;QAAE,OAAO,GAAG,CAAC;IACpB,MAAM,IAAI,GAAG,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,CAAC;IAC7C,IAAI,IAAI;QAAE,OAAO,SAAS,CAAC,IAAI,CAAC,CAAC;IACjC,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,wBAAwB,IAAI,GAAG,CAAC,iBAAiB,CAAC,CAAC;IAC3E,IAAI,GAAG,IAAI,GAAG,CAAC,WAAW,EAAE,KAAK,gBAAgB;QAAE,OAAO,SAAS,CAAC,GAAG,CAAC,CAAC;IACzE,OAAO,gBAAgB,CAAC;AAC1B,CAAC;AAaD,6EAA6E;AAC7E,MAAM,OAAO,WAAY,SAAQ,KAAK;IAC3B,IAAI,CAAS;IACb,MAAM,CAAS;IACf,SAAS,CAAU;IACnB,MAAM,CAAU;IAEzB,YAAY,MAAc,EAAE,OAAgB,EAAE,QAAgB;QAC5D,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,OAAO,CAAC,KAAK,IAAI,QAAQ,CAAC;QAC3D,KAAK,CAAC,MAAM,CAAC,CAAC;QACd,IAAI,CAAC,IAAI,GAAG,aAAa,CAAC;QAC1B,IAAI,CAAC,IAAI,GAAG,OAAO,CAAC,IAAI,IAAI,QAAQ,MAAM,EAAE,CAAC;QAC7C,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,MAAM,CAAC;QACvC,IAAI,CAAC,SAAS,GAAG,OAAO,CAAC,SAAS,IAAI,MAAM,IAAI,GAAG,CAAC;QACpD,IAAI,CAAC,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;IAChC,CAAC;CACF;AAoBD,MAAM,OAAO,YAAY;IACd,OAAO,CAAS;IACzB,+EAA+E;IACtE,aAAa,CAAS;IAC/B,gFAAgF;IACvE,MAAM,CAAS;IACxB,2EAA2E;IAClE,WAAW,CAAS;IACZ,SAAS,CAAS;IAEnC,YAAY,MAAoB;QAC9B,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC;YACnB,MAAM,IAAI,KAAK,CACb,kHAAkH,CACnH,CAAC;QACJ,CAAC;QACD,IAAI,CAAC,OAAO,GAAG,CAAC,MAAM,CAAC,OAAO,IAAI,gBAAgB,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACxE,IAAI,CAAC,aAAa,GAAG,CAAC,MAAM,CAAC,aAAa,IAAI,IAAI,CAAC,OAAO,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QAChF,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAC;QAC5B,IAAI,CAAC,WAAW,GAAG,CAAC,MAAM,CAAC,WAAW,IAAI,eAAe,EAAE,CAAC,CAAC,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC;QACjF,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,IAAI,kBAAkB,CAAC;IAC1D,CAAC;IAED,+DAA+D;IAC/D,KAAK,CAAC,MAAM,CAAC,MAA+B;QAC1C,OAAO,IAAI,CAAC,OAAO,CAAC,MAAM,EAAE,YAAY,EAAE,MAAM,CAAC,CAAC;IACpD,CAAC;IAED,kEAAkE;IAClE,KAAK,CAAC,OAAO,CACX,MAAc,EACd,IAAY,EACZ,IAA8B;QAE9B,MAAM,UAAU,GAAG,IAAI,eAAe,EAAE,CAAC;QACzC,MAAM,KAAK,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,UAAU,CAAC,KAAK,EAAE,EAAE,IAAI,CAAC,SAAS,CAAC,CAAC;QACnE,IAAI,QAAkB,CAAC;QACvB,IAAI,CAAC;YACH,QAAQ,GAAG,MAAM,KAAK,CAAC,GAAG,IAAI,CAAC,OAAO,GAAG,IAAI,EAAE,EAAE;gBAC/C,MAAM;gBACN,OAAO,EAAE;oBACP,aAAa,EAAE,UAAU,IAAI,CAAC,MAAM,EAAE;oBACtC,MAAM,EAAE,kBAAkB;oBAC1B,YAAY,EAAE,UAAU;oBACxB,GAAG,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,cAAc,EAAE,kBAAkB,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;iBACxD;gBACD,IAAI,EAAE,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,SAAS;gBAC7C,MAAM,EAAE,UAAU,CAAC,MAAM;aAC1B,CAAC,CAAC;QACL,CAAC;QAAC,OAAO,GAAG,EAAE,CAAC;YACb,IAAI,GAAG,YAAY,KAAK,IAAI,GAAG,CAAC,IAAI,KAAK,YAAY,EAAE,CAAC;gBACtD,MAAM,IAAI,KAAK,CACb,cAAc,IAAI,oBAAoB,IAAI,CAAC,SAAS,mEAAmE,IAAI,CAAC,OAAO,kBAAkB,CACtJ,CAAC;YACJ,CAAC;YACD,MAAM,IAAI,KAAK,CACb,uCAAuC,IAAI,CAAC,OAAO,GAAG,IAAI,KACxD,GAAG,YAAY,KAAK,CAAC,CAAC,CAAC,GAAG,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CACjD,2DAA2D,CAC5D,CAAC;QACJ,CAAC;gBAAS,CAAC;YACT,YAAY,CAAC,KAAK,CAAC,CAAC;QACtB,CAAC;QAED,8EAA8E;QAC9E,IAAI,QAAQ,CAAC,EAAE,IAAI,SAAS,CAAC,QAAQ,CAAC,KAAK,iBAAiB;YAAE,OAAO,UAAU,CAAC,QAAQ,CAAC,CAAC;QAE1F,MAAM,IAAI,GAAG,MAAM,QAAQ,CAAC,IAAI,EAAE,CAAC;QACnC,IAAI,MAAe,CAAC;QACpB,IAAI,CAAC;YACH,MAAM,GAAG,IAAI,CAAC,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;QACxC,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;YACpE,oEAAoE;YACpE,MAAM,GAAG,QAAQ,CAAC,EAAE,IAAI,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,CAAC,CAAC,EAAE,MAAM,EAAE,IAAI,EAAE,CAAC;QAC3G,CAAC;QAED,yEAAyE;QACzE,uEAAuE;QACvE,sEAAsE;QACtE,sEAAsE;QACtE,WAAW;QACX,+EAA+E;QAC/E,MAAM,mBAAmB,GAAG,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,UAAU,CAAC,KAAK,IAAI,CAAC;QACtE,MAAM,SAAS,GACb,OAAO,MAAM,KAAK,QAAQ,IAAI,MAAM,KAAK,IAAI,IAAI,OAAQ,MAAkB,CAAC,IAAI,KAAK,QAAQ,CAAC;QAChG,IAAI,CAAC,QAAQ,CAAC,EAAE,IAAI,CAAC,SAAS,IAAI,CAAC,mBAAmB,CAAC,EAAE,CAAC;YACxD,MAAM,IAAI,WAAW,CACnB,QAAQ,CAAC,MAAM,EACf,MAAiB,EACjB,4BAA4B,QAAQ,CAAC,MAAM,EAAE,CAC9C,CAAC;QACJ,CAAC;QACD,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AAED,gEAAgE;AAChE,SAAS,SAAS,CAAC,QAAkB;IACnC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,cAAc,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;AACzF,CAAC;AAED;;;;GAIG;AACH,KAAK,UAAU,UAAU,CAAC,QAAkB;IAC1C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC;IACxD,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE,CAAC,QAAQ,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,SAAS,CAAC;IACzE,MAAM,MAAM,GAAG,CAAC,IAAY,EAAE,EAAE;QAC9B,MAAM,CAAC,GAAG,MAAM,CAAC,IAAI,CAAC,CAAC;QACvB,OAAO,CAAC,KAAK,SAAS,IAAI,CAAC,KAAK,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,SAAS,CAAC;IAC3F,CAAC,CAAC;IACF,MAAM,GAAG,GAA4B;QACnC,GAAG,EAAE,EAAE,YAAY,EAAE,iBAAiB,EAAE,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,QAAQ,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,QAAQ,CAAC,EAAE;KACvH,CAAC;IACF,MAAM,MAAM,GAA4B;QACtC,MAAM,EAAE,MAAM,CAAC,UAAU,CAAC;QAC1B,MAAM,EAAE,MAAM,CAAC,iBAAiB,CAAC;QACjC,OAAO,EAAE,MAAM,CAAC,mBAAmB,CAAC;QACpC,SAAS,EAAE,MAAM,CAAC,aAAa,CAAC;QAChC,UAAU,EAAE,MAAM,CAAC,cAAc,CAAC;KACnC,CAAC;IACF,KAAK,MAAM,CAAC,CAAC,EAAE,CAAC,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,MAAM,CAAC;QAAE,IAAI,CAAC,KAAK,SAAS;YAAE,GAAG,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC;IAC7E,OAAO,GAAG,CAAC;AACb,CAAC"}