Kozou - Compilador PostgreSQL
kozou-dev/kozou
De um schema PostgreSQL, gera UI, tipos, APIs e docs sem duplicação
Ver no GitHubMCP Server que lê um schema PostgreSQL uma única vez e gera múltiplas formas dele: UI admin, contexto MCP, tipos TypeScript, endpoints REST e documentação. Elimina duplicação de definições e drift de schema através de uma única fonte de verdade.
Instalação
npx convez-ai kozou-dev/kozou1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.
Métricas
Casos de uso
- Gerar UI admin automática a partir de schema PostgreSQL
- Criar tipos TypeScript e endpoints REST sincronizados com o banco
- Documentar schemas em Markdown de forma automática
- Integrar IA (Claude, etc) com contexto estruturado via MCP
Veredito

Solução madura (v1.3.0) que resolve um problema real: sincronização de múltiplas representações de um schema. Excelente para equipes que usam IA e precisam manter tipos, APIs e docs alinhados. Atenção à política de segurança quanto a COMMENT ON em ambientes multi-tenant.
README
A tradução para o português deste README ainda está na fila.
kozou
PostgreSQL compiler. One source, many faithful forms.
Kozou reads a PostgreSQL schema once and produces every form a modern team and its AI need from it — admin UI, MCP context, TypeScript types, REST endpoints, and documentation. No duplicate definitions. No drift.
Status
v1.3.0 (latest release). The CLI, schema introspection, MCP server (stdio + HTTP), reference Admin UI (now with composite-foreign-key support, including a composite relation picker in the create/edit forms), Markdown schema-document generation (kozou docs), and Kozou's in-house REST backend (@kozou/api, the default kozou dev data layer) are all available on npm; the runtime image lives on GHCR as a multi-arch manifest (linux/amd64 + linux/arm64). Releases land via the workflow in .github/workflows/release.yml.
Quickstart
# Scaffold a project (docker-compose + kozou.config.yaml + ui-hints.yaml).
# `create-kozou` ships as a secondary bin of the `kozou` package, so npx
# needs `-p kozou` to find it on a clean machine.
npx -p kozou create-kozou my-project
cd my-project
# Bring up PostgreSQL and the Admin UI. The scaffold's docker-compose
# runs a `kozou` service (`kozou dev`: the bundled SvelteKit Admin UI,
# MCP HTTP server, and Kozou's in-house REST backend, all in-process),
# so `docker compose up` brings the full stack online — no separate REST
# container by default.
cp .env.example .env
docker compose up
Or pull the CLI runtime image directly:
docker pull ghcr.io/kozou-dev/kozou:v1.3.0
docker run --rm ghcr.io/kozou-dev/kozou:v1.3.0 inspect --help
docker run --rm ghcr.io/kozou-dev/kozou:v1.3.0 mcp --help
For library use (custom hosts, embedded MCP), install the workspace packages from npm:
npm install kozou @kozou/core @kozou/introspect @kozou/mcp @kozou/svelte-ui
@kozou/api (Kozou's in-house REST layer — its wire format and OpenAPI are a stable contract as of v1.0) is the default kozou dev backend and is bundled with kozou, so no separate install is needed. The experimental @kozou/codegen TypeScript codegen ships as an optional companion — install it alongside kozou when you want kozou codegen:
npm install kozou @kozou/codegen
Security
Kozou introspects COMMENT ON text, view definitions, and type information from PostgreSQL, then hands them verbatim to AI agents through @kozou/mcp. This relies on an important assumption: schema authors (the principals with permission to edit DB schema) are trusted. We call this the trust boundary.
Designs where tenants in a multi-tenant SaaS can edit DB COMMENT text are discouraged (prompt-injection risk). See docs/security.md for the threat model and mitigation plans, and SECURITY.md if you need to report a vulnerability privately.
On the access-control axis, Kozou is a resource server and enforcement layer, not an identity provider: with auth enabled it verifies the JWT on each request that carries one — with an optional anonymous-role path for tokenless requests — and runs each under a PostgreSQL role so your own RLS policies decide access. Identity provision (registration, login, passwords and OAuth, token issuance) is delegated to an external provider — Supabase Auth (recommended), Auth0 / Clerk via JWKS, or a minimal self-hosted issuer. See docs/security.md.
Requirements
Runtime requirements for v1.3.0:
- PostgreSQL 16 or later — the canonical source of truth
- Docker 24 or later (optional) — recommended for the
docker compose upstack, which brings up PostgreSQL and akozouservice runningkozou dev(the bundled Admin UI + MCP HTTP server, plus Kozou's in-house REST backend served in-process) fromghcr.io/kozou-dev/kozou(a multi-arch image, native on linux/amd64 and linux/arm64). The default stack needs no separate REST container; to opt out and use an external PostgREST instead, setadapter.type: postgrestand add the (commented) service in the scaffold'sdocker-compose.yml. - Node.js 20 or later — for running the npm-published packages directly (
npx kozou …)
Contributors additionally need pnpm 9 or later. See CONTRIBUTING.md for the development environment setup.
Roadmap
- v0.1.0 (shipped): schema introspection, MCP server (stdio), reference Admin UI,
create-kozouscaffold, PostgREST adapter - v0.1.1 (shipped): MCP HTTP transport,
kozou devhost integration, multi-arch Docker image (linux/amd64 + linux/arm64), Playwright E2E for the Admin UI, CodeQL reactivation, zod 4 / TypeScript 6 migration - v0.2.0 (shipped):
kozou docsMarkdown schema documents;@policyadvisory metadata surfaced to AI agents through the MCP server - v0.2.1 (shipped): multi-line
@ai/@policyCOMMENT blocks are now captured in full (not just the first line) in the MCP describe tools and@kozou/apiOpenAPI; the experimental@kozou/apiREST layer — with multi-hop relation embedding and opt-in JWT + Postgres RLS — and@kozou/codegenTypeScript row types are now published to npm as optional companions, exercised viakozou dev --adapter apiandkozou codegen - v1.0.0 (shipped):
@kozou/api, Kozou's in-house REST backend, is now the defaultkozou devdata layer and ships bundled with the CLI; PostgREST drops to an opt-out adapter (adapter.type: postgrest). Its REST wire format and OpenAPI are a stable contract. Composite primary keys are addressable end to end, and list filters gain PostgREST-compatible operators (eq/neq/gt/gte/lt/lte/like/ilike/in/is). See the scope table in the@kozou/apiREADME for which relational-REST features the default backend covers and which to keep PostgREST for. - v1.1.0 (shipped): composite foreign keys become first-class — they embed as relations (multi-column joins,
x-kozou-embedshints carrying the foreign-key column set, MCP /kozou docsvisibility), the relation-select endpoint serves composite-key targets (array option ids), and the Admin UI's create/edit forms gain a relation picker: single-column FKs get a searchable picker, and an eligible composite FK becomes one picker that fills every key column at once, with a non-enhanced (no-JS) form path. See the@kozou/svelte-uiREADME for the picker's eligibility rules and known limitations. The OpenAPI document is also faithful to runtime request bodies and modes. - v1.1.1 (shipped): a patch release of fixes from v1.0/v1.1 field reports. The scaffold's docker-compose now forwards the documented
KOZOU_JWT_*auth variables (they previously never reached the container, leaving auth silently off) andkozou devprints an unambiguousapi auth:state line at startup.@kozou/apimaps database outcomes to stable HTTP statuses — privilege / row-level-security denials return 403, constraint conflicts 409/400 — with raw database text kept out of response bodies (see the Errors section of the@kozou/apiREADME). The Admin UI can create rows that leave defaulted NOT NULL columns empty, two long-standing form bugs are fixed (defaulted non-text columns no longer 500 the create/edit forms; manual uuid entry submits again), and runtime warnings no longer carry stale version pins. - v1.2.0 (shipped): the auto-minted Admin UI service token (the HS256 development convenience) can now carry custom JWT claims via
auth.ui.claims(or theKOZOU_UI_CLAIMSenvironment variable), so RLS policies keyed on claims beyondrolecan be exercised from the bundled UI in local development. Theroleclaim stays reserved — a colliding entry is dropped so a custom claim can never smuggle in a role — andiatis always set by the mint; a configurediss/audwins over a custom one, while a custom temporal claim (exp/nbf) is passed through but warned about when it would make the token rejected. Schema introspection also warns when a known COMMENT tag (@ai,@policy, …) appears mid-line instead of at the start of a line — such tags are not parsed and would otherwise leak verbatim into the surrounding description. - v1.3.0 (shipped): opt-in privilege-aware introspection (
introspection.respectPrivileges, default off) makes the bundled Admin UI faithful to what the serving role may do, not just what the schema declares. A table or view the role cannotSELECT(gated by schemaUSAGE) is hidden from the nav; a column it cannot write renders read-only per form mode (noINSERT→ read-only on create, noUPDATE→ read-only on edit); and Delete is hidden where the role lacks it. The role evaluated is the Admin UI's (auth.ui.role/auth.defaultRole, or an explicitintrospection.role).@kozou/apiand the MCP server stay schema-wide. - v1.4.0 (shipped): opt-in RPC actions — a Postgres function tagged
@expose: rpcin its COMMENT is compiled into a callable action across all four surfaces at once: REST (POST /rpc/<schema>.<fn>with a named-args body), the COMMENT-native OpenAPI document, an MCPdescribe_functionstool, and an Admin UI "Actions" page. This recovers the verb-level capability the v1.0 default switch dropped, and lets the security model Kozou recommends (state changes funnelled through functions, table writes revoked) stay reachable. Exposure is opt-in and never silent: nothing is exposed by default; a function still grantingEXECUTEto PUBLIC is hard-skipped unless deliberately opened (@expose: rpc public/api.rpc.allowPublicExecute); aSECURITY DEFINERfunction needs a config double opt-in (api.rpc.allowDefiner) and an owner-safesearch_path; unsupported shapes are loudly skipped. Whether a caller may run an action is enforced by the PostgreSQLEXECUTEprivilege under the request's role — a denial is 403, so exposure is not permission. The wire shape is experimental until dogfooding settles it. See the RPC actions section of the@kozou/apiREADME. - Beyond v1.4: the MCP
call(execution) tool — letting an AI agent run an exposed action, not just describe it; React UI exploration
Name
Kozou carries three meanings in three syllables:
- kozō (calf) — the young elephant walking beside PostgreSQL's mascot Slonik
- kōzō (structure) — the structural transformation a compiler performs
- kozō (apprentice) — the quiet figure who serves something larger than itself
License
Apache 2.0