@emseepea/create-database-schema-server 0.0.0

package/README.md

@@ -0,0 +1,105 @@
+# `@emseepea/create-database-schema-server`
+
+This directory is both the maintained example and the template source for its
+public npm initializer.
+
+## Use This Template
+
+Use this template when PostgreSQL already defines the internal data contract
+and you want generated TypeScript and runtime validation to follow it. It shows
+reads and writes through a view, with one stored procedure as a secondary
+integration example.
+
+Choose the [API-backed server](../api-backed-server/README.md) for an HTTP API,
+or the [multi-instance PostgreSQL server](../multi-instance-postgres-server/README.md)
+when shared state across interchangeable processes is the main lesson.
+[Compare all templates](https://emseepea.github.io/emseepea/examples/).
+
+## Create a Project
+
+```sh
+npm init @emseepea/database-schema-server -- my-server
+```
+
+The command creates a standalone app in a new `my-server` directory and sets
+`private: true` in its `package.json` so the app cannot be published by
+accident. It includes the database schema, checked-in generated code, Docker
+Compose setup, lint checks, ordinary tests, and semantic tests.
+
+<!-- generated-project-readme -->
+
+## Database Schema Server
+
+PostgreSQL is authoritative for the internal contract. Kanel and Kanel Zod
+generate TypeScript and runtime validators from the committed schema. Normal
+builds and starts use the checked-in generated files, so they do not need a
+live database.
+
+The MCP schemas are small, public, and described for an AI. Database rows are
+validated with generated schemas at the integration boundary. New compatible
+database values, such as a new pea type, pass through without an application
+release.
+
+## Run Locally
+
+You need Node.js 22 or 24 and Docker Compose.
+
+```sh
+npm install
+npm run dev
+```
+
+Stop the server with Control-C. Remove the local database and volume when you
+no longer need them:
+
+```sh
+docker compose down --volumes
+```
+
+## Change the Database Contract
+
+Edit `schema.sql`, recreate the development database, then regenerate the
+checked-in files:
+
+```sh
+docker compose down --volumes
+docker compose up --detach --wait database
+npm run generate
+```
+
+Review the generated diff before committing it. CI recreates PostgreSQL from
+`schema.sql`, regenerates the files, and fails if they differ.
+
+Views are the preferred application boundary because they support ordinary
+reads and writes while insulating tools from storage tables. The
+`summarize-pea-catalog` procedure is included only for databases where an
+existing operation must remain procedural.
+
+## Tools
+
+- `list-pea-varieties` reads a bounded, fixed projection from the catalogue view.
+- `add-pea-variety` writes through the updatable catalogue view.
+- `summarize-pea-catalog` calls the secondary stored procedure.
+
+The tools never accept SQL, operators, table names, sort expressions, or
+destinations from the caller. PostgreSQL statements have a 1.5 second timeout,
+the connection pool is bounded, and provider failures return a generic error.
+
+## Check This Project
+
+Run generation, lint, build, and ordinary integration tests without spending
+model tokens:
+
+```sh
+npm run generate:check
+npm run lint
+npm test
+```
+
+Run the more expensive AI test separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Windy Road Technology Pty. Limited
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/initializer-dist/create.mjs

@@ -0,0 +1,44 @@
+#!/usr/bin/env node
+
+import { cp, mkdir, mkdtemp, readFile, readdir, rm, writeFile } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+
+const [destination, ...extra] = process.argv.slice(2);
+if (extra.length > 0 || !destination || !/^[a-z0-9][a-z0-9._-]*$/.test(destination)) {
+  throw new Error("Provide one simple lowercase destination name, such as my-server");
+}
+
+const target = resolve(destination);
+if (basename(target) !== destination) throw new Error("The destination must not contain a path");
+const staging = await mkdtemp(join(dirname(target), ".emseepea-create-"));
+
+try {
+  await copyContents(new URL("./template/", import.meta.url), staging);
+  const manifestPath = resolve(staging, "package.json");
+  const manifest = JSON.parse(await readFile(manifestPath, "utf8"));
+  await writeFile(manifestPath, `${JSON.stringify({ ...manifest, name: destination }, null, 2)}\n`);
+  await mkdir(target);
+  try {
+    await copyContents(staging, target);
+  } catch (error) {
+    await rm(target, { recursive: true, force: true });
+    throw error;
+  }
+} catch (error) {
+  if (["EEXIST", "ENOTEMPTY"].includes(error.code)) {
+    throw new Error(`The destination already exists: ${destination}`);
+  }
+  throw error;
+} finally {
+  await rm(staging, { recursive: true, force: true });
+}
+
+async function copyContents(source, destination) {
+  for (const entry of await readdir(source)) {
+    const from = source instanceof URL ? new URL(entry, source) : join(source, entry);
+    await cp(from, join(destination, entry), { recursive: true, errorOnExist: true, force: false });
+  }
+}
+
+console.log(`Created ${destination}.`);
+console.log(`Next: cd ${destination}; npm install; npm test; npm start`);

package/initializer-dist/template/README.md

@@ -0,0 +1,75 @@
+# Database Schema Server
+
+PostgreSQL is authoritative for the internal contract. Kanel and Kanel Zod
+generate TypeScript and runtime validators from the committed schema. Normal
+builds and starts use the checked-in generated files, so they do not need a
+live database.
+
+The MCP schemas are small, public, and described for an AI. Database rows are
+validated with generated schemas at the integration boundary. New compatible
+database values, such as a new pea type, pass through without an application
+release.
+
+## Run Locally
+
+You need Node.js 22 or 24 and Docker Compose.
+
+```sh
+npm install
+npm run dev
+```
+
+Stop the server with Control-C. Remove the local database and volume when you
+no longer need them:
+
+```sh
+docker compose down --volumes
+```
+
+## Change the Database Contract
+
+Edit `schema.sql`, recreate the development database, then regenerate the
+checked-in files:
+
+```sh
+docker compose down --volumes
+docker compose up --detach --wait database
+npm run generate
+```
+
+Review the generated diff before committing it. CI recreates PostgreSQL from
+`schema.sql`, regenerates the files, and fails if they differ.
+
+Views are the preferred application boundary because they support ordinary
+reads and writes while insulating tools from storage tables. The
+`summarize-pea-catalog` procedure is included only for databases where an
+existing operation must remain procedural.
+
+## Tools
+
+- `list-pea-varieties` reads a bounded, fixed projection from the catalogue view.
+- `add-pea-variety` writes through the updatable catalogue view.
+- `summarize-pea-catalog` calls the secondary stored procedure.
+
+The tools never accept SQL, operators, table names, sort expressions, or
+destinations from the caller. PostgreSQL statements have a 1.5 second timeout,
+the connection pool is bounded, and provider failures return a generic error.
+
+## Check This Project
+
+Run generation, lint, build, and ordinary integration tests without spending
+model tokens:
+
+```sh
+npm run generate:check
+npm run lint
+npm test
+```
+
+Run the more expensive AI test separately:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/compose.yaml

@@ -0,0 +1,20 @@
+services:
+  database:
+    image: postgres:18.6-alpine3.23
+    environment:
+      POSTGRES_DB: emseepea
+      POSTGRES_PASSWORD: emseepea
+      POSTGRES_USER: emseepea
+    healthcheck:
+      test: ["CMD-SHELL", "pg_isready -U emseepea -d emseepea"]
+      interval: 1s
+      timeout: 3s
+      retries: 20
+    ports:
+      - "127.0.0.1:${POSTGRES_PORT:-5432}:5432"
+    volumes:
+      - postgres-data:/var/lib/postgresql
+      - ./schema.sql:/docker-entrypoint-initdb.d/001-schema.sql:ro
+
+volumes:
+  postgres-data:

package/initializer-dist/template/eval/meaning.test.mjs

@@ -0,0 +1,48 @@
+import test from "node:test";
+import {
+  assertResponseContains,
+  assertResponseMeaning,
+  assertToolCalls,
+  createConversation,
+} from "@emseepea/testing/semantic";
+
+const trialDatabaseUrls = [1, 2, 3].map((trial) => {
+  const value = process.env[`DATABASE_URL_TRIAL_${trial}`];
+  if (!value) throw new Error(`DATABASE_URL_TRIAL_${trial} is required`);
+  return value;
+});
+
+test("finds and adds pea varieties through natural requests", async (t) => {
+  const chat = await createConversation(t, {
+    server: new URL("../dist/server.js", import.meta.url),
+    environment: (trial) => ({ DATABASE_URL: trialDatabaseUrls[trial - 1] }),
+  });
+
+  // One read and one write show both important selection decisions. Procedure
+  // selection stays in ordinary tests because a third model turn adds cost but
+  // does not teach a meaningfully different MCP interaction.
+  const fastest = await chat.send("Which snap pea variety matures fastest?");
+  assertToolCalls(fastest, [{
+    name: "list-pea-varieties",
+    arguments: { pea_type: "snap" },
+  }]);
+  await assertResponseMeaning(fastest, {
+    expected: "Sugar Ann is the fastest listed snap pea variety and matures in 56 days.",
+  });
+
+  const added = await chat.send(
+    "Add Golden Sweet as a climbing mangetout pea that matures in 70 days. " +
+    "Use exactly mangetout as its pea type. Its notes are: Purple flowers and flat edible pods.",
+  );
+  assertToolCalls(added, [{
+    name: "add-pea-variety",
+    arguments: {
+      name: "Golden Sweet",
+      pea_type: "mangetout",
+      growth_habit: "climbing",
+      days_to_maturity: 70,
+      notes: "Purple flowers and flat edible pods.",
+    },
+  }]);
+  assertResponseContains(added, ["Golden Sweet", "mangetout", "70"]);
+});

package/initializer-dist/template/kanel.config.cjs

@@ -0,0 +1,18 @@
+const { makePgTsGenerator } = require("kanel");
+const { generateZodSchemas } = require("kanel-zod");
+
+module.exports = {
+  connection: process.env.DATABASE_URL ?? "postgres://emseepea:emseepea@127.0.0.1:5432/emseepea",
+  schemaNames: ["public"],
+  resolveViews: true,
+  outputPath: "./src/generated",
+  preDeleteOutputFolder: true,
+  typescriptConfig: {
+    enumStyle: "literal-union",
+    tsModuleFormat: "explicit-esm",
+  },
+  generators: [makePgTsGenerator({
+    filter: ({ kind }) => kind !== "procedure",
+    preRenderHooks: [generateZodSchemas],
+  })],
+};

package/initializer-dist/template/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server with internal validation generated from a PostgreSQL schema.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "generate": "kanel --config kanel.config.cjs",
+    "generate:check": "node test/with-postgres.mjs node scripts/check-generated.mjs",
+    "start": "node dist/server.js",
+    "dev": "docker compose up --detach --wait database && npm run generate && npm run build && npm start",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-postgres.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-postgres.mjs emseepea-test eval",
+    "lint": "oxlint src test eval scripts kanel.config.cjs"
+  },
+  "devDependencies": {
+    "kanel": "4.0.4",
+    "kanel-zod": "4.0.1",
+    "@emseepea/testing": "0.5.2",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "@types/pg": "8.23.1",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.3.3",
+    "pg": "8.23.0",
+    "zod": "4.4.3"
+  }
+}

