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 six 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.

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”

In v0.1, Kozou wires up PostgREST as a side-by-side container to serve the REST API. PostgREST stays a separate service next to Kozou — it is not bundled inside the Kozou runtime image — and the Admin UI talks to it through a pluggable data adapter.

The v0.2 line adds an EXPERIMENTAL in-house REST layer, @kozou/api, that builds its endpoints from the same Schema Context. It is opt-in and gated behind a flag:

Terminal window
kozou dev --adapter api

When enabled, @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.

@kozou/api is experimental. In the v0.2 line, PostgREST remains the default; @kozou/api is an opt-in path you select with kozou dev --adapter api. Treat it as a preview, not a stable contract.

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, served at http://localhost:3333.
  • MCP context is the AI surface — six read-only tools that teach an agent what your schema means, over stdio or HTTP (default port 3334).
  • The REST API is the programmatic surface — PostgREST in v0.1, with the experimental in-house @kozou/api available in the v0.2 line.

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.