Kozou

What is Kozou?

Point an MCP-capable agent (Claude Code, Claude Desktop, Cursor) at a business PostgreSQL and ask it a real question — “what was our revenue last quarter?” — and it will confidently write a plausible, wrong query. Not because the model is weak, but because the answer isn’t in the column types. It’s in the business rules around them: which column is authoritative, what a status really means, which rows don’t count, which view is the source of truth.

Kozou reads that knowledge straight from your schema — COMMENT ON text, view definitions, types, and (opt-in) the serving role’s effective privileges — and hands it to the agent over MCP. Same model, same question, correct answer.

• AI agents understand your schema’s meaning. @kozou/mcp hands Claude Code, Claude Desktop, and other MCP clients the business semantics you wrote in COMMENT — @ai advisories, @policy rules, the “faithful, named concepts” your views encode — so agents reason from your rules instead of guessing.
• …and what a role may touch. Opt in (introspection.respectPrivileges) and the MCP describe tools and kozou docs also tell the agent a role’s effective GRANTs — that it may read a table but not write it — the wedge a query layer that enforces but doesn’t explain can’t give an agent. Advisory only; enforcement stays in PostgreSQL.
• PostgreSQL is the single source of truth. Structure, relations, and business meaning live physically in the database as DDL and COMMENT. If you can express it in PostgreSQL, you don’t repeat it in YAML.
• The same source also emits faithful forms. One compile produces a generated Admin UI, a REST API + OpenAPI (@kozou/api, the default backend — PostgREST is the opt-out), Markdown docs (kozou docs), and TypeScript types. No duplicate definitions, no drift.

The lever is COMMENT: annotate a column with @ai, @widget, or @example and that intent flows into the MCP context, the API docs, and the UI at once. See COMMENT conventions.

Kozou isn’t a tool for building your structure — it’s a tool for conveying that structure and its meaning, faithfully, to people and AI. You (and the AI you connect) build it; Kozou conveys it.

Install

# Scaffold a project (docker-compose + kozou.config.yaml + ui-hints.yaml)
npx -p kozou create-kozou my-project
cd my-project
cp .env.example .env
docker compose up

docker compose up brings PostgreSQL and a kozou service — serving the Admin UI, MCP, and the in-house REST layer in-process — online together. Prefer to run the CLI on your host instead? See Installation.

Status

Kozou is at v1.15.1. Schema introspection, the MCP server (stdio + HTTP), and the reference Admin UI are published on npm, and a multi-arch runtime image is on GHCR. @kozou/api, the in-house REST layer, is the default backend since v1.0, with PostgREST as an opt-out (kozou dev --adapter postgrest). Since v1.4, Postgres functions tagged @expose: rpc compile into RPC actions across REST, OpenAPI, MCP, and the Admin UI. Since v1.8, opt-in privilege-aware context lets the MCP describe tools and kozou docs annotate what a role may touch (see Connect an AI agent).

Source lives at github.com/kozou-dev/kozou. Published packages include kozou (CLI), @kozou/core, @kozou/introspect, @kozou/mcp, and @kozou/svelte-ui.

The name

Kozou carries three meanings in three syllables: kozō (calf — the young elephant beside PostgreSQL’s mascot Slonik), kōzō (structure — the transformation a compiler performs), and kozō (apprentice — the quiet figure that serves something larger than itself).