Почему самописный клей для инструментов не работает

Агентам нужны настоящие веб-инструменты, а не самописные Python-обёртки

Каждая команда пишет один и тот же клей: по Python-инструменту на каждый источник скрейпинга, наполовину сломанное хранилище сессий, самодельный оркестратор, теряющий контекст после первого же вызова. Через три недели агент срабатывает один раз, ломается дважды, и никто не помнит, какой прокси протух. Мы даём четыре части, нужные каждому агент-циклу, из коробки — по MCP, через один HTTP-эндпоинт.

Если ваш агент когда-нибудь отваливался по таймауту на третьем шаге многошагового краулинга — это для вас.

Отдельный Python-инструмент на каждый источник

Проблема. Каждая новая возможность агента — это ещё один декоратор @tool: один для Amazon, один для eBay, один для корпоративной вики. Дрейф схем, рассинхрон версий и реестр инструментов, которым никто не владеет. Подключение новой модели означает переписывание обёрток с нуля.

Как это решает Yozh Scraper. Один HTTP MCP-эндпоинт на localhost:8000/mcp автоматически публикует каждую возможность — scrape_page, scrape_batch, crawl, sessions, presets. Добавьте одну строку в конфиг Claude / Cursor / Cline — и модель обнаружит инструменты во время выполнения. Один эндпоинт, любой клиент.

Один MCP-эндпоинт
Автообнаружение
Без связующего кода

Вызовы инструментов без состояния теряют контекст входа

Проблема. Вызовы инструментов не имеют состояния — каждый запускает новый браузер, сбрасывает куки, проваливает второй шаг 2FA. Агенты застревают в цикле повторного входа, жгут токены и сдаются на третьей попытке. Ручное хранение куки хрупко и протекает между запусками.

Как это решает Yozh Scraper. Sessions API со «липким» session_id, который агент передаёт между вызовами. Декларативный DSL для входа (goto / fill / click / wait) или одноразовая вставка экспортированных куки — storageState хранится 24 часа. Каждый следующий вызов инструмента переиспользует сессию, без повторной авторизации.

Закреплённый session_id
Декларативный вход
TTL 24 ч

Ручная авторизация и обвязка прокси в коде агента

Проблема. Каждый агент в итоге сам разбирается с API-ключами, ротацией прокси, кодами стран, ретраями — конфигом, который никак не связан с задачей модели. Секреты утекают в промпты, агент принимает «креативные» решения о ретраях, и бюджет на прокси взрывается за неделю.

Как это решает Yozh Scraper. CYBERYOZH_API_KEY в .env сервера — код агента никогда не видит учётные данные. Укажите proxy: {country: "us", type: "mobile"} в вызове инструмента, а ротацию, отпечаток и ретраи Yozh берёт на себя на стороне сервера. Агент остаётся сосредоточен на рассуждении.

Аутентификация на сервере
Декларативный прокси
Никаких секретов в промптах

Многошаговый краулинг внутри агент-цикла

Проблема. «Найди все страницы товаров на этом сайте и вытяни цены» — это одно намерение пользователя, но в коде агента это 200 вызовов инструментов, очередь, слой дедупликации и нянченье таймаутов. Модель тратит контекстное окно на учёт URL, которого не должна видеть вовсе.

Как это решает Yozh Scraper. Yozh Crawler обходит сайт на стороне сервера, отдаёт найденные URL потоком по SSE и на каждом совпадении сцепляется со скрейпером. Агент вызывает crawl_and_scrape один раз и получает единый поток структурированных результатов. Очередь держит сервер, а модель сохраняет свой контекст.

SSE-стриминг
Очередь на сервере
Один вызов инструмента

Как это работает

От `docker compose up` до агента, вызывающего инструменты, — за 3 шага

Один MCP-эндпоинт, одна строка конфига в вашем клиенте, ноль клея-кода. Тот же поток работает для Claude Desktop, Cursor, Cline или вашего собственного агент-цикла.

1 Поднимите MCP-эндпоинт

Клонируйте репозиторий и docker compose up. MCP-сервер работает на localhost:8000/mcp — скрейпер, краулер, сессии и пресеты автоматически опубликованы как инструменты.

# one-time setup
git clone 
  github.com/CyberYozh-data/yozh-scraper
cd yozh-scraper
docker compose up -d

2 Подключите к своему клиенту

Одна строка в claude_desktop_config.json (или эквивалент для Cursor / Cline). Перезапустите клиент — инструменты обнаруживаются автоматически, без обёрток под каждый источник.

{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url": "http://localhost:8000/mcp"
    }
  }
}

3 Дайте агенту вызывать инструменты

Модель выбирает инструмент, заполняет параметры и получает обратно структурированный JSON. Сессии сохраняются между вызовами. Многошаговый краулинг идёт потоком по SSE.

// claude calls scrape_page autonomously
{
  "tool":   "scrape_page",
  "input":  {"url": "…",
              "preset": "amazon_product"},
  "result": { /* structured JSON */ }
}

Живой пример

Что вы получаете на выходе — одна структура для каждого маркетплейса

Выберите пресет, чтобы увидеть, как выглядит ответ. Набор полей зависит от источника, но структура запроса одинакова.

Рецепты

Как агенты подключают это — по 10 строк на каждый

Три конкретных агентских сценария, готовых вставить. От однострочника для Claude Desktop до полного цикла LangChain — за всеми один и тот же MCP-эндпоинт.

1 Исследовательский агент в Claude Desktop

Подключите Yozh к Claude Desktop один раз. Попросите модель исследовать тему — она сама выберет scrape_page / crawl и синтезирует ответ.

