@emseepea/create-mongodb-backed-server 0.0.0

package/README.md

@@ -0,0 +1,109 @@
+# `@emseepea/create-mongodb-backed-server`
+
+This directory is both the maintained example and the template source for its
+public npm initializer.
+
+## Use This Template
+
+Use this template when MongoDB stores the data and your collections use either
+database-enforced schemas or schemaless storage. It shows both approaches in
+one project, using the official driver directly without an object-document
+mapper.
+
+Choose the [database-schema server](../database-schema-server/README.md) when
+PostgreSQL is authoritative, or the [API-backed server](../api-backed-server/README.md)
+for an HTTP service. [Compare all templates](https://emseepea.github.io/emseepea/examples/).
+
+## Create a Project
+
+```sh
+npm init @emseepea/mongodb-backed-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 Docker Compose, lint checks, ordinary tests, and semantic
+tests.
+
+<!-- generated-project-readme -->
+
+## MongoDB-Backed Server
+
+`pea_varieties` is schema-enforced. `src/pea-document.ts` contains its only
+stored-document schema. MongoDB applies that exact object as its collection
+validator, Ajv checks data in the application, and `FromSchema` infers its
+TypeScript type.
+
+`pea_observations` is intentionally schemaless in MongoDB.
+`src/pea-observation-document.ts` contains its only application schema. Ajv
+validates every observation before a write and after a read, while `FromSchema`
+infers its TypeScript type. This protects the MCP boundary without pretending
+that MongoDB will reject writes made outside the application.
+
+Choose the approach collection by collection. Do not copy either JSON Schema
+into a TypeScript interface or a second field validator.
+
+The public MCP schemas remain small and described for an AI. A compatible new
+string value, such as another pea type, passes through without a translation
+map or application release. MongoDB `_id` values stay internal.
+
+## 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
+```
+
+For a managed MongoDB deployment, set `MONGODB_URL`, build, apply the collection
+schema once, then start the server:
+
+```sh
+npm run build
+npm run db:setup
+npm start
+```
+
+Use the database name in the connection URL, such as
+`mongodb://127.0.0.1:27017/emseepea`. When it is omitted, the example uses
+`emseepea`.
+
+Protect `MONGODB_URL` as a secret. Do not put it in source control or send it to
+an MCP client.
+
+## Tools
+
+- `add-pea-variety` validates and inserts one document.
+- `list-pea-varieties` reads a fixed projection of at most 20 varieties.
+- `record-pea-observation` validates and records one dated observation.
+- `list-pea-observations` reads a fixed projection of at most 20 observations.
+
+The tools never accept database operators, collection names, sort documents,
+or destinations. The pool and database operations are bounded, and provider
+failures return a generic error.
+
+## Check This Project
+
+Run lint, build, and ordinary database integration tests without spending model
+tokens:
+
+```sh
+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,80 @@
+# MongoDB-Backed Server
+
+`pea_varieties` is schema-enforced. `src/pea-document.ts` contains its only
+stored-document schema. MongoDB applies that exact object as its collection
+validator, Ajv checks data in the application, and `FromSchema` infers its
+TypeScript type.
+
+`pea_observations` is intentionally schemaless in MongoDB.
+`src/pea-observation-document.ts` contains its only application schema. Ajv
+validates every observation before a write and after a read, while `FromSchema`
+infers its TypeScript type. This protects the MCP boundary without pretending
+that MongoDB will reject writes made outside the application.
+
+Choose the approach collection by collection. Do not copy either JSON Schema
+into a TypeScript interface or a second field validator.
+
+The public MCP schemas remain small and described for an AI. A compatible new
+string value, such as another pea type, passes through without a translation
+map or application release. MongoDB `_id` values stay internal.
+
+## 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
+```
+
+For a managed MongoDB deployment, set `MONGODB_URL`, build, apply the collection
+schema once, then start the server:
+
+```sh
+npm run build
+npm run db:setup
+npm start
+```
+
+Use the database name in the connection URL, such as
+`mongodb://127.0.0.1:27017/emseepea`. When it is omitted, the example uses
+`emseepea`.
+
+Protect `MONGODB_URL` as a secret. Do not put it in source control or send it to
+an MCP client.
+
+## Tools
+
+- `add-pea-variety` validates and inserts one document.
+- `list-pea-varieties` reads a fixed projection of at most 20 varieties.
+- `record-pea-observation` validates and records one dated observation.
+- `list-pea-observations` reads a fixed projection of at most 20 observations.
+
+The tools never accept database operators, collection names, sort documents,
+or destinations. The pool and database operations are bounded, and provider
+failures return a generic error.
+
+## Check This Project
+
+Run lint, build, and ordinary database integration tests without spending model
+tokens:
+
+```sh
+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,16 @@
+services:
+  database:
+    image: mongo:8.0.15-noble
+    command: ["mongod", "--quiet"]
+    healthcheck:
+      test: ["CMD", "mongosh", "--quiet", "--eval", "db.adminCommand('ping').ok"]
+      interval: 1s
+      timeout: 3s
+      retries: 30
+    ports:
+      - "127.0.0.1:${MONGODB_PORT:-27017}:27017"
+    volumes:
+      - mongodb-data:/data/db
+
+volumes:
+  mongodb-data:

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

@@ -0,0 +1,75 @@
+import test from "node:test";
+import {
+  assertResponseContains,
+  assertResponseMeaning,
+  assertToolCalls,
+  createConversation,
+} from "@emseepea/testing/semantic";
+
+const trialUris = [1, 2, 3].map((trial) => {
+  const value = process.env[`MONGODB_URL_TRIAL_${trial}`];
+  if (!value) throw new Error(`MONGODB_URL_TRIAL_${trial} is required`);
+  return value;
+});
+
+test("finds and adds MongoDB-backed pea varieties through natural requests", async (t) => {
+  const chat = await createConversation(t, {
+    server: new URL("../dist/server.js", import.meta.url),
+    environment: (trial) => ({ MONGODB_URL: trialUris[trial - 1] }),
+  });
+
+  // The read and write turns cover both public decisions. Storage validation
+  // remains in deterministic tests because asking a model cannot prove it.
+  const fastest = await chat.send("Among the saved snap pea varieties, which 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"]);
+
+  // Two further turns cover the separate observation task. Database enforcement
+  // stays in ordinary tests because a model conversation cannot prove it.
+  const recorded = await chat.send(
+    "Record that Golden Sweet was flowering in the west trellis on 2026-09-08. " +
+    "The notes are: First flower opened.",
+  );
+  assertToolCalls(recorded, [{
+    name: "record-pea-observation",
+    arguments: {
+      variety_name: "Golden Sweet",
+      observed_on: "2026-09-08",
+      location: "west trellis",
+      growth_stage: "flowering",
+      notes: "First flower opened.",
+    },
+  }]);
+
+  const observations = await chat.send("What have I observed about Golden Sweet?");
+  assertToolCalls(observations, [{
+    name: "list-pea-observations",
+    arguments: { variety_name: "Golden Sweet" },
+  }]);
+  await assertResponseMeaning(observations, {
+    expected:
+      "Golden Sweet was flowering in the west trellis on 8 September 2026, " +
+      "and the first flower had opened.",
+  });
+});

package/initializer-dist/template/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server with schema-enforced and schemaless MongoDB collections.",
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "db:setup": "node dist/setup-database.js",
+    "start": "node dist/server.js",
+    "dev": "docker compose up --detach --wait database && npm run build && npm run db:setup && npm start",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-mongodb.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-mongodb.mjs emseepea-test eval",
+    "lint": "oxlint src test eval"
+  },
+  "devDependencies": {
+    "@emseepea/testing": "0.5.2",
+    "@types/node": "24.13.3",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22.13.0"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.3.3",
+    "ajv": "8.20.0",
+    "json-schema-to-ts": "3.1.1",
+    "mongodb": "7.6.0",
+    "zod": "4.4.3"
+  }
+}

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

@@ -0,0 +1,49 @@
+import { createEmseepea, discoverCapabilities } from "@emseepea/server";
+import type { Collection, Db } from "mongodb";
+import { z } from "zod";
+import { createDatabase } from "./database.js";
+import type { PeaObservationDocument } from "./pea-observation-document.js";
+import type { PeaDocument } from "./pea-document.js";
+
+export interface MongoExampleOptions { readonly uri: string }
+
+export async function createMongoExample({ uri }: MongoExampleOptions) {
+  const parsedUri = z.string().url().refine(
+    (value) => ["mongodb:", "mongodb+srv:"].includes(new URL(value).protocol),
+    "uri must use MongoDB",
+  ).parse(uri);
+  const connected = createDatabase(parsedUri);
+  let database: Db | undefined = connected.database;
+  let varieties: Collection<PeaDocument> | undefined = connected.varieties;
+  let observations: Collection<PeaObservationDocument> | undefined = connected.observations;
+  const app = createEmseepea({
+    name: "emseepea-mongodb-backed-server",
+    version: "0.0.0",
+    instructions: "Read and add pea varieties, and record and review pea observations.",
+    readiness: async ({ signal }) => {
+      if (!database) return false;
+      try {
+        signal.throwIfAborted();
+        await database.command({ ping: 1 }, { timeoutMS: 1_500 });
+        signal.throwIfAborted();
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    readinessTimeoutMs: 2_500,
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), {
+      database: () => database,
+      observations: () => observations,
+      varieties: () => varieties,
+    }),
+  });
+  const closeProvider = async () => {
+    observations = undefined;
+    varieties = undefined;
+    database = undefined;
+    await connected.client.close();
+  };
+  app.addHook("onClose", closeProvider);
+  return { app, closeProvider };
+}

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

@@ -0,0 +1,25 @@
+import { randomUUID } from "node:crypto";
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { parsePeaDocument } from "../pea-document.js";
+import { varietySchema } from "../pea-variety.js";
+import type { MongoContext } from "../database.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 collection = context.varieties();
+    if (!collection) throw new Error("Variety provider unavailable");
+    signal.throwIfAborted();
+    const document = parsePeaDocument({ _id: randomUUID(), ...variety });
+    await collection.insertOne(document, { maxTimeMS: 1_500 });
+    signal.throwIfAborted();
+    return { data: variety };
+  },
+})) satisfies CapabilityModuleFactory<MongoContext>;

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

@@ -0,0 +1,46 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import type { MongoContext } from "../database.js";
+import { parsePeaObservationDocument } from "../pea-observation-document.js";
+import { observationSchema } from "../pea-observation.js";
+
+const inputSchema = z.object({
+  variety_name: z.string().trim().min(1).max(100).optional()
+    .describe("Optional variety name to match exactly. Omit it to list every variety."),
+});
+const outputSchema = z.object({
+  observations: z.array(observationSchema).max(20)
+    .describe("Up to 20 recent pea observations, newest first."),
+});
+
+export default ((context) => defineTool({
+  name: "list-pea-observations",
+  access: "public",
+  description: "List up to 20 recent observations of pea plants.",
+  inputSchema,
+  outputSchema,
+  async handler({ variety_name }, { signal }) {
+    const collection = context.observations();
+    if (!collection) throw new Error("Observation provider unavailable");
+    signal.throwIfAborted();
+    const rows = await collection.find(
+      variety_name ? { variety_name } : {},
+      {
+        projection: {
+          _id: 1,
+          variety_name: 1,
+          observed_on: 1,
+          location: 1,
+          growth_stage: 1,
+          notes: 1,
+        },
+      },
+    ).sort({ observed_on: -1, variety_name: 1 }).limit(20).maxTimeMS(1_500).toArray();
+    signal.throwIfAborted();
+    const observations = rows.map((row) => {
+      const { _id: _internalId, ...observation } = parsePeaObservationDocument(row);
+      return observation;
+    });
+    return { data: { observations } };
+  },
+})) satisfies CapabilityModuleFactory<MongoContext>;

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

@@ -0,0 +1,36 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import { parsePeaDocument } from "../pea-document.js";
+import { varietySchema } from "../pea-variety.js";
+import type { MongoContext } from "../database.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("Up to 20 matching pea varieties ordered by name."),
+});
+
+export default ((context) => defineTool({
+  name: "list-pea-varieties",
+  access: "public",
+  description: "List up to 20 pea varieties, optionally filtered by pea type.",
+  inputSchema,
+  outputSchema,
+  async handler({ pea_type }, { signal }) {
+    const collection = context.varieties();
+    if (!collection) throw new Error("Variety provider unavailable");
+    signal.throwIfAborted();
+    const rows = await collection.find(
+      pea_type ? { pea_type } : {},
+      { projection: { _id: 1, name: 1, pea_type: 1, growth_habit: 1, days_to_maturity: 1, notes: 1 } },
+    ).sort({ name: 1 }).limit(20).maxTimeMS(1_500).toArray();
+    signal.throwIfAborted();
+    const varieties = rows.map((row) => {
+      const { _id: _internalId, ...variety } = parsePeaDocument(row);
+      return variety;
+    });
+    return { data: { varieties } };
+  },
+})) satisfies CapabilityModuleFactory<MongoContext>;

package/initializer-dist/template/src/capabilities/tool.record-pea-observation.ts

@@ -0,0 +1,25 @@
+import { randomUUID } from "node:crypto";
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import type { MongoContext } from "../database.js";
+import { parsePeaObservationDocument } from "../pea-observation-document.js";
+import { observationSchema } from "../pea-observation.js";
+
+const inputSchema = observationSchema;
+const outputSchema = observationSchema;
+
+export default ((context) => defineTool({
+  name: "record-pea-observation",
+  access: "public",
+  description: "Record one dated observation of a pea plant.",
+  inputSchema,
+  outputSchema,
+  async handler(observation, { signal }) {
+    const collection = context.observations();
+    if (!collection) throw new Error("Observation provider unavailable");
+    signal.throwIfAborted();
+    const document = parsePeaObservationDocument({ _id: randomUUID(), ...observation });
+    await collection.insertOne(document, { maxTimeMS: 1_500 });
+    signal.throwIfAborted();
+    return { data: observation };
+  },
+})) satisfies CapabilityModuleFactory<MongoContext>;

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

@@ -0,0 +1,29 @@
+import { MongoClient, type Collection, type Db } from "mongodb";
+import type { PeaObservationDocument } from "./pea-observation-document.js";
+import type { PeaDocument } from "./pea-document.js";
+
+export const varietyCollectionName = "pea_varieties";
+export const observationCollectionName = "pea_observations";
+export const databaseName = "emseepea";
+
+export function createDatabase(uri: string) {
+  const client = new MongoClient(uri, {
+    connectTimeoutMS: 2_000,
+    maxPoolSize: 4,
+    serverSelectionTimeoutMS: 2_000,
+  });
+  const selectedDatabaseName = decodeURIComponent(new URL(uri).pathname.slice(1)) || databaseName;
+  const database = client.db(selectedDatabaseName);
+  return {
+    client,
+    database,
+    varieties: database.collection<PeaDocument>(varietyCollectionName),
+    observations: database.collection<PeaObservationDocument>(observationCollectionName),
+  };
+}
+
+export interface MongoContext {
+  readonly varieties: () => Collection<PeaDocument> | undefined;
+  readonly observations: () => Collection<PeaObservationDocument> | undefined;
+  readonly database: () => Db | undefined;
+}

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

@@ -0,0 +1,25 @@
+import { Ajv } from "ajv";
+import type { FromSchema } from "json-schema-to-ts";
+
+export const peaDocumentSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["_id", "name", "pea_type", "growth_habit", "days_to_maturity", "notes"],
+  properties: {
+    _id: { type: "string", minLength: 1, maxLength: 100 },
+    name: { type: "string", minLength: 1, maxLength: 100 },
+    pea_type: { type: "string", minLength: 1, maxLength: 40 },
+    growth_habit: { type: "string", minLength: 1, maxLength: 40 },
+    days_to_maturity: { type: "number", multipleOf: 1, minimum: 1, maximum: 365 },
+    notes: { type: "string", maxLength: 500 },
+  },
+} as const;
+
+export type PeaDocument = FromSchema<typeof peaDocumentSchema>;
+
+const validate = new Ajv({ strict: true }).compile<PeaDocument>(peaDocumentSchema);
+
+export function parsePeaDocument(value: unknown): PeaDocument {
+  if (!validate(value)) throw new Error("Invalid pea document");
+  return value;
+}

package/initializer-dist/template/src/pea-observation-document.ts

@@ -0,0 +1,26 @@
+import { Ajv } from "ajv";
+import type { FromSchema } from "json-schema-to-ts";
+
+export const peaObservationDocumentSchema = {
+  type: "object",
+  additionalProperties: false,
+  required: ["_id", "variety_name", "observed_on", "location", "growth_stage", "notes"],
+  properties: {
+    _id: { type: "string", minLength: 1, maxLength: 100 },
+    variety_name: { type: "string", minLength: 1, maxLength: 100 },
+    observed_on: { type: "string", pattern: "^[0-9]{4}-[0-9]{2}-[0-9]{2}$" },
+    location: { type: "string", minLength: 1, maxLength: 100 },
+    growth_stage: { type: "string", minLength: 1, maxLength: 40 },
+    notes: { type: "string", maxLength: 500 },
+  },
+} as const;
+
+export type PeaObservationDocument = FromSchema<typeof peaObservationDocumentSchema>;
+
+const validate = new Ajv({ strict: true })
+  .compile<PeaObservationDocument>(peaObservationDocumentSchema);
+
+export function parsePeaObservationDocument(value: unknown): PeaObservationDocument {
+  if (!validate(value)) throw new Error("Invalid pea observation document");
+  return value;
+}

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

@@ -0,0 +1,10 @@
+import { z } from "zod";
+
+export const observationSchema = z.object({
+  variety_name: z.string().min(1).max(100).describe("Name of the observed pea variety."),
+  observed_on: z.iso.date().describe("Calendar date of the observation in YYYY-MM-DD format."),
+  location: z.string().min(1).max(100).describe("Short human-readable name of the growing location."),
+  growth_stage: z.string().min(1).max(40)
+    .describe("Observed growth stage, such as germinating, flowering, or podding."),
+  notes: z.string().max(500).describe("Short notes about what was observed."),
+});

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

@@ -0,0 +1,10 @@
+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().min(1).max(365)
+    .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 { createMongoExample } from "./app.js";
+
+const uri = process.env.MONGODB_URL ?? "mongodb://127.0.0.1:27017";
+const { app } = await createMongoExample({ uri });
+const running = await serveEmseepea(app, {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
+
+console.log(`Em See Pea MongoDB-backed 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/src/setup-database.ts

@@ -0,0 +1,70 @@
+import { MongoServerError } from "mongodb";
+import {
+  observationCollectionName,
+  varietyCollectionName,
+  createDatabase,
+} from "./database.js";
+import { parsePeaObservationDocument } from "./pea-observation-document.js";
+import { peaDocumentSchema, type PeaDocument } from "./pea-document.js";
+
+const uri = process.env.MONGODB_URL ?? "mongodb://127.0.0.1:27017";
+const { client, database, observations, varieties } = createDatabase(uri);
+
+try {
+  await client.connect();
+  const validator = { $jsonSchema: peaDocumentSchema };
+  try {
+    await database.createCollection(varietyCollectionName, { validator });
+  } catch (error) {
+    if (!(error instanceof MongoServerError) || error.codeName !== "NamespaceExists") throw error;
+    await database.command({ collMod: varietyCollectionName, validator });
+  }
+  try {
+    await database.createCollection(observationCollectionName);
+  } catch (error) {
+    if (!(error instanceof MongoServerError) || error.codeName !== "NamespaceExists") throw error;
+    const [collection] = await database.listCollections(
+      { name: observationCollectionName },
+      { nameOnly: false },
+    ).toArray();
+    if (!collection) throw new Error(`${observationCollectionName} was not found`);
+    if (collection.options?.validator !== undefined) {
+      throw new Error(`${observationCollectionName} must not have a MongoDB validator`);
+    }
+  }
+  const seeds: PeaDocument[] = [
+    {
+      _id: "green-arrow",
+      name: "Green Arrow",
+      pea_type: "shelling",
+      growth_habit: "climbing",
+      days_to_maturity: 68,
+      notes: "Long pods with sweet peas.",
+    },
+    {
+      _id: "sugar-ann",
+      name: "Sugar Ann",
+      pea_type: "snap",
+      growth_habit: "bush",
+      days_to_maturity: 56,
+      notes: "Compact plants with edible pods.",
+    },
+  ];
+  for (const seed of seeds) {
+    await varieties.replaceOne({ _id: seed._id }, seed, { upsert: true });
+  }
+  await observations.replaceOne(
+    { _id: "sugar-ann-flowering" },
+    parsePeaObservationDocument({
+      _id: "sugar-ann-flowering",
+      variety_name: "Sugar Ann",
+      observed_on: "2026-08-30",
+      location: "North bed",
+      growth_stage: "flowering",
+      notes: "First flowers opened.",
+    }),
+    { upsert: true },
+  );
+} finally {
+  await client.close();
+}

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

@@ -0,0 +1,341 @@
+import assert from "node:assert/strict";
+import { spawnSync } from "node:child_process";
+import test, { after } from "node:test";
+
+import { startMcpServer } from "@emseepea/testing";
+import { MongoClient } from "mongodb";
+import { createMongoExample } from "../dist/app.js";
+import {
+  databaseName,
+  observationCollectionName,
+  varietyCollectionName,
+} from "../dist/database.js";
+import {
+  parsePeaObservationDocument,
+  peaObservationDocumentSchema,
+} from "../dist/pea-observation-document.js";
+import { parsePeaDocument, peaDocumentSchema } from "../dist/pea-document.js";
+
+const uri = process.env.MONGODB_URL;
+assert.ok(uri, "MONGODB_URL is required");
+const provider = new MongoClient(uri, { maxPoolSize: 2, serverSelectionTimeoutMS: 2_000 });
+await provider.connect();
+const database = provider.db(databaseName);
+const observations = database.collection(observationCollectionName);
+const varieties = database.collection(varietyCollectionName);
+after(() => provider.close());
+const requestMeta = {
+  "io.modelcontextprotocol/protocolVersion": "2026-07-28",
+  "io.modelcontextprotocol/clientInfo": { name: "mongodb-test", version: "0.0.0" },
+  "io.modelcontextprotocol/clientCapabilities": {},
+};
+
+test("each collection has one application schema and only varieties enforce it in MongoDB", async () => {
+  const [varietyCollection] = await database
+    .listCollections({ name: varietyCollectionName }).toArray();
+  const [observationCollection] = await database
+    .listCollections({ name: observationCollectionName }).toArray();
+  assert.deepEqual(varietyCollection.options.validator, { $jsonSchema: peaDocumentSchema });
+  assert.equal(observationCollection.options.validator, undefined);
+  assert.throws(() => parsePeaDocument({ name: "missing required fields" }));
+  assert.throws(() => parsePeaObservationDocument({ variety_name: "missing required fields" }));
+  await assert.rejects(varieties.insertOne({
+    _id: "invalid-write",
+    name: "Invalid Write",
+    pea_type: "snap",
+    growth_habit: "bush",
+    days_to_maturity: "soon",
+    notes: "MongoDB must reject this.",
+  }));
+
+  const invalidObservation = { _id: "invalid-direct-write", variety_name: "Schemaless" };
+  await observations.insertOne(invalidObservation);
+  assert.deepEqual(await observations.findOne({ _id: invalidObservation._id }), invalidObservation);
+  await observations.deleteOne({ _id: invalidObservation._id });
+  assert.deepEqual(Object.keys(peaObservationDocumentSchema.properties), [
+    "_id", "variety_name", "observed_on", "location", "growth_stage", "notes",
+  ]);
+});
+
+test("setup fails closed when the schemaless collection already has a validator", async () => {
+  await database.command({
+    collMod: observationCollectionName,
+    validator: { $jsonSchema: { bsonType: "object", required: ["unexpected"] } },
+  });
+  try {
+    const rejected = spawnSync(process.execPath, ["dist/setup-database.js"], {
+      encoding: "utf8",
+      env: { ...process.env, MONGODB_URL: uri },
+    });
+    assert.notEqual(rejected.status, 0);
+    assert.match(rejected.stderr, /pea_observations must not have a MongoDB validator/);
+  } finally {
+    await observations.drop();
+    const restored = spawnSync(process.execPath, ["dist/setup-database.js"], {
+      encoding: "utf8",
+      env: { ...process.env, MONGODB_URL: uri },
+    });
+    assert.equal(restored.status, 0, restored.stderr);
+  }
+});
+
+test("reads, writes, and passes through a compatible new value", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: uri },
+  });
+  const client = await running.connect();
+  const snap = await client.callTool({ name: "list-pea-varieties", arguments: { pea_type: "snap" } });
+  assert.deepEqual(snap.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);
+  assert.equal(Object.hasOwn(added.structuredContent, "_id"), false);
+
+  const passedThrough = await client.callTool({
+    name: "list-pea-varieties",
+    arguments: { pea_type: "mangetout" },
+  });
+  assert.deepEqual(passedThrough.structuredContent, { varieties: [newVariety] });
+});
+
+test("records and reads observations while passing through a compatible new value", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: uri },
+  });
+  const client = await running.connect();
+  const newObservation = {
+    variety_name: "Golden Sweet",
+    observed_on: "2026-09-08",
+    location: "West trellis",
+    growth_stage: "tendrilling",
+    notes: "New tendrils reached the support.",
+  };
+  const recorded = await client.callTool({
+    name: "record-pea-observation",
+    arguments: newObservation,
+  });
+  assert.equal(recorded.isError, false);
+  assert.deepEqual(recorded.structuredContent, newObservation);
+  assert.equal(Object.hasOwn(recorded.structuredContent, "_id"), false);
+
+  const listed = await client.callTool({
+    name: "list-pea-observations",
+    arguments: { variety_name: "Golden Sweet" },
+  });
+  assert.deepEqual(listed.structuredContent, { observations: [newObservation] });
+});
+
+test("invalid stored documents never reach public output", async (t) => {
+  await varieties.insertOne({
+    _id: "invalid-read",
+    name: "Invalid Read",
+    pea_type: "test-invalid",
+    growth_habit: "bush",
+    days_to_maturity: "soon",
+    notes: "Inserted only to prove read validation.",
+  }, { bypassDocumentValidation: true });
+  t.after(() => varieties.deleteOne({ _id: "invalid-read" }));
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: uri },
+  });
+  assertGenericToolFailure(await rawCall(running.url, "list-pea-varieties", {
+    pea_type: "test-invalid",
+  }));
+
+  await observations.insertOne({
+    _id: "invalid-observation-read",
+    variety_name: "Invalid Observation",
+    observed_on: "not-a-date",
+    location: "Test bed",
+    growth_stage: "test-invalid",
+    notes: "Inserted only to prove read validation.",
+  });
+  t.after(() => observations.deleteOne({ _id: "invalid-observation-read" }));
+  assertGenericToolFailure(await rawCall(running.url, "list-pea-observations", {
+    variety_name: "Invalid Observation",
+  }));
+});
+
+test("public schemas are described, bounded, and hide database details", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: uri },
+  });
+  const client = await running.connect();
+  const { tools } = await client.listTools();
+  assert.deepEqual(tools.map(({ name }) => name), [
+    "add-pea-variety",
+    "list-pea-observations",
+    "list-pea-varieties",
+    "record-pea-observation",
+  ]);
+  for (const tool of tools) {
+    for (const schema of [tool.inputSchema, tool.outputSchema]) {
+      for (const property of ["_id", "collection", "operator", "sort", "destination"]) {
+        assert.equal(Object.hasOwn(schema.properties, property), false);
+      }
+    }
+  }
+  for (const tool of tools) {
+    for (const schema of [tool.inputSchema, tool.outputSchema]) {
+      for (const property of Object.values(schema.properties)) {
+        assert.ok(property.description || property.type === "array");
+      }
+    }
+  }
+
+  await database.command({ profile: 0 });
+  await database.collection("system.profile").drop().catch(() => {});
+  await database.command({ profile: 2, slowms: 0 });
+  t.after(() => database.command({ profile: 0 }));
+
+  const countBefore = await varieties.countDocuments();
+  const rejected = await rawCall(running.url, "add-pea-variety", {
+    name: "Operator Attempt",
+    pea_type: { $ne: "snap" },
+    growth_habit: "bush",
+    days_to_maturity: 60,
+    notes: "Must not reach MongoDB.",
+  });
+  assert.equal(rejected.response.status, 200);
+  assert.equal(rejected.body.result.isError, true);
+  assert.equal(await varieties.countDocuments(), countBefore);
+
+  const observationCountBefore = await observations.countDocuments();
+  const rejectedObservation = await rawCall(running.url, "record-pea-observation", {
+    variety_name: "Operator Attempt",
+    observed_on: "2026-09-08",
+    location: "Test bed",
+    growth_stage: { $ne: "flowering" },
+    notes: "Must not reach MongoDB.",
+  });
+  assert.equal(rejectedObservation.response.status, 200);
+  assert.equal(rejectedObservation.body.result.isError, true);
+  assert.equal(await observations.countDocuments(), observationCountBefore);
+
+  await database.command({ profile: 0 });
+  const writes = await database.collection("system.profile").find({
+    $or: ["insert", "update", "delete", "findAndModify"].flatMap((command) => [
+      { [`command.${command}`]: varietyCollectionName },
+      { [`command.${command}`]: observationCollectionName },
+    ]),
+  }).toArray();
+  assert.deepEqual(writes, []);
+});
+
+test("both collection reads stay bounded and carry database timeouts", async (t) => {
+  const prefix = `bounded-${process.pid}-`;
+  const varietyDocuments = Array.from({ length: 25 }, (_, index) => ({
+    _id: `${prefix}variety-${index}`,
+    name: `${prefix}${String(index).padStart(2, "0")}`,
+    pea_type: prefix,
+    growth_habit: "bush",
+    days_to_maturity: 60,
+    notes: "Bounded result test.",
+  }));
+  const observationDocuments = Array.from({ length: 25 }, (_, index) => ({
+    _id: `${prefix}observation-${index}`,
+    variety_name: prefix,
+    observed_on: `2026-09-${String((index % 9) + 1).padStart(2, "0")}`,
+    location: "Test bed",
+    growth_stage: `stage-${index}`,
+    notes: "Bounded result test.",
+  }));
+  await varieties.insertMany(varietyDocuments);
+  await observations.insertMany(observationDocuments);
+  t.after(async () => {
+    await varieties.deleteMany({ _id: { $in: varietyDocuments.map(({ _id }) => _id) } });
+    await observations.deleteMany({ _id: { $in: observationDocuments.map(({ _id }) => _id) } });
+  });
+
+  await database.command({ profile: 0 });
+  await database.collection("system.profile").drop().catch(() => {});
+  await database.command({ profile: 2, slowms: 0 });
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: uri },
+  });
+  const client = await running.connect();
+  try {
+    const varietyResult = await client.callTool({
+      name: "list-pea-varieties",
+      arguments: { pea_type: prefix },
+    });
+    const observationResult = await client.callTool({
+      name: "list-pea-observations",
+      arguments: { variety_name: prefix },
+    });
+    assert.equal(varietyResult.structuredContent.varieties.length, 20);
+    assert.equal(observationResult.structuredContent.observations.length, 20);
+  } finally {
+    await database.command({ profile: 0 });
+  }
+  const profiled = await database.collection("system.profile").find({
+    "command.find": { $in: [varietyCollectionName, observationCollectionName] },
+  }).toArray();
+  assert.deepEqual(
+    new Map(profiled.map(({ command }) => [command.find, command.maxTimeMS])),
+    new Map([[varietyCollectionName, 1_500], [observationCollectionName, 1_500]]),
+  );
+});
+
+test("closing the app cleanly releases both collection paths", async () => {
+  const { app, closeProvider } = await createMongoExample({ uri });
+  await app.ready();
+  await app.close();
+  await closeProvider();
+});
+
+test("an unavailable database fails without connection details", async (t) => {
+  const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url), {
+    environment: { MONGODB_URL: "mongodb://127.0.0.1:1" },
+  });
+  assertGenericToolFailure(await rawCall(running.url, "list-pea-varieties", {}));
+  assertGenericToolFailure(await rawCall(running.url, "list-pea-observations", {}));
+  const readiness = await fetch(new URL("/readyz", running.url));
+  assert.equal(readiness.status, 503);
+  assert.equal(await readiness.text(), "not ready\n");
+});
+
+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 }),
+    /mongodb|database|connection|ECONNREFUSED|provider/i,
+  );
+}

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

