npm - @emseepea/create-multi-instance-postgres-server - Versions diffs - 0.0.1 → 0.0.3 - Mend

@emseepea/create-multi-instance-postgres-server 0.0.1 → 0.0.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (15) hide show

package/README.md CHANGED Viewed

@@ -1,51 +1,54 @@
 # `@emseepea/create-multi-instance-postgres-server`
-This directory is the maintained example and the candidate source for its
+This directory is both the maintained example and the template source for its
 public npm initializer.
 ## Use This Template
-Use this template when independently deployed server instances must share one
-PostgreSQL-backed store and repeated request IDs must resolve to one stored
-result. Choose the [tool server](../tool-server/README.md) when one process and
-in-memory data are enough. [Compare all eight templates](https://emseepea.github.io/emseepea/examples/).
+Use this template when independently deployed server processes must present one
+coherent PostgreSQL-backed application state. It demonstrates interchangeable,
+stateless MCP processes without exposing server identity or routing to users.
-## Create a Project
+Choose the [tool server](../tool-server/README.md) when one process and in-memory
+data are enough. [Compare all eight templates](https://emseepea.github.io/emseepea/examples/).
-Publication is pending exact Quality checks. After publication, use:
+## Create a Project
 ```sh
 npm init @emseepea/multi-instance-postgres-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 its PostgreSQL schema, Docker Compose setup, lint checks,
+ordinary tests, and semantic tests.
 <!-- generated-project-readme -->
 ## Multi-Instance PostgreSQL Server
-Choose this project when separate server instances may receive the same retry
-and must avoid creating duplicate stored work.
+Each server process owns its own Em See Pea app and bounded PostgreSQL
+connection pool. Every process reads and writes the same application state, so
+a client does not need sticky sessions or knowledge of which process served a
+request.
-Each server has its own Em See Pea app and PostgreSQL connection pool. The
-servers coordinate through one shared database without sharing a local
-filesystem.
-The same request ID creates one stored pea harvest report. A retry through any
-instance returns the original report, including the name of the instance that
-created it.
+The example stores one complete pea harvest report per garden bed and harvest
+date. PostgreSQL enforces that meaningful business key. Saving the same report
+again is safe, and saving changed counts replaces the complete desired state.
 ## Run Locally
 You need Node.js 22 or 24 and Docker Compose. Install dependencies, then start
-PostgreSQL and both server instances with one run command:
+PostgreSQL and two independent server processes:
 ```sh
 npm install
 npm run dev
 ```
-The run command applies the database schema, starts two independent server
-processes, and prints both MCP addresses. Stop them with Control-C. Remove the
-database container and local volume when you no longer need them:
+The command applies the database schema and prints both MCP addresses. Stop it
+with Control-C. Remove the database container and local volume when you no
+longer need them:
 ```sh
 docker compose down --volumes
@@ -54,59 +57,56 @@ docker compose down --volumes
 ## Use Managed PostgreSQL
 Set `DATABASE_URL` to a PostgreSQL connection string that every deployed
-instance can reach. Apply the included schema once, then start each instance
-with its own name:
+process can reach. Apply the included schema once, then start each process:
 ```sh
 npm run build
 npm run db:setup
-EMSEEPEA_INSTANCE=instance-a PORT=3000 npm run start:instance
+PORT=3000 npm run start:instance
 ```
-Run the final command for each deployed instance, changing
-`EMSEEPEA_INSTANCE` for each instance. Protect `DATABASE_URL` as a secret. Do
-not put it in source control or send it to an MCP client.
+Use a different port or deployment endpoint for each process. You may set
+`EMSEEPEA_INSTANCE` to add an operator-friendly label to logs. That label never
+enters the MCP tool contract. Protect `DATABASE_URL` as a secret. Do not put it
+in source control or send it to an MCP client.
 ## Tools
-- `create-shared-harvest-report` atomically creates or returns one stored report
-  for a request ID. The result identifies its original server instance.
-- `describe-instance` returns the instance handling the current request and
-  does not query PostgreSQL.
-PostgreSQL enforces one report per request ID with a unique constraint. The
-tool uses one atomic upsert, without an application-side existence check or a
-distributed lock.
+- `save-harvest-report` saves the complete report for one garden bed and
+  harvest date.
+- `get-harvest-report` retrieves that report, or returns `null` when it does not
+  exist.
-If PostgreSQL is unavailable, `/readyz` returns 503 and the report tool returns
-a generic failure. Independent endpoints and `describe-instance` remain
-available for diagnosis.
+If PostgreSQL is unavailable, `/readyz` returns 503 and both tools return a
+generic failure without connection details. Another healthy process connected
+to the shared database continues to serve the same state.
 ## Exact Scope
-- Independently deployable server instances connected to one PostgreSQL database.
+- Independently deployable server processes connected to one PostgreSQL database.
 - One bounded connection pool per process.
-- One atomic database statement per report request.
-- PostgreSQL bounds database statements to 1.5 seconds. The driver cannot
-  cancel an in-flight query from an AbortSignal, so the database timeout is the
+- One database statement per tool call.
+- PostgreSQL bounds statements to 1.5 seconds. The driver cannot cancel an
+  in-flight query from an AbortSignal, so the database timeout is the
   cancellation boundary.
-- No claim that an external service change happens exactly once.
-- No latency, throughput, or unlimited-scale claim.
+- No sticky-session requirement.
+- No claim of exactly-once external effects, latency, throughput, or unlimited
+  scale.
 ## Check This Project
-[Ordinary tests](test/) live in `test/`. The
-[AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately
-in `eval/`. Docker Compose is required because both suites exercise real
-PostgreSQL behavior.
+[Ordinary tests](test/) prove cross-process state, complete-state replacement,
+missing reports, provider failure, readiness, and bounded queries. The
+[semantic test](eval/meaning.test.mjs) checks that an AI naturally selects the
+save and get tools with the right arguments.
-Run the build and two-server MCP checks:
+Run the build and two-process MCP checks:
 ```sh
 npm test
 ```
-Check that Claude understands report replay correctly:
+Run the more expensive AI test separately:
 ```sh
 npm run test:llm

package/initializer-dist/template/README.md CHANGED Viewed

@@ -1,29 +1,27 @@
 # Multi-Instance PostgreSQL Server
-Choose this project when separate server instances may receive the same retry
-and must avoid creating duplicate stored work.
+Each server process owns its own Em See Pea app and bounded PostgreSQL
+connection pool. Every process reads and writes the same application state, so
+a client does not need sticky sessions or knowledge of which process served a
+request.
-Each server has its own Em See Pea app and PostgreSQL connection pool. The
-servers coordinate through one shared database without sharing a local
-filesystem.
-The same request ID creates one stored pea harvest report. A retry through any
-instance returns the original report, including the name of the instance that
-created it.
+The example stores one complete pea harvest report per garden bed and harvest
+date. PostgreSQL enforces that meaningful business key. Saving the same report
+again is safe, and saving changed counts replaces the complete desired state.
 ## Run Locally
 You need Node.js 22 or 24 and Docker Compose. Install dependencies, then start
-PostgreSQL and both server instances with one run command:
+PostgreSQL and two independent server processes:
 ```sh
 npm install
 npm run dev
 ```
-The run command applies the database schema, starts two independent server
-processes, and prints both MCP addresses. Stop them with Control-C. Remove the
-database container and local volume when you no longer need them:
+The command applies the database schema and prints both MCP addresses. Stop it
+with Control-C. Remove the database container and local volume when you no
+longer need them:
 ```sh
 docker compose down --volumes
@@ -32,59 +30,56 @@ docker compose down --volumes
 ## Use Managed PostgreSQL
 Set `DATABASE_URL` to a PostgreSQL connection string that every deployed
-instance can reach. Apply the included schema once, then start each instance
-with its own name:
+process can reach. Apply the included schema once, then start each process:
 ```sh
 npm run build
 npm run db:setup
-EMSEEPEA_INSTANCE=instance-a PORT=3000 npm run start:instance
+PORT=3000 npm run start:instance
 ```
-Run the final command for each deployed instance, changing
-`EMSEEPEA_INSTANCE` for each instance. Protect `DATABASE_URL` as a secret. Do
-not put it in source control or send it to an MCP client.
+Use a different port or deployment endpoint for each process. You may set
+`EMSEEPEA_INSTANCE` to add an operator-friendly label to logs. That label never
+enters the MCP tool contract. Protect `DATABASE_URL` as a secret. Do not put it
+in source control or send it to an MCP client.
 ## Tools
-- `create-shared-harvest-report` atomically creates or returns one stored report
-  for a request ID. The result identifies its original server instance.
-- `describe-instance` returns the instance handling the current request and
-  does not query PostgreSQL.
-PostgreSQL enforces one report per request ID with a unique constraint. The
-tool uses one atomic upsert, without an application-side existence check or a
-distributed lock.
+- `save-harvest-report` saves the complete report for one garden bed and
+  harvest date.
+- `get-harvest-report` retrieves that report, or returns `null` when it does not
+  exist.
-If PostgreSQL is unavailable, `/readyz` returns 503 and the report tool returns
-a generic failure. Independent endpoints and `describe-instance` remain
-available for diagnosis.
+If PostgreSQL is unavailable, `/readyz` returns 503 and both tools return a
+generic failure without connection details. Another healthy process connected
+to the shared database continues to serve the same state.
 ## Exact Scope
-- Independently deployable server instances connected to one PostgreSQL database.
+- Independently deployable server processes connected to one PostgreSQL database.
 - One bounded connection pool per process.
-- One atomic database statement per report request.
-- PostgreSQL bounds database statements to 1.5 seconds. The driver cannot
-  cancel an in-flight query from an AbortSignal, so the database timeout is the
+- One database statement per tool call.
+- PostgreSQL bounds statements to 1.5 seconds. The driver cannot cancel an
+  in-flight query from an AbortSignal, so the database timeout is the
   cancellation boundary.
-- No claim that an external service change happens exactly once.
-- No latency, throughput, or unlimited-scale claim.
+- No sticky-session requirement.
+- No claim of exactly-once external effects, latency, throughput, or unlimited
+  scale.
 ## Check This Project
-[Ordinary tests](test/) live in `test/`. The
-[AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately
-in `eval/`. Docker Compose is required because both suites exercise real
-PostgreSQL behavior.
+[Ordinary tests](test/) prove cross-process state, complete-state replacement,
+missing reports, provider failure, readiness, and bounded queries. The
+[semantic test](eval/meaning.test.mjs) checks that an AI naturally selects the
+save and get tools with the right arguments.
-Run the build and two-server MCP checks:
+Run the build and two-process MCP checks:
 ```sh
 npm test
 ```
-Check that Claude understands report replay correctly:
+Run the more expensive AI test separately:
 ```sh
 npm run test:llm

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

@@ -1,6 +1,5 @@
 import test from "node:test";
 import {
-  assertNoToolCalls,
   assertResponseContains,
   assertResponseMeaning,
   assertToolCalls,
@@ -10,35 +9,44 @@ import {
 const databaseUrl = process.env.DATABASE_URL;
 if (!databaseUrl) throw new Error("DATABASE_URL is required for the PostgreSQL semantic test");
-test("reuses the original shared report across server instances", async (t) => {
+test("saves and retrieves a harvest report without exposing server instances", async (t) => {
   const chat = await createConversation(t, {
     server: new URL("../dist/server.js", import.meta.url),
-    environment: { DATABASE_URL: databaseUrl, EMSEEPEA_INSTANCE: "eval-instance" },
+    environment: { DATABASE_URL: databaseUrl },
   });
-  // Cross-process concurrency stays in ordinary tests because asking the model
-  // to simulate routing would not exercise it. Only the comparison turn needs
-  // a semantic judge; the other turns use exact tool and literal assertions.
-  const created = await chat.send(
-    "Create a shared harvest report with request ID daily-harvest-report.",
+  // Two natural turns cover write and read tool selection at low model cost.
+  // Cross-process behavior stays in ordinary tests because a model cannot
+  // prove which process served a request.
+  const saved = await chat.send(
+    "Save a harvest report for North Bed on 2026-09-08 with 12 shelling pea " +
+    "plants and 8 snap pea plants.",
   );
-  assertToolCalls(created, [
-    { name: "create-shared-harvest-report", arguments: { requestId: "daily-harvest-report" } },
+  assertToolCalls(saved, [
+    {
+      name: "save-harvest-report",
+      arguments: {
+        gardenBed: "North Bed",
+        harvestDate: "2026-09-08",
+        shellingCount: 12,
+        snapCount: 8,
+      },
+    },
   ]);
-  const repeated = await chat.send(
-    "Create that report again with the same request ID. Is its report ID the " +
-    "same as before?",
+  assertResponseContains(saved, ["North Bed", "12", "8", "20"]);
+  const retrieved = await chat.send(
+    "What harvest report do we have for that garden bed and date?",
   );
-  assertToolCalls(repeated, [
-    { name: "create-shared-harvest-report", arguments: { requestId: "daily-harvest-report" } },
+  assertToolCalls(retrieved, [
+    {
+      name: "get-harvest-report",
+      arguments: { gardenBed: "North Bed", harvestDate: "2026-09-08" },
+    },
   ]);
-  await assertResponseMeaning(repeated, {
-    expected: "The repeated request returned the same report ID.",
+  await assertResponseMeaning(retrieved, {
+    expected:
+      "The saved report for North Bed on 2026-09-08 has 12 shelling pea plants, " +
+      "8 snap pea plants, and 20 plants in total.",
   });
-  const creator = await chat.send(
-    "What exact createdByInstance value did those tool results return?",
-  );
-  assertNoToolCalls(creator);
-  assertResponseContains(creator, "eval-instance");
 });

package/initializer-dist/template/package.json CHANGED Viewed

@@ -1,7 +1,7 @@
 {
   "name": "emseepea-starter",
   "version": "0.0.0",
-  "description": "Create multiple Em See Pea server instances backed by PostgreSQL.",
+  "description": "Create interchangeable Em See Pea server instances sharing PostgreSQL state.",
   "license": "MIT",
   "type": "module",
   "scripts": {

package/initializer-dist/template/schema.sql CHANGED Viewed

@@ -1,20 +1,7 @@
-CREATE TABLE IF NOT EXISTS pea_plants (
-  name text PRIMARY KEY,
-  pea_type text NOT NULL CHECK (pea_type IN ('shelling', 'snap'))
-);
-INSERT INTO pea_plants (name, pea_type) VALUES
-  ('Harbour Gem', 'shelling'),
-  ('Highland Snap', 'snap'),
-  ('Meadow Sweet', 'snap'),
-  ('Garden Pearl', 'shelling')
-ON CONFLICT (name) DO NOTHING;
-CREATE TABLE IF NOT EXISTS reports (
-  report_id integer GENERATED ALWAYS AS IDENTITY PRIMARY KEY,
-  idempotency_key text NOT NULL UNIQUE,
-  created_by_instance text NOT NULL,
-  total_plants integer NOT NULL,
-  shelling_count integer NOT NULL,
-  snap_count integer NOT NULL
+CREATE TABLE IF NOT EXISTS harvest_reports (
+  garden_bed text NOT NULL,
+  harvest_date date NOT NULL,
+  shelling_count integer NOT NULL CHECK (shelling_count >= 0),
+  snap_count integer NOT NULL CHECK (snap_count >= 0),
+  PRIMARY KEY (garden_bed, harvest_date)
 );

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

@@ -4,11 +4,9 @@ import { z } from "zod";
 export interface MultiInstanceExampleOptions {
   readonly databaseUrl: string;
-  readonly instanceName: string;
 }
 export async function createMultiInstanceExample(options: MultiInstanceExampleOptions) {
-  const instanceName = z.string().min(1).max(64).parse(options.instanceName);
   const databaseUrl = z.string().url().refine(
     (value) => ["postgres:", "postgresql:"].includes(new URL(value).protocol),
     "databaseUrl must use PostgreSQL",
@@ -28,12 +26,12 @@ export async function createMultiInstanceExample(options: MultiInstanceExampleOp
   const app = createEmseepea({
     name: "emseepea-multi-instance-postgres-server",
     version: "0.0.0",
-    instructions: "Use create-shared-harvest-report for a stored pea harvest report. Reusing a request ID returns the original report.",
+    instructions: "Save and retrieve pea harvest reports by garden bed and harvest date.",
     readiness: async ({ signal }) => {
       if (!database) return false;
       try {
         signal.throwIfAborted();
-        await database.query("SELECT 1 FROM reports LIMIT 1");
+        await database.query("SELECT 1 FROM harvest_reports LIMIT 1");
         signal.throwIfAborted();
         return true;
       } catch {
@@ -43,7 +41,6 @@ export async function createMultiInstanceExample(options: MultiInstanceExampleOp
     readinessTimeoutMs: 2_500,
     ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), {
       database: () => database,
-      instanceName,
     }),
   });
   const closeProvider = async () => {

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

@@ -2,5 +2,4 @@ import type { Pool } from "pg";
 export interface MultiInstanceContext {
   readonly database: () => Pool | undefined;
-  readonly instanceName: string;
 }

package/initializer-dist/template/src/capabilities/tool.get-harvest-report.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import { reportKeySchema, reportSchema } from "../harvest-report.js";
+import type { MultiInstanceContext } from "./context.js";
+const inputSchema = reportKeySchema;
+const outputSchema = z.object({
+  report: reportSchema.nullable().describe(
+    "The saved harvest report, or null when no report exists for that garden bed and date.",
+  ),
+});
+export default ((context) => defineTool({
+  name: "get-harvest-report",
+  access: "public",
+  description: "Get the pea harvest report for a garden bed and date.",
+  inputSchema,
+  outputSchema,
+  async handler({ gardenBed, harvestDate }, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Report provider unavailable");
+    signal.throwIfAborted();
+    const result = await database.query({
+      text: `
+        SELECT
+          garden_bed AS "gardenBed",
+          harvest_date::text AS "harvestDate",
+          shelling_count AS "shellingCount",
+          snap_count AS "snapCount",
+          (shelling_count + snap_count)::integer AS "totalPlants"
+        FROM harvest_reports
+        WHERE garden_bed = $1 AND harvest_date = $2
+      `,
+      values: [gardenBed, harvestDate],
+    });
+    signal.throwIfAborted();
+    return { data: { report: result.rows[0] ?? null } };
+  },
+})) satisfies CapabilityModuleFactory<MultiInstanceContext>;

package/initializer-dist/template/src/capabilities/tool.save-harvest-report.ts ADDED Viewed

@@ -0,0 +1,39 @@
+import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { z } from "zod";
+import { editableReportSchema, reportSchema } from "../harvest-report.js";
+import type { MultiInstanceContext } from "./context.js";
+const inputSchema = editableReportSchema;
+const outputSchema = reportSchema;
+export default ((context) => defineTool({
+  name: "save-harvest-report",
+  access: "public",
+  description: "Save the complete pea harvest report for a garden bed and date.",
+  inputSchema,
+  outputSchema,
+  async handler({ gardenBed, harvestDate, shellingCount, snapCount }, { signal }) {
+    const database = context.database();
+    if (!database) throw new Error("Report provider unavailable");
+    signal.throwIfAborted();
+    const result = await database.query({
+      text: `
+        INSERT INTO harvest_reports (
+          garden_bed, harvest_date, shelling_count, snap_count
+        ) VALUES ($1, $2, $3, $4)
+        ON CONFLICT (garden_bed, harvest_date) DO UPDATE SET
+          shelling_count = EXCLUDED.shelling_count,
+          snap_count = EXCLUDED.snap_count
+        RETURNING
+          garden_bed AS "gardenBed",
+          harvest_date::text AS "harvestDate",
+          shelling_count AS "shellingCount",
+          snap_count AS "snapCount",
+          (shelling_count + snap_count)::integer AS "totalPlants"
+      `,
+      values: [gardenBed, harvestDate, shellingCount, snapCount],
+    });
+    signal.throwIfAborted();
+    return { data: result.rows[0] as z.input<typeof outputSchema> };
+  },
+})) satisfies CapabilityModuleFactory<MultiInstanceContext>;

package/initializer-dist/template/src/harvest-report.ts ADDED Viewed

@@ -0,0 +1,17 @@
+import { z } from "zod";
+export const editableReportSchema = z.object({
+  gardenBed: z.string().min(1).max(80).describe("Garden bed that this harvest report describes."),
+  harvestDate: z.iso.date().describe("Harvest date in YYYY-MM-DD format."),
+  shellingCount: z.number().int().nonnegative().describe("Shelling pea plants harvested."),
+  snapCount: z.number().int().nonnegative().describe("Snap pea plants harvested."),
+});
+export const reportKeySchema = editableReportSchema.pick({
+  gardenBed: true,
+  harvestDate: true,
+});
+export const reportSchema = editableReportSchema.extend({
+  totalPlants: z.number().int().nonnegative().describe("Total pea plants harvested."),
+});

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

@@ -3,7 +3,7 @@ import { createMultiInstanceExample } from "./app.js";
 const instanceName = process.env.EMSEEPEA_INSTANCE ?? `instance-${process.pid}`;
 const databaseUrl = process.env.DATABASE_URL ?? "postgres://emseepea:emseepea@127.0.0.1:5432/emseepea";
-const { app, closeProvider } = await createMultiInstanceExample({ databaseUrl, instanceName });
+const { app, closeProvider } = await createMultiInstanceExample({ databaseUrl });
 const running = await serveEmseepea(app, {
   port: Number.parseInt(process.env.PORT ?? "3000", 10),
 });

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

@@ -16,9 +16,11 @@ const requestMeta = {
   "io.modelcontextprotocol/clientCapabilities": {},
 };
-test("two server processes share one atomic report store", async (t) => {
+test("two interchangeable server processes share one coherent report store", async (t) => {
   const first = await startInstance("instance-a", databaseUrl);
   const second = await startInstance("instance-b", databaseUrl);
+  assert.notEqual(first.child.pid, second.child.pid);
+  assert.notEqual(first.url.href, second.url.href);
   const firstClient = await connect(first.url);
   const secondClient = await connect(second.url);
   t.after(async () => {
@@ -26,56 +28,46 @@ test("two server processes share one atomic report store", async (t) => {
     await Promise.all([stopInstance(first.child), stopInstance(second.child)]);
   });
-  const localRace = await Promise.all(Array.from({ length: 6 }, () => (
-    createReport(firstClient, "single-instance-race")
-  )));
-  assert.equal(new Set(localRace.map(({ reportId }) => reportId)).size, 1);
-  assert.equal(await reportCount("single-instance-race"), 1);
+  const original = {
+    gardenBed: "North Bed",
+    harvestDate: "2026-09-08",
+    shellingCount: 12,
+    snapCount: 8,
+    totalPlants: 20,
+  };
+  assert.deepEqual(await saveReport(firstClient, original), original);
+  assert.deepEqual(await getReport(secondClient, original), { report: original });
-  const [fromFirst, fromSecond] = await Promise.all([
-    createReport(firstClient, "shared-instance-race"),
-    createReport(secondClient, "shared-instance-race"),
-  ]);
-  assert.deepEqual(fromFirst, fromSecond);
-  assert.match(fromFirst.createdByInstance, /^instance-[ab]$/);
-  assert.deepEqual(fromFirst.peaTypeCounts, { shelling: 2, snap: 2 });
-  assert.equal(fromFirst.totalPlants, 4);
-  assert.equal(await reportCount("shared-instance-race"), 1);
-  const replay = await createReport(
-    fromFirst.createdByInstance === "instance-a" ? secondClient : firstClient,
-    "shared-instance-race",
-  );
-  assert.deepEqual(replay, fromFirst);
+  assert.deepEqual(await saveReport(secondClient, original), original);
+  assert.equal(await reportCount(original), 1);
+  const updated = { ...original, shellingCount: 14, totalPlants: 22 };
+  assert.deepEqual(await saveReport(secondClient, updated), updated);
+  assert.deepEqual(await getReport(firstClient, updated), { report: updated });
+  assert.equal(await reportCount(updated), 1);
+  assert.deepEqual(await getReport(secondClient, {
+    gardenBed: "Missing Bed",
+    harvestDate: original.harvestDate,
+  }), { report: null });
-  const raw = await rawCreateReport(first.url, "raw-http-report");
+  const raw = await rawCall(first.url, "get-harvest-report", reportKey(updated));
   assert.equal(raw.response.status, 200);
   assert.equal(raw.body.result.isError, false);
-  assert.equal(raw.body.result.structuredContent.requestId, "raw-http-report");
-  assert.equal(raw.body.result.content[0].text, JSON.stringify(raw.body.result.structuredContent));
-  assert.equal(await reportCount("raw-http-report"), 1);
+  assert.deepEqual(raw.body.result.structuredContent, { report: updated });
+  assert.equal(raw.body.result.content[0].text, JSON.stringify({ report: updated }));
   await closeProvider(first.child);
-  const unavailable = await rawCreateReport(first.url, "must-not-be-created");
-  assert.equal(unavailable.response.status, 200);
-  assert.equal(unavailable.body.result.content[0].text, "Tool execution failed");
-  assert.doesNotMatch(
-    JSON.stringify({ ...unavailable.body.result, _meta: undefined }),
-    /postgres|database|connection|provider/i,
-  );
-  assert.equal(await reportCount("must-not-be-created"), 0);
+  const unavailable = await rawCall(first.url, "get-harvest-report", reportKey(updated));
+  assertGenericToolFailure(unavailable);
+  assert.deepEqual(await getReport(secondClient, updated), { report: updated });
-  const independent = await firstClient.callTool({ name: "describe-instance", arguments: {} });
-  assert.deepEqual(independent.structuredContent, { instanceName: "instance-a" });
   const readiness = await fetch(new URL("/readyz", first.url));
   assert.equal(readiness.status, 503);
   assert.equal(await readiness.text(), "not ready\n");
-  const secondStillWorks = await createReport(secondClient, "provider-b-still-works");
-  assert.equal(secondStillWorks.requestId, "provider-b-still-works");
 });
-test("describes every multi-instance tool property", async (t) => {
+test("describes every public harvest report property", async (t) => {
   const instance = await startInstance("schema-instance", databaseUrl);
   const client = await connect(instance.url);
   t.after(async () => {
@@ -85,43 +77,52 @@ test("describes every multi-instance tool property", async (t) => {
   const listed = await client.listTools();
   assert.deepEqual(listed.tools.map(({ name }) => name), [
-    "create-shared-harvest-report",
-    "describe-instance",
+    "get-harvest-report",
+    "save-harvest-report",
   ]);
-  const reportInput = listed.tools[0].inputSchema.properties;
-  const reportOutput = listed.tools[0].outputSchema.properties;
-  assert.equal(reportInput.requestId.description, "Idempotency key. Reusing it returns the existing report instead of creating another.");
-  assert.equal(reportOutput.reportId.description, "Stored report identifier.");
-  assert.equal(reportOutput.requestId.description, reportInput.requestId.description);
-  assert.equal(reportOutput.createdByInstance.description, "Server instance that originally created the report.");
-  assert.equal(reportOutput.totalPlants.description, "Total pea plants counted in the report.");
-  assert.equal(reportOutput.peaTypeCounts.description, "Plant counts grouped by pea type.");
-  assert.equal(reportOutput.peaTypeCounts.properties.shelling.description, "Shelling pea plants counted in the report.");
-  assert.equal(reportOutput.peaTypeCounts.properties.snap.description, "Snap pea plants counted in the report.");
-  assert.equal(listed.tools[1].outputSchema.properties.instanceName.description, "Server instance that handled this request.");
+  const get = listed.tools[0];
+  const save = listed.tools[1];
+  assert.equal(get.inputSchema.properties.gardenBed.description, "Garden bed that this harvest report describes.");
+  assert.equal(get.inputSchema.properties.harvestDate.description, "Harvest date in YYYY-MM-DD format.");
+  assert.equal(
+    get.outputSchema.properties.report.description,
+    "The saved harvest report, or null when no report exists for that garden bed and date.",
+  );
+  const retrievedReport = get.outputSchema.properties.report.anyOf[0].properties;
+  assert.equal(retrievedReport.gardenBed.description, "Garden bed that this harvest report describes.");
+  assert.equal(retrievedReport.harvestDate.description, "Harvest date in YYYY-MM-DD format.");
+  assert.equal(retrievedReport.shellingCount.description, "Shelling pea plants harvested.");
+  assert.equal(retrievedReport.snapCount.description, "Snap pea plants harvested.");
+  assert.equal(retrievedReport.totalPlants.description, "Total pea plants harvested.");
+  assert.equal(save.inputSchema.properties.gardenBed.description, "Garden bed that this harvest report describes.");
+  assert.equal(save.inputSchema.properties.harvestDate.description, "Harvest date in YYYY-MM-DD format.");
+  assert.equal(save.inputSchema.properties.shellingCount.description, "Shelling pea plants harvested.");
+  assert.equal(save.inputSchema.properties.snapCount.description, "Snap pea plants harvested.");
+  assert.equal(save.outputSchema.properties.gardenBed.description, "Garden bed that this harvest report describes.");
+  assert.equal(save.outputSchema.properties.harvestDate.description, "Harvest date in YYYY-MM-DD format.");
+  assert.equal(save.outputSchema.properties.shellingCount.description, "Shelling pea plants harvested.");
+  assert.equal(save.outputSchema.properties.snapCount.description, "Snap pea plants harvested.");
+  assert.equal(save.outputSchema.properties.totalPlants.description, "Total pea plants harvested.");
 });
-test("an unavailable PostgreSQL provider fails readiness but not independent tools", async (t) => {
+test("an unavailable PostgreSQL provider fails safely", async (t) => {
   const instance = await startInstance(
     "unavailable-before-start",
     "postgres://emseepea:emseepea@127.0.0.1:1/emseepea",
   );
-  const client = await connect(instance.url);
-  t.after(async () => {
-    await client.close();
-    await stopInstance(instance.child);
-  });
+  t.after(() => stopInstance(instance.child));
-  assert.deepEqual(
-    (await client.callTool({ name: "describe-instance", arguments: {} })).structuredContent,
-    { instanceName: "unavailable-before-start" },
-  );
-  const unavailable = await rawCreateReport(instance.url, "provider-never-connected");
-  assert.equal(unavailable.body.result.content[0].text, "Tool execution failed");
-  assert.doesNotMatch(
-    JSON.stringify({ ...unavailable.body.result, _meta: undefined }),
-    /postgres|database|connection|ECONNREFUSED|provider/i,
-  );
+  assertGenericToolFailure(await rawCall(instance.url, "get-harvest-report", {
+    gardenBed: "Unavailable Bed",
+    harvestDate: "2026-09-08",
+  }));
+  assertGenericToolFailure(await rawCall(instance.url, "save-harvest-report", {
+    gardenBed: "Unavailable Bed",
+    harvestDate: "2026-09-08",
+    shellingCount: 1,
+    snapCount: 1,
+  }));
   const readiness = await fetch(new URL("/readyz", instance.url));
   assert.equal(readiness.status, 503);
   assert.equal(await readiness.text(), "not ready\n");
@@ -136,19 +137,27 @@ test("blocked PostgreSQL work finishes at the database timeout", async (t) => {
     await stopInstance(instance.child);
   });
   await blocker.query("BEGIN");
-  await blocker.query("LOCK TABLE reports IN ACCESS EXCLUSIVE MODE");
+  await blocker.query("LOCK TABLE harvest_reports IN ACCESS EXCLUSIVE MODE");
+  const blockedReport = {
+    gardenBed: "Blocked Bed",
+    harvestDate: "2026-09-08",
+    shellingCount: 2,
+    snapCount: 3,
+  };
   const started = Date.now();
-  const [readiness, report] = await Promise.all([
+  const [readiness, save, get] = await Promise.all([
     fetch(new URL("/readyz", instance.url)),
-    rawCreateReport(instance.url, "blocked-report"),
+    rawCall(instance.url, "save-harvest-report", blockedReport),
+    rawCall(instance.url, "get-harvest-report", reportKey(blockedReport)),
   ]);
   assert.ok(Date.now() - started < 3_000, "blocked database work exceeded its bounded timeout");
   assert.equal(readiness.status, 503);
-  assert.equal(report.body.result.content[0].text, "Tool execution failed");
+  assertGenericToolFailure(save);
+  assertGenericToolFailure(get);
   await blocker.query("ROLLBACK");
-  assert.equal(await reportCount("blocked-report"), 0);
+  assert.equal(await reportCount(blockedReport), 0);
 });
 async function startInstance(instanceName, connectionString) {
@@ -172,13 +181,26 @@ async function connect(url) {
   return client;
 }
-async function createReport(client, requestId) {
-  const result = await client.callTool({ name: "create-shared-harvest-report", arguments: { requestId } });
+async function saveReport(client, report) {
+  const result = await client.callTool({
+    name: "save-harvest-report",
+    arguments: { ...reportKey(report), shellingCount: report.shellingCount, snapCount: report.snapCount },
+  });
+  assert.equal(result.isError, false);
+  return result.structuredContent;
+}
+async function getReport(client, report) {
+  const result = await client.callTool({ name: "get-harvest-report", arguments: reportKey(report) });
   assert.equal(result.isError, false);
   return result.structuredContent;
 }
-async function rawCreateReport(url, requestId) {
+function reportKey({ gardenBed, harvestDate }) {
+  return { gardenBed, harvestDate };
+}
+async function rawCall(url, name, arguments_) {
   const response = await fetch(url, {
     method: "POST",
     headers: {
@@ -186,22 +208,31 @@ async function rawCreateReport(url, requestId) {
       "Content-Type": "application/json",
       "MCP-Protocol-Version": "2026-07-28",
       "Mcp-Method": "tools/call",
-      "Mcp-Name": "create-shared-harvest-report",
+      "Mcp-Name": name,
     },
     body: JSON.stringify({
       jsonrpc: "2.0",
       id: crypto.randomUUID(),
       method: "tools/call",
-      params: { name: "create-shared-harvest-report", arguments: { requestId }, _meta: requestMeta },
+      params: { name, arguments: arguments_, _meta: requestMeta },
     }),
   });
   return { response, body: await response.json() };
 }
-async function reportCount(requestId) {
+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,
+  );
+}
+async function reportCount({ gardenBed, harvestDate }) {
   const result = await database.query(
-    "SELECT COUNT(*)::integer AS count FROM reports WHERE idempotency_key = $1",
-    [requestId],
+    "SELECT COUNT(*)::integer AS count FROM harvest_reports WHERE garden_bed = $1 AND harvest_date = $2",
+    [gardenBed, harvestDate],
   );
   return result.rows[0].count;
 }

package/package.json CHANGED Viewed

@@ -1,14 +1,10 @@
 {
   "name": "@emseepea/create-multi-instance-postgres-server",
-  "version": "0.0.1",
-  "description": "Create multiple Em See Pea server instances backed by PostgreSQL.",
+  "version": "0.0.3",
+  "description": "Create interchangeable Em See Pea server instances sharing PostgreSQL state.",
   "license": "MIT",
   "type": "module",
-  "starterDependencies": [
-    "@emseepea/server",
-    "pg",
-    "zod"
-  ],
+  "starterDependencies": ["@emseepea/server", "pg", "zod"],
   "scripts": {
     "build": "npm run build:example && npm run build:initializer",
     "build:example": "tsc -p tsconfig.json",
@@ -26,33 +22,22 @@
   },
   "devDependencies": {
     "@emseepea/server": "0.3.3",
+    "pg": "8.23.0",
+    "zod": "4.4.3",
     "@emseepea/testing": "0.5.2",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "24.13.3",
     "@types/pg": "8.23.1",
-    "oxlint": "1.80.0",
-    "pg": "8.23.0",
     "typescript": "6.0.3",
-    "zod": "4.4.3"
+    "oxlint": "1.80.0"
   },
   "engines": {
     "node": ">=22.13.0"
   },
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emseepea/emseepea.git",
-    "directory": "examples/multi-instance-postgres-server"
-  },
+  "repository": { "type": "git", "url": "git+https://github.com/emseepea/emseepea.git", "directory": "examples/multi-instance-postgres-server" },
   "homepage": "https://emseepea.github.io/emseepea/examples/",
   "bugs": "https://github.com/emseepea/emseepea/issues",
-  "publishConfig": {
-    "access": "public",
-    "provenance": true
-  },
-  "bin": {
-    "create-multi-instance-postgres-server": "./initializer-dist/create.mjs"
-  },
-  "files": [
-    "initializer-dist"
-  ]
+  "publishConfig": { "access": "public", "provenance": true },
+  "bin": { "create-multi-instance-postgres-server": "./initializer-dist/create.mjs" },
+  "files": ["initializer-dist"]
 }

package/initializer-dist/template/src/capabilities/tool.create-shared-harvest-report.ts DELETED Viewed

@@ -1,81 +0,0 @@
-import { defineMappedTool, type CapabilityModuleFactory } from "@emseepea/server";
-import { z } from "zod";
-import type { MultiInstanceContext } from "./context.js";
-const requestIdSchema = z.string().min(3).max(64).regex(/^[a-z0-9][a-z0-9-]*$/)
-  .describe("Idempotency key. Reusing it returns the existing report instead of creating another.");
-const inputSchema = z.object({ requestId: requestIdSchema });
-const outputSchema = z.object({
-  reportId: z.number().int().positive().describe("Stored report identifier."),
-  requestId: requestIdSchema,
-  createdByInstance: z.string().min(1).max(64).describe("Server instance that originally created the report."),
-  totalPlants: z.number().int().nonnegative().describe("Total pea plants counted in the report."),
-  peaTypeCounts: z.object({
-    shelling: z.number().int().nonnegative().describe("Shelling pea plants counted in the report."),
-    snap: z.number().int().nonnegative().describe("Snap pea plants counted in the report."),
-  }).describe("Plant counts grouped by pea type."),
-});
-const backendInputSchema = z.object({ idempotency_key: requestIdSchema });
-const backendOutputSchema = z.object({
-  report_id: z.number().int().positive(),
-  idempotency_key: requestIdSchema,
-  created_by_instance: z.string().min(1).max(64),
-  total_plants: z.number().int().nonnegative(),
-  shelling_count: z.number().int().nonnegative(),
-  snap_count: z.number().int().nonnegative(),
-});
-export default ((context) => defineMappedTool({
-  name: "create-shared-harvest-report",
-  access: "public",
-  description: "Create or return one stored pea harvest report per request ID. The result identifies its original server instance.",
-  inputSchema,
-  outputSchema,
-  backendInputSchema,
-  backendOutputSchema,
-  isAvailable: () => {
-    return context.database() !== undefined;
-  },
-  mapInput: ({ requestId }) => ({ idempotency_key: requestId }),
-  async adapter({ idempotency_key }, { signal }) {
-    const database = context.database();
-    if (!database) throw new Error("Report provider unavailable");
-    signal.throwIfAborted();
-    const result = await database.query({
-      text: `
-        INSERT INTO reports (
-          idempotency_key, created_by_instance, total_plants,
-          shelling_count, snap_count
-        )
-        SELECT
-          $1,
-          $2,
-          COUNT(*)::integer,
-          COUNT(*) FILTER (WHERE pea_type = 'shelling')::integer,
-          COUNT(*) FILTER (WHERE pea_type = 'snap')::integer
-        FROM pea_plants
-        ON CONFLICT (idempotency_key) DO UPDATE
-          SET idempotency_key = EXCLUDED.idempotency_key
-        RETURNING
-          report_id, idempotency_key, created_by_instance, total_plants,
-          shelling_count, snap_count
-      `,
-      values: [idempotency_key, context.instanceName],
-    });
-    signal.throwIfAborted();
-    return result.rows[0] as z.input<typeof backendOutputSchema>;
-  },
-  mapOutput: (report) => {
-    const data = {
-      reportId: report.report_id,
-      requestId: report.idempotency_key,
-      createdByInstance: report.created_by_instance,
-      totalPlants: report.total_plants,
-      peaTypeCounts: {
-        shelling: report.shelling_count,
-        snap: report.snap_count,
-      },
-    };
-    return { data };
-  },
-})) satisfies CapabilityModuleFactory<MultiInstanceContext>;

package/initializer-dist/template/src/capabilities/tool.describe-instance.ts DELETED Viewed

@@ -1,14 +0,0 @@
-import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
-import { z } from "zod";
-import type { MultiInstanceContext } from "./context.js";
-export default (({ instanceName }) => defineTool({
-  name: "describe-instance",
-  access: "public",
-  description: "Return the server instance handling this request, not the instance that created a stored report.",
-  inputSchema: z.object({}),
-  outputSchema: z.object({
-    instanceName: z.string().describe("Server instance that handled this request."),
-  }),
-  handler: () => ({ data: { instanceName } }),
-})) satisfies CapabilityModuleFactory<MultiInstanceContext>;