Skip to content

🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev

10.7 KB
Raw Blame

title: "Справочник API MCP-сервера Scrapling" description: "Инструменты MCP, модели запросов и ответов и операции с сессиями для сбора данных через HTTP и браузер."

Справочник API MCP-сервера {#mcp-server-api-reference}

MCP-сервер Scrapling предоставляет шестнадцать инструментов для сбора данных и работы с браузером через Model Context Protocol (MCP). Он подключает Scrapling к AI-ботам и агентам, чтобы можно было собирать данные через диалог и обходить защиту от ботов.

Запустите MCP-сервер командой:

scrapling mcp

Или импортируйте класс сервера напрямую:

from scrapling.core.ai import ScraplingMCPServer

server = ScraplingMCPServer()
server.serve(http=False, host="127.0.0.1", port=8000)

Чтобы использовать собственный браузер на основе Chromium, передайте путь в executable_path:

server = ScraplingMCPServer(executable_path="/path/to/chromium")

Модель ответа {#response-model}

Инструменты загрузки страниц и HTTP-запросов возвращают по одному ответу на вызов в формате ниже. Управление сессиями использует отдельные модели, описанные дальше. browser_screenshot возвращает изображение страницы или элемента и текущий URL как блоки изображения и текста. browser_extract и browser_actions возвращают обычный текст. Оба сетевых инструмента возвращают структурированный JSON в моделях ниже. browser_evaluate возвращает результат в виде JSON в текстовом блоке.

::: scrapling.core.ai.server.ResponseModel

handler: python
:docstring:

Модели сетевых запросов {#network-request-models}

browser_network_requests возвращает NetworkRequestsModel с полями requests, next_cursor, has_more и dropped_count. Каждый NetworkRequestInfo содержит id, url, method, resource_type и status. Для продолжения передайте next_cursor в after_id. Поле has_more показывает, есть ли ещё подходящие записи в текущей истории.

browser_network_request возвращает NetworkRequestModel с полями request_id, part, data и note. Сводка и заголовки представлены объектами. Полный сохранённый текст тела возвращается строкой, даже если это JSON. Поле note объясняет, почему тела нет или заголовки неполные.

::: scrapling.core.ai._network_formatting.NetworkRequestInfo

handler: python
:docstring:

::: scrapling.core.ai.server.NetworkRequestsModel

handler: python
:docstring:

::: scrapling.core.ai._network_formatting.NetworkRequestModel

handler: python
:docstring:

Модели сессий {#session-models}

Классы моделей для управления сессиями:

::: scrapling.core.ai.server.SessionInfo

handler: python
:docstring:

::: scrapling.core.ai.server.SessionCreatedModel

handler: python
:docstring:

::: scrapling.core.ai.server.SessionClosedModel

handler: python
:docstring:

Класс MCP-сервера {#mcp-server-class}

Основной класс MCP-сервера предоставляет следующие инструменты:

  • make_request: получает один URL по HTTP с имитацией браузера и автоматически закрывает клиент. Поддерживает GET, POST, PUT и DELETE.

  • browser_fetch_once: получает один URL через скрытный браузер, выполняет JavaScript, проходит проверки Cloudflare и закрывает браузер. Если нужны дальнейшие действия или история запросов, используйте постоянную сессию.

  • browser_extract: читает текущую страницу или элемент в виде снимка структуры для AI, HTML, Markdown или текста без перезагрузки. Результаты работы с формами и страницей сохраняются. Снимок содержит роли, имена, ссылки на элементы, их положение и размеры. Поиск по регулярному выражению возвращает совпавшие строки, соседний контекст и родительские узлы.

  • browser_actions: выполняет движения мыши, наведение, клики, прокрутку, заполнение полей, сочетания клавиш, ответы на диалоги и ожидание за один вызов. Принимайте или закрывайте уведомления и подтверждения, вводите текст в диалогах. Можно заполнить поиск, отправить его, дождаться результатов и открыть один из них без отдельного вызова на каждый шаг.

    Для движения и клика укажите селектор, ссылку из снимка или координаты. Инструмент дождётся элемента и прокрутит его в видимую область. Есть пошаговое движение, левая, правая и средняя кнопки, двойной клик и прокрутка вложенных областей.

    Находите поля через селекторы или ссылки из снимка. Вводите текст, ставьте и снимайте флажки, выбирайте радиокнопки и один или несколько пунктов обычного выпадающего списка по подписи. Заменяйте и очищайте текст или добавляйте его в позиции курсора. Сочетания клавиш действуют на элемент в фокусе. Медленный режим добавляет случайные паузы между символами и действиями.

    Ждите, пока содержимое или индикатор загрузки достигнет нужного состояния, используя селектор или ссылку из снимка. Можно также дождаться события загрузки, прекращения сетевой активности или задать паузу.

  • browser_evaluate: выполняет JavaScript на текущей странице для извлечения данных, вычислений, чтения состояния приложения или изменения содержимого. Поддерживает асинхронные скрипты и возвращает результат в JSON.

  • browser_network_requests: ищет завершённые запросы из разных вкладок, переходов и действий. Находит API-вызовы, HTTP-ошибки и сохранённые перенаправления. Статические ресурсы по умолчанию скрыты, чтобы сократить результат. Незавершённые запросы и запросы со сбоем не включаются. Возвращает структурированные данные с разбивкой на страницы.

  • browser_network_request: читает сводку, заголовки, отправленные данные или текст тела сохранённого ответа в виде структурированного JSON, не повторяя запрос. Выбранная часть возвращается целиком, включая сохранённый текст. Ответы остаются доступны после переходов по страницам, в том числе ответы HTTP 4xx и 5xx. Запись появляется после завершения сохранения. Чтение истории и закрытие сессии не ждут его окончания, поэтому незавершённая запись может потеряться при переходе или закрытии. Байты получены от Playwright и могут отличаться от байтов сервера. Текст декодируется как UTF-8 по правилам Playwright, если сохранённые байты корректны для этой кодировки. Иначе используется объявленная кодировка. Читаются и сохраняются только тела с поддерживаемым текстовым Content-Type. Для двоичных данных, неизвестного или отсутствующего типа сохраняются только метаданные и заголовки без чтения тела. Загрузка браузером не меняется. Размер истории ограничен. Дополнительная заметка объясняет, почему тело не текстовое, слишком большое или недоступно для чтения. Прочитайте нужные данные до закрытия MCP-сессии.

  • browser_fetch: загружает страницу в открытой скрытной браузерной сессии и извлекает HTML, Markdown, текст или снимок структуры. Снимок может охватывать всю страницу или один элемент и содержит ссылки на элементы, их положение и размеры для последующих действий.

::: scrapling.core.ai.server.ScraplingMCPServer

handler: python
:docstring: