Власний хостинг

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

Скажемо чесно, як стоять справи: інсталятора «однією командою» для продакшну немає. Є набір Helm-чартів, якими розгортається сам наш сервіс, генератор конфігурації, realm-и як код і скрипт, що піднімає всю систему на одній машині. Якщо вам звично підтримувати сервіс у Kubernetes, це робота на звичайний півдня. Якщо вам потрібен готовий пакет «під ключ», він ще не готовий.

Складники

СкладникЩо він робитьОбов’язковий
Шлюз (gateway)MCPG на власних (first-party) плагінах. Приймає з’єднання MCP, перевіряє особу, застосовує правила для кожного інструмента і для кожного інструмента викликає Postgres або imd-svc.так
PostgresPostgreSQL 17 з pg_trgm, pgvector і pgcrypto під керуванням CloudNativePG. Авторитетний стан і правила реєстру у вигляді SQL-функцій.так
imd-svcВласна служба сервера поруч зі шлюзом: підписи, облікові дані агентів, файли, фоновий виконавець і міграції схеми.так
NATSJetStream: сесії, підписки та сповіщення шлюзу, спільні для його реплік. Нічого довговічного там немає.для двох і більше реплік шлюзу
KeycloakВхід, з realm-ами як кодом: люди, власні облікові дані агентів, адміністратори.так
Модель ембедингівText Embeddings Inference з BAAI/bge-base-en-v1.5, усередині кластера: пошук за змістом. Текст інструкцій його не залишає.ні
СтудіяРедактор: статичний сайт, який входить через ваш Keycloak і зберігає свій робочий простір на вашому сервері.ні

Зверніть увагу на останній рядок. Уся поверхня — це MCP, тож агенти й клієнт командного рядка звертаються до шлюзу напряму. Студія — один клієнт із кількох, і екземпляр, який обслуговує лише агентів, її не потребує. Без моделі ембедингів пошук знаходить слова й назви, але не зміст.

Найменший робочий екземпляр

Продакшн-чарти в локальному кластері k3d, з’єднані так само, як у продакшні, на одному origin: сайт на / зі студією на /editor/, MCP-сервер на /mcp, Keycloak на /auth. Потрібні Docker, k3d, kubectl, helm, Python 3 з PyYAML, Node з pnpm, rsync, openssl і близько 6 ГБ на диску. Це справжній реєстр: версії, посилання (refs), пропозиції, організації, підписи й доставка через MCP — усе працює.

Shell
# 1. build the site, the studio, the docs and Learn for the stack's origin, as one tree (dist/web)
PUBLIC_IMD_AUTH_ISSUER=http://localhost:18080/auth/realms/instruction-md PUBLIC_IMD_AUTH_CLIENT=platform-web \
  PUBLIC_IMD_MCP_URL=http://localhost:18080/mcp PUBLIC_IMD_STUDIO_SIGN_IN=on pnpm build:web

# 2. a k3d cluster, the operators, the secrets and every chart
deploy/k8s/stack/up.sh                  # http://localhost:18080

# the same, on MCPG's published release
IMD_GATEWAY_IMAGE=ghcr.io/mcpg-dev/mcpg:0.1.0-beta.68 deploy/k8s/stack/up.sh

Доки MCPG 0.1.0-beta.68 не опубліковано, типовий шлюз скрипта — це локальна збірка: опублікований образ beta.67 зі шлюзом і двома його бекенд-плагінами, зібраними на машині з deploy/mcpg/data. Після виходу релізу другий варіант використовує опублікований образ і його підписані плагіни. Увійдіть на http://localhost:18080/ і спрямуйте агента на http://localhost:18080/mcp. Realm цього стека має користувачів для розробки; продакшн-realm їх не має. Решта — у deploy/k8s/stack/README.md.

Postgres і резервні копії, які мають значення

Postgres — це весь стан. SQL-прив’язки шлюзу звертаються до нього через PgBouncer у транзакційному режимі, якому потрібен max_prepared_statements, бо MCPG готує свої запити заздалегідь, а LISTEN і читач подій ідуть прямо до основного сервера, бо транзакційний пулер не може тримати LISTEN. Кожен клієнт перевіряє сертифікат сервера за центром сертифікації кластера. Усе це налаштовує чарт.

Резервні копії йдуть через плагін Barman Cloud для CloudNativePG у будь-яке S3-сумісне сховище: WAL безперервно, базова копія щоночі, і те, й те зберігається 30 днів, тож ви можете відновитися на певний момент часу на іншому хості.

YAML
# deploy/k8s/imd-postgres/values.yaml
backup:
  enabled: true
  destinationPath: s3://imd-postgres-backup/imd-postgres
  endpointURL: http://rgw.internal:7480
  credentialsSecret: imd-postgres-backup   # ACCESS_KEY_ID, ACCESS_SECRET_KEY
  retentionPolicy: "30d"
  schedule: "0 0 3 * * *"                  # a base backup nightly; WAL all the time

deploy/k8s/restore-drill.sh відновлює другий кластер зі сховища, порівнює кожну таблицю з робочою і видаляє його. Запустіть його після першої нічної копії та після будь-якої зміни в резервному копіюванні. NATS резервних копій не потребує: якщо його втратити, шлюз відбудує те, що там тримав.

Ідентифікація

Шлюзу потрібні від токена три речі: сталий суб’єкт, аудиторія, прив’язана до вашої точки доступу MCP, і твердження про те, хто викликає — людина, агент чи служба, бо агенти обмежені нижче від повного адміністрування, хоч би від чийого імені вони діяли. Сервер покладається на Keycloak не лише для входу: imd-svc випускає власні облікові дані кожного агента в realm-і агентів. Тому постачальник ідентифікації — Keycloak, а ваші люди все одно можуть входити через вашого власного постачальника завдяки брокерингу Keycloak.

