コンテンツにスキップ
Kozou

kozou dev

kozou dev はローカルランタイム用のコマンドです。バンドルされた @kozou/svelte-ui の Admin UI、MCP Streamable HTTP サーバー、そして Kozou 自前の @kozou/api REST バックエンドを単一のプロセスグループとして 立ち上げ、これらを kozou.config.yaml から配線します。 これはスキャフォールドされた docker-compose.yml の kozou サービスの 背後で動くコマンドであり、Kozou が出力するすべてのサーフェスを実際の データベースに対して確認する最速の方法です。

このページは、kozou dev が何を起動するか、どのフラグを受け付けるか、 ポートがどのように構成されるかについてのオペレーター向けリファレンスです。

概要

Section titled “概要”
Terminal window
kozou dev [--config <path>] [--adapter <kind>] [--api-port <n>]

フラグなしの場合、kozou dev は ./kozou.config.yaml を読み込み、 Admin UI、MCP HTTP サーバー、そして自前の @kozou/api REST バックエンドを 起動し、Ctrl-C で停止するまで実行を続けます。

起動されるもの

Section titled “起動されるもの”

デフォルトでは、kozou dev は 3 つのリスナーを立ち上げます。

  1. Admin UI — バンドルされた @kozou/svelte-ui アプリケーションで、 子プロセスとして起動されます。構成されたスキーマ内のすべてのテーブルと ビューに対して、生成された CRUD UI を提供します。デフォルトポート: 3333。
  2. MCP HTTP サーバー — @kozou/mcp の Streamable HTTP トランスポートで、 プロセス内で実行されます。AI エージェントが呼び出せるのと同じ Schema Context ツールを公開します。デフォルトポート: 3334。
  3. 自前の @kozou/api REST バックエンド — Kozou 自身の REST レイヤーで、 プロセス内で実行され、127.0.0.1 にバインドされます。Admin UI の サーバーサイド fetch から到達され、ブラウザには公開されません。 デフォルトポート: 3335。外部 PostgREST にオプトアウトするには --adapter postgrest を使います — REST バックエンドの選択 を参照してください。

これらは単一の kozou.config.yaml から配線されるため、1 つのデータベース 接続と 1 セットの UI hints を共有します。コマンドを停止すると (Ctrl-C、または任意の SIGINT / SIGTERM) すべてが一緒に終了します。 Admin UI プロセスが自ら終了した場合、ほかもそれに伴って停止します。

デフォルトでは両サービスは 0.0.0.0 にバインドされるため、docker compose のポートマッピングがそのまま機能します。Admin UI と MCP HTTP のサーフェスには それ自身の認証がありません。そのため、いずれかが非ループバックホストに バインドされると目立つ警告が表示されます。kozou dev は信頼境界内 (自分の マシン、またはプライベートな compose ネットワーク) に留めるか、その前段に 認証プロキシを置いてください。(自前の @kozou/api REST バックエンドは、 auth を設定すれば JWT + RLS を 施行できます。)

フラグ

Section titled “フラグ”
フラグ引数説明
--config<path>kozou.config.yaml へのパス。デフォルトはカレントワーキングディレクトリからの相対パス ./kozou.config.yaml です。
--adapter<kind>この実行での REST バックエンド: api (自前の @kozou/api、デフォルト) または postgrest (外部 PostgREST、オプトアウト)。adapter.type 設定フィールドを上書きします。REST バックエンドの選択 を参照してください。
--api-port<n>自前の @kozou/api サーバー用のポート。バックエンドが api のときに使われます。デフォルトは 3335 です。

kozou dev 自体には、ホストやサービスごとのポートを指定するフラグは ありません。UI と MCP のポートおよびバインドホストは、コマンドラインでは なく kozou.config.yaml から取得されます (下記参照)。

ポートの構成

Section titled “ポートの構成”

Admin UI と MCP HTTP のリスナーは、kozou.config.yaml の server.ui と server.mcp.http で構成します。それぞれが port と host を取ります。

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

上記の値はデフォルトです。変更したいキーだけを書けば十分です。config の 他の部分と同様に、${VAR} および ${VAR:-default} のプレースホルダーは ロード時にプロセス環境から展開されます。完全なスキーマについては kozou.config.yaml を、スタンドアロンの MCP サーバーとその独自のトランスポートフラグについては kozou mcp を参照してください。

Admin UI は SvelteKit の adapter-node サーバーであり、Origin がサーバーの 期待するオリジンと一致しないフォーム POST を拒否します。デフォルトでは kozou dev がそのオリジンを http://localhost:<server.ui.port> に設定します。 UI を別の公開 URL で提供する場合は、フォーム送信が受け付けられるように ORIGIN (または KOZOU_ORIGIN) 環境変数を設定してください。

例

Section titled “例”

kozou dev をデータベースと config ファイルに向け、Admin UI を開きます。

Terminal window
DATABASE_URL=postgres://kozou:kozou@localhost:5432/kozou \
  kozou dev --config ./kozou.config.yaml

次のような config を使うと、

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


server:
  ui:
    port: 3333
  mcp:
    http:
      port: 3334


uiHints:
  path: ./ui-hints.yaml

Admin UI が http://localhost:3333 (たとえば products、orders、 authors テーブルの CRUD ページ付き) で、MCP HTTP エンドポイントが http://localhost:3334 で得られます。UI のラベル、ウィジェット、説明は、 DDL に加えて @widget や @ai といった COMMENT タグから取得されます。 たとえば、COMMENT で draft / published / archived を列挙する products.status カラムはセレクトとしてレンダリングされます。生成される もののツアーについては Admin UI を、HTTP エンド ポイントにエージェントを向ける方法については Connect MCP を参照してください。

REST バックエンドの選択

Section titled “REST バックエンドの選択”

v1.0 以降、kozou dev はデフォルトで自前の @kozou/api バックエンドを通じて REST を提供します。これは Admin UI を立ち上げる前にインプロセスで起動され、 UI はそれと通信するよう配線されます。そのため、デフォルトの kozou dev は 3 つのリスナーを立ち上げます。

  • server.ui.port (デフォルト 3333) 上の Admin UI、
  • server.mcp.http.port (デフォルト 3334) 上の MCP HTTP サーバー、そして
  • --api-port の値 (デフォルト 3335) 上の自前 @kozou/api サーバー。

@kozou/api サーバーは 127.0.0.1 のみにバインドされます。Admin UI の サーバーサイド fetch からのみ到達され、ブラウザやネットワークには一切 公開されません。3335 が使われている場合は --api-port でポートを上書き してください。

Terminal window
kozou dev --api-port 4000

バックエンドは adapter.type 設定フィールド (デフォルト api) で選択され、 単発の実行では --adapter で上書きできます。代わりに外部の PostgREST を使う には — たとえば既存のデプロイ — --adapter postgrest を設定します (または config の adapter.type: postgrest)。このモードでは @kozou/api サーバーは起動されません。

Terminal window
kozou dev --adapter postgrest

自前バックエンドの全体像 — 生成されるエンドポイント、COMMENT 駆動の OpenAPI 出力、そしてセキュリティ境界 (デフォルトはループバック、JWT + RLS は オプション) — については @kozou/api REST レイヤー を参照してください。