クイックスタート

このウォークスルーでは、ゼロから、あなたが理解できる稼働中の Kozou スタックまでを案内します。あなたは PostgreSQL スキーマを書き、 Kozou はそれを一度読み込んで、同じ DDL と COMMENT から Admin UI、 REST レイヤー、MCP コンテキストを提供します — 定義の重複はありません。

所要時間は約 10 分を見込んでください。終わるころには、ローカルで稼働するスタックと、MCP 経由であなたのスキーマを読む AI エージェントが手元にあります。

最終的に手に入るもの

PostgreSQL — スキーマの単一の信頼できる情報源。
REST レイヤー — v0.1 では PostgREST が提供し、並列のコンテナとして起動されます。
Admin UI — あなたのテーブルとビューから生成される、ブラウザ上の CRUD インターフェース。ポート 3333 で動作します。
MCP エンドポイント — AI エージェント向けの読み取り専用スキーマコンテキスト。ポート 3334 の HTTP 経由、またはエージェントを直接接続する stdio 経由で利用できます。

前提条件

PostgreSQL 16 以降 — 正準的な信頼できる情報源。scaffold されたスタックは独自の PostgreSQL コンテナを起動するため、このウォークスルーではローカルへのインストールは不要です。
Docker 24 以降 — docker compose up スタックのために推奨します。
Node.js 20 以降 — 公開パッケージを npx で直接実行するために必要です。

npx を使う代わりに CLI をグローバルにインストールしたい、あるいはランタイムイメージを pull したい場合は、インストールを参照してください。

1. create-kozou で scaffold する

create-kozou は単体の npm パッケージではなく、kozou パッケージのセカンダリ bin として配布されています。そのため、クリーンなマシンで npx がそれを見つけるには -p kozou が必要です:

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

これにより、バンドルされたテンプレートからプロジェクトディレクトリが書き出されます。生成された内容を見てみましょう:

my-project/
├── docker-compose.yml      # PostgreSQL + PostgREST + a `kozou` service
├── kozou.config.yaml       # database URL, adapter, and UI-hints path
├── ui-hints.yaml           # optional per-column label / widget overrides
├── .env.example            # template for the env vars the stack reads
└── migrations/             # your schema; starts with a placeholder 0001_init.sql

一行ずつ説明します:

docker-compose.yml — PostgreSQL、PostgREST(REST レイヤー)、そして kozou dev を実行して Admin UI と MCP HTTP サーバーをホストする kozou サービスを起動します。
kozou.config.yaml — Kozou をあなたのデータベース (${DATABASE_URL})に向け、REST アダプターを選択し、UI ヒントを参照します。${VAR} と ${VAR:-default} は読み込み時に環境変数から展開されます。
ui-hints.yaml — データベースに触れずに、カラムのラベル、入力ウィジェット、表示フィールドを上書きするためのオプションファイルです。ヒューリスティクスと COMMENT タグでほとんどのケースをカバーできるため、これは最初はほぼ空です。
.env.example — DATABASE_URL を含む、スタックが読み込む環境変数のテンプレートです。次のステップで .env にコピーします。

スターターの migrations/0001_init.sql は空のプレースホルダーです。そこにあなた自身の CREATE TABLE / CREATE VIEW / COMMENT ON … ステートメントを追加してください — 例えば products テーブル、 orders テーブル、authors/books のリレーションなどです。Kozou はそのスキーマを、以下で見ていく Admin UI と MCP コンテキストに変換します。

2. スタックを起動する

env テンプレートをコピーし、すべてを起動します:

cp .env.example .env
docker compose up

kozou サービスは kozou dev(バンドルされた SvelteKit Admin UI と MCP HTTP サーバー)を実行するため、docker compose up は一つのコマンドでフルスタックをオンラインにします。デフォルトのポートは次のとおりです:

Admin UI — http://localhost:3333
MCP HTTP — http://localhost:3334

これらを変更するには、kozou.config.yaml で server.ui / server.mcp.http を設定します。バックグラウンドで実行するには -d を追加します。

3. Admin UI を見て回る

http://localhost:3333 を開きます。Admin UI は完全にあなたのスキーマから生成されます — 書くべき UI コードはありません。

ダッシュボード — すべてのテーブルを一覧し、別のセクションですべてのビューを一覧します。それぞれにラベルと説明の抜粋が付きます。エントリをクリックすると開きます。
リストビュー — テーブルについて、表示フィールドを先頭に、主要なカラムを並べて行を表示します。検索(カラムをまたいだ大文字小文字を区別しないマッチ)、ソート(カラムヘッダーをクリックして昇順/降順を切り替え)、ページネーション(1 始まり、デフォルトで 1 ページあたり 50 行)に対応しています。
作成・編集フォーム — テーブルのカラムから生成され、ウィジェットを意識した入力を備えます: enum カラムはドロップダウンとして、 boolean はチェックボックスとして、日付は日付ピッカーとして描画され、以下同様です。データベースのデフォルト(created_at など)のみで埋められるカラムは、編集フォームでは読み取り専用になります。
外部キーのリレーションピッカー — 外部キーのカラムは、参照先の行のラベルを解決する検索可能なコンボボックスとして描画されるため、関連するレコードを id ではなく名前で選べます。
読み取り専用ビュー — ビューは、同じ検索、ソート、ページネーションを備えたリストとして開きますが、作成、編集、削除のコントロールはありません。