package/initializer-dist/template/schema.sql

@@ -0,0 +1,46 @@
+CREATE TYPE pea_catalog_summary AS (
+  pea_type text,
+  variety_count integer,
+  fastest_days_to_maturity integer
+);
+
+CREATE TABLE pea_varieties (
+  name text PRIMARY KEY,
+  pea_type text NOT NULL,
+  growth_habit text NOT NULL,
+  days_to_maturity integer NOT NULL CHECK (days_to_maturity > 0),
+  notes text NOT NULL DEFAULT ''
+);
+
+CREATE VIEW pea_variety_catalog AS
+SELECT name, pea_type, growth_habit, days_to_maturity, notes
+FROM pea_varieties;
+
+CREATE PROCEDURE summarize_pea_catalog(
+  IN selected_pea_type text,
+  INOUT summary pea_catalog_summary
+)
+LANGUAGE plpgsql
+AS $$
+BEGIN
+  SELECT
+    COALESCE(selected_pea_type, 'all'),
+    COUNT(*)::integer,
+    MIN(days_to_maturity)::integer
+  INTO summary.pea_type, summary.variety_count, summary.fastest_days_to_maturity
+  FROM pea_variety_catalog
+  WHERE selected_pea_type IS NULL OR pea_type = selected_pea_type;
+END;
+$$;
+
+INSERT INTO pea_variety_catalog
+  (name, pea_type, growth_habit, days_to_maturity, notes)
+VALUES
+  ('Green Arrow', 'shelling', 'climbing', 68, 'Long pods with sweet peas.'),
+  ('Sugar Ann', 'snap', 'bush', 56, 'Compact plants with edible pods.'),
+  ('Oregon Sugar Pod II', 'snow', 'bush', 65, 'Flat edible pods.');
+
+COMMENT ON VIEW pea_variety_catalog IS
+  'Stable read and write boundary for the pea variety catalogue.';
+COMMENT ON TYPE pea_catalog_summary IS
+  'Summary returned by the secondary stored-procedure example.';

