Adobe Launch / Tags MCP Server

MCP-сервер, оборачивающий Adobe Experience Platform Reactor API — API, лежащий в основе Adobe Launch, теперь называемого Adobe Experience Platform Tags.

Он предоставляет ассистенту доступ на чтение к вашим свойствам тегов, правилам, элементам данных, расширениям, библиотекам и средам, а также возможность вносить изменения. По умолчанию он ничего не публикует. Ничто из того, что делает этот сервер, не попадает на живой сайт, если вы явно не включите режим dangerous и не одобрите сборку.

Почему это существует

API Reactor — это поверхность JSON:API с ~240 конечными точками и несколькими острыми углами, из-за которых его неудобно передавать модели в сыром виде:

• Конфигурация делегата хранится в атрибуте settings, который представляет собой строку в формате JSON, а не объект. Передача объекта возвращает непонятную ошибку 422.

• Ресурсы тяжёлые — компонент правила содержит около 20 полей аудита, — поэтому список из 200 правил переполнит контекстное окно.

• Правила бессмысленны без их компонентов, которые находятся на отдельной конечной точке.

• Авторинг и публикация — это совершенно разные задачи, и их легко перепутать.

Этот обёртка решает все четыре проблемы: она кодирует и декодирует settings, сокращает ответы до сути, объединяет правила с их компонентами и ограничивает публикацию явным согласием.

Настройка

1. Создайте учётные данные OAuth Server-to-Server

Adobe прекратил поддержку потока Service Account (JWT) 1 января 2025 года. Вам нужны учётные данные OAuth Server-to-Server.

1. Перейдите в Adobe Developer Console и войдите.

2. Создайте новый проект (или откройте существующий).

3. Add API → выберите Adobe Experience Platform Launch API (указан в разделе Experience Cloud).

4. Выберите OAuth Server-to-Server в качестве типа аутентификации.

5. Выберите профиль(и) продукта, которые предоставляют доступ к нужным свойствам. Профили продуктов управляются в Adobe Admin Console; если вы не администратор, спросите своего администратора, какой профиль покрывает ваши свойства. Это самая частая причина пустых результатов или ошибок 403 — учётные данные могут успешно проходить аутентификацию, но при этом ничего не видеть.

6. Со страницы учётных данных скопируйте:

   • Client ID → REACTOR_CLIENT_ID

   • Client Secret → REACTOR_CLIENT_SECRET

   • Organization ID (заканчивается на @AdobeOrg) → REACTOR_ORG_ID

   • Scopes (список, разделённый запятыми, показанный на странице учётных данных) → REACTOR_SCOPES

Сервер обменивает их на 24-часовой токен доступа по адресу https://ims-na1.adobelogin.com/ims/token/v3 и автоматически обновляет его. Вам никогда не придётся работать с токеном самостоятельно.

2. Установка

Готовый пакет без зависимостей поставляется в build/adobe-launch-reactor-mcp.mjs. Это один автономный ESM-файл — для запуска сервера не требуется npm install. Единственное требование — Node 20+.

Чтобы пересобрать его из исходников или запустить тесты:

npm install
npm run build     # tsc -> dist/
npm run bundle    # single file -> build/adobe-launch-reactor-mcp.mjs
npm test

Сервер читает свои учётные данные из переменных окружения, предоставленных вашим MCP-клиентом. Он не загружает файл .env — .env.example служит справочником по тому, какие значения задавать.

3. Настройте ваш MCP-клиент

Claude Desktop — claude_desktop_config.json:

{
  "mcpServers": {
    "adobe-launch": {
      "command": "node",
      "args": ["/absolute/path/to/launch-mcp/build/adobe-launch-reactor-mcp.mjs"],
      "env": {
        "REACTOR_CLIENT_ID": "your-client-id",
        "REACTOR_CLIENT_SECRET": "your-client-secret",
        "REACTOR_ORG_ID": "XXXXXXXXXXXX@AdobeOrg",
        "REACTOR_SCOPES": "openid,AdobeID,read_organizations,additional_info.projectedProductContext,additional_info.roles,session",
        "REACTOR_WRITE_MODE": "read"
      }
    }
  }
}

Claude Code — claude mcp add:

claude mcp add adobe-launch \
  --env REACTOR_CLIENT_ID=... \
  --env REACTOR_CLIENT_SECRET=... \
  --env REACTOR_ORG_ID=...@AdobeOrg \
  --env REACTOR_WRITE_MODE=safe \
  -- node /absolute/path/to/launch-mcp/build/adobe-launch-reactor-mcp.mjs

Затем спросите: «Какие правила есть в моём свойстве Acme Web, и какие из них не опубликованы?»

Конфигурация

