Genesys Archivist

Erfasst Genesys Cloud Architect-Flows und alle Ressourcen, von denen sie abhängen, und erzeugt aus dieser Erfassung fachliche und technische Dokumentation.

Zwei Konsumenten, zwei Garantien:

Archivist baut diesen Migrationsserver nicht. Es garantiert den Datenvertrag, den dieser Server konsumieren wird.

Status

Beide Stufen funktionieren Ende-zu-Ende gegen eine echte Genesys-Organisation. ~1.166 Tests, mit Format-, Lint-, Produktions- und Test-Typprüfung sowie Schema-Validierung in npm run verify.

Pläne 1–5 sind umgesetzt. Jeder archivist-Befehl ist angebunden: profile, doctor, capture, document, verify. Der MCP-Server stellt neun Tools bereit, acht davon mit echten Implementierungen. Der Quellpfad wurde durch Messung statt durch Annahme festgelegt — der Platform-API-Konfigurationsendpunkt (ADR-015) — und der Adapter erreicht ihn über einen Transport, der nur GET freigibt. Dadurch ist der Schreibschutz eine Eigenschaft des Typs und nicht der Aufmerksamkeit des Reviewers überlassen (ADR-019).

Gemessen an der Pilot-Sandbox: 511 Flows in 15 Typen, 401 veröffentlicht. Eine context-Erfassung der gesamten Organisation umfasst etwa 400 Anfragen, ~95 Sekunden, ~10 MB (S6).

Ein Release-Gate ist offen

Die Berechtigungsmatrix schlägt fehl. Der OAuth-Client der Sandbox ist praktisch ein Administrator: 783 Berechtigungsrichtlinien, von denen 580 eine mutierende Aktion gewähren, darunter das Veröffentlichen und Löschen von architect:flow. Nichts in diesem Repository ruft diese Aktionen auf, und nichts kann es. Das Gate misst jedoch gehaltene Berechtigungen, nicht getätigte Aufrufe. npm run spike:s4 gibt die zu erstellende Read-only-Rolle aus. Ausführliche Details und Abhilfe in S4.

Bekannte Lücken

• Der Migrationsmodus hält alle Assets gleichzeitig im Speicher — ~110 MB in der Sandbox, unbegrenzt wachsend mit der Organisationsgröße. Führen Sie ihn noch nicht gegen eine große echte Organisation aus; der context-Modus ist nicht betroffen. Drei priorisierte Korrekturen finden sich in Plan 5.

• genesys_flow_diff gibt weiterhin eine explizite Ablehnung zurück statt eines Ergebnisses.

• Die Änderungserkennung existiert als reine Entscheidungsfunktion, aber ihre Ein-/Ausgabe ist nicht angebunden, sodass jeder Lauf jeden Flow erneut verarbeitet.

• Eine Testdatei ist unter Windows bei etwa einem von sechs Läufen flaky; das ist in ihrem eigenen Header dokumentiert.

Related MCP server: codebase-doc-generator

Zwei Erfassungsmodi

Gemäß ADR-018 hat die Erfassung zwei Aufgaben, und sie werden getrennt benannt:

archivist capture --mode context   --org <id> [--flow <id>...]
archivist capture --mode migration --org <id> [--flow <id>...]

context erfasst Flow-Definitionen und das Ressourcen-Manifest, das mit ihnen geliefert wird, sodass sich Entwickler:innen, die zu einer unbekannten IVR zurückkehren, schnell neu orientieren können. Es verfolgt Ressourcen nicht bis zur vollständigen Auflösung und lädt keine Assets herunter, was es schnell genug macht, um routinemäßig organisationsweit ausgeführt zu werden.

migration erfasst alles, was nötig ist, um die IVRs andernorts neu aufzubauen: jeden Ressourcenrumpf, jedes Byte Prompt-Audio und die Zeilen der Datentabellen.

Beide erzeugen ein Bundle. Ein context-Bundle hinterlegt policy.mode: "context", meldet migrationReadiness.archyImportableYaml: false und enthält einen entsprechenden Hinweis in Worten — es kann nie mit einem migrationsbereiten Bundle verwechselt werden.

Die Architektur in einem Absatz

