Files
flexly-cms/docs/extends/mcp-agent-integration.md
T

236 lines
38 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Внешний агент: MCP, подключение и подготовка изменений
Дата: 2026-11-17.
Статус: архитектурное предложение по результатам обсуждения. Документ сохраняет направление развития и этапы для будущей спецификации; сам по себе не означает готовность MCP, утверждение точного API или начало реализации. Имена новых инструментов и scopes предварительные. Номер будущей спеки здесь не резервируется.
## 1. Цель и границы
Агент подключается по MCP, получает доступный ему контекст сайта, готовит набор изменений, проверяет его и передаёт человеку на просмотр. Применение изменений к рабочим файлам и публикация — отдельные операции с отдельными разрешениями.
Один прикладной контракт должен обслуживать человека, агента и автоматизацию: одинаковые предметные операции, права, схемы, валидация, контроль версий и ошибки. Контент остаётся в Markdown/YAML, публичный сайт — статическим результатом штатного renderer. Отдельная реализация CMS для агента не нужна.
Первый рабочий сценарий: агент изучает страницы, коллекции и каталог фрагментов, предлагает изменения нескольких документов, получает diff и preview, человек проверяет и применяет точную версию предложения. Агент по умолчанию не публикует сайт и не меняет исполняемый код.
## 2. Что уже есть, а чего пока нет
| Область | Фактическое состояние на дату документа |
|---|---|
| MCP | В `src/site_engine/mcp/server.py` перечислены 15 предполагаемых инструментов; `build_server()` вызывает `NotImplementedError`. Работающего подключения нет |
| Зависимость SDK | Extra `mcp` в `pyproject.toml`; наличие зависимости не означает готовность сервера |
| JSON API | FastAPI `/admin/api/v1/`, DTO на Pydantic, внутренний клиент HTML-адаптера |
| Авторизация API | Credentials для внутренних запросов UI, привязанные к админской сессии. Для внешнего агента не предназначены |
| Документы | PageService/EntryService/DocumentService: чтение, создание, преобразование, проверка, явное сохранение |
| Запись | ContentService: безопасные пути, SiteLock, CAS/etag, история, атомарная запись отдельного файла |
| Кандидат в памяти | Общая очередь редактора и overlay одного документа без записи исходника. Это ещё не сохранённый многодокументный changeset |
| Preview | Реальный renderer, immutable snapshots, TTL и CSP; владельцем сейчас служит пользовательская сессия, отзыв связан с эпохой админской авторизации |
| Изучение контента | Схемы, категории фрагментов, метаданные коллекций; структурированные связи и usages записей. Полного индекса Markdown/Jinja/JS нет |
| Релизы | Сборка, публикация и откат; это не workflow согласования предложений агента |
| API keys и RBAC | В `db/models.py` есть декларативные модели User/ApiToken с хешем, scopes и сроками; работающий жизненный цикл ключей и политики агента не реализованы |
| Changeset | `services/changeset.py` — заглушка. `ContentService.update_files` не гарантирует восстановление после аварии между записями файлов |
Текущая архитектура подходит для развития MCP. Основные пробелы — общая авторизация предметных операций, внешний доступ, изоляция предлагаемых изменений и согласование их точной версии.
## 3. Общий прикладной слой
```mermaid
flowchart TD
H[Человек: админка / htmx] --> F[FastAPI JSON]
A[Внешний агент] --> M[MCP / Streamable HTTP]
F --> S[Общие операции и политика доступа]
M --> S
S --> D[Документы, схемы, валидация, preview]
S --> C[Changeset и согласование]
D --> W[Файловый workspace]
C --> W
W --> R[Сборка и immutable-релизы]
```
Выделить транспортно-независимый слой прикладных операций поверх существующих сервисов. Он принимает доверенный контекст вызывающего, проверяет доступ, вызывает предметные сервисы и возвращает единый результат. FastAPI преобразует его в HTTP/JSON, MCP — в результат инструмента. Ядро сохраняет dataclass; общие DTO и схемы операций находятся вне HTML-обработчиков и могут использовать Pydantic на границах.
Из HTTP-маршрутов вынести повторно используемую оркестрацию update/validate/preview, нормализацию предметных ошибок и проверки разрешений. HTTP-статусы, cookies, CSRF и рендер HTML остаются транспортными задачами. Инфраструктурные ошибки логируются со стеком на сервере и безопасным request ID для клиента.
В одном процессе MCP вызывает общие операции напрямую. При отдельном развёртывании допустим серверный API-клиент с той же политикой доступа. Открывать внутренний UI-токен внешнему клиенту нельзя. Дублировать renderer, парсер схем, проверки или файловые записи в MCP нельзя.
Агент получает типизированные операции: metadata, entry_fields, add/update/move/delete block и т. п. Операция `inspector`, работающая с именами HTML-полей, остаётся внутренним адаптером UI. Блоки адресуются по стабильному ID; новые ID следуют правилу `<fragment_id>_<suffix>`.
Авторизация действует на общем входе в прикладные операции, включая чтение. Низкоуровневые файловые сервисы сохраняют собственные ограничения путей и CAS. Внешний транспорт не может обойти политику прямым вызовом иной операции.
## 4. Подключение, API keys и scopes
### 4.1 Транспорт и идентичность
Для удалённых агентов — Streamable HTTP, предполагаемый путь `/mcp`, первоначально внутри того же FastAPI-приложения. Версию протокола и SDK, lifecycle сессии и поведение reverse proxy уточнить в спецификации с учётом выбранных клиентов.
Подключение — отдельная сущность с владельцем, именем агента/интеграции, разрешениями и статусом. Ключ — сменяемый credential подключения, а не пароль администратора. Контекст операции включает владельца, тип актора `agent`, ID подключения, ID credential без секрета, разрешения, область объектов и correlation/request ID.
API key подходит для управляемой интеграции, если клиент умеет передавать Bearer credential. Подключение через стандартную интерактивную авторизацию для разных MCP-клиентов требует OAuth-процесса по поддерживаемой версии MCP. Нельзя обещать совместимость API key со всеми клиентами. Минимальную матрицу клиентов и способ авторизации выбрать до реализации транспорта.
### 4.2 Жизненный цикл ключа
- Создание владельцем с явной областью доступа и сроком действия; секрет показывается один раз.
- Криптографически случайный секрет; в служебном хранилище только стойкий проверочный хеш и несекретный идентификатор, название, владелец, сроки и состояние.
- Просмотр метаданных, последнее использование, отзыв и ротация. Секреты не попадают в ответы диагностики, аудит, URL или логи.
- Отзыв/истечение проверяются на каждом запросе; существующая MCP-сессия не продолжает работу по отозванному ключу.
- Права ключа не превышают действующие права владельца; блокировка владельца и сокращение прав учитываются без повторного подключения.
- Состояние ключей, отзыва и операций общее для workers и сохраняется после перезапуска. Одного process-local словаря недостаточно.
Использовать либо расширить имеющиеся модели служебной БД после проверки миграций и транзакций. Хранилище ключей и workflow не становится источником контента сайта.
### 4.3 Модель разрешений
Предварительное разделение действий:
| Разрешение | Назначение |
|---|---|
| `content:read` | Чтение разрешённых документов и их метаданных |
| `catalog:read` | Доступ к разрешённым схемам фрагментов, коллекций, layouts/display и правилам |
| `assets:read` | Поиск и чтение разрешённых ассетов |
| `changeset:write` | Создание и изменение своих предложений, передача на проверку |
| `preview:read` | Получение preview разрешённого кандидата |
| `changeset:apply` | Применение конкретного разрешённого/согласованного предложения |
| `assets:upload` | Отдельно разрешённая безопасная загрузка |
| `content:write` | Опциональная прямая запись в workspace для доверенной автоматизации |
Это варианты для будущей матрицы, не готовые публичные имена. Правила доступа к чужим changeset, согласования и административных действий определить отдельно. `publish`/`rollback` по умолчанию не выдаются и не включаются в первый набор инструментов агента.
Scope задаёт действие, а отдельные ограничения — сайт, разделы страниц, коллекции и при необходимости объекты/поля. Пустая или отсутствующая область не должна случайно означать полный доступ. Проверять итоговое состояние документа: raw source, status, route, layout, ссылки и вложенные блоки не должны обходить ограничения через другой формат команды.
Фильтрация действует до пагинации и расчёта счётчиков; учитывается в поиске, refs/usages, diff, preview и ошибках. Недоступные документы не раскрываются через соседние результаты. Рендер использует только разрешённую проекцию: возможность увидеть данные, подтягиваемые query/refs/layout, должна быть согласована с правами. Если корректный preview требует недоступных данных, возвращать явное ограничение, не скрытую утечку.
## 5. Онбоардинг и контекст агента
Протокольное подключение и знакомство с сайтом — разные шаги. После initialize клиенту доступен небольшой инструмент `get_agent_context`:
- Идентичность и назначение сайта, язык, включённые features.
- Эффективные права и область доступа этого подключения.
- Версия контракта и схемы, поддерживаемые операции, лимиты.
- Версия workspace и текущего релиза, способ получения схем и правил.
- Семантика draft/workspace/changeset/live, порядок проверки и согласования.
- Инструкции по ID, типизированным ссылкам, bindings, query и явным ограничениям движка.
Стартовый ответ компактный. Документы и схемы загружаются по необходимости. MCP resources публикуют руководство, правила и схемы; prompts могут предлагать типовые сценарии. Критичные сведения доступны также инструментами: поддержка resources/prompts зависит от клиента. Наличие инструкции не заменяет серверную проверку прав.
Каталог формируется из настоящих `fragment.yaml`: ID, name, description, категория, поля, defaults, слоты, допустимые места использования и preview. Категории `content`, `data`, `forms`, `marketing`, `media`, `system`, дополнительные категории и старое плоское размещение сохраняют существующую семантику. Отдельный вручную поддерживаемый каталог для агента не создавать.
Текст страниц, записей и ассетов передаётся как данные сайта. Он не может выдавать новые полномочия, подменять правила подключения или становиться доверенной инструкцией сервера.
## 6. Инструменты и объём ответов
Существующие 15 ToolSpec не покрывают весь самостоятельный рабочий цикл. Предлагаемый состав по задачам:
| Область | Возможности для будущего контракта |
|---|---|
| Ориентация | `get_agent_context`, `get_site_info`, получение правил |
| Контент | `list_pages`, `get_page`, `list_collections`, `list_entries`, `get_entry`, `search_content` |
| Схемы | `list_fragments`, `get_fragment_schema`, `get_collection_schema`, получение layout/display и ограничений регионов |
| Ассеты | `list_assets`, `get_asset`; `upload_asset` только после отдельной реализации загрузок |
| Зависимости | `get_references`, `get_usages` с явным указанием покрытия анализа |
| Предложения | Создание/чтение changeset, добавление типизированных операций, изменение и отказ от предложения |
| Проверка | `validate_changeset`, `get_changeset_diff`, `get_preview_url` |
| Согласование | `submit_changeset`, просмотр состояния; approve/apply только соответствующим акторам |
| Расширения | Rename со ссылками, меню, data, тема — отдельные разрешения и этапы |
Точный набор и объединение инструментов определить в спецификации. Не нужно отдельного инструмента на каждую кнопку UI. Создание страницы/записи и изменение блоков могут быть операциями changeset вместо немедленной записи инструментами `create_*`/`patch_*`.
Обязательные свойства контракта:
- Пагинация, стабильный порядок, фильтры и максимальный размер ответа у списков. Сначала краткие сведения, полный source/schema — отдельным запросом.
- Ограничение размера исходников, числа операций, глубины структуры, стоимости query/рендера и частоты вызовов.
- У чтения документа — source/модель и `etag`; у схем — версия/fingerprint; у кандидата — собственная revision.
- Проверка dry-run не пишет workspace. Создание самого changeset и временных preview — явно описанные служебные записи.
- MCP-результаты структурированы; предметная ошибка отличается от протокольной. Полезные поля: `code`, `message`, `request_id`, `issues`, путь поля, признак возможности повтора и сведения о фактическом commit.
- Нет неограниченного `read_file`/`write_file`, произвольных путей, выполнения Python/Jinja/JS или доступа к секретам через контентные инструменты.
Текущие структурированные refs/usages можно переиспользовать, сохранив ограничение: произвольные ссылки в Markdown/Jinja/JS пока не индексируются. Ответ не должен обещать полноту графа зависимостей.
## 7. Changeset и семантика черновиков
Различать три сущности:
1. `status: draft` — статус документа и участие в публикации.
2. Changeset — ещё не применённое предложение изменить один или несколько документов.
3. Релиз — immutable опубликованный снимок сайта.
Запрет агенту вызывать publish недостаточен: запись в общий workspace может попасть в следующую публикацию человека. Поэтому обычный агент сначала работает с изолированным changeset. Существующая опубликованная страница не переводится автоматически в draft ради подготовки новой редакции.
Предлагаемый цикл:
1. Прочитать нужные документы и схемы, получить базовые версии.
2. Создать changeset с целью и автором.
3. Добавить операции для существующих/новых документов; новые блоки получают стабильные ID.
4. Построить общий overlay нескольких документов с учётом взаимных ссылок и queries.
5. Проверить схемы, ссылки, маршруты и рендер; получить diff и preview.
6. Передать конкретную revision человеку.
7. Человек согласовывает и применяет эту версию; общий workspace меняется через ContentService и механизм журнала.
8. Публикация выполняется отдельно по правилам релизного процесса.
Хранить ID, владельца и актора, цель, базовые etag, revision, операции/подготовленные исходники, schema fingerprint, результаты проверки и сведения о согласовании/применении. Предварительные состояния: editing → submitted → approved → applied; rejected/discarded, conflict и операция с неопределённым результатом должны иметь явное поведение. Точный автомат состояний определить в спеках.
Любое изменение после согласования создаёт новую revision и снимает применимость прежнего согласования. Удаление/rename требует проверки зависимостей и явного списка затронутых объектов. Прямая запись в workspace возможна позднее как отдельная привилегия доверенной автоматизации.
Текущий редактор человека продолжает хранить несохранённые правки в памяти вкладки и писать только по Save. Changeset агента не вводит скрытый autosave документов и не меняет этот контракт.
## 8. Конкурентность, применение и восстановление
Diff, validation, preview и согласование привязываются к одной revision changeset, базовым версиям документов и значимым схемам/зависимостям. Применение перепроверяет их под блокировкой. Для точного просмотренного результата учитывать также изменения данных, влияющих на query/рендер: одного etag изменяемого файла недостаточно. Гранулярность проверки зависимостей либо fingerprint всего workspace выбрать в спецификации.
При конфликте возвращать изменившиеся объекты и разрешённые свежие версии. Агент должен перечитать данные и явно пересобрать предложение. Автоматическая подстановка нового etag и перезапись по принципу «последний победил» недопустимы.
Многодокументное применение требует staging, предварительной проверки набора, журнала и восстановления после сбоя по ADR-004. Нельзя заявлять атомарность нескольких файлов на уровне ОС. Определить, как чтение/публикация исключают наблюдение частично применённого состояния, и выполнять recovery до открытия доступа к workspace.
Создание и применение поддерживают ключ идемпотентности и запрос результата операции. Повтор с тем же ключом и другим payload — конфликт. После таймаута или отказа аудита агент сначала выясняет результат, а не повторяет запись вслепую. Сохранить семантику текущих `committed`/`deleted`, дополнив её ID операции и состоянием.
Согласование changeset не означает согласование любого будущего релиза: публикация общего workspace может включать другие изменения. В этапе 5 админки уже реализованы неизменяемый кандидат релиза и guarded activation (см. [publication-backend.md](../../specs/001-antirion-admin/publication-backend.md)). Связь reviewed changeset агента с этим кандидатом остаётся отдельной задачей будущей MCP-спеки; до неё не обещать публикацию «только проверенного набора».
## 9. Preview, аудит и эксплуатация
Preview агента связывается с подключением, changeset/revision и разрешённым набором данных. Нужен жизненный цикл отдельно от sid и общей эпохи админской сессии: TTL, отзыв, последствия отзыва ключа/подключения, ограничения количества snapshots. У проверяющего человека должен быть доступ через собственную авторизацию или отдельный ограниченный токен просмотра; credential агента ему не передаётся.
Сохраняются immutable snapshots, CSP, изоляция origin, запрет исполнения JS сайта в административном preview и отсутствие побочных записей workspace при рендере.
Аудит связывает владельца, подключение, ключ по несекретному ID, changeset/revision, request/correlation ID, операции проверки/применения и человека, который согласовал/применил/опубликовал. Не логировать секреты, полные тела документов и персональные данные. Успешный commit с отказом аудита должен быть отличим от отказа записи.
Лимиты на ключ/подключение и дорогие операции, совместимость нескольких workers, очистка snapshots/заброшенных changeset, резервное копирование служебного состояния и recovery входят в работоспособность интеграции. Подключение не должно зависеть от памяти единственного процесса.
## 10. Этапы реализации
Это последовательность для будущей спецификации. Сейчас ни один новый этап этим документом не считается выполненным.
| Этап | Состав | Проверяемый результат / зависимость |
|---|---|---|
| 1. Выделить общий прикладной слой | Общие команды/DTO и контекст актора; оркестрация read/update/validate/preview; единые ошибки и точка политики доступа. FastAPI и UI сохраняют поведение | Одни предметные операции доступны из адаптеров, нет копирования логики MCP и обхода сервиса; регрессия текущих UI/API проходит |
| 2. API keys и scopes | Сущности подключения/ключа, хеши, выпуск, TTL, отзыв, ротация, владелец; разрешения действий и объектов; миграции и аудит | Ключ с ограничением видит и меняет только разрешённое; отзыв действует между запросами и после рестарта, в нескольких workers. Внешнюю запись пока не включать |
| 3. MCP-подключение и онбоардинг | SDK/Streamable HTTP, выбранный способ авторизации, `get_agent_context`, resources/prompts, лимиты и диагностика; решение по OAuth | Реальный выбранный внешний клиент подключается, понимает права и получает контекст. Критичные сведения доступны без поддержки resources. Зависит от этапов 1–2 |
| 4. Инструменты чтения | Страницы/коллекции/записи, поиск, схемы, layouts/display, фрагменты с категориями, ассеты, refs/usages; пагинация | Агент самостоятельно находит данные и допустимые способы редактирования без догадок и утечек. Первый полезный релиз MCP только на чтение |
| 5. Изолированный changeset | Сохранённое предложение, версии базы/схем, типизированные операции, overlay нескольких документов, операции создания и отказа | Агент готовит связанные документы; исходный workspace и live не меняются. Это служебная подготовка, не разрешение прямой записи |
| 6. Проверка, diff и preview | Валидация всего кандидата и зависимостей, diff, preview точной revision, отдельные токены просмотра и доступ проверяющего | Человек и агент видят один кандидат; нет смешения live/workspace/changeset, проверка не пишет исходники. Зависит от этапа 5 |
| 7. Согласование и надёжное применение | Submit/review/approve/apply, права и точная revision; CAS зависимостей, staging/journal/recovery, идемпотентность, результат операции и аудит | Применяется согласованный набор; конфликт не затирает чужие данные; авария восстанавливается. Согласование можно выполнить текущим UI/API или CLI; новый экран требует отдельного согласованного дизайна |
| 8. Расширение по потребности | OAuth для дополнительных клиентов, если не вошёл в этап 3; uploads, rename, меню/data/тема, опциональная прямая запись, интеграция с reviewed release candidate | Каждая возможность имеет отдельный scope, зависимость и проверки. Доступ к шаблонам/JS/схемам и publish/rollback не включается автоматически |
Разработку инфраструктуры changeset можно вести параллельно с инструментами чтения после фиксации общего контракта, но включение внешней записи зависит от проверки доступа и надёжности соответствующего пути. Публикация и RBAC могут потребовать отдельных спецификаций; не сводить все направления в один неделимый релиз.
Для будущей приёмки предусмотреть: реальный MCP-клиент; успешный onboarding; фильтрацию чтения/поиска/preview; истечение и отзыв ключа; согласованный многодокументный набор; конфликт с правками человека; таймаут после commit и безопасный повтор; аварию между записями и recovery; совместимость старой админки; отсутствие публикации без отдельного права.
## 11. Что решить при написании спецификации
- Какие внешние клиенты поддерживаем сначала, какая версия MCP/SDK и способ авторизации обязательны; нужен ли OAuth уже в первом релизе.
- Точная матрица ролей/scopes/объектов, доступ к общим данным рендера и правила для недоступных зависимостей.
- Размещение общего прикладного слоя и общих DTO без лишней переработки ядра.
- Служебное хранилище ключей, changeset и результатов операций; миграции, retention, recovery и работа нескольких workers.
- Точный набор инструментов и схемы операций, включая dry-run, source vs typed operations и лимиты ответов.
- Автомат состояний, полномочия согласующего, последствия изменения базы/схем и условия повторного согласования.
- Гранулярность workspace/dependency fingerprint, проверка коллизий маршрутов и взаимных ссылок новых документов.
- Гарантии применения нескольких файлов и поведение всех читателей при незавершённом commit.
- Жизненный цикл preview при отзыве ключа и способ доступа человека к предложению.
- Где человек проверяет предложение: существующие инструменты на первом этапе или новый экран. UI переносится из предоставленного дизайна; самостоятельно новый дизайн не придумывается.
## 12. Связанные документы и код
- [Исходное ТЗ, разделы 11–12](../TZ-site-engine.md) — исторический более широкий набор возможностей.
- [Журнал решений, ADR-004…006](../TZ-site-engine-decisions.md) — CAS, восстановимые changeset, права и границы MVP. Этот документ предлагает уточнения для новой спеки, не подменяет принятые ADR и не возвращает автоматически отложенные возможности старого ТЗ.
- [Заготовка MCP](../../src/site_engine/mcp/server.py), [заготовка changeset](../../src/site_engine/services/changeset.py), [модели служебной БД](../../src/site_engine/db/models.py).
- [Текущий JSON API](../../src/site_engine/web/api/routes.py), [DTO](../../src/site_engine/web/api/models.py), [DocumentService](../../src/site_engine/services/documents.py), [ContentService](../../src/site_engine/services/content.py).
- [Спецификация админки](../../specs/001-antirion-admin/spec.md) и [доработки Content](../../specs/001-antirion-admin/content-backend.md).
- [Фоновый редактор](../../specs/003-background-editor/spec.md) — stateless update, overlay и явное сохранение; эти механизмы переиспользуются без изменения поведения текущего UI.