kozou.config.yaml

kozou.config.yaml は、すべての Kozou コマンドが読み込む唯一のファイルです。kozou inspect、kozou mcp、kozou dev はいずれもこのファイルを読み込み、データベースの場所を見つけ、レコードの読み書き方法を決定し、UI ヒントの場所を特定し、Admin UI と MCP サーバーが待ち受けるポートを選びます。create-kozou は、スキャフォールドしたプロジェクトに完全にコメント付きのコピーを書き出します。

すべてのフィールドにはデフォルト値があります。Kozou は DATABASE_URL 環境変数だけを設定すれば起動できるように設計されています。設定ファイルが存在しない場合、ローダーはデータベース接続にこの変数をフォールバックとして使い、その他のすべてのフィールドを組み込みのデフォルト値で埋めます。

このファイルを利用するコマンドについては kozou dev を参照してください。このファイルが指す UI ヒントファイルについては UI ヒントを参照してください。

概要

database:
  url: ${DATABASE_URL}
  schemas: [public]

adapter:
  type: postgrest
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

uiHints:
  path: ./ui-hints.yaml

Kozou はデフォルトで、現在の作業ディレクトリにある kozou.config.yaml を探します。--config で任意のコマンドに別のパスを指定できます。

kozou inspect --config ./config/kozou.config.yaml
kozou dev --config ./config/kozou.config.yaml

セクション

`database`

PostgreSQL 接続と、Kozou がイントロスペクトするスキーマです。

フィールド	型	デフォルト	説明
`url`	string	—（必須）	PostgreSQL 接続文字列。必須ですが、ファイルから省略された場合はローダーが `DATABASE_URL` 環境変数から補完します。
`schemas`	string array	`[public]`	Kozou が Schema Context を構築するためにイントロスペクトするスキーマ。

database:
  url: ${DATABASE_URL}
  schemas: [public]

database.url は、使用可能なデフォルト値がない唯一のフィールドです。ファイルと DATABASE_URL 環境変数の両方から欠落している場合、ローダーはエラーを出して設定を拒否します。

`adapter`

Kozou がレコードデータを読み書きする方法です。Admin UI が直接 PostgreSQL と通信することはなく、必ずデータアダプターを経由します。これにより読み書きの境界を差し替え可能に保ちます。

フィールド	型	デフォルト	説明
`type`	`postgrest`	`postgrest`	アダプターの実装。v0.1.1 では設定ファイルが受け付ける値は `postgrest` のみです。
`url`	string	`http://postgrest:3000`	アダプターが呼び出す REST エンドポイントのベース URL。

adapter:
  type: postgrest
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

v0.1.1 では、Kozou は PostgREST を通じてレコードを読み書きします。これはデータベースを REST で公開する独立したサービスです。スキャフォールドされた docker-compose.yml は、これをデータベースと並行して実行します。

v0.2 系列では、同じアダプター境界の背後に実験的な自前の REST レイヤー @kozou/api が追加されます。adapter.type を変更するのではなく、実行時に kozou dev の --adapter api フラグでオプトインします。

kozou dev --adapter api

これは実験的であり、安定した v0.1.1 のサーフェスには含まれません。カバー範囲と現在の制限については実験的な @kozou/api を参照してください。

`uiHints`

出力される Admin UI を洗練させる UI ヒントファイルの場所です。

フィールド	型	デフォルト	説明
`path`	string または null	`null`	UI ヒント YAML ファイルへのパス。`null` の場合、Kozou は `COMMENT` 由来のヒントのみに依存します。

uiHints:
  path: ./ui-hints.yaml

UI ヒントは、Kozou が COMMENT タグ（@ai、@widget、@policy、@example）から読み取る規約の上に重なります。ファイル形式と、これらのタグとどのように組み合わさるかについては UI ヒントを参照してください。

`server`

kozou dev が起動する Admin UI と MCP サーバーのバインドホストとポートです。

フィールド	型	デフォルト	説明
`ui.port`	integer	`3333`	Admin UI のポート。
`ui.host`	string	`0.0.0.0`	Admin UI のバインドホスト。
`mcp.http.port`	integer	`3334`	MCP HTTP サーバーのポート。
`mcp.http.host`	string	`0.0.0.0`	MCP HTTP サーバーのバインドホスト。
`mcp.stdio`	boolean	`false`	MCP サーバーが stdio トランスポートを使用するかどうか。

server:
  ui:
    port: 3333
    host: 0.0.0.0
  mcp:
    http:
      port: 3334
      host: 0.0.0.0
    stdio: false

