Подключите помощника для поиска книг и подготовки покупок. Каталог доступен ограниченными поисковыми окнами; выгрузка каталога и перебор идентификаторов не поддерживаются.
Подключение клиента
Используется Streamable HTTP, версия MCP 2025-06-18. Клиент должен поддерживать HTTP POST JSON и OAuth Authorization Code с PKCE S256. Адрес сервера: https://server.exlibrus.net/api/v1/mcp/customer/. Метаданные авторизации: https://server.exlibrus.net/.well-known/oauth-authorization-server.
Выполните initialize, затем notifications/initialized и tools/list. Клиент регистрируется как публичный OAuth-клиент. Регистрация и подтверждение почты проходят на сайте. Для существующего подтверждённого аккаунта recover_customer_access отправляет специальный MCP-код простым текстовым письмом через SMTP, без HTML и ссылок. Только этот запрошенный MCP-код можно передать агенту для complete_customer_access с исходными PKCE verifier и state. Альтернатива — разрешить выбранные scopes в существующем кабинете. Пароли, коды входа, сброса пароля, 2FA и платёжные данные не передаются в инструменты.
Поиск и заявки
search_books принимает query и фильтры publisher_ids, series_ids, periodical_series_ids и category_path. Ответ содержит до 10 книг, окно одного запроса — до 30. Используйте выданный cursor без изменения запроса и размера страницы. book_details доступен для уже показанной книги. resolve_filters помогает найти значения фильтров по имени.
create_book_request создаёт заявку с дополнительными книгами; get_book_request, инструменты изменения позиций и send_request_message продолжают общий диалог. Capability предварительной заявки даёт доступ только к ней. После подтверждения почты её можно присоединить к своему кабинету.
Заказы, подарки и оплата
Инструменты корзины, checkout_quote и prepare_gift_purchase возвращают точный расчёт, quote_summary, quote_hash и version. Ассистент показывает условия каждого заказа, включая сохранённые условия периодической подписки, дизайн и получателя подарка. После явного согласия пользователя в диалоге ассистент вызывает confirm_purchase с quote_id и expected_quote_hash. Отдельное подтверждение покупки в браузере не требуется. create_order, purchase_gift и purchase_status только читают состояние и повторяемую квитанцию. При изменении условий или истечении расчёта нужны новый расчёт и новое согласие. Оплата выполняется человеком через payment_url, когда счёт готов к оплате; ответ инструмента не означает оплату.
list_orders, order_status и gift_status показывают состояние собственных покупок. gift_config и gift_quote показывают доступный дизайн и расчёт. gift_human_download ведёт в защищённый раздел кабинета: PDF и слова погашения сертификата не выдаются в общем статусе.
Разрешения и восстановление
Scopes: catalog:read, requests:read, requests:write, cart:read, cart:write, orders:read, orders:create, gifts:read и gifts:purchase. Разрешение привязано к конкретному клиенту; отозвать одно или все можно в разделе AI-доступа кабинета. Refresh и восстановление через подтверждённую почту сохраняют ограничения. Новый секрет получается только после человеческого согласия и одноразового PKCE-обмена.
Ошибки и повтор
При 429 учитывайте Retry-After; не обходите лимит сменой токена. При invalid_token обновите доступ, при stale_quote получите новый расчёт и согласие. После тайм-аута повторяйте ту же команду с тем же idempotency_key и неизменным телом. Поддержка: [email protected]. Условия использования и конфиденциальность доступны в навигации сайта.
Семантический поиск и стоимость запросов
Параметр mode: text, vector или hybrid. Vector/hybrid доступны только проверенному покупателю с catalog:read; результаты проходят обычные публичные фильтры. vector_used сообщает, вошли ли в ответ векторные результаты. Недоступный векторный сервис даёт 503: текстовый режим выбирается явно. По умолчанию — 5 семантических запросов в минуту и 10 подготовленных расчётов покупки в минуту на покупателя, до двух параллельных операций каждого вида. Поиск ограничен окном кандидатов, не обещает полноту каталога.
Пример без доступа к аккаунту
Отправляйте сообщения последовательно HTTP POST с Content-Type: application/json и Accept: application/json, text/event-stream. После initialize передавайте MCP-Protocol-Version: 2025-06-18. notifications/initialized возвращает пустой202; сервер работает без SSE GET. Пример выполняет только анонимный текстовый поиск.
{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"shopping-client","version":"1.0.0"}}}{"jsonrpc":"2.0","method":"notifications/initialized"}{"jsonrpc":"2.0","id":2,"method":"tools/list"}{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"search_books","arguments":{"query":"rare books","locale":"en","limit":10,"mode":"text"}}}