{% extends "base.html" %}

{% block title %}{{ name }} — Документація{% endblock %}
{% block meta_description %}Як працює MCP-конектор {{ name }}: інструменти, джерела даних, автентифікація та обмеження.{% endblock %}

{% block content %}
<h1>Конектор {{ name }}</h1>
<p class="lede">MCP-сервер над каталогом {{ shop_url }} — рибальство, одяг і
взуття, туристичне спорядження, ножі та ліхтарі, полювання й спортивна
стрільба.</p>

<span class="endpoint">{{ mcp_url }}</span>

<p>Конектор працює <strong>лише на читання</strong>. Він відповідає на питання
про каталог: що є в наявності, скільки коштує, як змінювалася ціна, що пишуть
покупці і що підходить під конкретну стрілецьку дисципліну. Він не може
оформити замовлення, прийняти оплату чи змінити щось у магазині — коли покупець
визначився, конектор дає посилання на картку товару на {{ shop_url }}.</p>

<h2>Навіщо це</h2>

<p>Спорядження купують за характеристиками. У вудлища є довжина, тест і стрій;
у спальника — температура комфорту; у куртки — мембрана й проклейка швів; у
прицілу — кратність, об'єктив і сітка. Що саме підійде, залежить від того, як
людина цим користується, а це розмова, а не фільтр.</p>

<p>Конектор дозволяє спитати своїми словами — «спінінг на окуня до 2 500 ₴»,
«двомісний намет, який тримає справжній вітер», «черевики, щоб висидіти січневу
засідку» — і отримати відповідь із живого каталогу, а не здогад.</p>

<p>Типові сценарії:</p>
<ul>
  <li>Знайти товари за описом, брендом, категорією, ціновим діапазоном чи наявністю.</li>
  <li>Відкрити повну картку: характеристики, шлях у категоріях, рейтинг.</li>
  <li>Подивитися, як рухалася ціна за останні місяці, перш ніж купувати.</li>
  <li>Прочитати відгуки покупців разом із відповідями магазину.</li>
  <li>Окремо для стрільби — підібрати спорядження під дисципліну за правилами
  самого магазину.</li>
</ul>

<h2>Дані</h2>

<dl class="rows">
  <div class="row"><dt>Джерело</dt><dd>Публічний каталог <a href="{{ shop_url }}">{{ shop_url }}</a>, який веде {{ legal_entity }}.</dd></div>
  <div class="row"><dt>Обсяг</dt><dd>Близько 132 000 товарних позицій у 71 000 товарів, 1 300+ брендів, 1 000+ категорій.</dd></div>
  <div class="row"><dt>Асортимент</dt><dd>Рибальство (~52 тис. позицій), одяг та взуття (~38 тис.), спорядження для туризму (~20 тис.), зброя з оптикою та боєприпасами (~13 тис.), товари для військових (~9 тис.), ножі та ліхтарі (~8 тис.), подарунки (~2 тис.).</dd></div>
  <div class="row"><dt>Свіжість</dt><dd>Ціни й наявність асортименту оновлюються щодня з товарного фіду магазину; ширший каталог — за повільнішим циклом.</dd></div>
  <div class="row"><dt>Валюта</dt><dd>Усі ціни — гривні (UAH).</dd></div>
  <div class="row"><dt>Мова</dt><dd>Назви, описи й відгуки українською, як їх публікує магазин.</dd></div>
</dl>

<div class="card">
  <p><strong>Каталог — це знімок, а не каса.</strong> Наявність і ціни можуть
  відставати від магазину до доби. Сервер повідомляє про це у власних
  інструкціях, тож модель попереджає користувача, коли питання впирається в
  актуальність. Перед тим як покластися на ціну, перевіряйте на {{ shop_url }}.</p>
</div>

<h2>Інструменти</h2>

<p>Усі інструменти лише читають, і кожен це декларує
(<code>readOnlyHint</code>, неруйнівний, ідемпотентний, закритий світ) — клієнт
може міркувати про них, не викликаючи.</p>

{% for tool in tools %}
<div class="tool">
  <div class="tool-head">
    <span class="tool-name">{{ tool.name }}</span>
    <span class="tag">{{ tool.scope }}</span>
  </div>
  <p>{{ tool.description }}</p>
