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

Web scraping in Gemini CLI

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

Configuralo

spicrawl init non supporta Gemini CLI, quindi segui questi passaggi.

  1. Imposta la tua chiave, poi copiala con un secondo nome:

    bash
    export SPICRAWL_API_KEY=spicrawl_live_...   # add to your shell profile
    export SPICRAWL_MCP_BEARER="$SPICRAWL_API_KEY"

    Gemini CLI rimuove le variabili con KEY, TOKEN, AUTH e parole simili nel nome prima di compilare gli header. Quindi $SPICRAWL_API_KEY sarebbe vuoto e il server risponderebbe 401.

  2. Aggiungi il server a ~/.gemini/settings.json (o .gemini/settings.json per un solo progetto). Usa httpUrl, non url:

    ~/.gemini/settings.json
    {
      "mcpServers": {
        "spicrawl": {
          "httpUrl": "https://mcp.spicrawl.com/mcp",
          "headers": { "Authorization": "Bearer $SPICRAWL_MCP_BEARER" }
        }
      }
    }

    Oppure aggiungi la stessa voce dalla riga di comando. Gli apici singoli mantengono il riferimento alla variabile nel file:

    bash
    gemini mcp add --scope user --transport http \
      --header 'Authorization: Bearer $SPICRAWL_MCP_BEARER' \
      spicrawl https://mcp.spicrawl.com/mcp
  3. Installa la skill, poi esegui /skills reload in una sessione già avviata:

    bash
    spicrawl skill install --client codex
    
    # Without the CLI:
    mkdir -p .agents/skills/spicrawl
    curl -fsSL https://app.spicrawl.com/skill.md -o .agents/skills/spicrawl/SKILL.md
  4. Incolla questa sezione in GEMINI.md nella radice del progetto, poi esegui /memory reload:

    GEMINI.md
    # Web data (Spicrawl)
    
    Use Spicrawl to read web pages: the spicrawl_* MCP tools in chat, 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.
    - Never print or commit SPICRAWL_API_KEY. Log `X-Request-Id` for failures.
  5. Avvia gemini ed esegui /mcp. spicrawl dovrebbe risultare connesso con 25 strumenti spicrawl_*.

Un primo task da provare

Avvia gemini 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.

L’agente dovrebbe richiamare spicrawl_scrape con format: "markdown". Gemini CLI ti chiede di confermare ogni chiamata a uno strumento, a meno che il server non abbia "trust": true.

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

Perché non usare SPICRAWL_API_KEY nell’header?

Gemini CLI rimuove le variabili i cui nomi contengono KEY, TOKEN, AUTH e parole simili prima di espandere gli header. $SPICRAWL_API_KEY sarebbe vuota e il server risponderebbe 401. Usa SPICRAWL_MCP_BEARER.

spicrawl init supporta Gemini CLI?

No. Segui i passaggi manuali in questa pagina.

Devo usare url o httpUrl?

Usa httpUrl. In Gemini CLI, url significa SSE, e il server Spicrawl usa Streamable HTTP.

Esiste un’estensione di Spicrawl per Gemini CLI?

No. Non è pubblicata alcuna estensione di Spicrawl, quindi usa la voce nelle impostazioni.

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.