Skip to content
Kozou

The three surfaces

Kozou reads your PostgreSQL schema once — the CREATE TABLE, CREATE VIEW, and COMMENT ON statements — and builds a single Schema Context. Every surface Kozou emits is derived from that one model: an Admin UI, MCP context for AI agents, and a REST API.

Because all three read the same Schema Context, they cannot disagree with each other or fall behind the database. Rename a column, add an enum value, or rewrite a COMMENT, and the next build refreshes every surface together. There is no second place to update.

The semantics each surface exposes come straight from your COMMENT text — the @ai, @widget, @policy, and @example tags. See COMMENT conventions for the tag grammar.

Admin UI

Section titled “Admin UI”

The Admin UI is a runtime-generated reference application built on SvelteKit (@kozou/svelte-ui). It is not scaffolded code you edit and maintain — it reads the Schema Context at startup and renders itself from your tables and views.

What it gives you:

  • CRUD forms for every table — create, read, update, and delete, with validation derived from NOT NULL, CHECK constraints, and column data types.
  • Widget-aware inputs. Each form field picks an input from the column’s @widget tag (or a heuristic when none is given). An enum-backed column renders a dropdown; a free-text column renders a text input.
  • Relation pickers. A foreign key renders as a searchable combobox, and detail views resolve the related row to a readable label instead of showing a raw id.
  • Read-only views. A CREATE VIEW shows up as a browsable, read-only list — search, sort, and pagination, but no create, edit, or delete controls.

Start it with kozou dev, which brings up the Admin UI (and the MCP HTTP server alongside it). By default the UI is served at http://localhost:3333.

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

MCP context

Section titled “MCP context”

The same Schema Context is exposed to AI agents through @kozou/mcp, an MCP server. An agent such as Claude Code or Claude Desktop connects and reads the meaning of your tables, views, and business concepts — pulling in the descriptions and @ai notes you wrote in COMMENT.

The server exposes seven tools, all of them read-only context providers:

  • list_tables — table names with their descriptions.
  • describe_table — the full schema and COMMENT for one table.
  • list_views — view names with their purpose.
  • describe_view — a view’s columns, purpose, and the tables it depends on.
  • list_concepts — the business concepts (modeled as views).
  • get_concept_context — the related tables and a suggested query path for one concept.
  • describe_functions — the signatures of any functions exposed as RPC actions, with their @ai and @policy advisory notes.

These tools provide context only. None of them generate SQL, execute SQL, or write data, so an agent connected to Kozou can read what the schema means but cannot mutate your data through this surface.

You can run the server over either transport:

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

The HTTP transport listens on port 3334 by default.

REST API

Section titled “REST API”

Since v1.0, Kozou’s own REST layer — @kozou/api — is the default backend. kozou dev serves it in-process from the same Schema Context, with no separate container, and the Admin UI talks to it through a pluggable data adapter. (An external PostgREST remains a deliberate opt-out you select with kozou dev --adapter postgrest.)

@kozou/api generates:

  • CRUD endpoints for each table (list, get, create, update, delete) and read-only endpoints for each view, querying PostgreSQL directly.
  • An OpenAPI 3.1 document at /openapi.json whose descriptions are drawn from your COMMENT text — table, view, and column comments become schema descriptions, so the API document carries the same semantics you wrote in the database.
  • RPC actions (since v1.4) — a Postgres function tagged @expose: rpc in its COMMENT becomes a callable POST /rpc/<schema>.<fn>, so the verbs of your schema are compiled too, not just the nouns. See RPC actions.

Its REST wire format and OpenAPI are a stable contract as of v1.0 (the RPC actions wire as of v1.6). See The @kozou/api REST layer for the full endpoint surface and security boundary.

One schema, three surfaces

Section titled “One schema, three surfaces”

Three surfaces, one source:

  • The Admin UI is the human surface — a generated SvelteKit app for browsing and editing rows (and running exposed functions from an “Actions” page), served at http://localhost:3333.
  • MCP context is the AI surface — read-only tools (including describe_functions for the exposed RPC actions) that teach an agent what your schema means, over stdio or HTTP (default port 3334).
  • The REST API is the programmatic surface — the in-house @kozou/api by default since v1.0, with PostgREST as an opt-out.

You maintain one thing: the schema and its COMMENT text. Kozou keeps all three surfaces derived from it, which is why they never drift. To shape what those surfaces show, write it in the database — see COMMENT conventions.