Исторический документ из исходной ревизии 61e75e9. Этот план реализации сохранён для справки и не является актуальной инструкцией по реализации. Исходный документ.

Техническое задание: OKF v0.2 в okf-mcp

1. Цель

Сделать MCP-адаптер v0.2, спроектированный от схемы, с подробными структурированными результатами и безопасным предпросмотром/применением изменений, сохранив прежний текстовый контракт пяти инструментов.

Зависимости: task09.md–task18.md.

2. Схемы в репозитории

Добавить internal/mcpserver/contracts/*.schema.json для:

• общих конвертов, конвертов версии и ошибок;
• перечисления, чтения, проверки и графа;
• результата прежней операции записи;
• предпросмотра/применения патча концепта;
• предпросмотра/применения миграции.

JSON Schema — источник истины:

• инструмент регистрирует исходные схемы входа/выхода;
• включена валидация серверного вывода;
• объекты закрыты через additionalProperties: false, кроме явно заданных расширений;
• даты/временные метки/перечисления/лимиты зафиксированы;
• массивы не сериализуются как null;
• успешный результат возвращает structuredContent и резервный текстовый вывод прежнего формата.

Стабильный конверт ошибки содержит code, message, retryable и диагностику.

3. Совместимость существующих инструментов

list_concepts

Добавить входной параметр as_of. Структурированный результат включает:

• объявленную/эффективную версию и совместимость;
• статус/доверие/устаревание/время создания (generated)/количество источников;
• маркер аттестованного вычисления (Attested Computation)/среды исполнения;
• явный маркер данных, полученных из старого формата.

read_concept

Сохранить исходный текст Markdown. Структурированный результат содержит:

• frontmatter_yaml без потерь;
• тело;
• типизированное представление известных полей v0.2;
• флаги резервного чтения старого формата.

Не преобразовывать неизвестный YAML в закрытую JSON-модель с потерями.

validate_bundle

Входные параметры:

• target_version: auto|0.1|0.2;
• явный as_of.

Вывод:

• объявленная/эффективная версия, разрешение версии, совместимость;
• соответствие отдельно от рекомендаций;
• счётчики и стабильный код диагностики/поле/ссылка на спецификацию.

get_semantic_graph

Резервный текстовый вывод остаётся выводом пакета graph; структурированное содержимое — разобранный документ согласно профилю task12. MCP не строит собственную модель графа.

write_concept

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

4. Инструменты безопасного редактирования

Добавить:

• preview_concept_patch;
• apply_concept_patch.

Операции отображаются только на доменные операции task14. Предпросмотр возвращает:

• applicable/noop/rejected;
• исходную/результирующую ревизию;
• дайджест плана;
• ограниченный по размеру diff;
• затронутые пути;
• диагностику;
• подтверждение сохранения неизвестного содержимого.

Применение требует expected_revision и expected_plan_digest, заново строит план и публикует через CAS/журнал хранилища. Прямая запись в файловую систему запрещена.

5. Инструменты миграции

Добавить:

• preview_v02_migration;
• apply_v02_migration.

Это адаптеры планировщика task15:

• явный субъект при создании generated;
• безопасная политика старого timestamp;
• извлечение цитирований только при явном сопоставлении;
• ручные действия/блокирующие проблемы при неоднозначности;
• одно транзакционное применение к нескольким файлам;
• идемпотентное повторное выполнение.

6. Безопасность

• Значения resource/computation/executor/attester — пассивные данные.
• MCP не обращается к сети и не исполняет код.
• Метаданные субъекта не являются аутентификацией.
• Сохранить границы абсолютного корня, запрет следования по ссылкам, ограничение путей корнем и CAS.
• Добавить ограничения на байты входа/элементы/вложенность/различия.
• Ошибки не раскрывают пути вне корня.
• Отмена между разбором/валидацией/предпросмотром/фиксацией не оставляет изменений.

7. Файлы

• internal/mcpserver/server.go;
• tools.go, write.go;
• новые patch.go, migration.go;
• схемы в репозитории;
• тесты протокола/инструментов/контрактов/миграции/состязательных сценариев;
• документация после стабилизации контракта.

8. Тесты

Все тесты следуют AAA.

• Объявленные схемы/валидация вывода/additionalProperties.
• Старые аргументы/текстовые данные совместимы на уровне байтов.
• Структурированные результаты соответствуют схемам.
• Все уровни доверия, одиночная форма verified/список, граница stable/stale.
• v0.1/v0.2/отсутствующая/будущая версия/переопределение.
• Детерминированные массивы/диагностика.
• Сохранение неизвестного YAML/комментариев/тела.
• Изменения с потоковым YAML/псевдонимами/дубликатами/неоднозначностью отклоняются по безопасному принципу.
• Конфликт ревизии/несоответствие плана/повторное выполнение/конкурентная запись.
• Миграция целиком или никак/восстановление.
• Символические ссылки/выход за пределы корня/специальные файлы/UTF-8/лимиты ресурсов.
• Вредоносные значения executor/attester остаются пассивными.
• Отмена оставляет набор без изменений.

9. Критерии приёмки

• Существующие пять инструментов и текстовый контракт сохраняют совместимость.
• Каждый успешный результат имеет проверенный structuredContent.
• Сигналы v0.2 доступны в операциях перечисления, чтения и получения графа.
• Валидация сообщает версию/совместимость/as_of.
• Патч/миграция доступны только по схеме предпросмотр → применение с привязкой к дайджесту/ревизии.
• Ни один инструмент не исполняет и не загружает ресурсы вычислений.
• Тесты пакета MCP и полный набор тестов проходят.

10. Вне рамок задачи

Инструменты исполнения/аттестации, протокол квитанций/вердиктов, ABI/песочница/кеш аттестатора.