</div>
{% endfor %}

<h3>Промпти</h3>
<ul>
  {% for slug, text in prompts %}<li><code>/{{ slug }}</code> — {{ text }}</li>
  {% endfor %}
</ul>

<h3>Ресурси</h3>
<p>Каталог також читається як документи, а не лише викликається як інструменти:</p>
<ul>
  {% for uri, text in resources %}<li><code>{{ uri }}</code> — {{ text }}</li>
  {% endfor %}
</ul>

<h3>Картка товару в чаті</h3>
<p>Сервер віддає ресурс MCP Apps UI — <code>ui://ibis/product-card</code>, який
малює товар прямо в розмові з фото й ціною і вміє дозапитати історію ціни.
Клієнти без підтримки MCP Apps отримують звичайний структурований вміст і
втрачають лише оформлення.</p>

<h2>Автентифікація</h2>

<p><strong>Вхід не потрібен.</strong> Конектор віддає каталог товарів — те
саме, що будь-хто читає на сайті, — тож не треба ні реєструватися, ні вставляти
ключ. Підключіть і питайте.</p>

<p>Клієнт отримує права лише на читання (<code>catalog:read</code>,
<code>prices:read</code>, <code>reviews:read</code>, <code>images:read</code>)
і обмеження кількості запитів на адресу. Права на запис не існує в принципі:
сервер не вміє нічого змінювати.</p>

<p>Оскільки вхід не потрібен, сервер не оголошує сервер авторизації: документи
OAuth-discovery та ендпоінти <code>/oauth/*</code> у цій конфігурації
відповідають 404, тож клієнт підключається напряму, а не проходить через екран
згоди, який йому не потрібен. Реалізація OAuth&nbsp;2.1 за цим перемикачем
існує — метадані захищеного ресурсу (RFC&nbsp;9728), метадані сервера
авторизації (RFC&nbsp;8414), динамічна реєстрація клієнтів (RFC&nbsp;7591),
PKCE&nbsp;S256, refresh-токени, resource indicators і відкликання
(RFC&nbsp;7009) — і буде увімкнена, якщо конектор колись почне зберігати щось,
що належить конкретному користувачу. Організація, якій уже сьогодні потрібен
іменований креденшл із власним лімітом, може запросити статичний API-ключ.</p>

<h3 id="enterprise">Налаштування для організації</h3>

<p>Адміністратору, який розгортає це на компанію, не потрібно нічого, крім
адреси вище: входу немає, тож немає ключа, який треба видавати на кожного,
немає OAuth-клієнта, якого треба реєструвати, і немає списку, який треба
підтримувати.</p>

<p>Питання, на яких зазвичай зупиняється погодження:</p>
<ul>
  <li><strong>Дані вашої організації нікуди не йдуть.</strong> Конектор читає
  публічний каталог товарів. Він отримує лише те, що людина шукає, — без
  облікового запису, історії розмови й файлів.</li>
  <li><strong>Записати нічого не можна.</strong> Усі інструменти лише читають;
  права на запис клієнтам із каталогу конекторів не видаються.</li>
  <li><strong>Запити обмежені за частотою</strong> на кожен креденшл, а ліміт і
  підказку про повтор клієнт отримує в самій помилці — некоректний клієнт
  деградує, а не заважає іншим.</li>
  <li><strong>Строк зберігання</strong> журналу викликів описано в
  <a href="{{ privacy_url }}">політиці конфіденційності</a>.</li>
</ul>

<p>Якщо організації потрібен окремий креденшл, інший ліміт або підписана
угода — пишіть на <a href="mailto:{{ support_email }}">{{ support_email }}</a>.</p>

<h2>Обмеження</h2>
<ul>
  <li>Один пошук повертає щонайбільше 50 позицій; разом із ними йде загальна
  кількість збігів, щоб модель запропонувала звузити фільтри, а не гортала
  наосліп.</li>
  <li>Посилання на фото підписані й діють близько години.</li>
  <li>Історія ціни типово за 180 днів.</li>
</ul>

<h2>Підтримка</h2>
<p>Питання, звіти про помилки та запити на доступ —
<a href="{{ support_url }}">сторінка підтримки</a>.</p>
{% endblock %}