package/initializer-dist/template/scripts/check-generated.mjs

@@ -0,0 +1,22 @@
+import assert from "node:assert/strict";
+import { readFile, readdir } from "node:fs/promises";
+
+import { processDatabase } from "kanel";
+import config from "../kanel.config.cjs";
+
+const generated = new URL("../src/generated/", import.meta.url);
+const before = await snapshot(generated);
+assert.ok(Object.keys(before).length > 0, "checked-in generated files are missing");
+await processDatabase(config);
+assert.deepEqual(await snapshot(generated), before, "database-generated files are stale");
+
+async function snapshot(directory, prefix = "") {
+  const result = {};
+  for (const entry of await readdir(directory, { withFileTypes: true })) {
+    const path = new URL(`${entry.name}${entry.isDirectory() ? "/" : ""}`, directory);
+    const name = `${prefix}${entry.name}`;
+    if (entry.isDirectory()) Object.assign(result, await snapshot(path, `${name}/`));
+    else result[name] = await readFile(path, "utf8");
+  }
+  return result;
+}

package/initializer-dist/template/src/app.ts

@@ -0,0 +1,53 @@
+import { createEmseepea, discoverCapabilities } from "@emseepea/server";
+import { Pool } from "pg";
+import { z } from "zod";
+
+export interface DatabaseSchemaExampleOptions {
+  readonly databaseUrl: string;
+}
+
+export async function createDatabaseSchemaExample(options: DatabaseSchemaExampleOptions) {
+  const databaseUrl = z.string().url().refine(
+    (value) => ["postgres:", "postgresql:"].includes(new URL(value).protocol),
+    "databaseUrl must use PostgreSQL",
+  ).parse(options.databaseUrl);
+  let database: Pool | undefined = new Pool({
+    connectionString: databaseUrl,
+    connectionTimeoutMillis: 2_000,
+    idleTimeoutMillis: 10_000,
+    max: 4,
+    query_timeout: 2_000,
+    statement_timeout: 1_500,
+  });
+  database.on("error", () => {
+    // Readiness and tool calls report provider failure without exposing details.
+  });
+
+  const app = createEmseepea({
+    name: "emseepea-database-schema-server",
+    version: "0.0.0",
+    instructions: "Read, add, and summarize pea varieties in a database-backed catalogue.",
+    readiness: async ({ signal }) => {
+      if (!database) return false;
+      try {
+        signal.throwIfAborted();
+        await database.query("SELECT 1 FROM pea_variety_catalog LIMIT 1");
+        signal.throwIfAborted();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    readinessTimeoutMs: 2_500,
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), {
+      database: () => database,
+    }),
+  });
+  const closeProvider = async () => {
+    const activeDatabase = database;
+    database = undefined;
+    await activeDatabase?.end();
+  };
+  app.addHook("onClose", closeProvider);
+  return { app, closeProvider };
+}

