@emseepea/create-api-backed-server 0.0.2 → 0.0.4

package/README.md

@@ -1,22 +1,78 @@
 # `@emseepea/create-api-backed-server`
 
-Create a private, standalone Em See Pea project whose tool reads a public web
-API. The package builds its starter from the maintained
-[API-backed server example](https://github.com/emseepea/emseepea/tree/main/examples/backend-no-ui).
+This directory is both the maintained example and its public npm initializer.
 
-## Create the Project
+## Use This Template
 
-This initializer is queued for the next pre-alpha release and is not yet
-available from npm.
+Use this template when a tool calls a public JSON API and must validate and
+select the fields returned to the caller. Choose the [tool server](../tool-server/README.md)
+when all data is local, or the [sign-in tool server](../sign-in-tool-server/README.md)
+when calling the tool requires authentication. [Compare all eight templates](https://emseepea.github.io/emseepea/examples/).
+
+## Create a Project
 
 ```sh
-npm init @emseepea/api-backed-server@next -- my-server
+npm init @emseepea/api-backed-server -- my-server
 ```
 
+<!-- generated-project-readme -->
+
+## Public Web Service Backend Example
+
+Choose this example when your MCP tool needs to read a public web service and
+return selected, checked data in a clear result for an assistant.
+
+This example exposes one read-only `search-pea-taxa` tool. A normal run searches
+[iNaturalist's public taxon catalogue](https://api.inaturalist.org/v1/docs/)
+and returns at most five matching species.
+
+Unlike the [first public tool example](https://github.com/emseepea/emseepea/tree/main/examples/tool-server),
+this tool adapts a separate service. The public input and result use the Model Context Protocol
+(MCP). The iNaturalist query and response are checked before the result is returned.
+
+The tool preserves iNaturalist's useful field names and values. For example,
+`rank` remains an open string, so iNaturalist can add a valid rank without
+requiring an MCP release. Separate public and backend schemas still select and
+check every field that can reach the caller.
+
+The caller can choose a search term. The caller cannot change
+the website, path, result limit, credentials, or HTTP rules. Search
+terms are sent to iNaturalist. The example does not send authentication details or
+change data. Do not include personal, secret, or confidential information in a
+search term.
+
+The automated checks use fixed pea taxon records through the same MCP server.
+They do not depend on iNaturalist being available and do not make a speed or uptime
+claim for iNaturalist. Normal runs use iNaturalist's public API.
+
+## Run
+
+From this directory:
+
 ```sh
-cd my-server
 npm install
-npm test
-npm run lint
+npm run build
 npm start
 ```
+
+The endpoint is `http://127.0.0.1:3000/mcp`.
+
+## Check This Example
+
+[Ordinary tests](test/) live in `test/`.
+The [AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately in `eval/`.
+The commands below run each suite independently.
+
+Run its build, mapping, validation, and MCP checks:
+
+```sh
+npm test
+```
+
+Check that Claude chooses taxon search and understands the observation count:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/README.md

@@ -0,0 +1,59 @@
+# Public Web Service Backend Example
+
+Choose this example when your MCP tool needs to read a public web service and
+return selected, checked data in a clear result for an assistant.
+
+This example exposes one read-only `search-pea-taxa` tool. A normal run searches
+[iNaturalist's public taxon catalogue](https://api.inaturalist.org/v1/docs/)
+and returns at most five matching species.
+
+Unlike the [first public tool example](https://github.com/emseepea/emseepea/tree/main/examples/tool-server),
+this tool adapts a separate service. The public input and result use the Model Context Protocol
+(MCP). The iNaturalist query and response are checked before the result is returned.
+
+The tool preserves iNaturalist's useful field names and values. For example,
+`rank` remains an open string, so iNaturalist can add a valid rank without
+requiring an MCP release. Separate public and backend schemas still select and
+check every field that can reach the caller.
+
+The caller can choose a search term. The caller cannot change
+the website, path, result limit, credentials, or HTTP rules. Search
+terms are sent to iNaturalist. The example does not send authentication details or
+change data. Do not include personal, secret, or confidential information in a
+search term.
+
+The automated checks use fixed pea taxon records through the same MCP server.
+They do not depend on iNaturalist being available and do not make a speed or uptime
+claim for iNaturalist. Normal runs use iNaturalist's public API.
+
+## Run
+
+From this directory:
+
+```sh
+npm install
+npm run build
+npm start
+```
+
+The endpoint is `http://127.0.0.1:3000/mcp`.
+
+## Check This Example
+
+[Ordinary tests](test/) live in `test/`.
+The [AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately in `eval/`.
+The commands below run each suite independently.
+
+Run its build, mapping, validation, and MCP checks:
+
+```sh
+npm test
+```
+
+Check that Claude chooses taxon search and understands the observation count:
+
+```sh
+npm run test:llm
+```
+
+If Claude is not already signed in, run `claude auth login` first.

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

@@ -0,0 +1,23 @@
+import { toolSelectionTest } from "@emseepea/testing/semantic";
+
+toolSelectionTest("Taxon fields retain their documented meaning", {
+  server: new URL("../test-support/llm-server.mjs", import.meta.url),
+  question:
+    "Search the public taxon catalogue for pea species. Give the scientific and " +
+    "common names of each result, say which has more recorded observations, and " +
+    "explain whether that count estimates the wild population.",
+  criticalFacts: [
+    "Pisum sativum",
+    "Common Pea",
+    "Lathyrus odoratus",
+    "Sweet Pea",
+    /8,?720/,
+    /6,?240/
+  ],
+  criteria:
+    "The answer reports Pisum sativum as Common Pea and Lathyrus odoratus as Sweet " +
+    "Pea. It says Pisum sativum has more recorded observations, 8720 compared with " +
+    "6240. It explains that observations_count is a count of recorded observations, " +
+    "not an estimate of the wild population.",
+  expectedTools: ["search-pea-taxa"],
+});

package/{dist → initializer-dist}/template/package.json

@@ -1,7 +1,7 @@
 {
   "name": "emseepea-starter",
   "version": "0.0.0",
-  "private": true,
+  "description": "Create an Em See Pea server backed by a public web API.",
   "license": "MIT",
   "type": "module",
   "scripts": {
@@ -13,12 +13,8 @@
     "test:llm:built": "emseepea-test eval",
     "lint": "oxlint src test eval test-support"
   },
-  "dependencies": {
-    "@emseepea/server": "0.1.0",
-    "zod": "4.4.3"
-  },
   "devDependencies": {
-    "@emseepea/testing": "0.2.1",
+    "@emseepea/testing": "0.2.2",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
@@ -26,5 +22,10 @@
   },
   "engines": {
     "node": ">=22"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.2.2",
+    "zod": "4.4.3"
   }
 }

package/{dist → initializer-dist}/template/src/app.ts

@@ -3,9 +3,9 @@ import type { JsonHttpClient } from "@emseepea/server/http";
 
 export async function createBackendExample(client: JsonHttpClient): Promise<ReturnType<typeof createEmseepea>> {
   return createEmseepea({
-    name: "emseepea-backend-no-ui",
+    name: "emseepea-api-backed-server",
     version: "0.0.0",
-    instructions: "Use search-coffee-catalog to search BrewMark's public coffee catalogue.",
+    instructions: "Use search-pea-taxa to search iNaturalist's public taxon catalogue for pea species.",
     ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), { client }),
   });
 }

package/initializer-dist/template/src/capabilities/tool.search-pea-taxa.ts

@@ -0,0 +1,88 @@
+import { defineMappedTool, type CapabilityModuleFactory } from "@emseepea/server";
+import type { JsonHttpClient } from "@emseepea/server/http";
+import { z } from "zod";
+
+export interface BackendExampleContext { readonly client: JsonHttpClient }
+
+const taxon = z.object({
+  id: z.number().int().positive(),
+  name: z.string().min(1).max(200),
+  preferred_common_name: z.string().min(1).max(200).nullable().optional(),
+  rank: z.string().min(1).max(40),
+  observations_count: z.number().int().nonnegative(),
+});
+const backendTaxon = z.object({
+  id: z.number().int().positive(),
+  name: z.string().min(1).max(200),
+  preferred_common_name: z.string().min(1).max(200).nullable().optional(),
+  rank: z.string().min(1).max(40),
+  observations_count: z.number().int().nonnegative(),
+});
+const searchInput = z.object({ query: z.string().trim().min(2).max(80) });
+const searchReport = z.object({
+  query: z.string().max(80),
+  total_results: z.number().int().nonnegative(),
+  results: z.array(taxon).max(5),
+  source: z.literal("iNaturalist"),
+  source_url: z.literal("https://www.inaturalist.org"),
+});
+const backendCommand = z.object({
+  pathname: z.literal("/v1/taxa"),
+  searchParams: z.object({
+    q: z.string().min(2).max(80),
+    rank: z.literal("species"),
+    per_page: z.literal("5"),
+  }),
+});
+const backendPayload = z.object({
+  total_results: z.number().int().nonnegative(),
+  results: z.array(backendTaxon).max(5),
+});
+const backendResult = z.object({ request: backendCommand, payload: backendPayload });
+
+export default (({ client }) => defineMappedTool({
+  name: "search-pea-taxa",
+  access: "public",
+  description: "Search iNaturalist's public taxon catalogue for pea species.",
+  inputSchema: searchInput,
+  outputSchema: searchReport,
+  backendInputSchema: backendCommand,
+  backendOutputSchema: backendResult,
+  mapInput: ({ query }) => ({
+    pathname: "/v1/taxa" as const,
+    searchParams: { q: query, rank: "species" as const, per_page: "5" as const },
+  }),
+  async adapter(request, { signal, deadlineMs }) {
+    return { request, payload: await client.get({ ...request, signal, deadlineMs }) };
+  },
+  mapOutput: ({ request, payload }) => {
+    const data = {
+      query: request.searchParams.q,
+      total_results: payload.total_results,
+      results: payload.results.map((record) => ({
+        id: record.id,
+        name: record.name,
+        preferred_common_name: record.preferred_common_name,
+        rank: record.rank,
+        observations_count: record.observations_count,
+      })),
+      source: "iNaturalist" as const,
+      source_url: "https://www.inaturalist.org" as const,
+    };
+    const lines = data.results.map((record) => [
+      record.preferred_common_name ?? "Common name not provided",
+      record.name,
+      `rank: ${record.rank}`,
+      `recorded observations: ${record.observations_count}`,
+    ].join("; "));
+    return {
+      text: [
+        `iNaturalist returned ${data.results.length} of ${data.total_results} matching taxa for “${data.query}”.`,
+        "observations_count is the number of recorded observations, not a population estimate.",
+        ...lines,
+        "Source: https://www.inaturalist.org",
+      ].join("\n"),
+      data,
+    };
+  },
+})) satisfies CapabilityModuleFactory<BackendExampleContext>;

package/{dist → initializer-dist}/template/src/server.ts

@@ -3,7 +3,7 @@ import { createJsonHttpClient } from "@emseepea/server/http";
 import { createBackendExample } from "./app.js";
 
 const client = createJsonHttpClient({
-  origin: "https://brewmark.io",
+  origin: "https://api.inaturalist.org",
   maxResponseBytes: 128 * 1024,
 });
 const running = await serveEmseepea(
@@ -11,7 +11,7 @@ const running = await serveEmseepea(
   { port: Number.parseInt(process.env.PORT ?? "3000", 10) },
 );
 
-console.log(`Em See Pea backend no-UI example listening at ${running.url}`);
+console.log(`Em See Pea API-backed server example listening at ${running.url}`);
 
 async function shutdown(): Promise<void> {
   await running.close();

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

@@ -0,0 +1,101 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { serveEmseepea } from "@emseepea/server";
+import { createBackendExample } from "../dist/app.js";
+import { inaturalistFixture } from "../test-support/inaturalist-fixture.mjs";
+
+test("the API-backed example checks and passes through selected iNaturalist values", async () => {
+  const requests = [];
+  let response = inaturalistFixture;
+  const app = await createBackendExample({
+    async get(options) {
+      requests.push(options);
+      if (response instanceof Error) throw response;
+      return response;
+    },
+  });
+  const running = await serveEmseepea(app, { port: 0 });
+  const client = new Client(
+    { name: "api-backed-example-test", version: "0.0.0" },
+    { versionNegotiation: { mode: { pin: "2026-07-28" } } },
+  );
+  await client.connect(new StreamableHTTPClientTransport(new URL(running.url)));
+
+  try {
+    const listed = await client.listTools();
+    assert.deepEqual(listed.tools.map(({ name }) => name), ["search-pea-taxa"]);
+
+    const invalidInput = await client.callTool({
+      name: "search-pea-taxa",
+      arguments: { query: "x" },
+    });
+    assert.equal(invalidInput.isError, true);
+    assert.equal(requests.length, 0);
+
+    const result = await client.callTool({
+      name: "search-pea-taxa",
+      arguments: { query: " pea " },
+    });
+    assert.equal(result.isError, false);
+    assert.deepEqual(result.structuredContent, {
+      query: "pea",
+      ...inaturalistFixture,
+      source: "iNaturalist",
+      source_url: "https://www.inaturalist.org",
+    });
+    assert.match(result.content[0].text, /not a population estimate/);
+    assert.equal(requests[0].pathname, "/v1/taxa");
+    assert.deepEqual(requests[0].searchParams, {
+      q: "pea",
+      rank: "species",
+      per_page: "5",
+    });
+    assert.equal(requests[0].signal instanceof AbortSignal, true);
+    assert.ok(requests[0].deadlineMs > Date.now());
+
+    response = {
+      total_results: 1,
+      results: [{
+        id: 123,
+        name: "Pisum example",
+        preferred_common_name: null,
+        rank: "new-provider-rank",
+        observations_count: 0,
+        private_note: "do not expose",
+      }],
+    };
+    const newProviderValue = await client.callTool({
+      name: "search-pea-taxa",
+      arguments: { query: "Pisum" },
+    });
+    assert.equal(newProviderValue.isError, false);
+    assert.deepEqual(newProviderValue.structuredContent.results[0], {
+      id: 123,
+      name: "Pisum example",
+      preferred_common_name: null,
+      rank: "new-provider-rank",
+      observations_count: 0,
+    });
+    assert.equal("private_note" in newProviderValue.structuredContent.results[0], false);
+
+    response = { total_results: 1, results: [{ id: "bad provider row" }] };
+    const invalidProviderData = await client.callTool({
+      name: "search-pea-taxa",
+      arguments: { query: "pea" },
+    });
+    assert.equal(invalidProviderData.isError, true);
+    assert.doesNotMatch(JSON.stringify(invalidProviderData), /bad provider row|preferred_common_name/);
+
+    response = new Error("private-provider-error");
+    const providerFailure = await client.callTool({
+      name: "search-pea-taxa",
+      arguments: { query: "pea" },
+    });
+    assert.equal(providerFailure.isError, true);
+    assert.doesNotMatch(JSON.stringify(providerFailure), /private-provider-error|inaturalist\.org/i);
+  } finally {
+    await client.close();
+    await running.close();
+  }
+});

package/initializer-dist/template/test-support/inaturalist-fixture.mjs

@@ -0,0 +1,19 @@
+export const inaturalistFixture = {
+  total_results: 2,
+  results: [
+    {
+      id: 54522,
+      name: "Pisum sativum",
+      preferred_common_name: "Common Pea",
+      rank: "species",
+      observations_count: 8720,
+    },
+    {
+      id: 125973,
+      name: "Lathyrus odoratus",
+      preferred_common_name: "Sweet Pea",
+      rank: "species",
+      observations_count: 6240,
+    },
+  ],
+};

package/{dist → initializer-dist}/template/test-support/llm-server.mjs

@@ -1,20 +1,20 @@
 import assert from "node:assert/strict";
 import { serveEmseepea } from "@emseepea/server";
 import { createBackendExample } from "../dist/app.js";
-import { brewmarkFixture } from "./brewmark-fixture.mjs";
+import { inaturalistFixture } from "./inaturalist-fixture.mjs";
 
 const app = await createBackendExample({
   async get({ pathname, searchParams }) {
-    assert.equal(pathname, "/api/coffees");
+    assert.equal(pathname, "/v1/taxa");
     const { q, ...options } = searchParams;
-    assert.match(q, /\bnatural\b/i);
-    assert.deepEqual(options, { sort: "alpha", limit: "5" });
-    return brewmarkFixture;
+    assert.match(q, /\bpea\b/i);
+    assert.deepEqual(options, { rank: "species", per_page: "5" });
+    return inaturalistFixture;
   },
 });
 const running = await serveEmseepea(app, { port: 0 });
 
-console.log(`Em See Pea backend no-UI fixture listening at ${running.url}`);
+console.log(`Em See Pea API-backed fixture listening at ${running.url}`);
 
 async function shutdown() {
   await running.close();

package/package.json

@@ -1,22 +1,38 @@
 {
   "name": "@emseepea/create-api-backed-server",
-  "version": "0.0.2",
+  "version": "0.0.4",
   "description": "Create an Em See Pea server backed by a public web API.",
   "license": "MIT",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/emseepea/emseepea.git",
-    "directory": "packages/create-api-backed-server"
-  },
-  "homepage": "https://emseepea.github.io/emseepea/examples/",
-  "bugs": "https://github.com/emseepea/emseepea/issues",
-  "publishConfig": { "access": "public", "provenance": true, "tag": "next" },
   "type": "module",
-  "bin": { "create-api-backed-server": "./dist/create.mjs" },
-  "files": ["dist"],
+  "starterDependencies": ["@emseepea/server", "zod"],
   "scripts": {
-    "build": "node ../../scripts/build-initializer.mjs",
-    "prepack": "npm run build"
+    "build": "npm run build:example && npm run build:initializer",
+    "build:example": "tsc -p tsconfig.json",
+    "build:initializer": "node ../../scripts/build-initializer.mjs",
+    "start": "node dist/server.js",
+    "test": "npm run build && npm run test:built",
+    "test:built": "node --test test/*.test.mjs",
+    "test:llm": "npm run build && npm run test:llm:built",
+    "test:llm:built": "emseepea-test eval",
+    "lint": "oxlint src test eval test-support",
+    "prepack": "npm run build:initializer"
+  },
+  "devDependencies": {
+    "@emseepea/server": "0.2.2",
+    "zod": "4.4.3",
+    "@emseepea/testing": "0.2.2",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
   },
-  "engines": { "node": ">=22" }
+  "engines": {
+    "node": ">=22"
+  },
+  "repository": { "type": "git", "url": "git+https://github.com/emseepea/emseepea.git", "directory": "examples/api-backed-server" },
+  "homepage": "https://emseepea.github.io/emseepea/examples/",
+  "bugs": "https://github.com/emseepea/emseepea/issues",
+  "publishConfig": { "access": "public", "provenance": true },
+  "bin": { "create-api-backed-server": "./initializer-dist/create.mjs" },
+  "files": ["initializer-dist"]
 }

package/dist/template/README.md

@@ -1,54 +0,0 @@
-# Public Web Service Backend Example
-
-Choose this example when your MCP tool needs to read a public web service and
-translate its data into a clear result for an assistant.
-
-This example exposes one read-only `search-coffee-catalog` tool. A normal run
-searches [BrewMark's public coffee catalogue](https://brewmark.io/developers/api-docs)
-and returns at most five coffees.
-
-Unlike the [first public tool example](https://github.com/emseepea/emseepea/tree/main/examples/basic-no-ui),
-this tool adapts a separate service. The public input and result use the Model Context Protocol
-(MCP). BrewMark's query and response are checked before the result is returned.
-
-The caller can choose a search term and roast filter. The caller cannot change
-the website, path, result limit, sort order, credentials, or HTTP rules. Search
-terms are sent to BrewMark. The example does not send authentication details or
-change data. Do not include personal, secret, or confidential information in a
-search term.
-
-The automated checks use invented coffee records through the same MCP server.
-They do not depend on BrewMark being available and do not make a speed or uptime
-claim for BrewMark. Normal runs use BrewMark's fair-use public web service.
-
-## Run
-
-From this directory:
-
-```sh
-npm install
-npm run build
-npm start
-```
-
-The endpoint is `http://127.0.0.1:3000/mcp`.
-
-## Check This Example
-
-[Ordinary tests](test/) live in `test/`.
-The [AI tool-choice and understanding test](eval/meaning.test.mjs) lives separately in `eval/`.
-The commands below run each suite independently.
-
-Run its build, mapping, validation, and MCP checks:
-
-```sh
-npm test
-```
-
-Check that Claude chooses catalogue search and understands the rating scales:
-
-```sh
-npm run test:llm
-```
-
-If Claude is not already signed in, run `claude auth login` first.

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

@@ -1,32 +0,0 @@
-import { toolSelectionTest } from "@emseepea/testing/semantic";
-
-toolSelectionTest("Coffee ratings retain their documented meaning", {
-  server: new URL("../test-support/llm-server.mjs", import.meta.url),
-  question:
-    "Search the coffee catalogue for natural coffees. Name each returned coffee, " +
-    "its roaster and origin, say whether more matches are available, and explain " +
-    "exactly what the acidity and body scores mean. Which coffee is more acidic, " +
-    "and which has the fuller body?",
-  criticalFacts: [
-    "Riverlight Natural",
-    "North Star Sample Roasters",
-    "Burundi",
-    "Cedar Grove",
-    "Harbour Sample Coffee",
-    "Colombia",
-    "more matches",
-    "low acidity",
-    "high acidity",
-    "light body",
-    "full body"
-  ],
-  criteria:
-    "The answer reports Riverlight Natural by North Star Sample Roasters from " +
-    "Burundi and Cedar Grove by Harbour Sample Coffee from Colombia. It says more " +
-    "matches are available. It explains that acidity runs from 1 for low acidity to " +
-    "5 for high acidity, while body runs from 1 for light body to 5 for full body. " +
-    "It identifies Riverlight Natural as more acidic and Cedar Grove as having the " +
-    "fuller body. It does not treat either score as a quality rating or reverse " +
-    "either scale.",
-  expectedTools: ["search-coffee-catalog"],
-});

package/dist/template/src/capabilities/tool.search-coffee-catalog.ts

@@ -1,112 +0,0 @@
-import { defineMappedTool, type CapabilityModuleFactory } from "@emseepea/server";
-import type { JsonHttpClient } from "@emseepea/server/http";
-import { z } from "zod";
-
-export interface BackendExampleContext { readonly client: JsonHttpClient }
-
-const publicRoast = z.enum(["light", "medium-light", "medium", "medium-dark", "dark"]);
-const brewmarkRoast = z.enum(["LIGHT", "MEDIUM_LIGHT", "MEDIUM", "MEDIUM_DARK", "DARK"]);
-const publicToBrewmarkRoast = {
-  light: "LIGHT", "medium-light": "MEDIUM_LIGHT", medium: "MEDIUM",
-  "medium-dark": "MEDIUM_DARK", dark: "DARK",
-} as const;
-const brewmarkToPublicRoast = {
-  LIGHT: "light", MEDIUM_LIGHT: "medium-light", MEDIUM: "medium",
-  MEDIUM_DARK: "medium-dark", DARK: "dark",
-} as const;
-const searchInput = z.object({ query: z.string().trim().min(2).max(80), roast: publicRoast.optional() });
-const coffee = z.object({
-  name: z.string().max(200), roaster: z.string().max(200), origin: z.string().max(200).nullable(),
-  roast: publicRoast, processingMethod: z.string().max(100).nullable(),
-  flavourNotes: z.string().max(500).nullable(), acidityLevel: z.number().int().min(1).max(5).nullable(),
-  bodyLevel: z.number().int().min(1).max(5).nullable(),
-});
-const searchReport = z.object({
-  query: z.string().max(80), roastFilter: publicRoast.nullable(), returnedCount: z.number().int().min(0).max(5),
-  moreMatchesAvailable: z.boolean(),
-  ratingScale: z.object({
-    acidity: z.literal("1 = low acidity; 5 = high acidity"),
-    body: z.literal("1 = light body; 5 = full body"),
-  }),
-  coffees: z.array(coffee).max(5), source: z.literal("BrewMark"), sourceUrl: z.literal("https://brewmark.io"),
-});
-const backendCommand = z.object({
-  pathname: z.literal("/api/coffees"),
-  searchParams: z.object({
-    q: z.string().min(2).max(80), roastLevel: brewmarkRoast.optional(),
-    sort: z.literal("alpha"), limit: z.literal("5"),
-  }),
-});
-const backendCoffee = z.object({
-  name: z.string().max(200), roasterName: z.string().max(200), roastLevel: brewmarkRoast,
-  origin: z.string().max(200).nullable(), processingMethod: z.string().max(100).nullable(),
-  flavorProfile: z.string().max(500).nullable(), acidityLevel: z.number().int().min(1).max(5).nullable(),
-  bodyLevel: z.number().int().min(1).max(5).nullable(),
-});
-const backendPayload = z.object({
-  data: z.array(backendCoffee).max(5), cursor: z.string().max(2_048).nullable(), hasMore: z.boolean(),
-});
-const backendResult = z.object({ request: backendCommand, payload: backendPayload });
-
-export default (({ client }) => defineMappedTool({
-  name: "search-coffee-catalog",
-  access: "public",
-  description: "Search BrewMark's public coffee catalogue and explain its acidity and body ratings.",
-  inputSchema: searchInput,
-  outputSchema: searchReport,
-  backendInputSchema: backendCommand,
-  backendOutputSchema: backendResult,
-  mapInput: ({ query, roast }) => ({
-    pathname: "/api/coffees" as const,
-    searchParams: {
-      q: query,
-      ...(roast ? { roastLevel: publicToBrewmarkRoast[roast] } : {}),
-      sort: "alpha" as const,
-      limit: "5" as const,
-    },
-  }),
-  async adapter(request, { signal, deadlineMs }) {
-    return { request, payload: await client.get({ ...request, signal, deadlineMs }) };
-  },
-  mapOutput: ({ request, payload }) => {
-    const coffees = payload.data.map((record) => ({
-      name: record.name, roaster: record.roasterName, origin: record.origin,
-      roast: brewmarkToPublicRoast[record.roastLevel], processingMethod: record.processingMethod,
-      flavourNotes: record.flavorProfile, acidityLevel: record.acidityLevel, bodyLevel: record.bodyLevel,
-    }));
-    const roastFilter = request.searchParams.roastLevel
-      ? brewmarkToPublicRoast[request.searchParams.roastLevel]
-      : null;
-    const data = {
-      query: request.searchParams.q,
-      roastFilter,
-      returnedCount: coffees.length,
-      moreMatchesAvailable: payload.hasMore,
-      ratingScale: {
-        acidity: "1 = low acidity; 5 = high acidity" as const,
-        body: "1 = light body; 5 = full body" as const,
-      },
-      coffees,
-      source: "BrewMark" as const,
-      sourceUrl: "https://brewmark.io" as const,
-    };
-    const lines = coffees.map((record) => [
-      `${record.name} by ${record.roaster}`,
-      `origin: ${record.origin ?? "not provided"}`,
-      `roast: ${record.roast}`,
-      `acidity: ${record.acidityLevel ?? "not provided"}`,
-      `body: ${record.bodyLevel ?? "not provided"}`,
-    ].join("; "));
-    return {
-      text: [
-        `BrewMark returned ${coffees.length} coffee${coffees.length === 1 ? "" : "s"} for “${data.query}”.`,
-        `More matches available: ${data.moreMatchesAvailable ? "yes" : "no"}.`,
-        "Acidity: 1 = low acidity; 5 = high acidity.",
-        "Body: 1 = light body; 5 = full body.",
-        ...lines,
-        "Source: https://brewmark.io",
-      ].join("\n"),
-      data,
-    };
-  },
-})) satisfies CapabilityModuleFactory<BackendExampleContext>;

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

@@ -1,132 +0,0 @@
-import assert from "node:assert/strict";
-import test from "node:test";
-import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
-import { serveEmseepea } from "@emseepea/server";
-import { createBackendExample } from "../dist/app.js";
-import { brewmarkFixture } from "../test-support/brewmark-fixture.mjs";
-
-test("the backend example maps, checks, and explains BrewMark data", async () => {
-  const requests = [];
-  let response = brewmarkFixture;
-  const app = await createBackendExample({
-    async get(options) {
-      requests.push(options);
-      if (response instanceof Error) throw response;
-      if (response === brewmarkFixture && options.searchParams.roastLevel === "LIGHT") {
-        return { ...response, data: response.data.filter(({ roastLevel }) => roastLevel === "LIGHT") };
-      }
-      return response;
-    },
-  });
-  const running = await serveEmseepea(app, { port: 0 });
-  const client = new Client(
-    { name: "backend-example-test", version: "0.0.0" },
-    { versionNegotiation: { mode: { pin: "2026-07-28" } } },
-  );
-  await client.connect(new StreamableHTTPClientTransport(new URL(running.url)));
-
-  try {
-    const listed = await client.listTools();
-    assert.deepEqual(listed.tools.map(({ name }) => name), ["search-coffee-catalog"]);
-
-    const invalidInput = await client.callTool({
-      name: "search-coffee-catalog",
-      arguments: { query: "x" },
-    });
-    assert.equal(invalidInput.isError, true);
-    assert.equal(requests.length, 0);
-
-    const result = await client.callTool({
-      name: "search-coffee-catalog",
-      arguments: { query: " natural ", roast: "light" },
-    });
-    assert.equal(result.isError, false);
-    assert.deepEqual(result.structuredContent, {
-      query: "natural",
-      roastFilter: "light",
-      returnedCount: 1,
-      moreMatchesAvailable: true,
-      ratingScale: {
-        acidity: "1 = low acidity; 5 = high acidity",
-        body: "1 = light body; 5 = full body",
-      },
-      coffees: [
-        {
-          name: "Riverlight Natural",
-          roaster: "North Star Sample Roasters",
-          origin: "Burundi",
-          roast: "light",
-          processingMethod: "Natural",
-          flavourNotes: "Blackberry, hibiscus",
-          acidityLevel: 5,
-          bodyLevel: 2,
-        },
-      ],
-      source: "BrewMark",
-      sourceUrl: "https://brewmark.io",
-    });
-    assert.match(result.content[0].text, /Acidity: 1 = low acidity; 5 = high acidity\./);
-    assert.match(result.content[0].text, /Body: 1 = light body; 5 = full body\./);
-    assert.equal(requests[0].pathname, "/api/coffees");
-    assert.deepEqual(requests[0].searchParams, {
-      q: "natural",
-      roastLevel: "LIGHT",
-      sort: "alpha",
-      limit: "5",
-    });
-    assert.equal(requests[0].signal instanceof AbortSignal, true);
-    assert.ok(requests[0].deadlineMs > Date.now());
-
-    response = {
-      data: [{
-        name: "Details Pending",
-        roasterName: "Sample Coffee",
-        roastLevel: "LIGHT",
-        origin: null,
-        processingMethod: null,
-        flavorProfile: null,
-        acidityLevel: null,
-        bodyLevel: null,
-      }],
-      cursor: null,
-      hasMore: false,
-    };
-    const missingDetails = await client.callTool({
-      name: "search-coffee-catalog",
-      arguments: { query: "pending" },
-    });
-    assert.equal(missingDetails.isError, false);
-    assert.deepEqual(missingDetails.structuredContent.coffees[0], {
-      name: "Details Pending",
-      roaster: "Sample Coffee",
-      origin: null,
-      roast: "light",
-      processingMethod: null,
-      flavourNotes: null,
-      acidityLevel: null,
-      bodyLevel: null,
-    });
-    assert.match(missingDetails.content[0].text, /origin: not provided/);
-    assert.match(missingDetails.content[0].text, /acidity: not provided/);
-    assert.match(missingDetails.content[0].text, /body: not provided/);
-
-    response = { data: [{ name: "bad provider row" }], cursor: null, hasMore: false };
-    const invalidProviderData = await client.callTool({
-      name: "search-coffee-catalog",
-      arguments: { query: "natural" },
-    });
-    assert.equal(invalidProviderData.isError, true);
-    assert.doesNotMatch(JSON.stringify(invalidProviderData), /bad provider row|roasterName/);
-
-    response = new Error("private-provider-error");
-    const providerFailure = await client.callTool({
-      name: "search-coffee-catalog",
-      arguments: { query: "natural" },
-    });
-    assert.equal(providerFailure.isError, true);
-    assert.doesNotMatch(JSON.stringify(providerFailure), /private-provider-error|brewmark\.io/i);
-  } finally {
-    await client.close();
-    await running.close();
-  }
-});

package/dist/template/test-support/brewmark-fixture.mjs

@@ -1,26 +0,0 @@
-export const brewmarkFixture = {
-  data: [
-    {
-      name: "Riverlight Natural",
-      roasterName: "North Star Sample Roasters",
-      roastLevel: "LIGHT",
-      origin: "Burundi",
-      processingMethod: "Natural",
-      flavorProfile: "Blackberry, hibiscus",
-      acidityLevel: 5,
-      bodyLevel: 2,
-    },
-    {
-      name: "Cedar Grove",
-      roasterName: "Harbour Sample Coffee",
-      roastLevel: "MEDIUM",
-      origin: "Colombia",
-      processingMethod: "Washed",
-      flavorProfile: "Caramel, almond",
-      acidityLevel: 2,
-      bodyLevel: 4,
-    },
-  ],
-  cursor: "fixture-next-page",
-  hasMore: true,
-};