Рішення 002: єдиний MCP і REST-модуль магазину

Прийнято · 1 жовтня 2026. Засновник обрав другий варіант після обговорення ідентифікації та кошика. Він замінює попереднє рішення того самого дня про MCP безпосередньо в OpenCart. Це цільова архітектура, не твердження про готову інтеграцію.

Рішення

App / чат вітрини → harness Agentfy → MCP / права Store Deputy
                                             ↓ HTTPS REST/JSON
                                        Модуль OpenCart
                                             ↓
                                Справжній каталог і кошик

Agentfy відповідає за виконання агента, skills, розмови й виклики інструментів. Store Deputy — за інтерфейс акаунта та підключення і контрольований доступ до магазину: єдиний MCP, команди, права, контекст людини, підписки, погодження й аудит. Модуль OpenCart надає версіонований REST API, перевіряє звернення та виконує підтримані операції платформи. Повного MCP у модулі немає.

В app: команди (типово одна), агенти, акаунт, білінг і чат із кожним агентом. Connect веде на вхід/реєстрацію, безпечне підключення, автоматичне створення агента в Agentfy з MCP URL Store Deputy й повернення до модуля. Перша команда та базове підключення вже реалізовані локально; інтеграція й нові інструменти — ні.

Три межі повноважень

Межа	Довірене підтвердження	Обсяг доступу
Підключення магазину	Окремі відкличні серверні ключі модуля	Дозволений магазин і його можливості
Дія працівника	Користувач Store Deputy, членство, роль і перевірений контекст runtime	Права цього працівника; точна згода на захищений запис
Діалог покупця	Сесія вітрини, перевірена модулем і пов'язана з розмовою	Кошик цього відвідувача та явно дозволені дані

Agentfy авторизується в центральному MCP; Store Deputy окремо авторизується в модулі. MCP bearer не пересилається в OpenCart. Сервісний ключ Agentfy сам по собі не доводить належність кошика покупцю. Runtime додає поза prompt перевірений контекст: тип учасника, команда/магазин, conversation/run, scopes, строк і за потреби непрозора прив'язка покупця. Модель не обирає собі особу чи права.

Права перевіряються на кожному виклику. Перевірки належності й локальна Pause у модулі діють незалежно від центральної оркестрації. Не можна зберігати current_customer на спільному агенті: кожен відвідувач має окрему розмову й контекст.

Покупець і кошик

1. Віджет звертається до модуля на домені магазину. Модуль визначає гостя/клієнта за справжньою сесією OpenCart, а не за customer_id з браузера.
2. Через захищений серверний обмін створюється прив'язка розмови в Store Deputy. Браузер отримує короткостроковий доступ до чату. Cookie OpenCart залишається в магазині; непрозоре посилання не замінює перевірки повноважень.
3. Agentfy отримує розмову й делегований контекст через сервіс чату. cart.get або cart.addItem(productId, quantity) працює з цією прив'язкою, не з обраним моделлю клієнтом.
4. Store Deputy перевіряє права й прив'язку; модуль повторно перевіряє належність і працює з наявним кошиком засобами OpenCart.
5. Магазин розраховує ціни, наявність, акції, податок і підсумок. Підтверджений результат та ревізія оновлюють видимий кошик; другого незалежного кошика в Store Deputy/Agentfy немає.

Вхід, вихід, завершення сесії та об'єднання гостьового кошика потребують оновлення або відкликання прив'язки. Для кількох вкладок потрібен контроль конфліктів. Зміна має один operation key на намір: повтор не додає товар двічі; інший payload із тим самим ключем відхиляється. Невизначений результат після timeout спершу звіряється. Checkout, платежі, створення замовлень та історія замовлень не входять у перший обсяг кошика.

В OpenCart 3.0.3.5 вибір кошика використовує api_id, customer_id, session_id, а стандартний API login створює окрему API-сесію. Тому самого такого входу недостатньо для кошика відвідувача. Поведінку адаптера треба довести на обох підтримуваних тестових версіях.

Контракт і етапи

Спочатку узгодити REST schemas, MCP transport/auth, делегування Agentfy, capabilities, помилки, відкликання, operation key і cart revision. Конкретні технічні механізми ще треба реалізувати та перевірити. Запропонований контракт, який ще треба погодити, — REST 1.0.

Етап A: захищений API модуля, lifecycle підключення, центральний MCP, контекст працівника, автоматичне створення агента й справжнє читання каталогу. До запису цін за наявним епіком перевірити ізоляцію та відкликання доступу.

Етап B: bootstrap покупця, ізольовані frontend-розмови, читання кошика, потім дозволені зміни й оновлення вітрини. Цей етап залежить від Frontend Agent та підписки; він не блокує першого Admin Agent. Автономного checkout немає.

PHP і модуль — Artem Belikov. API, Agentfy, спільний контракт і наскрізна інтеграція — yevhen.kariakin. Роботи на двох сторонах оформлюються окремими задачами. Наявні продуктові епіки зберігають результати; цей епік створює основу інтеграції.

Наслідки й альтернативи

Єдиний шлюз дає сталий інтерфейс агенту й централізує права, аудит та комерційні обмеження. Відмінності версій сховані в адаптерах; непідтримані функції явно відхиляються. Ціна — додатковий мережевий перехід і залежність операцій від доступності/захисту Store Deputy. Потрібні перевірки і в API, і в модулі.

Прямий MCP у модулі не означає автоматичної втрати контролю: авторизується клієнт MCP, не модель. Для нашого продукту централізовані правила й єдиний інтерфейс корисніші за незалежний MCP кожного магазину. Другий harness у Store Deputy не створюється. Попередні чернетки Bridge RPC не накладають вимог сумісності на REST 1.0; наявний експериментальний код не реалізує цей контракт.

Джерела

• Обговорення із засновником та журнал рішень.
• Авторизація MCP: окремі ресурси й audience токена.
• Безпека MCP: ідентифікатор стану не є авторизацією.
• OpenCart 3.0.3.5: кошик, API login.

Протокол модуля ↔ API: REST 1.0