package/initializer-dist/template/src/capabilities/context.ts

@@ -0,0 +1,5 @@
+import type { Pool } from "pg";
+
+export interface DatabaseSchemaContext {
+  readonly database: () => Pool | undefined;
+}

package/initializer-dist/template/src/capabilities/tool.add-pea-variety.ts

@@ -0,0 +1,37 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { peaVarietyCatalog } from "../generated/public/PeaVarietyCatalog.mjs";
+import { varietySchema } from "../pea-variety.js";
+import type { DatabaseSchemaContext } from "./context.js";
+
+const inputSchema = varietySchema;
+const outputSchema = varietySchema;
+
+export default ((context) => defineTool({
+  name: "add-pea-variety",
+  access: "public",
+  description: "Add one pea variety to the catalogue.",
+  inputSchema,
+  outputSchema,
+  async handler(variety, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Variety provider unavailable");
+    signal.throwIfAborted();
+    const result = await database.query({
+      text: `
+        INSERT INTO pea_variety_catalog
+          (name, pea_type, growth_habit, days_to_maturity, notes)
+        VALUES ($1, $2, $3, $4, $5)
+        RETURNING name, pea_type, growth_habit, days_to_maturity, notes
+      `,
+      values: [
+        variety.name,
+        variety.pea_type,
+        variety.growth_habit,
+        variety.days_to_maturity,
+        variety.notes,
+      ],
+    });
+    signal.throwIfAborted();
+    return { data: peaVarietyCatalog.parse(result.rows[0]) };
+  },
+})) satisfies CapabilityModuleFactory<DatabaseSchemaContext>;

package/initializer-dist/template/src/capabilities/tool.list-pea-varieties.ts

@@ -0,0 +1,39 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import { peaVarietyCatalog } from "../generated/public/PeaVarietyCatalog.mjs";
+import { varietySchema } from "../pea-variety.js";
+import type { DatabaseSchemaContext } from "./context.js";
+
+const inputSchema = z.object({
+  pea_type: z.string().trim().min(1).max(40).optional()
+    .describe("Optional pea type to match exactly. Omit it to list every type."),
+});
+const outputSchema = z.object({
+  varieties: z.array(varietySchema).max(20).describe("Matching pea varieties ordered by name."),
+});
+
+export default ((context) => defineTool({
+  name: "list-pea-varieties",
+  access: "public",
+  description: "List pea varieties, optionally filtered by pea type.",
+  inputSchema,
+  outputSchema,
+  async handler({ pea_type }, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Variety provider unavailable");
+    signal.throwIfAborted();
+    const result = await database.query({
+      text: `
+        SELECT name, pea_type, growth_habit, days_to_maturity, notes
+        FROM pea_variety_catalog
+        WHERE ($1::text IS NULL OR pea_type = $1)
+        ORDER BY name
+        LIMIT 20
+      `,
+      values: [pea_type ?? null],
+    });
+    signal.throwIfAborted();
+    const varieties = z.array(peaVarietyCatalog).max(20).parse(result.rows);
+    return { data: { varieties } };
+  },
+})) satisfies CapabilityModuleFactory<DatabaseSchemaContext>;