Zwei Stufen, getrennt durch eine harte Naht. Stufe 1 (capture) ist der einzige Code, der mit Genesys spricht: Sie entdeckt jeden Flow jedes Typs, ruft Definitionen ab, verfolgt den Ressourcen-Referenzgraphen bis zur vollständigen Auflösung, lädt binäre Assets herunter und versiegelt ein unveränderliches, inhaltsgehashtes Capture-Bundle. Stufe 2 (document) öffnet keine Sockets — sie liest ein Bundle und erzeugt Markdown, SVG-Diagramme und PDF, mit KI-Erzählung in der Mitte. Das erneute Rendern der Dokumentation kostet daher null Genesys-API-Aufrufe, und das Bundle ist ein veröffentlichter Vertrag statt eines Wegwerf-Caches.

flowchart TD
    A["AI client"] -->|MCP STDIO| B["MCP adapter"]
    C["archivist CLI"] --> D["Application service"]
    B --> D
    D --> E["Genesys source provider"]
    E --> F["Genesys Cloud"]
    D --> G["Capture bundle (sealed, immutable)"]
    G --> H["Normalize, analyze, document"]
    H --> I["Markdown + diagrams + PDF"]
    G --> J["Future migration server"]

Erste Schritte

npm install
npm run verify        # format + lint + typecheck + test + schema validation
npm run build

Auf eine Organisation ausrichten

Ein Profil enthält die nicht-geheimen Metadaten und benennt die Zugangsdaten. Das Client-Secret wird von stdin oder über eine versteckte Eingabeaufforderung gelesen, niemals über ein Flag — argv ist in Prozesslisten und im Shell-Verlauf sichtbar. Deshalb wird --client-secret mit einer Erklärung abgelehnt, statt akzeptiert zu werden.

archivist profile add \
  --id acme --display-name "Acme Bank" \
  --region euw1 --org <organizationId> \
  --client-id <oauthClientId> \
  --output-root /path/to/output
# then paste the secret at the prompt, or:  echo "$SECRET" | archivist profile add ...

archivist doctor                 # Node version, credential store, profiles
archivist profile validate acme  # profile parses, secret present, root writable

Erfassen und dokumentieren

# Fast, whole-organization. Definitions plus the resource manifest that
# already travels with them. Cannot be migrated — see ADR-018.
archivist capture --profile acme --mode context --org <organizationId>

# Everything needed to rebuild elsewhere: resource bodies, prompt audio,
# data-table rows. See the memory caveat above before running this at scale.
archivist capture --profile acme --mode migration --org <organizationId> --flow <flowId>

archivist verify   --bundle <bundleDir>    # content hashes still match
archivist document --bundle <bundleDir>    # business.md, technical.md, operations.md, diagrams

--profile ist für capture erforderlich, und nicht nur aus Bequemlichkeit: Das Profil liefert das freigegebene Ausgabewurzelverzeichnis und die expectedOrganizationId, die davor schützt, dass eine falsch eingegebene Anmeldeinformation die Konfiguration des falschen Kunden erfasst.

Über einen KI-Client ansteuern

{
  "mcpServers": {
    "genesys-archivist": { "command": "genesys-archivist-mcp" }
  }
}

Nur STDIO. Der Server schreibt Protokollnachrichten nach stdout und alles andere nach stderr, öffnet keinen Netzwerk-Listener und stellt kein Tool bereit, das eine Anmeldeinformation akzeptiert — ein Test durchläuft das Eingabeschema jedes registrierten Tools und schlägt fehl, wenn irgendein Eigenschaftsname in beliebiger Tiefe wie eine Anmeldeinformation aussieht. Die Bereitstellung erfolgt ausschließlich über die CLI, für immer.

Lesen Sie dann in dieser Reihenfolge:

1. CLAUDE.md — Orientierung für alle (Menschen oder Agenten), die hier Code schreiben werden.

2. AGENTS.md — nicht verhandelbare Grenzen. Eine davon zu verletzen ist ein Release-Blocker.

3. Die Design-Spezifikation — was gebaut wird und warum. Abschnitt 2 listet auf, wo sie von den unten nummerierten Blueprint-Dokumenten abweicht.

4. Plan 1: Fundament — zwölf TDD-Aufgaben Schritt für Schritt, die keinen Genesys-Zugriff benötigen.

