Зміст
Коротко
Автор на Habr розібрав сервер протоколу MCP, що надає LLM-агенту доступ до даних Яндекс Вебмайстра. Замість кількох десятків окремих методів API сервер пропонує вісім інструментів для зрозумілих завдань: від переліку сайтів і пошукових запитів до діагностики та відправлення URL на переобхід.
Матеріал присвячено не лише обгортці над API. Він описує зручний сценарій входу: агент помічає відсутність авторизації, запускає вхід через Яндекс ID і після підтвердження користувача продовжує виконання запиту. Сервер написано на TypeScript та опубліковано за ліцензією MIT.
Що сталося
Яндекс Вебмайстер зберігає дані про те, як пошук бачить сайт до переходу відвідувача: покази й кліки за запитами, стан індексації, помилки, карти сайту, зовнішні посилання та ліміти переобходу. Ці відомості доповнюють Яндекс Метрику, яка показує поведінку людини вже після переходу.
Автор не створює інструмент на кожен метод API. Натомість виклики MCP об'єднані навколо питання користувача. Наприклад, search_queries видає і перелік популярних запитів, і їхню динаміку, а get_indexing поєднує пов'язані перевірки обходу та сторінок у пошуку.
Окремий get_hosts потрібен не для зручності, а для правильності роботи. Ідентифікатор сайту в API неможливо надійно вгадати за звичайною адресою, тому модель має спочатку отримати перелік доступних сайтів.
Чому це важливо
Шар MCP перетворює звичайний API на інструмент для діалогу з агентом ШІ. Запит на кшталт «які фрази мають багато показів, але мало кліків» стає одним викликом, а не ручним переглядом кількох сторінок консолі та зведенням чисел.
Водночас агенту не варто віддавати необроблені відповіді постачальника. Сервер залишає лише активні діагностичні проблеми, упорядковує їх за серйозністю та додає підсумкові лічильники. Перед запитом на переобхід він повертає залишок добової квоти, щоб дія не була випадковою.
Важливе місце займає і пояснення помилок. Статус 401 означає потребу знову ввійти, а 403 може вказувати, що чинний токен не має прав на певний сайт. Для агента це різні наступні кроки: без такого розрізнення він здатен без користі повторювати авторизацію.
На практиці
Створюючи сервер MCP над зовнішнім API, варто починати з намірів користувача, а не копіювати всі методи по одному. Із розбору можна взяти такі рішення:
- Групуйте методи за результатом, якого прагне людина, і застосовуйте режими там, де вони не ускладнюють інструмент.
- Додайте отримання ідентифікаторів, які модель не може безпечно визначити сама, та прямо зазначте, що це перший виклик.
- Перетворюйте великі відповіді API на стислу відповідь зі станом, контекстом і наступною дією.
- Відокремлюйте операції читання від дій зі зміною стану; перед переобходом показуйте квоту й наявні завдання.
- Не зберігайте довготривалий токен у конфігурації
MCP— для нього потрібне окреме локальне сховище з обмеженими правами.
Для входу використано OAuth-потік авторизації з кодом і механізмом PKCE, а також локальну адресу перенаправлення. Якщо локальний сервер не може зайняти порт, можливий запасний варіант з ручною передачею коду, але його не слід підміняти ним будь-яку помилку обміну.
Підсумок
Основна думка матеріалу: авторизація та обробка помилок — це частина інтерфейсу інструмента для ШІ, а не підготовчий крок у терміналі. Сервер, який запускається без токена й уміє пояснити агенту наступну дію, робить інтеграцію значно доступнішою.
Підхід корисний не лише для Яндекс Вебмайстра. Для будь-якого зовнішнього API варто зберігати важливі відмінності протоколу, кешувати тільки успішні результати та формулювати помилки так, щоб агент міг правильно продовжити роботу в інтеграції MCP.