Genesys Archivist

Captura los flujos de Genesys Cloud Architect y todos los recursos de los que dependen, y luego genera documentación técnica y de negocio a partir de esa captura.

Dos consumidores, dos garantías:

Archivist no construye ese servidor de migración. Garantiza el contrato de datos que ese servidor consumirá.

Estado

Ambas fases funcionan de extremo a extremo contra una organización real de Genesys. ~1166 pruebas, con formato, lint, comprobación de tipos en producción y pruebas, y validación de esquema en npm run verify.

Los planes 1–5 están construidos. Cada comando de archivist está conectado: profile, doctor, capture, document, verify. El servidor MCP expone nueve herramientas, ocho de ellas respaldadas por implementaciones reales. La ruta de origen se estableció mediante medición, no mediante suposiciones — el endpoint de configuración de Platform API (ADR-015) — y el adaptador accede a él a través de un transporte que expone solo GET, por lo que el modo solo lectura es una propiedad del tipo, no una cuestión de atención del revisor (ADR-019).

Medido contra el sandbox piloto: 511 flujos en 15 tipos, 401 publicados. Una captura de context de toda la organización son unas 400 peticiones, ~95 segundos, ~10 MB (S6).

Una puerta de lanzamiento sigue abierta

La matriz de permisos falla. El cliente OAuth del sandbox es efectivamente un administrador: 783 políticas de permisos, 580 de ellas conceden una acción de mutación, incluida la publicación y eliminación de architect:flow. Nada en este repositorio las invoca y nada puede hacerlo, pero la puerta mide permiso poseído, no llamadas realizadas. npm run spike:s4 genera el rol de solo lectura que hay que crear. Detalle completo y remediación en S4.

Brechas conocidas

• El modo de migración mantiene todos los activos en memoria a la vez — ~110 MB en el sandbox, sin límite en función del tamaño de la organización. No lo ejecutes todavía contra una organización real grande; el modo context no se ve afectado. Tres correcciones priorizadas están en el Plan 5.

• genesys_flow_diff todavía devuelve un rechazo explícito en lugar de un resultado.

• La detección de cambios existe como una función de decisión pura, pero su E/S no está conectada, por lo que cada ejecución vuelve a procesar todos los flujos.

• Un archivo de pruebas falla de forma intermitente aproximadamente 1 de cada 6 ejecuciones en Windows, documentado en su propio encabezado.

Related MCP server: codebase-doc-generator

Dos modos de captura

Según ADR-018, la captura tiene dos cometidos y se nombran por separado:

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

context captura las definiciones de flujo y el manifiesto de recursos que llega con ellas, de modo que un desarrollador que regresa a un IVR desconocido pueda reorientarse rápidamente. No recorre los recursos hasta el cierre ni descarga activos, lo que lo hace lo bastante rápido para ejecutarse con regularidad en toda una organización.

migration captura todo lo necesario para reconstruir los IVR en otro lugar: cada cuerpo de recurso, cada byte del audio de los prompts, las filas de las tablas de datos.

Ambos producen un paquete. Un paquete context registra policy.mode: "context", informa migrationReadiness.archyImportableYaml: false y lleva una advertencia que lo dice con palabras: nunca puede confundirse con uno listo para la migración.

La arquitectura en un párrafo

Dos fases separadas por una frontera rígida. La fase 1 (captura) es el único código que se comunica con Genesys: descubre todos los flujos de todos los tipos, obtiene las definiciones, recorre el grafo de referencias de recursos hasta el cierre, descarga los activos binarios y sella un paquete de captura inmutable con hash de contenido. La fase 2 (documentación) no abre sockets — lee un paquete y produce Markdown, diagramas SVG y PDF, con narración de IA en el medio. Por tanto, volver a renderizar la documentación cuesta cero llamadas a la API de Genesys, y el paquete es un contrato publicado, no una caché desechable.

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"]

Primeros pasos

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

Apuntar a una organización

Un perfil guarda los metadatos no secretos y nombra la credencial. El secreto de cliente se lee desde stdin o desde un prompt oculto, nunca desde una bandera — argv es visible en los listados de procesos y en el historial del shell, por lo que --client-secret se rechaza con una explicación en lugar de aceptarse.

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