# claude_desktop_config.json (~/Library/...)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# restart Claude · prompt:
# "compare ssd prices on amazon vs walmart"
# → claude calls scrape_page on each PDP

HTTP-транспорт автообнаружение инструментов без связующего кода

2 Copilot в Cursor с веб-инструментами

Добавьте тот же MCP-сервер в Cursor — и ваш IDE-агент сможет подтягивать свежую документацию, проверять цены конкурентов или скрейпить ответ со Stack Overflow прямо в процессе.

# .cursor/mcp.json (project root)
{
  "mcpServers": {
    "yozh": {
      "type": "http",
      "url":  "http://localhost:8000/mcp"
    }
  }
}

# prompt in Cmd+L composer:
# "fetch the latest pricing from acme.com/plans
#  and update PricingTable.tsx"

конфиг на проект тот же MCP-эндпоинт вызовы инструментов в чате

3 Цикл на LangChain / Anthropic SDK

Обычный Python-агент — Anthropic SDK со списком mcp_servers. Один HTTP-URL, и модель получает каждый инструмент Yozh. Точно так же работает с MCP-адаптером LangChain.

# anthropic SDK · plain python
client = Anthropic()
resp   = client.messages.create(
  model="claude-sonnet-4-5",
  mcp_servers=[{
    "type": "url",
    "url":  "https://your-host/mcp"
  }],
  messages=[{
    "role": "user",
    "content": "crawl docs.x.com, summarize"
  }],
)

SSE-стриминг автопилот с набором инструментов ваш оркестратор

FAQ

Частые вопросы про MCP и интеграцию с агентами

Какие MCP-клиенты поддерживаются?

Всё, что говорит по HTTP-транспорту Model Context Protocol: Claude Desktop, Cursor, Cline, Continue, Zed, MCP-нода n8n, MCP-адаптер LangChain и параметр mcp_servers в Anthropic SDK. Эндпоинт на localhost:8000/mcp — это один URL, на который вы направляете любой из них. Никаких обёрток под каждый клиент и stdio-прослоек.

Как инструменты регистрируются у агента?

Автообнаружение по MCP. Когда клиент подключается к /mcp, сервер перечисляет каждый доступный инструмент с его JSON-схемой: scrape_page, scrape_batch, crawl, create_session, list_presets, generate_preset. Модель видит их как нативные инструменты во время выполнения — без декораторов, без ручных схем. Новые возможности в апстриме yozh-scraper появляются автоматически после следующего обновления.

Может ли мой агент получать многошаговый краулинг потоком?

Да — Yozh Crawler обходит сайт на стороне сервера и отдаёт найденные URL потоком по SSE. Агент вызывает crawl один раз и получает единый поток событий со структурированными результатами по мере их появления. Каждый краулинг поддерживает область (same-domain / same-host / allow-list), RPS на домен и опциональное сцепление со скрейпером, чтобы каждый найденный URL был разобран до попадания в поток. Отмена через DELETE /scrape/{id} — мягкая остановка даёт долететь страницам в процессе; жёсткая — второй вызов.

Как сессии сохраняются между вызовами инструментов?

Sessions API. Создайте сессию один раз декларативным DSL для входа (goto / fill / click / wait) или вставкой экспортированных куки. Yozh хранит куки + storageState Playwright на стороне сервера и выдаёт вам «липкий» session_id. Каждый следующий вызов инструмента с этим ID переиспользует то же состояние браузера — включая порталы с 2FA, LinkedIn, партнёрские админки. TTL по умолчанию 24 часа, продлевается. Агент никогда не касается учётных данных — он лишь передаёт полученный ID сессии.

Как расширить своими инструментами?

Три варианта. (1) Свой пресет — положите JSON-файл в src/presets/custom/ или вызовите POST /api/v1/presets/generate с примером URL и дайте LLM определить схему. Пресет появляется как параметр у существующего инструмента scrape_page. (2) Свой MCP-инструмент — зарегистрируйте свой обработчик в src/mcp/tools/, он попадёт в автообнаруживаемый список. (3) Форк — репозиторий под лицензией MIT, MCP-сервер живёт в одном Python-модуле (src/mcp/server.py) и легко расширяется.

Инструменты, которые ваш агент реально может вызвать

Агентам нужны настоящие веб-инструменты, а не самописные Python-обёртки

Отдельный Python-инструмент на каждый источник

Вызовы инструментов без состояния теряют контекст входа

Ручная авторизация и обвязка прокси в коде агента

Многошаговый краулинг внутри агент-цикла

От `docker compose up` до агента, вызывающего инструменты, — за 3 шага

Что вы получаете на выходе — одна структура для каждого маркетплейса

Как агенты подключают это — по 10 строк на каждый

Частые вопросы про MCP и интеграцию с агентами

Готовы дать своему агенту настоящие инструменты?

Нас любят data-команды и AI-разработчики

Инструменты, которые ваш агент реально может вызвать

Агентам нужны настоящие веб-инструменты, а не самописные Python-обёртки

Отдельный Python-инструмент на каждый источник

Вызовы инструментов без состояния теряют контекст входа

Ручная авторизация и обвязка прокси в коде агента

Многошаговый краулинг внутри агент-цикла

От docker compose up до агента, вызывающего инструменты, — за 3 шага

Что вы получаете на выходе — одна структура для каждого маркетплейса

Как агенты подключают это — по 10 строк на каждый

Частые вопросы про MCP и интеграцию с агентами

Готовы дать своему агенту настоящие инструменты?

Нас любят data-команды и AI-разработчики

От `docker compose up` до агента, вызывающего инструменты, — за 3 шага