package/initializer-dist/template/src/capabilities/tool.summarize-pea-catalog.ts

@@ -0,0 +1,44 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import { peaCatalogSummary } from "../generated/public/PeaCatalogSummary.mjs";
+import type { DatabaseSchemaContext } from "./context.js";
+
+const inputSchema = z.object({
+  pea_type: z.string().trim().min(1).max(40).optional()
+    .describe("Optional pea type to summarize. Omit it to summarize the whole catalogue."),
+});
+const outputSchema = z.object({
+  pea_type: z.string().nullable().describe("Requested pea type, or all for an unfiltered summary."),
+  variety_count: z.number().int().nonnegative().describe("Number of matching pea varieties."),
+  fastest_days_to_maturity: z.number().int().positive().nullable()
+    .describe("Fewest days to maturity among matching varieties, or null when none match."),
+});
+
+export default ((context) => defineTool({
+  name: "summarize-pea-catalog",
+  access: "public",
+  description: "Summarize the pea catalogue.",
+  inputSchema,
+  outputSchema,
+  async handler({ pea_type }, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Variety provider unavailable");
+    signal.throwIfAborted();
+    const client = await database.connect();
+    try {
+      const called = await client.query({
+        text: "CALL summarize_pea_catalog($1, NULL)",
+        values: [pea_type ?? null],
+      });
+      signal.throwIfAborted();
+      const expanded = await client.query({
+        text: "SELECT ($1::pea_catalog_summary).*",
+        values: [called.rows[0]?.summary],
+      });
+      signal.throwIfAborted();
+      return { data: outputSchema.parse(peaCatalogSummary.parse(expanded.rows[0])) };
+    } finally {
+      client.release();
+    }
+  },
+})) satisfies CapabilityModuleFactory<DatabaseSchemaContext>;

package/initializer-dist/template/src/generated/public/PeaCatalogSummary.mts

@@ -0,0 +1,19 @@
+import { z } from 'zod';
+
+/**
+ * Represents the compositeType public.pea_catalog_summary
+ * Summary returned by the secondary stored-procedure example.
+ */
+export default interface PeaCatalogSummary {
+  pea_type: string | null;
+
+  variety_count: number | null;
+
+  fastest_days_to_maturity: number | null;
+}
+
+export const peaCatalogSummary = z.object({
+  pea_type: z.string().nullable(),
+  variety_count: z.number().nullable(),
+  fastest_days_to_maturity: z.number().nullable(),
+}) as unknown as z.Schema<PeaCatalogSummary>;

package/initializer-dist/template/src/generated/public/PeaVarieties.mts

@@ -0,0 +1,70 @@
+import { z } from 'zod';
+
+/** Identifier type for public.pea_varieties */
+export type PeaVarietiesName = string & { __brand: 'public.pea_varieties' };
+
+/** Represents the table public.pea_varieties */
+export default interface PeaVarieties {
+  name: PeaVarietiesName;
+
+  pea_type: string;
+
+  growth_habit: string;
+
+  days_to_maturity: number;
+
+  notes: string;
+}
+
+/** Represents the initializer for the table public.pea_varieties */
+export interface PeaVarietiesInitializer {
+  name: PeaVarietiesName;
+
+  pea_type: string;
+
+  growth_habit: string;
+
+  days_to_maturity: number;
+
+  /** Default value: ''::text */
+  notes?: string;
+}
+
+/** Represents the mutator for the table public.pea_varieties */
+export interface PeaVarietiesMutator {
+  name?: PeaVarietiesName;
+
+  pea_type?: string;
+
+  growth_habit?: string;
+
+  days_to_maturity?: number;
+
+  notes?: string;
+}
+
+export const peaVarietiesName = z.string() as unknown as z.Schema<PeaVarietiesName>;
+
+export const peaVarieties = z.object({
+  name: peaVarietiesName,
+  pea_type: z.string(),
+  growth_habit: z.string(),
+  days_to_maturity: z.number(),
+  notes: z.string(),
+}) as unknown as z.Schema<PeaVarieties>;
+
+export const peaVarietiesInitializer = z.object({
+  name: peaVarietiesName,
+  pea_type: z.string(),
+  growth_habit: z.string(),
+  days_to_maturity: z.number(),
+  notes: z.string().optional(),
+}) as unknown as z.Schema<PeaVarietiesInitializer>;
+
+export const peaVarietiesMutator = z.object({
+  name: peaVarietiesName.optional(),
+  pea_type: z.string().optional(),
+  growth_habit: z.string().optional(),
+  days_to_maturity: z.number().optional(),
+  notes: z.string().optional(),
+}) as unknown as z.Schema<PeaVarietiesMutator>;

package/initializer-dist/template/src/generated/public/PeaVarietyCatalog.mts

