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: api

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`	`api` \| `postgrest`	`api`	Admin UI が動作するバックエンド: `api` (自前の `@kozou/api`、デフォルト) または `postgrest` (外部 PostgREST、オプトアウト)。
`url`	string	`http://postgrest:3000`	PostgREST エンドポイントのベース URL。`type: postgrest` のときにのみ利用され、REST をインプロセスで提供する自前の `api` バックエンドでは無視されます。

adapter:
  type: api

v1.0 以降、Kozou はデフォルトで自前の @kozou/api バックエンドを通じてレコードを読み書きします。これは kozou dev の下で REST をインプロセスで提供し、別個のコンテナは不要です。

代わりに外部の PostgREST を使うようオプトアウトするには、type: postgrest を設定して url をそこに向けます (スキャフォールドされた docker-compose.yml には PostgREST サービスがコメントアウトされた opt-out として含まれているので、コメントを外します)。

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

単発の実行に対しては、kozou dev の --adapter postgrest (または --adapter api) でバックエンドを上書きすることもできます。自前バックエンドのエンドポイント、OpenAPI ドキュメント、セキュリティ境界については @kozou/api REST レイヤーを参照してください。

`api`

opt-in の RPC アクション (v1.4 以降) — COMMENT で @expose: rpc とタグ付けされた Postgres 関数を、内製の @kozou/api バックエンドが POST /rpc/<schema>.<fn> として提供します。以下のリストは、よりリスクの高いケースが必要とする 追加の deploy 時 opt-in であり、いずれも schema 修飾 の関数名を保持し、デフォルトは空です。

フィールド	型	デフォルト	説明
`rpc.allowDefiner`	string[]	`[]`	露出を承認する `SECURITY DEFINER` 関数。所有者権限で実行され RLS をバイパスしうるため、`@expose: rpc` タグおよび owner-safe な `SET search_path` に加えてこれが必要です。
`rpc.allowPublicExecute`	string[]	`[]`	意図的に `EXECUTE` を `PUBLIC` に付与したままにする (匿名呼び出し可能な) 関数。これが無いと、PUBLIC EXECUTE が残った関数は黙って全員に開放されるのではなく hard-skip されます。`@expose: rpc public` が関数単位のタグ相当です。

api:
  rpc:
    allowDefiner:
      - public.approve_order
    allowPublicExecute:
      - public.search

露出は opt-in であり、黙って起こることはありません。@expose: rpc 無しでは何も露出されず、ガードレールを満たさないタグ付き関数 (PUBLIC EXECUTE の残存、unsafe な definer search_path、オーバーロード名など) は静かに落とされるのではなく大きく skip されます。呼び出し元が実際にアクションを実行できるかは、リクエストの role における PostgreSQL の EXECUTE 権限が施行します — 露出は権限ではありません。RPC の wire 形式は Kozou v1.6 時点で安定した契約です。opt-out の PostgREST バックエンドはこのセクションを無視します (PostgREST 自身の /rpc/ を使います)。

`auth`

自前の @kozou/api バックエンド向けのオプションの JWT 検証です。auth ブロックがなければ、バックエンドはループバック上で 認証なし で動作します。これを追加すると、各リクエストの署名付き JWT を検証します。Kozou は token を検証し、リクエストを SET LOCAL ROLE <claim の role> の下で、PostgreSQL に公開された claim とともに実行します。そして、あなた自身の行レベルセキュリティ (RLS) ポリシー が、何を読み書きするかを決めます。token を持たないリクエストは、anonRole を設定していない限り 401 で拒否されます。設定している場合は、空の claim でその匿名ロールの下で実行されます。Kozou は施行するだけで、identity を発行しません — 認証と認可を参照してください。

フィールド	型	デフォルト	説明
`jwt.secret`	string	—	HS256 共有シークレット。`secret`、`publicKey`、`jwksUri` のいずれか 1 つだけを指定します。
`jwt.publicKey`	string	—	RS256 公開鍵 (PEM)。
`jwt.jwksUri`	string	—	プロバイダのリモート JWKS エンドポイント (Auth0 / Clerk / Supabase)。鍵は `kid` で選択され、キャッシュされ、ローテーション時に更新されます。
`jwt.algorithms`	string array	—	許可する署名アルゴリズム (`HS256` / `RS256`)。
`jwt.issuer`	string	—	設定時に期待される `iss` claim。
`jwt.audience`	string または array	—	設定時に期待される `aud` claim。
`roleClaim`	string	`role`	引き受ける PostgreSQL ロールを示す claim 名。
`allowedRoles`	string array	—	これらのロールのみ引き受け可能。リスト外のロールは `403`。
`defaultRole`	string	—	token が `roleClaim` を省略したときに引き受けるロール。
`anonRole`	string	—	token がないリクエスト向けのロール。未設定なら token なしのリクエストは `401`。
`claimsGuc`	string	`request.jwt.claims`	検証済みの claim が公開されるランタイム設定。
`ui.role`	string	—	同梱の Admin UI が動作するロール (HS256: CLI がこのロールを claim する token を発行)。
`ui.token`	string	—	Admin UI 向けの出来合いの token (RS256 / 外部 IdP で CLI が発行できない場合)。

auth:
  jwt:
    secret: ${KOZOU_JWT_SECRET}        # HS256 — or publicKey (RS256), or jwksUri
    # publicKey: ${KOZOU_JWT_PUBLIC_KEY}
    # jwksUri: https://your-idp/.well-known/jwks.json  # Auth0 / Clerk / Supabase
    algorithms: [HS256]
    issuer: my-issuer                  # optional
    audience: my-api                   # optional
  roleClaim: role                      # claim naming the DB role (default: role)
  allowedRoles: [app_reader, app_admin] # only these roles may be assumed
  defaultRole: app_reader              # role when the token omits roleClaim
  anonRole: web_anon                   # role for requests with no token (else 401)
  ui:
    role: app_admin                    # role the bundled Admin UI runs as (HS256)
    # token: ${KOZOU_ADAPTER_TOKEN}    # RS256 / external IdP: supply a token instead