Realm-и постачаються як код, згенерований, а не написаний вручну (deploy/keycloak/gen-realms.py): один для людей, один для агентів, один для адміністраторів. Keycloak імпортує їх під час першого запуску. Після кожного встановлення чи оновлення окреме завдання знову застосовує їхній вміст через адміністративний API: воно додає нове й не чіпає наявного, бо заміна робочого realm-у знищила б організації та зв’язки федеративних ідентичностей. Назовні маршрутизуються лише realm-и людей і агентів. Адміністрування залишається всередині кластера.

Генератори мають профіль для кожного місця, де працює сервер: машина розробника, локальний стек і продакшн на instruction.md. Ваш власний домен — це ваш власний профіль у deploy/mcpg/gen-config.py і deploy/keycloak/gen-realms.py, з вашим origin, видавцями токенів (issuers) та аудиторією.

Підписи

imd-svc виводить ключ видавця для кожної організації з одного головного ключа, тож жоден приватний ключ ніколи не зберігається: публічні половини віддаються для перевірки, а приватні існують лише всередині процесу, поки він підписує. Другий ключ підписує кожну доставку.

Secrets
# deploy/k8s/bootstrap-secrets.sh, in the Secret imd-keys
IMD_SIGNING_MASTER_KEY   # each organization's publisher key is derived from it
IMD_DELIVERY_KEY         # signs each delivery: one reader, one resolution

deploy/k8s/bootstrap-secrets.sh створює обидва під час першого запуску й надалі їх зберігає. Тримайте копію там, де ви тримаєте такі речі: якщо втратити головний ключ, ключ видавця кожної організації зміниться; якщо втратити ключ доставки, попередні доставки більше не можна буде перевірити. Без головного ключа платформа нічого не підписує, і це цілком законний вибір. Видавці все одно можуть принести власні ключі й підписувати на своїх машинах, а отримувачі перевіряють так само.

Kubernetes

Шість чартів, один простір імен, установлюються в такому порядку, і кожного чекають до готовності. У цьому ж порядку їх запускає .github/workflows/deploy-server.yml, і цей workflow передає файли realm-ів і скрипт завдання застосування повністю. Шлюз завантажує свої first-party плагіни під час запуску й допускає лише підписані.

Shell
# first, once per cluster: the CloudNativePG operator, cert-manager and the Barman Cloud plugin
# (docs/runbooks/server-deploy.md §1). Then the namespace's secrets:
deploy/k8s/bootstrap-secrets.sh instruction-md

helm upgrade --install imd-postgres   deploy/k8s/imd-postgres   -n instruction-md
kubectl -n instruction-md wait cluster/imd-postgres --for=condition=Ready --timeout=15m
helm upgrade --install imd-nats       deploy/k8s/imd-nats       -n instruction-md --wait
helm upgrade --install imd-keycloak   deploy/k8s/imd-keycloak   -n instruction-md --wait \
  --set-file realms.users=deploy/keycloak/realms/prod/instruction-md-realm.json …
helm upgrade --install imd-embeddings deploy/k8s/imd-embeddings -n instruction-md --wait
helm upgrade --install imd-svc        deploy/k8s/imd-svc        -n instruction-md --wait \
  --set image.tag=<tag>
helm upgrade --install imd-gateway    deploy/k8s/imd-gateway    -n instruction-md --wait \
  --set-file config=deploy/mcpg/prod.yaml

Скрипт секретів створює кожен секрет у просторі імен. Кожне значення він бере із середовища (те, що йому передає ваш менеджер секретів), інакше з уже наявного Secret, інакше створює нове випадкове, а потім записує похідні Secret-и, які читають чарти. Жоден із них не має бути у файлах values, і чарти їх там не приймуть. Більше ніж одна репліка шлюзу, об’єднана в кластер через NATS, потребує ліцензії MCPG. Локальний стек працює на безкоштовному дозволі MCPG для непродакшн-використання.

Сервер розмовляє одним протоколом, MCP 2026-07-28, у якому немає сесії, тож будь-яка репліка відповідає на будь-який запит. Поки що чарти запускають одну репліку, у кластерному режимі: шлюз досі приймає старіший протокол із сесіями, запити якого на двох репліках можуть потрапити на ту, що не бачила початку їхньої сесії. Друга репліка повернеться, щойно MCPG вимкне цей протокол.

Оновлення та експлуатація

Інструкції з експлуатації (runbooks), якими користується наш сервіс, є в репозиторії в docs/runbooks: розгортання сервера, відкат, ротація ключів, відновлення Postgres, спостережуваність, перевірка релізів MCPG, реагування на інциденти та виведення організації з експлуатації. Вони написані для нашого середовища, але загальний підхід можна перенести.

Ліцензія

Текст специфікації поширюється за ліцензією Creative Commons Attribution 4.0. Реалізовуйте його, цитуйте, відгалужуйте, продавайте. Набір тестів на відповідність має ліцензію Apache 2.0, бо реалізації копіюють ці файли у власні дерева коду.

Код платформи поширюється за Business Source License 1.1. На практиці: ви можете запускати його, змінювати й використовувати для власних потреб, зокрема комерційно, і єдине, чого не можна, — пропонувати його третім особам як конкурентний хостинговий сервіс. Кожен реліз переходить на Apache 2.0 через чотири роки після публікації. Сьогодні це не ліцензія відкритого коду, і повідомлення в репозиторії прямо про це каже.

Комерційну підтримку та альтернативне ліцензування ще не визначено, тож якщо вам потрібне щось із цього, відповідь наразі — розмова, а не сторінка.