@@ -0,0 +1,26 @@
+import { peaVarietiesName, type PeaVarietiesName } from './PeaVarieties.mjs';
+import { z } from 'zod';
+
+/**
+ * Represents the view public.pea_variety_catalog
+ * Stable read and write boundary for the pea variety catalogue.
+ */
+export default interface PeaVarietyCatalog {
+  name: PeaVarietiesName;
+
+  pea_type: string;
+
+  growth_habit: string;
+
+  days_to_maturity: number;
+
+  notes: string;
+}
+
+export const peaVarietyCatalog = z.object({
+  name: peaVarietiesName,
+  pea_type: z.string(),
+  growth_habit: z.string(),
+  days_to_maturity: z.number(),
+  notes: z.string(),
+}) as unknown as z.Schema<PeaVarietyCatalog>;

package/initializer-dist/template/src/pea-variety.ts

@@ -0,0 +1,9 @@
+import { z } from "zod";
+
+export const varietySchema = z.object({
+  name: z.string().min(1).max(100).describe("Name of the pea variety."),
+  pea_type: z.string().min(1).max(40).describe("Type of pea, such as shelling, snap, or snow."),
+  growth_habit: z.string().min(1).max(40).describe("How the plant grows, such as bush or climbing."),
+  days_to_maturity: z.number().int().positive().describe("Typical number of days from sowing to harvest."),
+  notes: z.string().max(500).describe("Short growing or eating notes."),
+});

package/initializer-dist/template/src/server.ts

