Adobe Launch / Tags MCP 서버

Adobe Experience Platform Reactor API를 래핑하는 MCP 서버입니다. 이 API는 Adobe Launch(현재 Adobe Experience Platform Tags)의 기반이 되는 API입니다.

이 서버는 어시스턴트가 태그 속성, 규칙, 데이터 요소, 확장 프로그램, 라이브러리 및 환경에 대한 읽기 액세스 권한을 갖게 하며, 변경 사항을 작성할 수 있는 기능도 제공합니다. 기본적으로 아무것도 게시하지 않습니다. 이 서버가 수행하는 작업은 명시적으로 dangerous 모드를 활성화하고 빌드를 승인하지 않는 한 라이브 사이트에 도달하지 않습니다.

이 서버가 존재하는 이유

Reactor API는 약 240개의 엔드포인트를 가진 JSON:API 표면이며, 모델에 원시 형태로 전달하기 어색한 몇 가지 까다로운 부분이 있습니다.

• 델리게이트 구성은 settings 속성에 저장되는데, 이 속성은 JSON으로 인코딩된 문자열이지 객체가 아닙니다. 객체를 전달하면 이해할 수 없는 422 오류가 반환됩니다.

• 리소스는 방대합니다. 규칙 구성 요소에는 약 20개의 감사 필드가 있으므로 200개의 규칙 목록은 컨텍스트 창을 압도할 수 있습니다.

• 규칙은 별도의 엔드포인트에 있는 규칙 구성 요소 없이는 의미가 없습니다.

• 작성과 게시는 완전히 별개의 문제이며, 이 둘을 혼동하기 쉽습니다.

이 래퍼는 네 가지를 모두 처리합니다. settings를 인코딩/디코딩하고, 응답을 중요한 부분만 남기도록 다듬고, 규칙을 구성 요소와 결합하고, 게시를 명시적 옵트인 뒤에 게이트합니다.

설정

1. OAuth 서버 간 자격 증명 만들기

Adobe는 2025년 1월 1일에 Service Account(JWT) 흐름을 폐지했습니다. OAuth 서버 간 자격 증명이 필요합니다.

1. Adobe Developer Console로 이동하여 로그인합니다.

2. 새 프로젝트를 만들거나 기존 프로젝트를 엽니다.

3. API 추가 → Adobe Experience Platform Launch API(Experience Cloud 아래에 나열됨)를 선택합니다.

4. 인증 유형으로 OAuth 서버 간을 선택합니다.

5. 관심 있는 속성에 대한 액세스 권한을 부여하는 제품 프로필을 선택합니다. 제품 프로필은 Adobe Admin Console에서 관리됩니다. 관리자가 아닌 경우 어떤 프로필이 속성을 포함하는지 관리자에게 문의하세요. 이것은 빈 결과 또는 403 오류의 가장 흔한 원인입니다. 자격 증명이 인증은 정상적으로 수행되지만 아무것도 볼 수 없을 수 있습니다.

6. 자격 증명 페이지에서 다음을 복사합니다.

   • 클라이언트 ID → REACTOR_CLIENT_ID

   • 클라이언트 시크릿 → REACTOR_CLIENT_SECRET

   • 조직 ID(@AdobeOrg로 끝남) → REACTOR_ORG_ID

   • 범위(자격 증명 페이지에 표시된 쉼표로 구분된 목록) → REACTOR_SCOPES

서버는 이 자격 증명을 https://ims-na1.adobelogin.com/ims/token/v3에서 24시간 액세스 토큰으로 교환하고 자동으로 새로 고칩니다. 토큰을 직접 처리할 필요가 없습니다.

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에서 작성은 비파괴적입니다. 새 규칙이나 편집된 규칙은 속성의 작성 상태에 있으며, 해당 규칙을 포함하는 라이브러리가 빌드되고 게시될 때까지 라이브 사이트의 어떤 것도 변경하지 않습니다. 게시를 별도의 명시적으로 활성화된 계층에 유지하면 실수가 사고가 아니라 UI에서 수정할 수 있는 문제가 됩니다.

도구

읽기(모든 모드)

작성(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 UI에서 수행하세요.

개발

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.