Spicrawl ora funziona con OpenAI Agents SDK, LangChain, Codex, Claude Code e altri.Vedi le integrazioni
Vai al contenuto

Web scraping in Codex

Aggiungi il server MCP di Spicrawl a Codex. Potrà così leggere le pagine web come Markdown pulito.

Configuralo

Tre passaggi danno a Codex gli strumenti, il know-how per scrivere codice Spicrawl e le regole per usarli entrambi. Oppure fai tutti e tre con spicrawl init --client codex.

  1. Imposta la tua chiave API:

    bash
    export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile
  2. Aggiungi il server MCP. Codex legge la chiave da SPICRAWL_API_KEY a ogni connessione, quindi la chiave non finisce mai in un file:

    bash
    codex mcp add spicrawl --url https://mcp.spicrawl.com/mcp --bearer-token-env-var SPICRAWL_API_KEY

    Questo scrive la stessa cosa di questa configurazione:

    ~/.codex/config.toml
    [mcp_servers.spicrawl]
    url = "https://mcp.spicrawl.com/mcp"
    bearer_token_env_var = "SPICRAWL_API_KEY"

    Per un solo progetto, metti la tabella in .codex/config.toml. Codex la legge solo nei progetti attendibili.

  3. Installa la skill:

    bash
    mkdir -p .agents/skills/spicrawl
    curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md
  4. Incolla questa sezione in AGENTS.md nella radice del progetto:

    AGENTS.md
    ## Web data (Spicrawl)
    
    Use Spicrawl to read web pages: the spicrawl_* MCP tools, the `spicrawl` CLI, or
    POST https://api.spicrawl.com/v1/scrape with `Authorization: Bearer $SPICRAWL_API_KEY` in code.
    Docs: https://docs.spicrawl.com/llms.txt (append .md to any page URL for Markdown).
    
    - Ask for markdown: `response_format: "markdown"` (API default is html); on spicrawl_scrape, `format: "markdown"`.
    - Check the site's status, not only the HTTP status: `X-Target-Status` header, or `status`
      in the JSON envelope (spicrawl_scrape with `format: "json"`). 200 is the page; 404/410
      mean it does not exist; 403/429/503 mean the site refused, so escalate.
    - On an error, switch on `code`. Retry only when `retryable` is true, after
      `retry_after_seconds`. Read `diagnostics.hint` and change what it names first.
      Never retry ERR::REQUEST::*, ERR::AUTH::* or ERR::LIMIT::QUOTA_EXCEEDED.
    - Escalate one step at a time and stop at the first that works:
      plain fetch (1 credit) -> `js_render: true` (3) -> add the user's own `proxy`
      if they have one. Empty or skeleton content means render; ERR::UPSTREAM::CHALLENGE
      or a 403 target status means retry once, then the user's own proxy.
    - Set `max_cost` on every request to the price of the step you intend.
    - Keep the cache on (default). Set `cache: false` only for prices, stock or other live data.
    - Trim tokens with `main_content_only` (on by default for markdown), `include_tags`, `exclude_tags`.
    - For more than 20 URLs, use a batch job (spicrawl_batch_submit / POST /v1/batch).
      Batch items return html, markdown or text (spicrawl_batch_submit defaults to markdown,
      POST /v1/batch to html). Extraction, screenshots, actions and sessions are refused
      with a 400 before anything is charged: scrape those URLs one by one.
    - With the CLI, read stdout as JSON and branch on the exit code: 3 auth, 4 bad request,
      5 limit, 6 site refused or failed, 7 proxy, 8 engine or extraction, 10 network.
    - Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.
  5. Verificalo con codex mcp list, oppure /mcp in una sessione. Dovresti vedere 25 strumenti spicrawl_*.

Oppure usa la CLI

Codex lavora in una shell, quindi la CLI spicrawl funziona senza alcuna configurazione. Stampa JSON quando viene collegata in pipe e termina con un codice stabile:

bash
spicrawl scrape https://example.com/pricing --format markdown --max-cost 3 | jq -r .content

In Codex cloud non contare sul server MCP. Usa la CLI o semplice HTTP. Imposta SPICRAWL_API_KEY come variabile d’ambiente, non come secret, e consenti api.spicrawl.com nell’accesso a internet dell’agente.

Un primo task da provare

Avvia codex nel progetto e chiedi:

prompt
Use Spicrawl to read https://example.com/pricing as markdown. List each plan with its monthly price.
If the page comes back empty, retry with rendering.

Cosa può fare

Il server offre all’agente 25 strumenti spicrawl_*. Ogni chiamata viene eseguita con la tua chiave API, con gli stessi limiti e crediti di una chiamata diretta all’API.

  • Leggi una pagina: spicrawl_scrape restituisce Markdown (predefinito), testo, HTML, JSON o PDF.
  • Leggi molte pagine: spicrawl_batch_submit mette in coda fino a 10.000 URL. Poi usa spicrawl_batch_status e spicrawl_batch_results.
  • Pagine dietro un login: spicrawl_session_create mantiene cookie e storage tra una chiamata e l’altra.
  • Fai il debug di un errore: spicrawl_requests_list e spicrawl_request_get.
  • Controlla l’utilizzo: spicrawl_usage_summary e gli altri strumenti di utilizzo. Richiedono una chiave con lo scope read.
  • Cerca informazioni: spicrawl_docs_search e spicrawl_docs_read cercano e leggono nella documentazione di Spicrawl.

Uno strumento, spicrawl_browser_connect_url, è elencato ma in arrivo. Su spicrawl_scrape, l’argomento di rendering è render, non js_render come nell’API.

Da sapere

  • Nessun crawling. Spicrawl non segue link né trova pagine. Dai all’agente gli URL.
  • Crediti per richiesta. Un fetch semplice costa 1 credito. Il rendering JavaScript 3. Il rendering con browser completo 8.
  • I fallimenti sono gratuiti. Una richiesta fallita costa 0 crediti.
  • La cache fa risparmiare tempo, non crediti. La cache fa risparmiare tempo, non crediti.
  • Limita ogni chiamata. Imposta max_cost, e una richiesta che potrebbe costare di più viene rifiutata prima di essere eseguita.
  • In arrivo: proxy gestiti, modalità stealth, un browser remoto ed estrazione con AI da un prompt in linguaggio naturale. Oggi puoi usare il tuo proxy.

Domande frequenti

Dove salva il server Codex?

In ~/.codex/config.toml. Per usarlo in un solo progetto, metti la stessa tabella in .codex/config.toml. Codex legge la configurazione di progetto solo nei progetti attendibili.

Codex può usare la CLI al posto di MCP?

Sì. Codex lavora in una shell, quindi può eseguire spicrawl scrape URL --format markdown --max-cost 3. La CLI stampa JSON quando è in pipe e termina con un codice stabile.

Funziona nel cloud di Codex?

Non contare sul server MCP lì. Usa la CLI o semplice HTTP. Imposta SPICRAWL_API_KEY come variabile d’ambiente (non come segreto) e consenti api.spicrawl.com nell’accesso a internet dell’agente.

Perché il server restituisce 401?

SPICRAWL_API_KEY non era impostata nella shell che ha avviato codex. Esportala e avvia una nuova sessione.

Quanto costa ogni pagina?

Un fetch semplice costa 1 credito, il rendering JavaScript 3 e il rendering con browser completo 8. Le richieste fallite costano 0. Un cache hit costa quanto il fetch che l’ha salvato. Chiedi all’agente di impostare max_cost su ogni richiesta così non spende mai più del previsto.