はじめに

Kozou は PostgreSQL ネイティブなコンパイラ兼ランタイムです。データベースの DDL と COMMENT テキストを一度読み取り、Admin UI、REST API、AI エージェント向けの MCP コンテキストを生成します。定義の重複もドリフトもありません。

このページは5分で進める fast lane です。プロジェクトを scaffold し、スタックをオンラインにし、AI エージェントを MCP サーバーに向けるまでの happy path を案内します。背景にある考え方、出力サンプル、完全な手順を知りたい場合は Quickstart へ進んでください。

前提条件

PostgreSQL 16 以降 — 唯一の信頼できる source of truth です。
Docker 24 以降 (推奨) — docker compose up スタック用です。PostgreSQL と、Admin UI・MCP HTTP サーバー・自前の REST レイヤーをインプロセスで提供する kozou サービスを立ち上げます。
Node.js 20 以降 — 公開された npm パッケージを npx で直接実行するためのものです。scaffolder と host CLI を含みます。

完全な対応マトリクスと代替手段については Installation を参照してください。

1. プロジェクトを scaffold する

create-kozou は、docker-compose.yml、kozou.config.yaml、ui-hints.yaml、.env.example、そして starter migration を含む starter ディレクトリを書き出します。これは kozou パッケージの secondary bin として提供されるため、クリーンなマシンで見つけられるように npx には -p kozou が必要です。

npx -p kozou create-kozou my-project
cd my-project

2. スタックを起動する

example の環境ファイルをコピーし、すべてを立ち上げます。scaffold の docker-compose.yml には kozou dev を実行する kozou サービスが含まれているため、単一のコマンドでフルスタックがオンラインになります。PostgreSQL と、バンドルされた Admin UI・MCP HTTP サーバー・自前の REST レイヤーをすべてインプロセスで提供する kozou サービスです。

cp .env.example .env
docker compose up

3. Admin UI を開く

Admin UI はデフォルトでポート 3333 を listen します。ブラウザで開いてください:

http://localhost:3333

DDL と COMMENT テキストからレンダリングされた、スキーマのテーブルが表示されるはずです。カラムやテーブルの表示のされ方を整えるために、Kozou は @ai、@widget、@policy、@example といった COMMENT タグを読み取ります。詳しくは COMMENT conventions を参照してください。

4. AI エージェントを MCP サーバーに向ける

Kozou は同じ Schema Context を MCP 経由で AI エージェントに提供します。そのため、Claude Code や Claude Desktop のようなツールが introspect ツールや describe-table ツールを呼び出せます。

stdio トランスポート (デフォルト) では、host CLI を実行します:

kozou mcp --stdio

Step 2 の docker compose up で起動した kozou dev プロセスは、ポート 3334 で MCP を HTTP 経由でも提供します。そのため、HTTP に対応したエージェントは別途コマンドを実行することなくそこへ接続できます。

次に読むもの

Quickstart — 出力サンプル、構成の詳細、完全な手順を伴う同じフローです。
Installation — 要件マトリクス、Docker ランタイムイメージ、そして @kozou/core、@kozou/introspect、@kozou/mcp、@kozou/svelte-ui などのライブラリパッケージです。
COMMENT conventions — @ai、@widget、@policy、@example タグが生成されるサーフェスをどのように駆動するかについてです。