Adobe Launch / Tags MCP Server

Ein MCP-Server, der die Adobe Experience Platform Reactor API kapselt – die API hinter Adobe Launch, jetzt Adobe Experience Platform Tags genannt.

Er gibt einem Assistenten Lesezugriff auf Ihre Tag-Eigenschaften, Regeln, Datenelemente, Erweiterungen, Bibliotheken und Umgebungen sowie die Möglichkeit, Änderungen zu erstellen. Standardmäßig veröffentlicht er nichts. Nichts, was dieser Server tut, erreicht eine Live-Site, es sei denn, Sie aktivieren explizit den dangerous-Modus und genehmigen einen Build.

Warum es das gibt

Die Reactor-API ist eine JSON:API-Oberfläche mit ~240 Endpunkten und einigen scharfen Kanten, die es umständlich machen, sie einem Modell roh zu übergeben:

• Die Delegate-Konfiguration wird in einem settings-Attribut gespeichert, das ein JSON-codierter String ist, kein Objekt. Die Übergabe eines Objekts führt zu einer kryptischen 422.

• Ressourcen sind fett – eine Regelkomponente trägt etwa 20 Audit-Felder –, sodass eine Liste von 200 Regeln ein Kontextfenster überflutet.

• Regeln sind ohne ihre Regelkomponenten bedeutungslos, die sich an einem separaten Endpunkt befinden.

• Erstellen und Veröffentlichen sind völlig getrennte Anliegen, und es ist leicht, sie zu verwechseln.

Dieser Wrapper behandelt alle vier: Er codiert und decodiert settings, reduziert Antworten auf das Wesentliche, verbindet Regeln mit ihren Komponenten und macht das Veröffentlichen von einer expliziten Opt-in abhängig.

Einrichtung

1. Erstellen Sie eine OAuth Server-to-Server-Anmeldeinformation

Adobe hat den Service Account (JWT)-Flow am 1. Januar 2025 eingestellt. Sie benötigen eine OAuth Server-to-Server-Anmeldeinformation.

1. Gehen Sie zur Adobe Developer Console und melden Sie sich an.

2. Erstellen Sie ein neues Projekt (oder öffnen Sie ein vorhandenes).

3. API hinzufügen → wählen Sie Adobe Experience Platform Launch API (aufgeführt unter Experience Cloud).

4. Wählen Sie OAuth Server-to-Server als Authentifizierungstyp.

5. Wählen Sie das/die Produktprofil(e) aus, die Zugriff auf die Eigenschaften gewähren, die Sie betreffen. Produktprofile werden in der Adobe Admin Console verwaltet; wenn Sie kein Administrator sind, fragen Sie Ihren, welches Profil Ihre Eigenschaften abdeckt. Dies ist die häufigste Ursache für leere Ergebnisse oder 403er – die Anmeldeinformation kann sich problemlos authentifizieren und trotzdem nichts sehen.

6. Kopieren Sie von der Seite der Anmeldeinformation:

   • Client-ID → REACTOR_CLIENT_ID

   • Client-Geheimnis → REACTOR_CLIENT_SECRET

   • Organisations-ID (endet auf @AdobeOrg) → REACTOR_ORG_ID

   • Bereiche (die auf der Anmeldeseite angezeigte kommagetrennte Liste) → REACTOR_SCOPES

Der Server tauscht diese gegen ein 24-Stunden-Zugriffstoken unter https://ims-na1.adobelogin.com/ims/token/v3 aus und erneuert es automatisch. Sie müssen nie selbst ein Token verwalten.

2. Installation

Ein vorgefertigtes, abhängigkeitsfreies Bundle wird unter build/adobe-launch-reactor-mcp.mjs mitgeliefert. Es ist eine einzelne eigenständige ESM-Datei – kein npm install erforderlich, um den Server auszuführen. Node 20+ ist die einzige Voraussetzung.

Um es aus dem Quellcode neu zu erstellen oder die Tests auszuführen:

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

Der Server liest seine Anmeldedaten aus Umgebungsvariablen, die von Ihrem MCP-Client bereitgestellt werden. Er lädt keine .env-Datei – .env.example ist eine Referenz dafür, welche Werte zu setzen sind.