Capturar y documentar

# 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 es obligatorio para capture, y no solo por conveniencia: el perfil aporta la raíz de salida aprobada y el expectedOrganizationId que protege contra una credencial mal escrita que capture la configuración del cliente equivocado.

Usarla desde un cliente de IA

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

Solo STDIO. El servidor escribe los mensajes de protocolo en stdout y todo lo demás en stderr, no abre ningún listener de red y no expone ninguna herramienta que acepte una credencial — una prueba recorre el esquema de entrada de cada herramienta registrada y falla si algún nombre de propiedad tiene forma de credencial a cualquier profundidad. El aprovisionamiento es solo mediante CLI, para siempre.

Después, lee en orden:

1. CLAUDE.md — orientación para cualquier persona (humana o agente) que vaya a escribir código aquí.

2. AGENTS.md — límites innegociables. Violar uno es un bloqueante de lanzamiento.

3. La especificación de diseño — qué se está construyendo y por qué. La sección 2 enumera en qué se aparta de los documentos de plano numerados que aparecen más abajo.

4. Plan 1: Foundation — doce tareas de TDD una a una que no requieren acceso a Genesys.

5. Spikes de la fase 0 — la puerta go/no-go que desbloquea todo lo demás.

La fase 0 fue una puerta go/no-go, y la superó

Cuatro rutas de origen estuvieron en liza — Platform API, la CLI de Archy, el Architect Scripting SDK y YAML manual. Cuál ganó fue un resultado empírico, no una suposición.

El spike S1 midió el endpoint de configuración de Platform API con una fidelidad estructural del 100% frente a una línea base de YAML de Architect exportada manualmente: 47 nodos, 10 tipos de constructo, cero diferencias sin explicar. Además, proporciona un trackingId estable en cada nodo y un manifiesto de recursos referenciados con ids y procedencia por nodo. El Architect Scripting SDK se descartó por completo (ADR-015); habría aportado un subconjunto estricto con un coste de dependencia mucho mayor.

El spike de la matriz de permisos se ha ejecutado desde entonces y ha fallado — ver S4 y la sección Estado más arriba. Las descargas de solo lectura de audio de prompts superan el criterio de eliminación 11 (S5), y los presupuestos de escala están medidos (S6). Ten en cuenta que dos esquemas de numeración de spikes no coinciden a partir de S3; cita los spikes por nombre de archivo, no por número.

Estructura del repositorio

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

La dirección de dependencias la impone ESLint, no la convención: domain no importa nada, application importa solo domain, y apps/* se mantienen ligeros.

Nunca hagas commit

bundles/, derived/, documentation/, spike-evidence/, ni ningún .wav / .mp3. Los paquetes de captura están clasificados como restricted — contienen URLs de endpoints, DIDs, lógica de enrutamiento, filas de tablas de datos que pueden contener PII de clientes y audio de prompts. La CI hace fallar la compilación si alguno de estos está bajo seguimiento.

Terminología

El objetivo es Genesys Cloud CX, y el producto de autoría de IVR es Architect.

Un flujo tiene identificadores como flowId y una versión. Las colas, los prompts, las acciones de datos, los horarios y los flujos reutilizables también tienen identificadores. Estos no son claves de API secretas. Un client_id y un client_secret de OAuth de Genesys autentican la integración y son los únicos secretos implicados. La herramienta nunca enumera secretos ocultos, recupera secretos de clientes OAuth, extrae contraseñas ni omite los permisos de Genesys.

No-objetivos para la primera versión de producción

• Editar, publicar, eliminar o importar flujos de Genesys

• Recuperar o listar secretos de clientes

• Leer datos en vivo de llamadas, grabaciones, transcripciones o datos históricos de ejecución

• Herramientas de consulta o de preguntas y respuestas sobre los datos capturados

• Alojamiento HTTP remoto, automatización de git/PR o un demonio de programación

• Afirmar una intención de negocio que no pueda inferirse de la configuración

Documentos de plano

La entrega original. Sigue rigiendo allí donde la especificación de diseño no la anula.