5. Phase-0-Spikes — das Go/No-Go-Tor, das alles andere freischaltet.

Phase 0 war ein Go/No-Go-Tor und wurde bestanden

Vier Quellpfade standen zur Auswahl — Platform API, die Archy-CLI, das Architect Scripting SDK und manuelles YAML. Welcher gewann, war ein empirisches Ergebnis und keine Annahme.

Spike S1 hat den Platform-API-Konfigurationsendpunkt mit 100 % struktureller Übereinstimmung gegenüber einer manuell exportierten Architect-YAML-Basislinie gemessen: 47 Knoten, 10 Konstrukttypen, null ungeklärte Unterschiede. Er liefert außerdem eine stabile trackingId auf jedem Knoten und ein Manifest referenzierter Ressourcen mit IDs und Herkunftsnachweis pro Knoten. Das Architect Scripting SDK wurde vollständig verworfen (ADR-015); es hätte eine echte Teilmenge zu deutlich höheren Abhängigkeitskosten geliefert.

Der Berechtigungsmatrix-Spike ist inzwischen gelaufen und fehlgeschlagen — siehe S4 und den Statusabschnitt oben. Prompt-Audio wird schreibgeschützt heruntergeladen, was Abbruchkriterium 11 erfüllt (S5), und die Skalierungsbudgets sind gemessen (S6). Beachte: Zwei Spike-Nummerierungsschemata weichen ab S3 voneinander ab; zitiere Spikes per Dateinamen, nicht per Nummer.

Repository-Struktur

apps/cli               archivist CLI
apps/mcp-server        genesys-archivist MCP STDIO server
packages/domain        contracts and DTOs. Pure: no I/O, no SDK types
packages/application   use cases, run state machines, policy
packages/composition   the one place adapters are wired to interfaces
packages/...           adapters, capture, analysis, documentation, rendering, narrative
schemas/               versioned JSON Schema contracts
fixtures/              sanitized test fixtures. Never real customer configuration
docs/                  blueprint, design spec, plans, ADRs, spikes

Die Abhängigkeitsrichtung wird von ESLint erzwungen, nicht durch Konvention: domain importiert nichts, application importiert nur domain, und apps/* bleiben schlank.

Niemals committen

bundles/, derived/, documentation/, spike-evidence/ oder irgendeine .wav / .mp3. Capture-Bundles sind als restricted eingestuft — sie enthalten Endpunkt-URLs, DIDs, Routing-Logik, Zeilen aus Datentabellen, die personenbezogene Kundendaten enthalten können, sowie Prompt-Audio. CI lässt den Build fehlschlagen, wenn irgendetwas davon getrackt wird.

Terminologie

Das Ziel ist Genesys Cloud CX, und das IVR-Authoring-Produkt ist Architect.

Ein Flow hat Bezeichner wie flowId und eine Version. Auch Queues, Prompts, Datenaktionen, Zeitpläne und wiederverwendbare Flows haben Bezeichner. Dabei handelt es sich nicht um geheime API-Schlüssel. Ein Genesys-OAuth-client_id und ein client_secret authentifizieren die Integration und sind die einzigen beteiligten Geheimnisse. Das Tool listet niemals versteckte Geheimnisse auf, stellt keine OAuth-Client-Secrets wieder her, extrahiert keine Passwörter und umgeht keine Genesys-Berechtigungen.

Nicht-Ziele für die erste Produktionsversion

• Bearbeiten, Veröffentlichen, Löschen oder Importieren von Genesys-Flows

• Wiederherstellen oder Auflisten von Kundengeheimnissen

• Lesen von Live-Anruferdaten, Aufzeichnungen, Transkripten oder historischen Ausführungsdaten

• Abfrage- oder Q&-A-Werkzeuge über erfasste Daten

• Remote-HTTP-Hosting, Git-/PR-Automatisierung oder ein Planungs-Daemon

• Behaupten von Geschäftsabsichten, die nicht aus der Konfiguration abgeleitet werden können

Blueprint-Dokumente

Die ursprüngliche Übergabe. Sie ist weiterhin maßgeblich, wo immer die Design-Spezifikation sie nicht außer Kraft setzt.