Чому не спрацьовує спеціальний код-зв'язка для інструментів

Агентам потрібні справжні веб-інструменти, а не спеціальні обгорнуті модулі на 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-ендпоінт
Автовиявлення
Без зв'язувального коду

Виклики інструментів без збереження стану втрачають контекст входу

Проблема. Виклики інструменту не зберігають стан — кожен виклик запускає новий браузер, видаляє файли cookie та не проходить другий етап двофакторної аутентифікації. Агенти, що застрягли в циклі повторного входу, швидко витрачають токени та припиняють спроби після третьої спроби. Ручне зберігання файлів cookie є ненадійним і призводить до їх витоку між запусками.

Як Yozh Scraper вирішує цю проблему. API сесій із «прилипаючим» session_id агентом, що зберігається між викликами. Декларативний DSL для входу (goto / fill / click / wait) або вставте експортовані файли cookie один раз — стан зберігання зберігається протягом 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 — агент для проведення дослідження на основі даних з відкритих джерел

Один раз підключіть 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 Cursor Copilot із веб-інструментами

Додайте той самий сервер 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

Агент Plain Python — Anthropic SDK із mcp_servers списком. Один URL-адресу HTTP — і модель отримує всі інструменти 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, вузол n8n MCP, адаптер LangChain MCP, а також параметр mcp_servers param. Кінцева точка за адресою 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 один раз, отримуючи єдиний потік подій зі структурованими результатами по мірі їх надходження. Кожне сканування підтримує налаштування області дії (в межах одного домену / одного хосту / списку дозволених), RPS для кожного домену та опціональне ланцюгове підключення до скрепера, завдяки чому кожна знайдена URL-адреса аналізується ще до потрапляння в потік. Скасування за допомогою DELETE /scrape/{id} — м’яка зупинка дозволяє завершити обробку сторінок, що вже обробляються; примусова зупинка здійснюється другим викликом.

Як сесії зберігаються між викликами інструментів?

API сесій. Створіть сесію один раз за допомогою декларативного DSL для входу (goto / fill / click / wait) або шляхом вставлення експортованих файлів cookie. Yozh зберігає файли cookie на стороні сервера Playwright storageState на стороні сервера та надає вам фіксований session_id. Кожен наступний виклик інструменту, що передає цей ідентифікатор, повторно використовує той самий стан браузера — включаючи портали, захищені двофакторною автентифікацією, LinkedIn та адміністративні панелі партнерів. Час життя (TTL) за замовчуванням становить 24 години, його можна оновити. Агент ніколи не має доступу до облікових даних; він лише пересилає ідентифікатор сесії, який отримав у відповідь.

Як розширити функціонал за допомогою власних інструментів?

Три варіанти. (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 кроки