kozou dev は Admin UI を server.ui で、MCP HTTP サーバーを server.mcp.http で実行します。デフォルトでは 0.0.0.0 にバインドされるため、ポートはコンテナの外部から（たとえば Docker Compose のポートマッピングを通じて）到達可能になります。ネットワークから到達可能なマシンでは、Kozou v0.1.1 が独自の認証レイヤーを一切備えていないことを忘れないでください。それが問題になる場合は、ループバックホストにバインドするか、自前のゲートウェイの背後に配置してください。

`cache`

イントロスペクトした Schema Context が、Kozou が再構築するまでキャッシュされる時間です。

フィールド	型	デフォルト	説明
`ttlMs`	integer	`60000`	Schema Context キャッシュの有効期間（ミリ秒）。

cache:
  ttlMs: 60000

デフォルトの 60 秒の TTL は、スキーマの変更（たとえばマイグレーション実行後）が反映されるまで最大 1 分かかることを意味します。スキーマを反復して開発している間は ttlMs を下げ、安定したら上げてください。

環境変数の展開

ローダーは、検証の前、読み込み時にプロセス環境に対して文字列値内のプレースホルダーを展開します。認識される形式は 2 つあります。

形式	動作
`${VAR}`	`VAR` の値に置き換えられます。`VAR` が未設定の場合は空文字列に展開されます。
`${VAR:-default}`	`VAR` の値に置き換えられます。`VAR` が未設定の場合は `default` になります。

adapter:
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

この行があると、Kozou は $KOZOU_ADAPTER_URL が設定されている場合はそれを使い、設定されていない場合は http://postgrest:3000 にフォールバックします。

リテラルの $ を書くには、二重にします。$$ は 1 つの $ に展開されます。したがって $${VAR} は、展開されるのではなくリテラルのテキスト ${VAR} を生成します。

展開は設計上、単一レベルです。環境から代入された値が再スキャンされることはありません。正当に ${...} を含むシークレット（たとえば DATABASE_URL のパスワード内の ${ シーケンス）は、別のプレースホルダーと誤認されることなくそのまま保持されます。

`DATABASE_URL` フォールバック

ファイル内で database.url が欠落しているか空の場合、ローダーは DATABASE_URL 環境変数から補完します。これにより、同梱のテンプレートが url: ${DATABASE_URL} を出荷でき、Kozou が設定ファイルなしで DATABASE_URL だけから実行できるようになります。

DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou inspect --format yaml

kozou CLI は KOZOU_DATABASE_URL ではなく DATABASE_URL を利用します。明示したい場合は、database.url から ${DATABASE_URL}（または任意の変数）を明示的に参照してください。

完全な例

すべてのセクションをカバーする、完全にコメント付きの設定です。ここに示すすべてのフィールドはデフォルトに一致しているため、変更する必要のない行は削除できます。

#
# Every field has a sensible default; only set what you need to override.
# All ${VAR} and ${VAR:-fallback} placeholders are expanded against the
# process environment at load time. Use $$ for a literal `$`.

database:
  # Connection string. Falls back to the DATABASE_URL env var when omitted.
  url: ${DATABASE_URL}
  # Schemas to introspect when building the Schema Context.
  schemas: [public]

server:
  ui:
    port: 3333        # Admin UI port (kozou dev)
    host: 0.0.0.0     # bind host; 0.0.0.0 is container-reachable
  mcp:
    http:
      port: 3334      # MCP HTTP server port (kozou dev)
      host: 0.0.0.0
    stdio: false      # MCP stdio transport

adapter:
  # v0.1.1 reads/writes records through PostgREST.
  type: postgrest
  # Base URL of the REST endpoint; defaults to the compose service.
  url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

uiHints:
  # Path to the UI hints file, or null to rely on COMMENT tags only.
  path: ./ui-hints.yaml

cache:
  # Schema Context cache TTL in milliseconds.
  ttlMs: 60000

products（draft / published / archived を遷移する status カラムを持つ）、orders、authors / books リレーションを持つスキーマに適用すると、この設定は public スキーマをイントロスペクトし、結果として得られる Admin UI を http://localhost:3333 で提供し、MCP を HTTP 経由で http://localhost:3334 に公開し、その Schema Context を最大でも 60 秒に 1 回再構築します。

次に読むもの

kozou dev — server、adapter、cache を読み込んで Admin UI と MCP サーバーを実行するコマンド。
UI ヒント — uiHints.path が指すファイル。
実験的な @kozou/api — kozou dev --adapter api の背後にある自前の REST レイヤー。

kozou.config.yaml

概要

セクション

database

adapter

uiHints

server

cache