Files
crank/docs/development/rmcp-migration-plan.md
T
bsodfather 4832878468
CI / UI Checks (pull_request) Successful in 9s
CI / Rust Checks (pull_request) Successful in 27m19s
CI / Rust Feature Validation (pull_request) Skipped
CI / Frontend E2E (pull_request) Skipped
CI / Community Image Smoke (pull_request) Skipped
CI / Required Checks (pull_request) Successful in 1s
CI / Deploy (pull_request) Skipped
refactor(mcp): migrate compatible logging paths to rmcp SDK
2026-11-11 22:51:42 +00:00

22 KiB
Raw Blame History

Переход Crank на официальный MCP SDK rmcp

Статус: планирование одобрено владельцем 27.10.2026; 05.11.2026 разрешён изолированный опыт этапа 1 (#106), поставленный в v0.4.0-rc.15. Решением владельца 08.11.2026 разрешён первый Tools-срез этапа 2 (#107) в действующем endpoint без смены transport. #108, новая реализация 4.7 и production-переключение этим разрешением не запускаются. Исполняемый кандидат и конкретные несовместимости: rmcp106-tools-adapter.md; это не завершённая миграция. Владелец очереди — hermes_tl; реализация — hermes_dev; независимая проверка — hermes_qa; Git/CI/релизы — hermes_devops. ARC подключается к конкретному техническому затруднению, не как обязательный новый этап. Business reconciliation 4.6 отменена решением владельца и issue #34; она не prerequisite SDK. Input/unknown safety и остальные защитные ограничения сохраняются.

Результат

Стандартный протокольный слой MCP обслуживает официальный SDK. Crank сохраняет авторизацию, права Agent/workspace, опубликованные версии, REST mapping, admission и исполнение команд. Обе действующие версии протокола и функции Tools/Resources/Prompts остаются доступны. Снижается объём собственного протокольного кода; ускорение и производительность не объявляются измеренными заранее.

Исходная точка: принятый main после 4.1, известный merge cc612516a2. Перед исполнением получить актуальный main и убедиться, что в него вошла проверенная поставка. Плановый кандидат SDK — опубликованный rmcp 3.7.0; окончательный pin и lock проверяются на первом этапе, автоматического обновления на другую версию нет.

1. Проверить тонкий адаптер на реальном MCP-пути

Исполнитель: DEV, независимая QA. Риск: высокий — ошибка может нарушить доступ к инструментам.

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

Проверяемый результат:

  • Динамические tools/list и tools/call работают через SDK с действующими сервисами Crank, включая запрет чужого Agent/неверных credentials и сохранение ошибок инструмента.
  • Через настоящий HTTP-путь проверены обе revisions: legacy initialize/session и modern discover/stateless, JSON/SSE, headers, progress и cancellation.
  • Отдельно проверены пригодность SessionManager для существующего хранения сессий, переподключение и владение отменой; наличие SDK-типа само по себе не считается доказательством.
  • Установлены существенные gaps для Resources/Prompts/notifications/subscriptions и текущих execution modes. Наличие интерфейса не выдаётся за полную совместимость.
  • На небольшом smoke-наборе проверено, что adapter не обходит действующие ограничения; замеченный риск памяти/очередей записан. Нагрузочная квалификация относится к завершённой функции, не превращается в условие этого прототипа. Существующие ceilings не меняются.
  • Результат — работающий код и краткое решение TL: готов перенос либо конкретная несовместимость с минимальным вариантом решения. Если потребуется ослабить контракт, заменить хранилище или создать большой дополнительный framework — вопрос владельцу до продолжения.

Это один достаточный опыт, а не серия исследований SDK. Использовать существующие wire fixtures и точечные проверки, сохранять непроверенные пункты явно.

2. Перенести действующие MCP-функции на SDK

Зависит от положительного результата этапа 1 и решения TL о достаточности совместимости. Исполнитель: DEV, независимая QA. Риск: высокий — затрагивается общий клиентский интерфейс.

Подключить SDK к действующему пути и перенести стандартные envelopes, dispatch, lifecycle и transport. Порядок переноса устанавливается по результату первого опыта, без параллельных writers одних MCP-файлов.

Первый срез #107: build_app направляет tools/list обеих revisions и tools/call через app/rmcp_dispatch.rs. Параметры rmcp=3.7.0 (PaginatedRequestParams/CallToolRequestParams) определяют команду существующего shared Tools service; расширения Crank limit/confirmation сохраняются отдельно. Потребитель — штатный MCP HTTP клиент, не изолированный router #106. Текущие admission, свежая identity, lifecycle, era-specific ответы и PostgreSQL sessions остаются у прежнего transport; SDK HTTP transport не подключён. В следующем Tools response-срезе app/response.rs строит и сериализует настоящие rmcp ListToolsResult/Tool и CallToolResult/ContentBlock; эти builders используют оба HTTP dispatch и общий JSON/SSE terminal, а изолированный rmcp_tools переиспользует typed builders. Явная проекция сохраняет revision defaults, pretty text, tool-error contract, isError и present-null structuredContent; после SDK list serialization сохраняются исходные top-level extensions/optional null и непрозрачные annotations/icons. Штатный producer публикует name/title/description/inputSchema: расширения защищены локальной builder-регрессией, а не объявлены новыми runtime-полями. HTTP-тесты проверяют обе revisions, success/tool errors/InvalidParams, ID/correlation, modern SSE terminal и несколько страниц опубликованного каталога. JSON-RPC envelope/status остаются прежней внешней границей; остальные handlers, transport и lifecycle ещё не перенесены. Полный #107 не завершён; проверки #106 не являются доказательством завершения миграции.

Следующий Resources-срез #107 подключает resources/list, resources/read и resources/templates/list обеих revisions к тому же app/rmcp_dispatch.rs: PaginatedRequestParams/ReadResourceRequestParams передают cursor/URI прежнему shared Resources service, а Crank limit сохраняется отдельно. app/response.rs сериализует rmcp ListResourcesResult/Resource, ReadResourceResult/ResourceContents и ListResourceTemplatesResult/ResourceTemplate с прежними revision-specific cache defaults. Минимальная lossless-проекция сохраняет Crank template parameters, extensions/optional null и непрозрачные annotations/icons. Штатные producers по-прежнему публикуют прежние поля; builder-регрессия не добавляет runtime-возможностей. Потребитель — действующий build_app HTTP JSON/SSE terminal. Реальные HTTP-тесты отдельно подтверждают SDK request/result seam и сохранение wire; существующая Resources-матрица проверяет заполненные templates, exact-version binding, text/JSON/blob, scope/revocation и cursors. Handwritten builders этих трёх результатов заменены; domain/storage/auth, envelopes, transport и lifecycle не меняются. Subscribe/unsubscribe/notifications остаются прежними и не объявляются перенесёнными; остальные handlers и полный #107 ещё не завершены.

Prompts-срез #107 подключает prompts/list и prompts/get обеих revisions к app/rmcp_dispatch.rs: реальные PaginatedRequestParams/GetPromptRequestParams передают cursor/name и JSON-значения аргументов прежнему shared Prompts service; Crank limit сохраняется отдельно. app/response.rs сериализует rmcp ListPromptsResult/Prompt и GetPromptResult/PromptMessage/ContentBlock, используемые штатным build_app HTTP JSON/SSE. Lossless-проекция сохраняет typed argument schemas/defaults, extensions/optional null и существующую роль system, которую pinned SDK Role не представляет; она восстанавливается после SDK serialization, не меняя опубликованные message boundaries. Прежний dispatch сохраняет revision-specific result/cache projections и ошибки. HTTP ATDD проверяет wire обеих revisions и реальный SDK request/result seam отдельно; affected Prompts/composition regression — exact binding, archive, typed rendering, pinned static/dynamic Resource content и fail-closed dependency errors. Handwritten list/get builders заменены; domain/storage/auth/envelopes/transport/lifecycle не меняются. Completion, notifications/subscriptions/progress/cancel/logging не объявляются перенесёнными. Полный #107 и feature qualification (UI/full/load/p95) этим срезом не завершены.

Completion-срез #107 на базе rc.20/rmcp3.9.0 подключает completion/complete обеих revisions к тому же request-scoped app/rmcp_dispatch.rs: настоящие CompleteRequestParams/Reference/ArgumentInfo передают reference и argument прежнему shared service. SDK context представляет только строки, поэтому исходный Crank JSON context сохраняется отдельно без фильтрации/приведения типов и проходит прежнюю domain validation. app/response.rs заменяет handwritten completion builder сериализацией CompleteResult/CompletionInfo, сохраняя omission hasMore=false, точный bounded total либо его отсутствие при partial scan и прежнюю внешнюю modern/legacy result projection. Потребитель — штатный build_app MCP HTTP JSON/SSE. Runtime ATDD отдельно наблюдает SDK request/result seam и сохранение Prompt/Resource refs, pinned/archive, populated/empty/bounded результатов, safe refusals/context, correlation/IDs и revoked-key rejection. Domain/storage/auth/envelopes/transport/lifecycle не меняются; signals/logging/subscriptions ещё не перенесены. Это не завершение #107, не external-client/feature qualification и не production deployment.

Logging-срез #107 на базе rc.22/rmcp3.9.0 использует существующий общий protocol/logging.rs, уже подключённый к штатному build_app HTTP: legacy logging/setLevel после прежней bounded string boundary декодируется в настоящий SetLevelRequestParams, а modern _meta[io.modelcontextprotocol/logLevel] — в SDK LoggingLevel. Неизвестные legacy поля, включая _meta, остаются игнорируемыми; неверные уровни дают прежний безопасный INVALID_LEVEL, modern отсутствие/неверное значение не включает logging. Domain severity ordering/store сохраняются явно: SDK enum не задаёт Ord. notifications/message.params сериализуется через LoggingMessageNotificationParam только из закрытого safe vocabulary; JSON-RPC envelope остаётся прежним. HTTP ATDD наблюдает реальные SDK decode/serialization обеих revisions и revoked-auth rejection; существующая logging-матрица и streamed progress regression сохраняют opt-in/isolation/filtering/JSON silence и carried scope. Очереди, try_lock/drop, transport/session/auth/lifecycle/capabilities не меняются; собственного runtime parsing уровня и handwritten params builder больше нет. Потребитель — действующий MCP HTTP клиент; signals/progress/cancel/subscriptions/прочие notifications и envelopes/transport/lifecycle ещё не объявляются перенесёнными. Полный #107, feature qualification и production deployment этим срезом не завершены.

Проверяемый результат:

  • Через SDK проходят действующие Tools, Resources, Prompts, completion, уведомления и подписки в применимых revisions, а также progress/cancel и существующая logging policy.
  • Сохранены авторизация/отзыв доступа, agent scope, advertised capabilities, admission, deadlines и семантика ошибок. SDK defaults не расширяют объявленные capabilities или список разрешённых revisions.
  • Сессии, reconnect и ограничения памяти/очередей сохраняют действующий контракт; in-memory хранилище не заменяет существующее долговременное хранение без решения.
  • Перенесённые участки собственного протокольного кода удаляются по мере принятия. Временный способ безопасного сравнения/отката не превращается во второй постоянный MCP runtime.
  • Существующие affected ATDD подтверждают старое поведение; тесты меняются только там, где проверяли приватное устройство старого адаптера, а не нужный клиенту контракт.

Новые бизнес-возможности, переработка REST runtime, базы, модели или UI в эту работу не входят.

3. Завершить замену и поставить результат

Зависит от принятого этапа 2. Исполнители: DEV/QA, затем DevOps. Риск: высокий — финальный переход общего MCP-пути. Внешняя проверка относительно реализации: независимая QA на существующем клиентском/wire-наборе обеих revisions.

Проверяемый результат:

  • Удалены ставшие ненужными собственные parser/dispatch/transport участки, временные переключатели и неиспользуемые зависимости. Поддержка legacy protocol при этом сохраняется средствами SDK.
  • Один необходимый финальный feature-прогон подтверждает реальный клиентский путь обеих revisions, изоляцию доступа, streaming/cancel/session и применимые ограничения ресурсов. Полный набор не повторяется отдельно каждой ролью; обязательные CI-гейты сохраняются.
  • DevOps выполнил commit/push/PR, protected merge и честный release с проверенными артефактами. Документация описывает активный SDK, поддерживаемые версии и реальные ограничения.
  • План отката указывает предыдущую принятую версию и проверяет совместимость состояния. Production-переключение выполняется только отдельным разрешённым manual deployment по существующему runbook; эта карточка не даёт разрешения на выкатку.

Порядок относительно текущей разработки

  1. Закончить уже выполняемую проверку поставки 4.1, не открывать её разработку заново.
  2. Планировать SDK-адаптер перед дальнейшим расширением заменяемого transport/protocol слоя. Этап 1 не ждёт завершения будущих 4.2–4.7 или всей нагрузочной кампании.
  3. Доменные части будущих задач могут идти параллельно при отсутствии общего writer и явных интерфейсных зависимостях. Новую протокольную реализацию и миграцию одних файлов параллельно не вести.
  4. TL сопоставляет существующие 4.2–4.7 с SDK, чтобы не реализовать вручную уже предоставленный механизм. Действующие продуктовые AC не сокращаются. Неизвестная совместимость — проверка этапа 1, а не повод считать будущие функции готовыми.

Постановка и контроль

Достаточно трёх последовательных исполнений по этапам выше, с same-card QA и действующей приёмкой TL; не создавать отдельный новый бизнес-эпик, PRD, новый тестовый framework или цепочку архитектурных согласований.

На текущем шаге TL фиксирует эти этапы в существующем backlog/Gitea, зависимости и приоритет относительно текущей работы. Будущие исполнительские карточки оставить в triage/backlog; не запускать полную миграцию автоматически из задачи планирования. Сроки не выдумывать до первого опыта. Подтверждённая непригодность SDK эскалируется владельцу с фактами и вариантами, а не молчаливым возвращением к самописному MCP.

Основания

Канонические пути ниже находятся на Hermes 192.168.1.127 (SSH-пользователь codex); относительные пути считаются от /home/codex/code/crank. Это доступный TL источник R, а не текущая локальная папка оператора. Локальная копия аудита у оператора: /home/bsodfather/code/hermes/deploy/mcp-sdk-audit-20261027/REPORT.md.

  • Решение владельца 27.10.2026: запланировать переход на rmcp.
  • Аудит: /home/codex/.hermes/codex-operator/handoffs/crank-rmcp-audit-20261027.md.
  • Действующие AC: _bmad-output/initiative-crank/epic-mcp-capabilities/story-mcp-revision-capabilities.md, в том числе оценка SDK AT-3.1-14; остальные MCP AC остаются действующими.
  • Официальный SDK: https://github.com/modelcontextprotocol/rust-sdk ; документация ServerHandler: https://docs.rs/rmcp/latest/rmcp/handler/server/trait.ServerHandler.html .
  • Общий процесс: /home/codex/.hermes/team/development-delivery.md, validation-policy.md, delivery-efficiency.md.

Предыдущее default-правило «сохранять собственный transport» не является техническим доказательством отказа от SDK. Цель нового плана — проверить и принять SDK-путь; продуктовые и security-контракты сохраняются.