@emseepea/create-api-backed-server 0.0.14 → 0.0.18

package/README.md

@@ -6,8 +6,8 @@ This directory is both the maintained example and its public npm initializer.
 
 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 templates](https://emseepea.github.io/emseepea/examples/).
+when all data is local. Add authentication to either template when calling the
+tool requires permission. [Compare all templates](https://emseepea.github.io/emseepea/examples/).
 
 ## Create a Project
 
@@ -17,6 +17,30 @@ npm init @emseepea/api-backed-server -- my-server
 
 <!-- generated-project-readme -->
 
+## Choose Open or Protected Access
+
+Start open when the catalogue and operations are public.
+
+To protect this template, pass both options to the app factory:
+
+- `access: { access: "protected", requiredScopes: ["peas:read"] }`
+- an `authentication` adapter
+
+Keep `authentication.discovery` as `"public"` unless capability names or
+schemas are sensitive. Use `"protected"` only when each principal should see a
+permission-filtered catalogue. OAuth metadata remains public in both modes.
+
+## Add Observability
+
+The same factory accepts `observability`.
+
+- Use `structuredLogging` for safe structured events.
+- Use `openTelemetry` for traces and metrics.
+
+Adapters receive only redacted framework events. They never receive request
+bodies, arguments, results, tokens, provider claims, or raw errors. See the
+[server API](https://github.com/emseepea/emseepea/tree/main/packages/framework#authentication-and-observability) for the complete configuration.
+
 ## Public Web Service Backend Example
 
 Choose this example when your MCP tool needs to read a public web service and
@@ -57,6 +81,13 @@ npm start
 
 The endpoint is `http://127.0.0.1:3000/mcp`.
 
+## Add Feedback
+
+Install `@emseepea/feedback` when this server needs a detailed one-way
+observation or a durable support conversation. Pass its tools through the
+application factory's `additionalTools` option. Choose PostgreSQL, Firestore,
+GitHub Issues, or Zendesk in the [feedback guide](../../packages/feedback/README.md).
+
 ## Check This Example
 
 [Ordinary tests](test/) live in `test/`.

package/initializer-dist/template/README.md

@@ -1,4 +1,28 @@
-# Public Web Service Backend Example
+# Choose Open or Protected Access
+
+Start open when the catalogue and operations are public.
+
+To protect this template, pass both options to the app factory:
+
+- `access: { access: "protected", requiredScopes: ["peas:read"] }`
+- an `authentication` adapter
+
+Keep `authentication.discovery` as `"public"` unless capability names or
+schemas are sensitive. Use `"protected"` only when each principal should see a
+permission-filtered catalogue. OAuth metadata remains public in both modes.
+
+## Add Observability
+
+The same factory accepts `observability`.
+
+- Use `structuredLogging` for safe structured events.
+- Use `openTelemetry` for traces and metrics.
+
+Adapters receive only redacted framework events. They never receive request
+bodies, arguments, results, tokens, provider claims, or raw errors. See the
+[server API](https://github.com/emseepea/emseepea/tree/main/packages/framework#authentication-and-observability) for the complete configuration.
+
+## 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.
@@ -38,6 +62,13 @@ npm start
 
 The endpoint is `http://127.0.0.1:3000/mcp`.
 
+## Add Feedback
+
+Install `@emseepea/feedback` when this server needs a detailed one-way
+observation or a durable support conversation. Pass its tools through the
+application factory's `additionalTools` option. Choose PostgreSQL, Firestore,
+GitHub Issues, or Zendesk in the [feedback guide](../../packages/feedback/README.md).
+
 ## Check This Example
 
 [Ordinary tests](test/) live in `test/`.

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

@@ -1,9 +1,10 @@
 import test from "node:test";
 import {
   assertNoToolCalls,
+  assertNoNegativeFeedback,
   assertResponseContains,
   assertResponseMeaning,
-  assertToolCalls,
+  assertToolCallsWithOptionalFeedback,
   createConversation,
 } from "@emseepea/testing/semantic";
 
@@ -20,7 +21,7 @@ test("searches once and remembers the common name for a follow-up", async (t) =>
     "and does that count estimate the wild population?",
   );
 
-  assertToolCalls(search, [{
+  await assertToolCallsWithOptionalFeedback(search, [{
     name: "search-pea-taxa",
     arguments: { query: "pea" },
   }]);
@@ -35,4 +36,5 @@ test("searches once and remembers the common name for a follow-up", async (t) =>
   const followUp = await chat.send("What was its common name?");
   assertNoToolCalls(followUp);
   assertResponseContains(followUp, "Common Pea");
+  assertNoNegativeFeedback(search, followUp);
 });

package/initializer-dist/template/package.json

@@ -14,7 +14,8 @@
     "lint": "oxlint src test eval test-support"
   },
   "devDependencies": {
-    "@emseepea/testing": "0.5.3",
+    "@emseepea/feedback": "0.2.0",
+    "@emseepea/testing": "0.9.3",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
@@ -25,7 +26,7 @@
   },
   "private": true,
   "dependencies": {
-    "@emseepea/server": "0.3.3",
+    "@emseepea/server": "0.6.1",
     "zod": "4.4.3"
   }
 }

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

@@ -1,11 +1,25 @@
-import { createEmseepea, discoverCapabilities } from "@emseepea/server";
+import {
+  createEmseepea,
+  discoverCapabilities,
+  type AccessPolicy,
+  type EmseepeaExtensions,
+} from "@emseepea/server";
 import type { JsonHttpClient } from "@emseepea/server/http";
 
-export async function createBackendExample(client: JsonHttpClient): Promise<ReturnType<typeof createEmseepea>> {
+export interface BackendExampleOptions extends EmseepeaExtensions {
+  readonly access?: AccessPolicy;
+}
+
+export async function createBackendExample(
+  client: JsonHttpClient,
+  options: BackendExampleOptions = {},
+): Promise<ReturnType<typeof createEmseepea>> {
+  const { access = { access: "public" }, ...extensions } = options;
   return createEmseepea({
     name: "emseepea-api-backed-server",
     version: "0.0.0",
     instructions: "Use search-pea-taxa to search iNaturalist's public taxon catalogue for pea species.",
-    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), { client }),
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), { client, access }),
+    ...extensions,
   });
 }

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

@@ -1,8 +1,11 @@
-import { defineMappedTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { defineMappedTool, type AccessPolicy, type CapabilityModuleFactory } from "@emseepea/server";
 import type { JsonHttpClient } from "@emseepea/server/http";
 import { z } from "zod";
 
-export interface BackendExampleContext { readonly client: JsonHttpClient }
+export interface BackendExampleContext {
+  readonly client: JsonHttpClient;
+  readonly access: AccessPolicy;
+}
 
 const backendTaxon = z.object({
   id: z.number().int().positive().describe("iNaturalist identifier for the taxon."),
@@ -35,9 +38,9 @@ const backendInputSchema = z.object({
 });
 const backendOutputSchema = z.object({ request: backendInputSchema, payload: backendPayload });
 
-export default (({ client }) => defineMappedTool({
+export default (({ client, access }) => defineMappedTool({
   name: "search-pea-taxa",
-  access: "public",
+  ...access,
   description: "Search iNaturalist's public taxon catalogue for pea species.",
   inputSchema,
   outputSchema,

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

@@ -2,6 +2,7 @@ import assert from "node:assert/strict";
 import test from "node:test";
 import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
 import { serveEmseepea } from "@emseepea/server";
+import { insecureTestAuthentication, startEmseepea } from "@emseepea/testing";
 import { createBackendExample } from "../dist/app.js";
 import { inaturalistFixture } from "../test-support/inaturalist-fixture.mjs";
 
@@ -113,3 +114,21 @@ test("the API-backed example checks and passes through selected iNaturalist valu
     await running.close();
   }
 });
+
+test("the same template composes protected access and observability", async (t) => {
+  const events = [];
+  const permissions = ["taxa:search"];
+  const app = await createBackendExample(
+    { get: async () => inaturalistFixture },
+    {
+      access: { access: "protected", requiredScopes: permissions },
+      authentication: insecureTestAuthentication(permissions),
+      observability: [{ id: "test-log", emit: (event) => events.push(event) }],
+    },
+  );
+  const running = await startEmseepea(t, app);
+  const client = await running.connect("test-token");
+  const result = await client.callTool({ name: "search-pea-taxa", arguments: { query: "pea" } });
+  assert.equal(result.isError, false);
+  assert.ok(events.some(({ capability }) => capability === "search-pea-taxa"));
+});

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

@@ -1,9 +1,10 @@
 import assert from "node:assert/strict";
 import { serveEmseepea } from "@emseepea/server";
+import { defineFeedbackSubmission } from "@emseepea/feedback";
 import { createBackendExample } from "../dist/app.js";
 import { inaturalistFixture } from "./inaturalist-fixture.mjs";
 
-const app = await createBackendExample({
+const client = {
   async get({ pathname, searchParams }) {
     assert.equal(pathname, "/v1/taxa");
     const { q, ...options } = searchParams;
@@ -11,7 +12,12 @@ const app = await createBackendExample({
     assert.deepEqual(options, { rank: "species", per_page: "5" });
     return inaturalistFixture;
   },
+};
+const feedback = defineFeedbackSubmission({
+  access: "public",
+  backend: { submit: () => ({ id: crypto.randomUUID(), recordedAt: new Date().toISOString() }) },
 });
+const app = await createBackendExample(client, { additionalTools: [feedback] });
 const running = await serveEmseepea(app, { port: 0 });
 
 console.log(`Em See Pea API-backed fixture listening at ${running.url}`);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/create-api-backed-server",
-  "version": "0.0.14",
+  "version": "0.0.18",
   "description": "Create an Em See Pea server backed by a public web API.",
   "license": "MIT",
   "type": "module",
@@ -18,9 +18,10 @@
     "prepack": "npm run build:initializer"
   },
   "devDependencies": {
-    "@emseepea/server": "0.3.3",
+    "@emseepea/feedback": "0.2.0",
+    "@emseepea/server": "0.6.1",
     "zod": "4.4.3",
-    "@emseepea/testing": "0.5.3",
+    "@emseepea/testing": "0.9.3",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",