@emseepea/create-api-backed-server 0.0.1 → 0.0.3

package/README.md

@@ -1,22 +1,69 @@
 # `@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).
-
-## Create the Project
-
-This initializer is queued for the next pre-alpha release and is not yet
-available from npm.
+This directory is both the maintained example and its public npm initializer.
 
 ```sh
 npm init @emseepea/api-backed-server@next -- 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-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 tool preserves BrewMark's useful field names and values. It does not keep a
+second list of roast levels, so BrewMark can add a valid level 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 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
-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 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 → initializer-dist}/template/README.md

@@ -1,7 +1,7 @@
 # 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.
+return selected, checked data in 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)
@@ -11,6 +11,11 @@ Unlike the [first public tool example](https://github.com/emseepea/emseepea/tree
 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 tool preserves BrewMark's useful field names and values. It does not keep a
+second list of roast levels, so BrewMark can add a valid level 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 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

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,10 +13,6 @@
     "test:llm:built": "emseepea-test eval",
     "lint": "oxlint src test eval test-support"
   },
-  "dependencies": {
-    "@emseepea/server": "0.0.4",
-    "zod": "4.4.3"
-  },
   "devDependencies": {
     "@emseepea/testing": "0.2.1",
     "@modelcontextprotocol/client": "2.0.0",
@@ -26,5 +22,10 @@
   },
   "engines": {
     "node": ">=22"
+  },
+  "private": true,
+  "dependencies": {
+    "@emseepea/server": "0.2.1",
+    "zod": "4.4.3"
   }
 }

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

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

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

@@ -0,0 +1,103 @@
+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 roastLevel = z.string().trim().min(1).max(40);
+const searchInput = z.object({
+  query: z.string().trim().min(2).max(80),
+  roastLevel: roastLevel.describe("Optional BrewMark roast level, such as LIGHT or MEDIUM_LIGHT.").optional(),
+});
+const coffee = z.object({
+  name: z.string().max(200), roasterName: z.string().max(200), roastLevel,
+  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 searchReport = z.object({
+  query: z.string().max(80), roastLevelFilter: roastLevel.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: roastLevel.optional(),
+    sort: z.literal("alpha"), limit: z.literal("5"),
+  }),
+});
+const backendCoffee = z.object({
+  name: z.string().max(200), roasterName: z.string().max(200), roastLevel,
+  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, roastLevel }) => ({
+    pathname: "/api/coffees" as const,
+    searchParams: {
+      q: query,
+      ...(roastLevel ? { roastLevel } : {}),
+      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, roasterName: record.roasterName, roastLevel: record.roastLevel,
+      origin: record.origin, processingMethod: record.processingMethod,
+      flavorProfile: record.flavorProfile, acidityLevel: record.acidityLevel, bodyLevel: record.bodyLevel,
+    }));
+    const data = {
+      query: request.searchParams.q,
+      roastLevelFilter: request.searchParams.roastLevel ?? null,
+      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.roasterName}`,
+      `origin: ${record.origin ?? "not provided"}`,
+      `roast level: ${record.roastLevel}`,
+      `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 → initializer-dist}/template/src/server.ts

@@ -7,7 +7,7 @@ const client = createJsonHttpClient({
   maxResponseBytes: 128 * 1024,
 });
 const running = await serveEmseepea(
-  createBackendExample(client),
+  await createBackendExample(client),
   { port: Number.parseInt(process.env.PORT ?? "3000", 10) },
 );
 

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

@@ -5,10 +5,10 @@ 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 () => {
+test("the backend example checks and passes through selected BrewMark values", async () => {
   const requests = [];
   let response = brewmarkFixture;
-  const app = createBackendExample({
+  const app = await createBackendExample({
     async get(options) {
       requests.push(options);
       if (response instanceof Error) throw response;
@@ -38,12 +38,12 @@ test("the backend example maps, checks, and explains BrewMark data", async () =>
 
     const result = await client.callTool({
       name: "search-coffee-catalog",
-      arguments: { query: " natural ", roast: "light" },
+      arguments: { query: " natural ", roastLevel: "LIGHT" },
     });
     assert.equal(result.isError, false);
     assert.deepEqual(result.structuredContent, {
       query: "natural",
-      roastFilter: "light",
+      roastLevelFilter: "LIGHT",
       returnedCount: 1,
       moreMatchesAvailable: true,
       ratingScale: {
@@ -53,11 +53,11 @@ test("the backend example maps, checks, and explains BrewMark data", async () =>
       coffees: [
         {
           name: "Riverlight Natural",
-          roaster: "North Star Sample Roasters",
+          roasterName: "North Star Sample Roasters",
+          roastLevel: "LIGHT",
           origin: "Burundi",
-          roast: "light",
           processingMethod: "Natural",
-          flavourNotes: "Blackberry, hibiscus",
+          flavorProfile: "Blackberry, hibiscus",
           acidityLevel: 5,
           bodyLevel: 2,
         },
@@ -81,12 +81,13 @@ test("the backend example maps, checks, and explains BrewMark data", async () =>
       data: [{
         name: "Details Pending",
         roasterName: "Sample Coffee",
-        roastLevel: "LIGHT",
+        roastLevel: "OMNI_ROAST",
         origin: null,
         processingMethod: null,
         flavorProfile: null,
         acidityLevel: null,
         bodyLevel: null,
+        privateNote: "do not expose",
       }],
       cursor: null,
       hasMore: false,
@@ -98,14 +99,15 @@ test("the backend example maps, checks, and explains BrewMark data", async () =>
     assert.equal(missingDetails.isError, false);
     assert.deepEqual(missingDetails.structuredContent.coffees[0], {
       name: "Details Pending",
-      roaster: "Sample Coffee",
+      roasterName: "Sample Coffee",
+      roastLevel: "OMNI_ROAST",
       origin: null,
-      roast: "light",
       processingMethod: null,
-      flavourNotes: null,
+      flavorProfile: null,
       acidityLevel: null,
       bodyLevel: null,
     });
+    assert.equal("privateNote" in missingDetails.structuredContent.coffees[0], false);
     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/);

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

@@ -3,7 +3,7 @@ import { serveEmseepea } from "@emseepea/server";
 import { createBackendExample } from "../dist/app.js";
 import { brewmarkFixture } from "./brewmark-fixture.mjs";
 
-const app = createBackendExample({
+const app = await createBackendExample({
   async get({ pathname, searchParams }) {
     assert.equal(pathname, "/api/coffees");
     const { q, ...options } = searchParams;

package/package.json

@@ -1,22 +1,38 @@
 {
   "name": "@emseepea/create-api-backed-server",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "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"
+  "type": "module",
+  "starterDependencies": ["@emseepea/server", "zod"],
+  "scripts": {
+    "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.1",
+    "zod": "4.4.3",
+    "@emseepea/testing": "0.2.1",
+    "@modelcontextprotocol/client": "2.0.0",
+    "@types/node": "24.13.3",
+    "typescript": "6.0.3",
+    "oxlint": "1.80.0"
+  },
+  "engines": {
+    "node": ">=22"
   },
+  "repository": { "type": "git", "url": "git+https://github.com/emseepea/emseepea.git", "directory": "examples/backend-no-ui" },
   "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"],
-  "scripts": {
-    "build": "node ../../scripts/build-initializer.mjs",
-    "prepack": "npm run build"
-  },
-  "engines": { "node": ">=22" }
+  "bin": { "create-api-backed-server": "./initializer-dist/create.mjs" },
+  "files": ["initializer-dist"]
 }

package/dist/template/src/app.ts

@@ -1,157 +0,0 @@
-import { createEmseepea, defineMappedTool } from "@emseepea/server";
-import type { JsonHttpClient } from "@emseepea/server/http";
-import { z } from "zod";
-
-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 function createBackendExample(client: JsonHttpClient): ReturnType<typeof createEmseepea> {
-  const searchCoffeeCatalog = 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,
-      };
-    },
-  });
-
-  return createEmseepea({
-    name: "emseepea-backend-no-ui",
-    version: "0.0.0",
-    instructions: "Use search-coffee-catalog to search BrewMark's public coffee catalogue.",
-    tools: [searchCoffeeCatalog],
-  });
-}