コンテンツにスキップ
Kozou

kozou dev

kozou dev はローカルランタイム用のコマンドです。バンドルされた @kozou/svelte-ui の Admin UI と MCP Streamable HTTP サーバーを単一の プロセスグループとして立ち上げ、両者を 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 サーバーを起動し、Ctrl-C で停止するまで実行を 続けます。

起動されるもの

Section titled “起動されるもの”

kozou dev は 2 つのサービスを立ち上げます。

  1. Admin UI — バンドルされた @kozou/svelte-ui アプリケーションで、 子プロセスとして起動されます。構成されたスキーマ内のすべてのテーブルと ビューに対して、生成された CRUD UI を提供します。デフォルトポート: 3333。
  2. MCP HTTP サーバー — @kozou/mcp の Streamable HTTP トランスポートで、 プロセス内で実行されます。AI エージェントが呼び出せるのと同じ Schema Context ツールを公開します。デフォルトポート: 3334。

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

デフォルトでは両サービスは 0.0.0.0 にバインドされるため、docker compose のポートマッピングがそのまま機能します。Kozou v0.1 ではどちらのサーフェスにも 認証がありません。そのため、いずれかが非ループバックホストにバインド されると目立つ警告が表示されます。kozou dev は信頼境界内 (自分のマシン、 またはプライベートな compose ネットワーク) に留めるか、その前段に認証 プロキシを置いてください。

フラグ

Section titled “フラグ”
フラグ引数説明
--config<path>kozou.config.yaml へのパス。デフォルトはカレントワーキングディレクトリからの相対パス ./kozou.config.yaml です。
--adapter<kind>実験的。 api に設定すると、デフォルトの REST アダプターの代わりに自社製の @kozou/api サーバーで REST レイヤーを支えます。受け付けられる値は api のみで、それ以外の値はエラーになります。実験的な --adapter api フラグ を参照してください。
--api-port<n>自社製の @kozou/api サーバー用のポート。--adapter 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 を参照してください。

実験的な --adapter api フラグ

Section titled “実験的な --adapter api フラグ”

実験的 (v0.2)。 Kozou v0.1 では REST サーフェスは PostgREST によって 提供されます。v0.2 系では @kozou/api が追加されます。これは自社製の REST レイヤーで、テーブルの CRUD、ビューの読み取り、COMMENT を考慮した OpenAPI ドキュメントを Schema Context から直接生成します。これはオプト インかつ実験的であり、PostgREST が引き続きデフォルトです。

--adapter api を渡すと、kozou dev は Admin UI を立ち上げる前に自社製の @kozou/api サーバーも起動し、デフォルトの REST アダプターの代わりにそれと 通信するよう UI を配線します。これにより 3 つ目のリスナーが追加されます。

Terminal window
kozou dev --adapter api

これにより、次のものが立ち上がります。

  • 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 --adapter api --api-port 4000

@kozou/api は実験的で未公開のワークスペースパッケージであるため、 --adapter api は kozou をソースまたはワークスペースのチェックアウトから 実行したときにのみ機能します。公開された kozou のインストールにはこれが バンドルされておらず、--adapter api を外すように (これはデフォルトの REST アダプターにフォールバックします) 明確なエラーを表示します。全体像 — 生成 されるエンドポイント、COMMENT 駆動の OpenAPI 出力、現在の制限 — については 実験的な @kozou/api レイヤー を参照してください。