コンテンツにスキップ
Kozou

3 つのサーフェス

Kozou はあなたの PostgreSQL スキーマ（CREATE TABLE、 CREATE VIEW、COMMENT ON 文）を一度だけ読み取り、単一の Schema Context を構築します。Kozou が生成するすべてのサーフェスは、その 1 つのモデルから導出されます。すなわち Admin UI、AI エージェント向けの MCP コンテキスト、そして REST API です。

3 つすべてが同じ Schema Context を読み取るため、互いに食い違ったり、 データベースから遅れたりすることはありません。カラム名を変更したり、 enum 値を追加したり、COMMENT を書き換えたりすると、次の ビルドですべてのサーフェスがまとめて更新されます。更新する場所が 2 つに分かれることはありません。

各サーフェスが公開するセマンティクスは、あなたの COMMENT テキスト、つまり @ai、@widget、@policy、@example タグから直接得られます。タグの文法については COMMENT 規約 を参照してください。

Admin UI

Section titled “Admin UI”

Admin UI は、SvelteKit（@kozou/svelte-ui）上に構築された ランタイム生成のリファレンスアプリケーションです。これはあなたが編集して 保守するスキャフォールドされたコードではありません。起動時に Schema Context を 読み取り、あなたのテーブルとビューから自分自身をレンダリングします。

これが提供するもの:

  • すべてのテーブルに対する CRUD フォーム。作成、読み取り、更新、 削除に対応し、NOT NULL、CHECK 制約、カラムのデータ型から導出された バリデーションを備えます。
  • ウィジェットを意識した入力。 各フォームフィールドは、 カラムの @widget タグ（指定がない場合はヒューリスティック）から入力を 選択します。enum を背後に持つカラムはドロップダウンを、 自由記述のカラムはテキスト入力をレンダリングします。
  • リレーションピッカー。 外部キーは検索可能な コンボボックスとしてレンダリングされ、詳細ビューでは生の id を表示する 代わりに、関連する行を読みやすいラベルに解決します。
  • 読み取り専用ビュー。 CREATE VIEW は、閲覧可能で 読み取り専用のリストとして表示されます。検索、ソート、ページネーションは ありますが、作成、編集、削除のコントロールはありません。

kozou dev で起動すると、Admin UI（および隣接して MCP HTTP サーバー）が 立ち上がります。デフォルトでは UI は http://localhost:3333 で配信されます。

Terminal window
kozou dev
# Admin UI: http://localhost:3333

MCP コンテキスト

Section titled “MCP コンテキスト”

同じ Schema Context は、MCP サーバーである @kozou/mcp を通じて AI エージェントに公開されます。 Claude Code や Claude Desktop のようなエージェントが接続し、あなたのテーブル、 ビュー、ビジネス概念の意味を読み取ります。COMMENT に書いた 説明や @ai ノートを取り込みます。

このサーバーは 6 つのツールを公開しており、いずれも読み取り専用の コンテキストプロバイダーです:

  • list_tables — テーブル名とその説明。
  • describe_table — 1 つのテーブルの完全なスキーマと COMMENT。
  • list_views — ビュー名とその目的。
  • describe_view — ビューのカラム、目的、および依存している テーブル。
  • list_concepts — ビジネス概念（ビューとしてモデル化されたもの）。
  • get_concept_context — 1 つの概念に対する関連テーブルと推奨されるクエリ パス。

これらのツールはコンテキストのみを提供します。いずれも SQL を生成したり、 SQL を実行したり、データを書き込んだりしないため、Kozou に接続された エージェントは、スキーマが何を意味するかは読み取れますが、このサーフェスを通じて あなたのデータを変更することはできません。

サーバーはどちらのトランスポートでも実行できます:

Terminal window
# stdio — for a direct connection from Claude Desktop or Claude Code
kozou mcp --stdio


# HTTP — for Docker or remote use
kozou mcp --http --port 3334

HTTP トランスポートはデフォルトでポート 3334 をリッスンします。

REST API

Section titled “REST API”

v0.1 では、Kozou は REST API を配信するために PostgREST をサイドバイサイドのコンテナとして 組み込みます。PostgREST は Kozou の隣で独立したサービスのままです。 Kozou のランタイムイメージ内にはバンドルされず、Admin UI は プラガブルなデータアダプターを通じてそれと通信します。

v0.2 ラインでは、同じ Schema Context から エンドポイントを構築する EXPERIMENTAL な自社製 REST レイヤー、 @kozou/api が追加されます。これはオプトインで、フラグで制御されます:

Terminal window
kozou dev --adapter api

有効にすると、@kozou/api は以下を生成します:

  • 各テーブルに対する CRUD エンドポイント（list、get、create、update、 delete）と、各ビューに対する読み取り専用エンドポイント。PostgreSQL に直接 クエリを発行します。
  • /openapi.json における OpenAPI 3.1 ドキュメント。その 説明はあなたの COMMENT テキストから得られます。テーブル、ビュー、 カラムのコメントがスキーマの説明になるため、API ドキュメントはあなたがデータベースに書いたのと同じセマンティクスを保持します。

@kozou/api は実験的です。v0.2 ラインでは、PostgREST が 依然としてデフォルトであり、@kozou/api は kozou dev --adapter api で選択するオプトインのパスです。安定した契約ではなく、 プレビューとして扱ってください。

1 つのスキーマ、3 つのサーフェス

Section titled “1 つのスキーマ、3 つのサーフェス”

3 つのサーフェス、1 つのソース:

  • Admin UI は人間向けのサーフェスです。行の閲覧と編集のための 生成された SvelteKit アプリで、 http://localhost:3333 で配信されます。
  • MCP コンテキスト は AI 向けのサーフェスです。スキーマが何を意味するかを エージェントに教える 6 つの読み取り専用ツールで、stdio または HTTP （デフォルトポート 3334）で動作します。
  • REST API はプログラム向けのサーフェスです。v0.1 では PostgREST、 v0.2 ラインでは実験的な自社製 @kozou/api が利用できます。

あなたが保守するのは 1 つだけです。スキーマとその COMMENT テキストです。Kozou は 3 つすべてのサーフェスをそこから導出し続けるため、サーフェスが乖離することは ありません。それらのサーフェスが何を表示するかを形作るには、 データベースに書いてください。COMMENT 規約 を参照してください。