@@ -0,0 +1,21 @@
+import { serveEmseepea } from "@emseepea/server";
+import { createDatabaseSchemaExample } from "./app.js";
+
+const databaseUrl = process.env.DATABASE_URL ?? "postgres://emseepea:emseepea@127.0.0.1:5432/emseepea";
+const { app } = await createDatabaseSchemaExample({ databaseUrl });
+const running = await serveEmseepea(app, {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
+
+console.log(`Em See Pea database-schema-server example listening at ${running.url}`);
+
+let shuttingDown = false;
+async function shutdown(): Promise<void> {
+  if (shuttingDown) return;
+  shuttingDown = true;
+  await running.close();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/test/server.test.mjs

@@ -0,0 +1,210 @@
+import assert from "node:assert/strict";
+import test, { after } from "node:test";
+
+import { startMcpServer } from "@emseepea/testing";
+import { Pool } from "pg";
+
+const databaseUrl = process.env.DATABASE_URL;
+assert.ok(databaseUrl, "DATABASE_URL is required");
+const database = new Pool({ connectionString: databaseUrl, max: 2 });
+after(() => database.end());
+const requestMeta = {
+  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+  "io.modelcontextprotocol/clientInfo": { name: "database-schema-test", version: "0.0.0" },
+  "io.modelcontextprotocol/clientCapabilities": {},
+};
+
+test("reads and writes through the view and summarizes through the procedure", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { DATABASE_URL: databaseUrl },
+  });
+  const client = await running.connect();
+
+  const listed = await client.callTool({
+    name: "list-pea-varieties",
+    arguments: { pea_type: "snap" },
+  });
+  assert.equal(listed.isError, false);
+  assert.deepEqual(listed.structuredContent, {
+    varieties: [{
+      name: "Sugar Ann",
+      pea_type: "snap",
+      growth_habit: "bush",
+      days_to_maturity: 56,
+      notes: "Compact plants with edible pods.",
+    }],
+  });
+
+  const newVariety = {
+    name: "Golden Sweet",
+    pea_type: "mangetout",
+    growth_habit: "climbing",
+    days_to_maturity: 70,
+    notes: "Purple flowers and flat edible pods.",
+  };
+  const added = await client.callTool({ name: "add-pea-variety", arguments: newVariety });
+  assert.equal(added.isError, false);
+  assert.deepEqual(added.structuredContent, newVariety);
+
+  const passedThrough = await client.callTool({
+    name: "list-pea-varieties",
+    arguments: { pea_type: "mangetout" },
+  });
+  assert.deepEqual(passedThrough.structuredContent, { varieties: [newVariety] });
+
+  const summary = await client.callTool({
+    name: "summarize-pea-catalog",
+    arguments: { pea_type: "snap" },
+  });
+  assert.equal(summary.isError, false);
+  assert.deepEqual(summary.structuredContent, {
+    pea_type: "snap",
+    variety_count: 1,
+    fastest_days_to_maturity: 56,
+  });
+
+  const injected = await client.callTool({
+    name: "list-pea-varieties",
+    arguments: { pea_type: "snap' OR true --" },
+  });
+  assert.deepEqual(injected.structuredContent, { varieties: [] });
+  assert.doesNotMatch(
+    `${running.output().stdout}\n${running.output().stderr}`,
+    new RegExp(escapeRegExp(databaseUrl)),
+  );
+});
+
+test("the catalogue read has a fixed 20-row boundary", async (t) => {
+  await database.query(`
+    INSERT INTO pea_variety_catalog
+      (name, pea_type, growth_habit, days_to_maturity, notes)
+    SELECT 'Boundary ' || LPAD(number::text, 2, '0'), 'bounded', 'bush', 60, ''
+    FROM generate_series(1, 25) AS number
+  `);
+  t.after(() => database.query("DELETE FROM pea_variety_catalog WHERE pea_type = 'bounded'"));
+
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { DATABASE_URL: databaseUrl },
+  });
+  const client = await running.connect();
+  const result = await client.callTool({
+    name: "list-pea-varieties",
+    arguments: { pea_type: "bounded" },
+  });
+
+  assert.equal(result.isError, false);
+  assert.equal(result.structuredContent.varieties.length, 20);
+});
+
+test("advertises bounded and described public schemas", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { DATABASE_URL: databaseUrl },
+  });
+  const client = await running.connect();
+  const { tools } = await client.listTools();
+
+  assert.deepEqual(tools.map(({ name }) => name), [
+    "add-pea-variety",
+    "list-pea-varieties",
+    "summarize-pea-catalog",
+  ]);
+  const add = tools[0];
+  const list = tools[1];
+  const summary = tools[2];
+  for (const property of ["name", "pea_type", "growth_habit", "days_to_maturity", "notes"]) {
+    assert.ok(add.inputSchema.properties[property].description, `${property} input needs a description`);
+    assert.ok(add.outputSchema.properties[property].description, `${property} output needs a description`);
+  }
+  assert.deepEqual(Object.keys(list.inputSchema.properties), ["pea_type"]);
+  assert.ok(list.inputSchema.properties.pea_type.description);
+  assert.ok(list.outputSchema.properties.varieties.description);
+  assert.ok(summary.inputSchema.properties.pea_type.description);
+  assert.ok(summary.outputSchema.properties.variety_count.description);
+  assert.ok(summary.outputSchema.properties.fastest_days_to_maturity.description);
+});
+
+test("generated validation blocks an invalid database row at the tool boundary", async (t) => {
+  const schema = `invalid_output_${process.pid}`;
+  await database.query(`CREATE SCHEMA ${schema}`);
+  try {
+    await database.query(`
+      CREATE VIEW ${schema}.pea_variety_catalog AS
+      SELECT name, pea_type, growth_habit, days_to_maturity::text, notes
+      FROM public.pea_variety_catalog
+    `);
+    const invalidUrl = new URL(databaseUrl);
+    invalidUrl.searchParams.set("options", `-c search_path=${schema}`);
+    const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+      environment: { DATABASE_URL: invalidUrl.href },
+    });
+    assertGenericToolFailure(await rawCall(running.url, "list-pea-varieties", {}));
+  } finally {
+    await database.query(`DROP SCHEMA ${schema} CASCADE`);
+  }
+});
+
+test("an unavailable database fails without exposing provider details", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { DATABASE_URL: "postgres://emseepea:emseepea@127.0.0.1:1/emseepea" },
+  });
+  const result = await rawCall(running.url, "list-pea-varieties", {});
+  assertGenericToolFailure(result);
+  const readiness = await fetch(new URL("/readyz", running.url));
+  assert.equal(readiness.status, 503);
+  assert.equal(await readiness.text(), "not ready\n");
+  assert.doesNotMatch(
+    `${running.output().stdout}\n${running.output().stderr}`,
+    /postgres:\/\/emseepea:emseepea@127\.0\.0\.1:1\/emseepea/,
+  );
+});
+
+test("blocked database work stops at the statement timeout", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { DATABASE_URL: databaseUrl },
+  });
+  const blocker = await database.connect();
+  t.after(async () => {
+    await blocker.query("ROLLBACK").catch(() => {});
+    blocker.release();
+  });
+  await blocker.query("BEGIN");
+  await blocker.query("LOCK TABLE pea_varieties IN ACCESS EXCLUSIVE MODE");
+
+  const started = Date.now();
+  const result = await rawCall(running.url, "list-pea-varieties", {});
+  assert.ok(Date.now() - started < 3_000, "blocked query exceeded its bounded timeout");
+  assertGenericToolFailure(result);
+});
+
+async function rawCall(url, name, arguments_) {
+  const response = await fetch(url, {
+    method: "POST",
+    headers: {
+      Accept: "application/json, text/event-stream",
+      "Content-Type": "application/json",
+      "MCP-Protocol-Version": "2026-07-28",
+      "Mcp-Method": "tools/call",
+      "Mcp-Name": name,
+    },
+    body: JSON.stringify({
+      jsonrpc: "2.0",
+      id: crypto.randomUUID(),
+      method: "tools/call",
+      params: { name, arguments: arguments_, _meta: requestMeta },
+    }),
+  });
+  return { response, body: await response.json() };
+}
+
+function assertGenericToolFailure(result) {
+  assert.equal(result.response.status, 200);
+  assert.equal(result.body.result.content[0].text, "Tool execution failed");
+  assert.doesNotMatch(
+    JSON.stringify({ ...result.body.result, _meta: undefined }),
+    /postgres|database|connection|ECONNREFUSED|provider/i,
+  );
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}