存在するが無効な token は常に 401 です。database.url のログインロールには、すべての許可ロール (および設定時は anonRole) のメンバーシップを GRANT する必要があります。各フィールドには KOZOU_JWT_* / KOZOU_UI_ROLE / KOZOU_ADAPTER_TOKEN 環境変数の等価物があり、auth ブロックが存在しないときに使われます。オプトアウトの PostgREST バックエンドは、このセクションの影響を受けません。

`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 トランスポートを使用するかどうか。
`mcp.execution.enabled`	boolean	`false`	MCP `call` 実行ツールの opt-in。デフォルト off = describe 専用。
`mcp.execution.role`	string	—	すべての `call` が実行される DB role (`SET LOCAL ROLE` 経由)。`enabled` 時は必須。専用の least-privilege role を使ってください。
`mcp.execution.claims`	object	—	RLS 向けに publish される固定 claims (`request.jwt.claims` 配下)。
`mcp.execution.allow`	string[]	—	ツールが実行できる schema 修飾関数名の allowlist。省略 = 露出関数すべて。

server:
  ui:
    port: 3333
    host: 0.0.0.0
  mcp:
    http:
      port: 3334
      host: 0.0.0.0
    stdio: false
    # opt-in: MCP `call` ツールに露出 RPC アクションを実行させる (デフォルト off)。
    # execution:
    #   enabled: true
    #   role: kozou_mcp_agent
    #   # claims: { tenant_id: acme }
    #   # allow: [public.approve_order]

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

server.mcp.execution は デフォルト off です (MCP サーバーは describe 専用)。有効化すると、露出関数を実行する call ツールが現れます。server.mcp.http.auth なしでは呼び出しは単一の固定 role として実行され — per-caller identity が無いためマルチテナントの per-user 認可には不適で、トランスポートも無認証のため loopback ホストに留めてください。opt-in の OAuth resource-server ブロック (server.mcp.http.auth) を使うと、エンドポイントは毎リクエストにあなた自身の ID プロバイダの検証済み bearer トークンを要求し、call はトークンごとの role として実行されます (明示の allowedRoles allowlist に制限)。このブロックは HTTP トランスポート限定で、stdio 起動では無視されます。ブロックのキーとデプロイ指針はリモート MCP と OAuth を参照してください。SECURITY DEFINER の注意を含む実行の完全なガイダンスは MCP エージェントからアクションを実行するを参照してください。

`introspection`

オプトインの privilege-aware introspection。生成される各サーフェスを、スキーマが宣言する内容だけでなく、あるロールが実際にできることに合わせます。デフォルト off (スキーマ忠実)。

フィールド	型	デフォルト	説明
`respectPrivileges`	boolean	`false`	introspection 時にロールの実効テーブル/列 GRANT を評価し、各サーフェスに反映します。
`role`	string	—	評価するロール。既定では Admin UI のロール (`auth.ui.role`、無ければ `auth.defaultRole`)。上書きする場合に指定し、出来合いの `auth.ui.token` を渡す場合は (そのロールを推測できないため) 必須です。

introspection:
  respectPrivileges: true
  role: analyst

各サーフェスは結果をそれぞれに適した形で扱います。

Admin UI はロールが到達できないものを隠します — SELECT できないテーブルはナビから外れ、INSERT できない列は作成時に読み取り専用、UPDATE できない列は編集時に読み取り専用、Delete は権限の無いところで非表示になります。
MCP の describe_table / describe_view と kozou docs は隠さず注記します — すべてのリレーションが残り、ロールの実効 SELECT / INSERT / UPDATE / DELETE (およびテーブルの列ごとの insertable / updatable) が付記され、kozou docs にはテーブルごとの Security セクションが増えます。これにより AI エージェントは、読めないテーブルが消えるのではなく、何に触れてよいかを伝えられます。AI エージェントを接続するを参照してください。

Kozou が既に読み取っている権限を再利用するため追加クエリはなく、内容は advisory のみ です — 施行は常に PostgreSQL (ロールの GRANT とあなたの RLS ポリシー) に残ります。

`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:
  # Backend the Admin UI runs against. "api" (default) is the in-house
  # @kozou/api, served in-process by kozou dev — no extra container.
  type: api
  # To opt out to an external PostgREST instead, set type: postgrest and
  # point url at it (add a postgrest service to docker-compose.yml):
  #   type: postgrest
  #   url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}

# auth:
#   # Optional. Without this block @kozou/api runs unauthenticated on loopback.
#   # Add it to verify a signed JWT and run each request under SET LOCAL ROLE
#   # <role-from-claim> so your RLS policies decide access.
#   jwt:
#     secret: ${KOZOU_JWT_SECRET}   # HS256 — or publicKey (RS256), or jwksUri
#   roleClaim: role
#   allowedRoles: [app_reader, app_admin]
#   defaultRole: app_reader
#   ui:
#     role: app_admin

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、auth、cache を読み込んで Admin UI と MCP サーバーを実行するコマンド。
UI ヒント — uiHints.path が指すファイル。
@kozou/api REST レイヤー — 自前の REST バックエンド (デフォルト) と、それが読む auth 設定。

kozou.config.yaml

概要

セクション

database

adapter

api

auth

uiHints

server

introspection

cache