Genesys Archivist

Genesys Cloud Architect フローと、それらが依存するすべてのリソースをキャプチャし、そのキャプチャからビジネス文書と技術文書を生成します。

2つの利用者、2つの保証:

Archivist はその移行サーバーを構築しません。Archivist が保証するのは、そのサーバーが消費するデータ契約です。

Status

両ステージとも実際の Genesys 組織に対してエンドツーエンドで動作します。 約1,166件のテストがあり、フォーマット、lint、本番・テストの型チェック、スキーマ検証を npm run verify で行います。

プラン1〜5は構築済みです。すべての archivist コマンドが配線されています: profile、doctor、capture、document、verify。MCP サーバーは9つのツールを公開しており、そのうち8つは実際の実装に裏打ちされています。ソースパスは推測ではなく測定によって決定されました — Platform API 設定エンドポイント (ADR-015) — そしてアダプターは GET のみを公開するトランスポート経由でそこに到達するため、読み取り専用はレビュー担当者の注意事項ではなく型の性質です (ADR-019)。

パイロットサンドボックスに対する測定結果: 15タイプにわたる511フロー、うち401が公開済み。組織全体の context キャプチャは約400リクエスト、約95秒、約10 MB です (S6)。

未通過のリリースゲートが1つ

権限マトリックスが不合格です。 サンドボックスの OAuth クライアントは実質的に管理者です: 783件の権限ポリシーのうち580件が変更アクションを許可しており、architect:flow の公開と削除も含まれます。このリポジトリ内の何もそれらを呼び出さず、呼び出すこともできませんが、ゲートは呼び出しではなく保持している権限を測定します。npm run spike:s4 は作成すべき読み取り専用ロールを出力します。詳細と是正策は S4 にあります。

既知のギャップ

• 移行モードはすべてのアセットを一度にメモリに保持します — サンドボックスでは約110 MB、組織の規模に応じて無制限です。まだ大規模な実組織に対して実行しないでください。context モードは影響を受けません。優先順位付けされた3つの修正案が Plan 5 にあります。

• genesys_flow_diff はまだ結果ではなく明示的な拒否を返します。

• 変更検出は純粋な決定関数として存在しますが、その I/O は配線されていないため、実行のたびにすべてのフローが再処理されます。

• 1つのテストファイルが Windows 上で約6回に1回の割合でフレークします。ファイル自身のヘッダーに記載されています。

Related MCP server: codebase-doc-generator

2つのキャプチャモード

ADR-018 に従い、キャプチャには2つの役割があり、それぞれ別の名前で呼ばれます:

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

context はフロー定義とそれに付随するリソースマニフェストをキャプチャするため、馴染みのない IVR に戻ってきた開発者が素早く再把握できます。リソースを閉包まで辿ったりアセットをダウンロードしたりしないため、組織全体に対して定期的に実行できるほど高速です。

migration は別の場所で IVR を再構築するために必要なすべてをキャプチャします: すべてのリソース本体、プロンプト音声のすべてのバイト、データテーブルの行。

どちらもバンドルを生成します。context バンドルは policy.mode: "context" を記録し、migrationReadiness.archyImportableYaml: false を報告し、その旨を言葉で明記した注意書きを添えます — 移行対応バンドルと誤認されることは決してありません。

1段落でわかるアーキテクチャ

ハードな境界線で分離された2つのステージ。ステージ1 (capture) は Genesys と通信する唯一のコードです: すべてのタイプのすべてのフローを発見し、定義を取得し、リソース参照グラフを閉包まで辿り、バイナリアセットをダウンロードし、不変のコンテンツハッシュ化されたキャプチャバンドルを封印します。ステージ2 (document) はソケットを開きません — バンドルを読み取り、Markdown、SVG 図、PDF を生成し、途中で AI によるナレーションを挟みます。したがって、ドキュメントの再レンダリングには Genesys API 呼び出しが一切かからず、バンドルは使い捨てのキャッシュではなく公開された契約です。

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

はじめに

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

組織を指定する

プロファイルは非秘密のメタデータを保持し、資格情報を指定します。クライアントシークレットは stdin または非表示のプロンプトから読み取られ、フラグからは決して読み取られません — argv はプロセス一覧やシェル履歴に表示されるため、--client-secret は受け入れられるのではなく説明付きで拒否されます。

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

