Spicrawl działa teraz z OpenAI Agents SDK, LangChain, Codex, Claude Code i nie tylko.Zobacz integracje
Przejdź do treści

Web scraping w Gemini CLI

Dodaj serwer MCP Spicrawl do Gemini CLI. Będzie mógł wtedy czytać strony jako czysty Markdown.

Skonfiguruj

spicrawl init nie obsługuje Gemini CLI, więc wykonaj te kroki.

  1. Ustaw klucz, a potem skopiuj go pod drugą nazwę:

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

    Gemini CLI usuwa zmienne, które mają w nazwie KEY, TOKEN, AUTH i podobne słowa, zanim uzupełni nagłówki. Dlatego $SPICRAWL_API_KEY byłoby puste, a serwer odpowiedziałby 401.

  2. Dodaj serwer do ~/.gemini/settings.json (lub .gemini/settings.json dla jednego projektu). Użyj httpUrl, nie url:

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

    Albo dodaj ten sam wpis z wiersza poleceń. Pojedyncze cudzysłowy zachowują odwołanie do zmiennej w pliku:

    bash
    gemini mcp add --scope user --transport http \
      --header 'Authorization: Bearer $SPICRAWL_MCP_BEARER' \
      spicrawl https://mcp.spicrawl.com/mcp
  3. Zainstaluj skill, a potem uruchom /skills reload w działającej sesji:

    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. Wklej tę sekcję do GEMINI.md w katalogu głównym projektu, a potem uruchom /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. Uruchom gemini i wpisz /mcp. spicrawl powinien być połączony z 25 narzędziami spicrawl_*.

Pierwsze zadanie na próbę

Uruchom gemini w projekcie i zapytaj:

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.

Agent powinien wywołać spicrawl_scrape z format: "markdown". Gemini CLI prosi o potwierdzenie każdego wywołania narzędzia, chyba że serwer ma "trust": true.

Co potrafi

Serwer daje agentowi 25 narzędzi spicrawl_*. Każde wywołanie działa na Twoim kluczu API, z tymi samymi limitami i kredytami co bezpośrednie wywołanie API.

  • Przeczytaj jedną stronę: spicrawl_scrape zwraca Markdown (domyślnie), tekst, HTML, JSON lub PDF.
  • Czytaj wiele stron: spicrawl_batch_submit kolejkuje do 10,000 adresów URL. Potem użyj spicrawl_batch_status i spicrawl_batch_results.
  • Strony za logowaniem: spicrawl_session_create zachowuje ciasteczka i storage między wywołaniami.
  • Zdiagnozuj błąd: spicrawl_requests_list i spicrawl_request_get.
  • Sprawdź użycie: spicrawl_usage_summary i pozostałe narzędzia użycia. Wymagają klucza z uprawnieniem read.
  • Wyszukuj informacje: spicrawl_docs_search i spicrawl_docs_read przeszukują i czytają dokumentację Spicrawl.

Jedno narzędzie, spicrawl_browser_connect_url, jest na liście, ale wkrótce. W spicrawl_scrape argument renderowania to render, a nie js_render z API.

Warto wiedzieć

  • Bez crawlowania. Spicrawl nie podąża za linkami ani nie wyszukuje stron. Daj agentowi adresy URL.
  • Kredyty na żądanie. Zwykłe pobranie to 1 kredyt. Renderowanie JavaScriptu to 3. Renderowanie w pełnej przeglądarce to 8.
  • Błędy są darmowe. Nieudane żądanie kosztuje 0 kredytów.
  • Cache oszczędza czas, a nie kredyty. Trafienie w cache kosztuje tyle samo co pobranie, które je zapisało.
  • Ogranicz każde wywołanie. Ustaw max_cost, a żądanie, które mogłoby kosztować więcej, zostanie odrzucone, zanim się wykona.
  • Wkrótce: zarządzane proxy, tryb stealth, zdalna przeglądarka i ekstrakcja AI z promptu w zwykłym języku. Dziś możesz użyć własnego proxy.

Najczęściej zadawane pytania

Dlaczego nie użyć SPICRAWL_API_KEY w nagłówku?

Gemini CLI usuwa zmienne, których nazwy zawierają KEY, TOKEN, AUTH i podobne słowa, zanim rozwinie nagłówki. $SPICRAWL_API_KEY byłby pusty, a serwer odpowiedziałby 401. Użyj SPICRAWL_MCP_BEARER.

Czy spicrawl init obsługuje Gemini CLI?

Nie. Wykonaj kroki ręczne z tej strony.

Czy użyć url, czy httpUrl?

Użyj httpUrl. W Gemini CLI url oznacza SSE, a serwer Spicrawl używa Streamable HTTP.

Czy jest rozszerzenie Spicrawl dla Gemini CLI?

Nie. Nie opublikowano rozszerzenia Spicrawl, więc użyj wpisu w ustawieniach.

Ile kosztuje każda strona?

Zwykłe pobranie kosztuje 1 kredyt, renderowanie JavaScriptu 3, a renderowanie w pełnej przeglądarce 8. Nieudane żądania kosztują 0. Trafienie w cache kosztuje tyle samo, co pobranie, które je zapisało. Poproś agenta, aby ustawiał max_cost w każdym żądaniu, tak by nigdy nie wydał więcej, niż się spodziewasz.