package/initializer-dist/template/test/with-postgres.mjs

@@ -0,0 +1,75 @@
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { basename } from "node:path";
+
+const [command, ...args] = process.argv.slice(2);
+if (!command) throw new Error("A test command is required");
+
+const project = `emseepea-database-schema-test-${process.pid}`;
+const port = await availablePort();
+const composeEnvironment = { ...process.env, POSTGRES_PORT: String(port) };
+const compose = (...composeArgs) => run(
+  "docker",
+  ["compose", "--project-name", project, ...composeArgs],
+  composeEnvironment,
+  120_000,
+);
+
+let exitCode = 1;
+try {
+  if (await compose("up", "--detach", "--wait", "database") !== 0) {
+    throw new Error("Could not start the PostgreSQL test service");
+  }
+  const environment = {
+    ...process.env,
+    DATABASE_URL: `postgres://emseepea:emseepea@127.0.0.1:${port}/emseepea`,
+  };
+  if (basename(command) === "emseepea-test") {
+    for (let trial = 1; trial <= 3; trial += 1) {
+      const name = `emseepea_trial_${trial}`;
+      if (await compose("exec", "-T", "database", "createdb", "-U", "emseepea", name) !== 0
+        || await compose(
+          "exec", "-T", "database", "psql", "-U", "emseepea", "-d", name,
+          "-v", "ON_ERROR_STOP=1", "-f", "/docker-entrypoint-initdb.d/001-schema.sql",
+        ) !== 0) {
+        throw new Error(`Could not prepare PostgreSQL semantic trial ${trial}`);
+      }
+      environment[`DATABASE_URL_TRIAL_${trial}`] =
+        `postgres://emseepea:emseepea@127.0.0.1:${port}/${name}`;
+    }
+  }
+  exitCode = await run(command, args, environment);
+} finally {
+  await compose("down", "--volumes");
+}
+process.exitCode = exitCode;
+
+function run(executable, executableArgs, env, timeout = 600_000) {
+  return new Promise((resolve, reject) => {
+    const child = spawn(executable, executableArgs, { env, stdio: "inherit" });
+    const timer = setTimeout(() => child.kill("SIGKILL"), timeout);
+    child.once("error", (error) => {
+      clearTimeout(timer);
+      reject(error);
+    });
+    child.once("close", (code) => {
+      clearTimeout(timer);
+      resolve(code ?? 1);
+    });
+  });
+}
+
+function availablePort() {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      server.close((error) => {
+        if (error) reject(error);
+        else if (address && typeof address === "object") resolve(address.port);
+        else reject(new Error("Could not choose a PostgreSQL test port"));
+      });
+    });
+  });
+}

package/initializer-dist/template/tsconfig.json

@@ -0,0 +1,13 @@
+{
+  "compilerOptions": {
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "outDir": "dist",
+    "rootDir": "src",
+    "strict": true,
+    "target": "ES2023",
+    "types": ["node"],
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src/**/*.ts", "src/**/*.mts"]
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@emseepea/create-database-schema-server",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server with internal validation generated from a PostgreSQL schema.",
+  "license": "MIT",
+  "type": "module",
+  "starterDependencies": [
+    "@emseepea/server",
+    "pg",
+    "zod"
+  ],
+  "scripts": {
+    "build": "npm run build:example && npm run build:initializer",
+    "build:example": "tsc -p tsconfig.json",
+    "build:initializer": "node ../../scripts/build-initializer.mjs",
+    "generate": "kanel --config kanel.config.cjs",
+    "generate:check": "node test/with-postgres.mjs node scripts/check-generated.mjs",
+    "start": "node dist/server.js",
+    "dev": "docker compose up --detach --wait database && npm run generate && npm run build && npm start",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-postgres.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-postgres.mjs emseepea-test eval",
+    "lint": "oxlint src test eval scripts kanel.config.cjs",
+    "prepack": "npm run build:initializer"
+  },
+  "devDependencies": {
+    "@emseepea/server": "0.3.3",
+    "pg": "8.23.0",
+    "zod": "4.4.3",
+    "kanel": "4.0.4",
+    "kanel-zod": "4.0.1",
+    "@emseepea/testing": "0.5.3",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "@types/pg": "8.23.1",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/emseepea/emseepea.git",
+    "directory": "examples/database-schema-server"
+  },
+  "homepage": "https://emseepea.github.io/emseepea/examples/",
+  "bugs": "https://github.com/emseepea/emseepea/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "create-database-schema-server": "./initializer-dist/create.mjs"
+  },
+  "files": [
+    "initializer-dist"
+  ]
+}