3. Konfigurieren Sie Ihren MCP-Client

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

Fragen Sie dann: „Welche Regeln sind in meiner Acme-Web-Eigenschaft und welche sind unveröffentlicht?"

Konfiguration

Schreibmodi

Der Modus wird an zwei Stellen durchgesetzt: Schreibwerkzeuge werden unterhalb ihrer Stufe einfach nicht registriert, und die reactor_request-Notluke whitelistet HTTP-Methoden nach Modus – ein Modell kann die Stufe also nicht umgehen, indem es den rohen Endpunkt aufruft.

safe ist die richtige Standardeinstellung für die meisten Arbeiten. Das Erstellen in Reactor ist nicht destruktiv: Eine neue oder bearbeitete Regel befindet sich im Authoring-Zustand der Eigenschaft und ändert nichts an einer Live-Site, bis eine Bibliothek, die sie enthält, erstellt und veröffentlicht wird. Das Veröffentlichen in einer separaten, explizit aktivierten Stufe zu halten bedeutet, dass ein Fehler etwas ist, das Sie in der UI beheben, kein Vorfall.

Werkzeuge

Lesen (alle Modi)

Authoring (safe und 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.

Destruktiv (nur dangerous)

reactor_create_build, reactor_transition_library, reactor_delete_resource. Alle drei erfordern ein explizites confirm: true-Argument und tragen die MCP-destructiveHint-Annotation, sodass ein wohlverhaltener Client vor der Ausführung eine Rückfrage stellt.

Hinweise zur API

Filtern. Listen-Tools akzeptieren ein filter-Objekt, das nach Attributen verschlüsselt ist, mit Werten der Form "OPERATOR value". Operatoren: EQ, NOT, LT, GT, BETWEEN, CONTAINS.

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

Adobe ignoriert Filter auf nicht filterbaren Attributen stillschweigend und gibt die vollständige Menge zurück. Ein Filter, der scheinbar nichts bewirkt, ist also meist ein Tippfehler oder ein nicht unterstütztes Attribut und kein wirklich leeres Ergebnis.

Filterbare Attribute nach Ressource:

• rules, rule_components, data_elements: name, enabled, dirty, published, published_at, revision_number, origin_id, created_at, updated_at (Regelkomponenten auch 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

Paginierung. Standardmäßig 25 Datensätze pro Seite, maximal 100. Übergeben Sie fetch_all: true, um jede Seite zu durchlaufen (begrenzt auf 20 Seiten). Antworten, die größer als REACTOR_MAX_RESPONSE_CHARS sind, werden an einer Datensatzgrenze abgeschnitten, sodass das JSON parsebar bleibt und angibt, wie viel verworfen wurde.

Ratenbegrenzungen. Reactors Soft-Limit liegt bei etwa 120 Anfragen pro Minute und Integration. Der Client wiederholt 429- und 5xx-Antworten mit exponentiellem Backoff und beachtet dabei Retry-After.

Einstellungen. Reactor speichert die Delegate-Konfiguration als JSON-codierten String. Die Schreib-Tools akzeptieren ein einfaches Objekt und codieren es; die Lese-Tools decodieren es wieder. Wenn Sie einen String übergeben, wird er unverändert durchgereicht.

Veröffentlichungsmodell. Änderungen im Authoring sind wirkungslos. Um eine Änderung live zu schalten: Ressourcen erstellen oder bearbeiten → zu einer Bibliothek hinzufügen → die Bibliothek bauen → in den Status published überführen. Die letzten beiden Schritte erfordern den dangerous-Modus; andernfalls führen Sie sie in der Launch-UI aus.

Entwicklung

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

Die Testsuite deckt ab: Aufbau des Auth-Headers und Token-Caching, die Form des client_credentials-Grants, JSON:API-Filter-/Sortier-/Seiten-Codierung, mehrseitiges Durchlaufen, Antwortformatierung und -abschneidung, settings-Encode-/Decode-Roundtripping, Konstruktion von Beziehungen, Absicherung des Schreibmodus (einschließlich der Tatsache, dass der rohe Passthrough nicht zur Umgehung genutzt werden kann) sowie die Fehlermeldungsqualität für 404/422/429/500.

Struktur

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

Lizenz

MIT.