Режимы записи

Режим применяется в двух местах: инструменты записи просто не регистрируются ниже своего уровня, а запасной выход reactor_request разрешает HTTP-методы в зависимости от режима — поэтому модель не может обойти уровень, вызвав необработанную конечную точку.

safe — правильный выбор по умолчанию для большинства задач. Авторинг в Reactor не разрушителен: новое или изменённое правило находится в состоянии авторинга свойства и ничего не меняет на живом сайте, пока библиотека, содержащая его, не будет собрана и опубликована. Вынос публикации в отдельный, явно включаемый уровень означает, что ошибка — это то, что вы исправляете в интерфейсе, а не инцидент.

Инструменты

Чтение (все режимы)

Авторинг (safe и dangerous)

reactor_create_rule, reactor_update_rule, reactor_create_rule_component, reactor_update_rule_component, reactor_create_data_element, reactor_update_data_element, reactor_install_extension, reactor_update_extension, reactor_create_library, reactor_update_library, reactor_library_add_resources, reactor_library_remove_resources, reactor_create_note.

Разрушительные (dangerous только)

reactor_create_build, reactor_transition_library, reactor_delete_resource. Все три требуют явного аргумента confirm: true и несут аннотацию MCP destructiveHint, поэтому корректный клиент запросит подтверждение перед их выполнением.

Примечания по API

Фильтрация. Инструменты списка принимают объект filter, ключом которого является атрибут, со значениями вида "OPERATOR value". Операторы: EQ, NOT, LT, GT, BETWEEN, CONTAINS.

{ "filter": { "name": "CONTAINS checkout", "enabled": "EQ true" } }

Adobe молча игнорирует фильтры по нефильтруемым атрибутам и возвращает полный набор, поэтому фильтр, который, кажется, ничего не делает, обычно является опечаткой или неподдерживаемым атрибутом, а не действительно пустым результатом.

Фильтруемые атрибуты по ресурсам:

• rules, rule_components, data_elements: name, enabled, dirty, published, published_at, revision_number, origin_id, created_at, updated_at (rule components также negate)

• properties: name, platform, enabled, token, created_at, updated_at

• extensions: name, display_name, version, enabled, dirty, published, revision_number, created_at, updated_at

• libraries: name, state, stale, published_at, created_at, updated_at

• environments: name, stage, archive, token, created_at, updated_at

• builds: status, token, created_at, updated_at

• hosts: name, type_of, created_at, updated_at

Пагинация. 25 записей на страницу по умолчанию, максимум 100. Передайте fetch_all: true, чтобы пройти по всем страницам (не более 20 страниц). Ответы, превышающие REACTOR_MAX_RESPONSE_CHARS, обрезаются на границе записи, поэтому JSON остаётся разбираемым и сообщает, сколько было отброшено.

Лимиты запросов. Мягкий лимит Reactor составляет примерно 120 запросов в минуту на интеграцию. Клиент повторяет попытки при 429 и 5xx с экспоненциальной задержкой, учитывая Retry-After.

Настройки. Reactor хранит конфигурацию делегата в виде JSON-строки. Инструменты записи принимают обычный объект и кодируют его; инструменты чтения декодируют его обратно. Если вы передаёте строку, она передаётся без изменений.

Модель публикации. Изменения при авторстве инертны. Чтобы сделать изменение активным: создайте или отредактируйте ресурсы → добавьте их в библиотеку → соберите библиотеку → переведите её в состояние published. Последние два шага требуют режима dangerous; в противном случае выполните их в интерфейсе Launch.

Разработка

npm run typecheck   # tsc --noEmit
npm test            # 35 tests against an in-memory mock of IMS + Reactor
npm run build       # compile to dist/
npm run dev         # run from source via tsx

Тестовый набор покрывает построение заголовка аутентификации и кэширование токенов, форму гранта client_credentials, кодирование фильтров/сортировки/страниц JSON:API, обход нескольких страниц, формирование и усечение ответов, кодирование/декодирование settings, построение связей, ограничение режима записи (включая то, что прямой проход не может быть использован для его обхода), а также качество сообщений об ошибках для 404/422/429/500.

Структура

src/
  config.ts        env parsing, write-mode tiers
  auth.ts          IMS OAuth S2S token manager with caching + refresh collapsing
  client.ts        JSON:API client: headers, query encoding, retry, pagination, error formatting
  format.ts        response shaping and size-capped serialization
  server.ts        MCP server assembly
  index.ts         stdio entrypoint
  tools/
    common.ts      shared argument schemas and helpers
    read.ts        read-only tools
    write.ts       authoring tools + dangerous tier
    raw.ts         method-gated passthrough

Лицензия

MIT.