Kozou
Kozou とは
Section titled “Kozou とは”MCP 対応のエージェント (Claude Code・Claude Desktop・Cursor) を業務データベースの PostgreSQL に向けて、実際の質問 — 「先四半期の売上は?」 — を投げると、 エージェントはもっともらしいが誤った query を自信満々に書きます。モデルが 非力だからではなく、答えがカラムの型にはないからです。答えは型の周りの業務 ルール — どのカラムが正なのか、ある status が実際に何を意味するのか、どの行が 数えられないのか、どのビューが真実の源なのか — にあります。
Kozou はその知識をスキーマから直接読み取り — COMMENT ON のテキスト、ビュー
定義、型、そして (オプトインで) 配信ロールの実効権限 — を MCP 経由でエージェント
へ渡します。同じモデル、同じ質問で、正しい答えに。
- AI エージェントがスキーマの意味を理解。
@kozou/mcpが、あなたがCOMMENTに書いた業務セマンティクス —@aiの助言、@policyのルール、 ビューが符号化する「忠実で名前のついた概念」 — を Claude Code・Claude Desktop などの MCP クライアントへ渡すので、エージェントは推測せず、あなたの ルールに基づいて推論します。 - …そして何に触れてよいかも。 オプトイン
(
introspection.respectPrivileges) すると、 MCP の describe ツールとkozou docsが、あるロールの実効 GRANT — テーブルを 読めるが書けない、など — もエージェントに伝えます。施行はするが説明しない query 層にはエージェントへ渡せない差別化です。advisory のみで、施行は PostgreSQL に残ります。 - PostgreSQL を単一の真実の源に。 構造・リレーション・業務的な意味は、
DDL と
COMMENTとしてデータベースに物理的に存在します。PostgreSQL で 表現できるものを、YAML に二重に書くことはしません。 - 同じ源から忠実な各種の形も生成。 一度のコンパイルで、生成された
Admin UI、REST API + OpenAPI
(
@kozou/apiがデフォルト、PostgREST はオプトアウト)、Markdown ドキュメント (kozou docs)、TypeScript 型ができます。定義の重複なし、drift なし。
鍵となるのは COMMENT です。カラムに @ai・@widget・@example を注記
すると、その意図が MCP コンテキスト・API ドキュメント・UI へ同時に流れ込みます。
COMMENT 規約 を参照してください。
kozou は「構造を作る道具」ではなく、「構造とその意味を、人と AI に正しく 伝える道具」です。 作るのはあなた（と、あなたが繋いだ AI）、伝えるのが kozou。
インストール
Section titled “インストール”# プロジェクトを scaffold (docker-compose + kozou.config.yaml + ui-hints.yaml)npx -p kozou create-kozou my-projectcd my-projectcp .env.example .envdocker compose updocker compose up で PostgreSQL と、Admin UI・MCP・自前の REST 層をインプロセスで提供する kozou サービスがまとめて起動します。
ホスト上で CLI を直接動かしたい場合は インストール を
参照してください。
Kozou は v1.15.1 です。スキーマ introspection・MCP サーバー (stdio + HTTP)・
リファレンス Admin UI は npm で公開済みで、multi-arch の runtime イメージは
GHCR にあります。内製 REST 層 @kozou/api は v1.0 以降のデフォルトの
バックエンドで、PostgREST はオプトアウト (kozou dev --adapter postgrest) です。
v1.4 以降は、@expose: rpc でタグ付けした Postgres 関数が REST・OpenAPI・MCP・
Admin UI を横断する RPC アクション にコンパイルされます。
v1.8 以降は、オプトインの privilege-aware コンテキストにより、MCP の describe
ツールと kozou docs がロールの触れてよい範囲を注記できます
(AI エージェントを接続する を参照)。
ソースは github.com/kozou-dev/kozou にあります。 公開パッケージには kozou (CLI)、 @kozou/core、 @kozou/introspect、 @kozou/mcp、 @kozou/svelte-ui などが あります。
名前について
Section titled “名前について”Kozou は 3 音節に 3 つの意味を持ちます。kozō (子象 — PostgreSQL の マスコット Slonik の傍らを歩く幼い象)、kōzō (構造 — コンパイラが行う構造 変換)、kozō (小僧 — 自分より大きな何かに仕える静かな存在) です。