@emseepea/create-api-backed-server 0.0.0

package/README.md

@@ -0,0 +1,22 @@
+# `@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.
+
+```sh
+npm init @emseepea/api-backed-server@next -- my-server
+```
+
+```sh
+cd my-server
+npm install
+npm test
+npm run lint
+npm start
+```

package/dist/LICENSE

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

package/dist/create.mjs

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

package/dist/template/README.md

@@ -0,0 +1,54 @@
+# 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

@@ -0,0 +1,32 @@
+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/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "emseepea-starter",
+  "version": "0.0.0",
+  "private": true,
+  "license": "MIT",
+  "type": "module",
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "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"
+  },
+  "dependencies": {
+    "@emseepea/server": "0.0.4",
+    "zod": "4.4.3"
+  },
+  "devDependencies": {
+    "@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"
+  }
+}

package/dist/template/src/app.ts

@@ -0,0 +1,157 @@
+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],
+  });
+}

package/dist/template/src/server.ts

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

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

@@ -0,0 +1,132 @@
+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 = 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

@@ -0,0 +1,26 @@
+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,
+};

package/dist/template/test-support/llm-server.mjs

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import { serveEmseepea } from "@emseepea/server";
+import { createBackendExample } from "../dist/app.js";
+import { brewmarkFixture } from "./brewmark-fixture.mjs";
+
+const app = createBackendExample({
+  async get({ pathname, searchParams }) {
+    assert.equal(pathname, "/api/coffees");
+    const { q, ...options } = searchParams;
+    assert.match(q, /\bnatural\b/i);
+    assert.deepEqual(options, { sort: "alpha", limit: "5" });
+    return brewmarkFixture;
+  },
+});
+const running = await serveEmseepea(app, { port: 0 });
+
+console.log(`Em See Pea backend no-UI fixture listening at ${running.url}`);
+
+async function shutdown() {
+  await running.close();
+  process.exitCode = 0;
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/dist/template/tsconfig.json

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

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@emseepea/create-api-backed-server",
+  "version": "0.0.0",
+  "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": false,
+    "tag": "next"
+  },
+  "type": "module",
+  "bin": {
+    "create-api-backed-server": "./dist/create.mjs"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=22"
+  }
+}