# Внешний агент: 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 следуют правилу `_`. Авторизация действует на общем входе в прикладные операции, включая чтение. Низкоуровневые файловые сервисы сохраняют собственные ограничения путей и 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.