インストール

Kozou は 3 つのチャネルで提供されます。GHCR で公開されている Docker ランタイムイメージ、npm パッケージ群 (CLI とライブラリ)、そしてそれらを Docker Compose で結びつけるプロジェクト scaffold です。このページではそれぞれの方式を説明します。スタックを最短で動かしたいだけなら、option A から始めて、その後 Quickstart を読んでください。

現在公開されているリリースは v1.15.1 です。

要件

ランタイム要件です。

• PostgreSQL 16 以降 — Kozou が読み取る、信頼できる唯一の情報源です。
• Docker 24 以降 (任意) — docker compose up スタックには推奨され、ランタイムイメージを直接 pull したい場合には必須です。
• Node.js 20 以降 — npm で公開されているパッケージを直接実行する場合 (例: npx kozou …) に必要です。

コントリビューターはモノレポをビルドするために、加えて pnpm 9 以降 が必要です。開発環境のセットアップについては Contributing を参照してください。

オプション A — Scaffold + Docker Compose

これが最もシンプルな方式です。create-kozou scaffold は Docker Compose 向けに配線済みのプロジェクトディレクトリを生成するため、docker compose up 一発でスタック全体が立ち上がります。すなわち PostgreSQL と、kozou dev (バンドルされた Admin UI、MCP HTTP サーバー、そして Kozou 自前の REST バックエンドをすべてインプロセスで) を実行する kozou サービスです。デフォルトのスタックに別個の REST コンテナは含まれません。

create-kozou は独立した npm パッケージではなく kozou パッケージのセカンダリ bin として提供されるため、クリーンなマシンで npx がこれを見つけるには -p kozou が必要です。

# Scaffold a project.
npx -p kozou create-kozou my-project
cd my-project

# Copy the env template, then bring up the full stack.
cp .env.example .env
docker compose up

scaffold が生成するもの:

• docker-compose.yml — PostgreSQL と、kozou dev を実行して Admin UI・MCP HTTP サーバー・自前の REST バックエンド (すべてインプロセス) をホストする kozou サービスを立ち上げます。外部 PostgREST はコメントアウトされた opt-out サービスとしてのみ含まれます。
• kozou.config.yaml — すべての Kozou コマンドを駆動する設定ファイルです。
• ui-hints.yaml — kozou.config.yaml から参照される UI ヒントです。
• .env.example — データベースの認証情報 (POSTGRES_USER / POSTGRES_PASSWORD / POSTGRES_DB) などのスタック設定を供給するために .env へコピーするテンプレートです。docker compose up がこれらから DATABASE_URL を組み立てるため、接続文字列を手で設定する必要はありません。

スターターのマイグレーションも含まれているため、データベースは introspect するためのスキーマを備えた状態で立ち上がります。

デフォルトでは Admin UI はポート 3333 で、MCP HTTP サーバーは 3334 で待ち受けます。これらは kozou.config.yaml の server.ui と server.mcp.http で上書きできます。

オプション B — GHCR ランタイムイメージ

CLI ランタイムは GitHub Container Registry にマルチアーキテクチャの manifest として公開されており、linux/amd64 と linux/arm64 の両方でネイティブに動作します。Node.js をローカルにインストールせずに kozou CLI を実行したい場合は、直接 pull してください。

docker pull ghcr.io/kozou-dev/kozou:latest

任意のサブコマンドは docker run に付け加えて実行します。例えば inspect のフラグを確認するには次のようにします。

docker run --rm ghcr.io/kozou-dev/kozou:latest inspect --help

同じパターンが MCP サーバーでも使えます。

docker run --rm ghcr.io/kozou-dev/kozou:latest mcp --help

このイメージは kozou CLI、Admin UI、そして自前の REST バックエンドをバンドルしています。PostgREST はバンドルされておらず、デフォルトのスタックにも含まれません — 並列のコンテナとして追加できる任意の opt-out です。

オプション C — npm CLI

bin エントリを $PATH に通すために、CLI をグローバルにインストールします。

npm install -g kozou

これにより 2 つの bin が公開されます。

• kozou — メインのマルチコマンド CLI (inspect / mcp / dev)。
• create-kozou — プロジェクトディレクトリを scaffold します (option A で使われるジェネレーター)。

グローバルインストールせずに CLI を実行するには npx を使います。

npx kozou inspect --help

CLI には到達可能な PostgreSQL と kozou.config.yaml が必要です。バンドルされている設定テンプレートは、${DATABASE_URL} プレースホルダーを通じて接続文字列を DATABASE_URL 環境変数から読み取るため、コマンドを呼び出す際にこれを設定してください。

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

kozou inspect は設定されたデータベースを introspect し、Schema Context を stdout (または --output <path>) へ出力します。kozou mcp --stdio は stdio 経由で MCP サーバーを起動します。kozou mcp --http は同じツール群を HTTP 経由で提供します (--port / --host でリスナーを設定し、stdio がデフォルトのまま維持されます)。kozou dev は Admin UI を MCP HTTP サーバーと並べて実行し、どちらも kozou.config.yaml から配線されます。

最小限の kozou.config.yaml は次のようになります。

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

uiHints:
  path: ./ui-hints.yaml

${VAR} と ${VAR:-default} は、設定の読み込み時にプロセス環境から展開されます。

REST アダプター: Kozou 自前の REST レイヤー @kozou/api が v1.0 以降のデフォルトのバックエンドです。kozou dev が別コンテナなし・adapter セクション不要でインプロセスに提供し、その REST のワイヤーフォーマットと OpenAPI ドキュメントは安定した契約です。代わりに外部 PostgREST にオプトアウトするには、adapter ブロック (type: postgrest、url: ${KOZOU_ADAPTER_URL:-http://postgrest:3000}) を追加するか、kozou dev --adapter postgrest を渡します。

オプション D — 組み込み用ライブラリパッケージ

カスタムホストを構築したり、MCP サーバーを自分のアプリケーションに埋め込んだりする場合は、ワークスペースパッケージを npm からインストールします。

npm install kozou @kozou/core @kozou/introspect @kozou/mcp @kozou/svelte-ui

これらにより、introspection エンジン (@kozou/introspect)、コアコンパイラ (@kozou/core)、MCP サーバー (@kozou/mcp)、リファレンス Admin UI コンポーネント (@kozou/svelte-ui) が手に入り、kozou CLI もそれらと一緒に提供されます。

インストールの確認

CLI が解決され、そのコマンドサーフェスを出力することを確認します。

kozou inspect --help

代わりにランタイムイメージを pull した場合は、Docker 経由で同等のコマンドを実行します。

docker run --rm ghcr.io/kozou-dev/kozou:latest inspect --help

どちらもエラーなく inspect のフラグを出力するはずです。ここから CLI をデータベースに向けて、実際の出力を生成しましょう — status カラム (draft / published / archived) を持つ products テーブルや orders リレーションが、最初の対象として適しています。

次のステップ

• Getting started — Kozou の背後にある概念と、各要素がどのように噛み合うか。
• Quickstart — 空のディレクトリから、動作する Admin UI とライブな MCP コンテキストへ。