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

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

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.

package/initializer-dist/template/package.json

@@ -14,7 +14,7 @@
     "lint": "oxlint src test eval test-support"
   },
   "devDependencies": {
-    "@emseepea/testing": "0.5.3",
+    "@emseepea/testing": "0.6.1",
     "@modelcontextprotocol/client": "2.0.0",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
@@ -25,7 +25,7 @@
   },
   "private": true,
   "dependencies": {
-    "@emseepea/server": "0.3.3",
+    "@emseepea/server": "0.4.0",
     "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/package.json

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