@@ -0,0 +1,74 @@
+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-mongodb-test-${process.pid}`;
+const port = await availablePort();
+const composeEnvironment = { ...process.env, MONGODB_PORT: String(port) };
+const databaseUrl = `mongodb://127.0.0.1:${port}`;
+const compose = (...composeArgs) => run(
+  "docker",
+  ["compose", "--project-name", project, ...composeArgs],
+  composeEnvironment,
+  180_000,
+);
+
+let exitCode = 1;
+try {
+  if (await compose("up", "--detach", "--wait", "database") !== 0) {
+    throw new Error("Could not start the MongoDB test service");
+  }
+  const environment = { ...process.env, MONGODB_URL: databaseUrl };
+  if (await run(process.execPath, ["dist/setup-database.js"], environment) !== 0) {
+    throw new Error("Could not prepare the MongoDB test database");
+  }
+  if (basename(command) === "emseepea-test") {
+    for (let trial = 1; trial <= 3; trial += 1) {
+      const trialEnvironment = {
+        ...environment,
+        MONGODB_URL: `${databaseUrl}/emseepea_trial_${trial}`,
+      };
+      if (await run(process.execPath, ["dist/setup-database.js"], trialEnvironment) !== 0) {
+        throw new Error(`Could not prepare MongoDB semantic trial ${trial}`);
+      }
+      environment[`MONGODB_URL_TRIAL_${trial}`] = trialEnvironment.MONGODB_URL;
+    }
+  }
+  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 MongoDB 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"]
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "@emseepea/create-mongodb-backed-server",
+  "version": "0.0.0",
+  "description": "Create an Em See Pea server with schema-enforced and schemaless MongoDB collections.",
+  "license": "MIT",
+  "type": "module",
+  "starterDependencies": [
+    "@emseepea/server",
+    "ajv",
+    "json-schema-to-ts",
+    "mongodb",
+    "zod"
+  ],
+  "scripts": {
+    "build": "npm run build:example && npm run build:initializer",
+    "build:example": "tsc -p tsconfig.json",
+    "build:initializer": "node ../../scripts/build-initializer.mjs",
+    "db:setup": "node dist/setup-database.js",
+    "start": "node dist/server.js",
+    "dev": "docker compose up --detach --wait database && npm run build && npm run db:setup && npm start",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node test/with-mongodb.mjs node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "node test/with-mongodb.mjs emseepea-test eval",
+    "lint": "oxlint src test eval",
+    "prepack": "npm run build:initializer"
+  },
+  "devDependencies": {
+    "@emseepea/server": "0.3.3",
+    "ajv": "8.20.0",
+    "json-schema-to-ts": "3.1.1",
+    "mongodb": "7.6.0",
+    "zod": "4.4.3",
+    "@emseepea/testing": "0.5.3",
+    "@types/node": "24.13.3",
+    "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/mongodb-backed-server"
+  },
+  "homepage": "https://emseepea.github.io/emseepea/examples/",
+  "bugs": "https://github.com/emseepea/emseepea/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "bin": {
+    "create-mongodb-backed-server": "./initializer-dist/create.mjs"
+  },
+  "files": [
+    "initializer-dist"
+  ]
+}