4. MCP 経由で AI エージェントを接続する

Kozou は Model Context Protocol 経由で、あなたのスキーマを AI エージェントに公開します。Claude Code や Claude Desktop からの直接接続には、 kozou mcp --stdio を MCP サーバーとして登録します。

エージェントの MCP 設定にエントリを追加します。バンドルされた kozou.config.yaml 内の ${DATABASE_URL} プレースホルダーは DATABASE_URL 環境変数を消費するため、ここで渡します:

{
  "mcpServers": {
    "kozou": {
      "command": "npx",
      "args": ["-y", "kozou", "mcp", "--stdio"],
      "env": {
        "DATABASE_URL": "postgres://kozou:kozou@localhost:5432/kozou"
      }
    }
  }
}

登録すると、エージェントは 6 つの読み取り専用ツールを呼び出せます。これらはコンテキストプロバイダーにすぎません — SQL を生成したり、 SQL を実行したり、データを書き込んだりは決してしません:

list_tables — テーブル名と、そのラベルおよび説明。
describe_table — 一つのテーブルの完全なスキーマと COMMENT。
list_views — ビュー名と、その目的。
describe_view — ビューのカラム、目的、基となるテーブル。
list_concepts — ビュー 1 つにつき 1 つのビジネス概念。
get_concept_context — 概念に関連するテーブルと、推奨されるクエリパス。

ステップ 2 で起動したスタックも、ポート 3334 の HTTP 経由でこれらと同じツールを提供します。これは、エージェントが自前のプロセスを起動するのではなく、稼働中のコンテナに接続するときに使うトランスポートです。

5. COMMENT で注釈を付ける

Kozou は通常の PostgreSQL の COMMENT テキストを読み込みます。いくつかの接頭辞タグは構造化されたヒントとして抽出されます — @ai、 @widget、@policy、@example です。カラムにコメントを追加します:

COMMENT ON COLUMN products.status IS
  'Lifecycle state of the product.
   draft:     not yet visible
   published: visible in public listings
   archived:  retired from sale

   @ai: prefer the published view for public listings
   @widget: enum-select';

このひとつのコメントから、2 つのことが起こります:

@widget: enum-select は Admin UI の入力を変えます。プレーンなテキストフィールドの代わりに、products.status はドロップダウンとして描画されるようになります。@widget はカラムコメントでのみ尊重されます。(これがなくても、Kozou は CHECK 制約が status IN ('draft','published','archived') のような値リストであるカラムに対して enum-select を推論します — このタグはそれを明示的に上書きするものです。)
@ai: … は MCP コンテキストに届きます。このメモは describe_table や get_concept_context といったツールを通じて surface されるため、クエリを書くエージェントはあなたのガイダンスを目にします。@ai 行は人間が読める本文にも残るので、コメントは依然として自然に読めます。

規約の全体については、 COMMENT 規約を参照してください。

トラブルシューティング

ポートが既に使用中 — 別のプロセスが 3333 または 3334 にバインドされています。それを停止するか、kozou.config.yaml の server.ui / server.mcp.http(および docker-compose.yml の対応するマッピング) でポートを再マッピングしてください。
データベースに到達できない — .env の DATABASE_URL が docker-compose.yml の PostgreSQL サービスと一致していること、そしてデータベースコンテナが healthy であること(docker compose ps) を確認してください。初回起動が遅い場合、PostgreSQL が接続を受け付ける準備が整う前に他のサービスが起動することがあります。
Admin UI のフォーム POST が拒否される — Admin UI はプレーンな HTTP で提供されるため、SvelteKit は ORIGIN を必要とします。scaffold は ORIGIN=${KOZOU_ORIGIN:-http://localhost:3333} を設定します。 Admin UI のポートを再マッピングした場合は、それと同期を保ってください。
create-kozou が見つからない — npx -p kozou create-kozou … として実行したことを確認してください。これは kozou パッケージのセカンダリ bin であり、単体のものではありません。

次に

COMMENT 規約 — すべてのタグ (@ai、@widget、@policy、@example)と、それぞれがどう解析されるか。
出力されるサーフェス — Admin UI、 REST レイヤー、MCP がそれぞれ何を公開するか、そしてなぜか。
インストール — グローバルインストール、ランタイムイメージ、そしてワークスペースパッケージ(@kozou/core、 @kozou/introspect、@kozou/mcp、@kozou/svelte-ui)をライブラリとして使う方法。

v0.1 の REST レイヤーは PostgREST が提供します。v0.2 系では、実験的な自社製 REST レイヤー @kozou/api が追加され、kozou dev --adapter api で有効化できます。これは実験的なものであり、デフォルトではありません。