キャプチャとドキュメント生成

# 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 は capture に必須であり、単なる利便性のためではありません: プロファイルは承認済みの出力ルートと、誤って入力された資格情報が間違った顧客の設定をキャプチャするのを防ぐ expectedOrganizationId を提供します。

AI クライアントから操作する

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

STDIO のみ。サーバーはプロトコルメッセージを stdout に、それ以外のすべてを stderr に書き込み、ネットワークリスナーを開かず、資格情報を受け入れるツールを一切公開しません — テストが登録済みのすべてのツールの入力スキーマを走査し、いかなる深さでも資格情報の形をしたプロパティ名があれば失敗します。プロビジョニングは永久に CLI のみです。

次に、順番に読んでください:

1. CLAUDE.md — ここでコードを書こうとしているすべての人（人間またはエージェント）向けのオリエンテーション。

2. AGENTS.md — 交渉の余地のない境界。違反はリリースブロッカーです。

3. 設計仕様書 — 何を構築しているのか、そしてなぜか。セクション2に、以下の番号付きブループリント文書からの逸脱箇所が列挙されています。

4. Plan 1: Foundation — Genesys アクセスを必要としない、タスクごとの TDD タスク12件。

5. Phase 0 スパイク — 他のすべての障害を解除する go/no-go ゲート。

Phase 0 は go/no-go ゲートであり、合格しました

4つのソースパスが競合していました — Platform API、Archy CLI、Architect Scripting SDK、手動 YAML。どれが勝つかは推測ではなく実証的な結果でした。

スパイク S1 は、手動でエクスポートした Architect YAML ベースラインに対して Platform API 設定エンドポイントを100%の構造的忠実度で測定しました: 47ノード、10のコンストラクトタイプ、説明不能な差異はゼロ。さらに、すべてのノードに安定した trackingId を提供し、ID とノードごとの由来を含む参照リソースのマニフェストを提供します。Architect Scripting SDK は完全に破棄されました (ADR-015)。それははるかに高い依存関係コストで厳密なサブセットを提供したでしょう。

その後、権限マトリックスのスパイクが実行され、失敗しました — S4 と上記の Status セクションを参照してください。プロンプト音声は読み取り専用でダウンロードされ、キル基準11をクリアし (S5)、スケール予算が測定されています (S6)。S3 以降、2つのスパイク番号付け方式が食い違っていることに注意してください。スパイクは番号ではなくファイル名で引用してください。

リポジトリ構成

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

依存関係の方向は慣習ではなく ESLint によって強制されます: domain は何もインポートせず、application は domain のみをインポートし、apps/* は薄いままです。

決してコミットしないもの

bundles/、derived/、documentation/、spike-evidence/、または任意の .wav / .mp3。キャプチャバンドルは restricted に分類されます — エンドポイント URL、DID、ルーティングロジック、顧客の PII を含む可能性のあるデータテーブルの行、プロンプト音声が含まれます。これらのいずれかが追跡されている場合、CI はビルドを失敗させます。

用語

対象は Genesys Cloud CX であり、IVR オーサリング製品は Architect です。

フローには flowId やバージョンなどの識別子があります。キュー、プロンプト、データアクション、スケジュール、再利用可能なフローにも識別子があります。これらは秘密の API キーではありません。 Genesys OAuth の client_id と client_secret が統合を認証し、これらが関与する唯一の秘密情報です。このツールは隠された秘密情報を列挙したり、OAuth クライアントシークレットを復元したり、パスワードをスクレイピングしたり、Genesys の権限を迂回したりすることは決してありません。

最初の本番リリースの非目標

• Genesys フローの編集、公開、削除、インポート

• 顧客の秘密情報の復元または一覧表示

• ライブの発信者データ、録音、文字起こし、過去の実行データの読み取り

• キャプチャされたデータに対するクエリまたは Q&A ツール

• リモート HTTP ホスティング、git/PR 自動化、スケジューリングデーモン

• 設定から推測できないビジネス意図の主張

ブループリント文書

当初の引き継ぎ文書。設計仕様書が上書きしない限り、引き続き適用されます。