@emseepea/create-tool-server 0.0.14 → 0.0.20

package/README.md

@@ -4,8 +4,8 @@ This directory is both the maintained example and its public npm initializer.
 
 ## Use This Template
 
-Use this template for the smallest server with one public, read-only tool and
-no external service, sign-in, web page, progress stream, or shared storage.
+Use this template for the smallest server with one read-only tool and no
+external service, web page, progress stream, or shared storage.
 Choose the [API-backed server](../api-backed-server/README.md) when the tool
 must call a public web service. [Compare all templates](https://emseepea.github.io/emseepea/examples/).
 
@@ -17,6 +17,30 @@ npm init @emseepea/tool-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.
+
 ## Your First Public Tool
 
 Choose this example when you want the smallest working server with one public,
@@ -33,8 +57,9 @@ See Pea checks the input and result before returning them through the public
 - checks for tool input and output
 - local use on your computer only
 
-It does not include sign-in, saved sessions, live progress, changes to data, or
-production network setup.
+It does not include saved sessions, live progress, changes to data, or
+production network setup. The protected-access test shows how to add an
+application-supplied authentication adapter.
 
 ## Run
 
@@ -49,6 +74,13 @@ npm start
 The endpoint is `http://127.0.0.1:3000/mcp` and the health check is
 `http://127.0.0.1:3000/healthz`.
 
+## 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/`.
@@ -67,4 +99,9 @@ Check that Claude chooses the variety tool and understands its result:
 npm run test:llm
 ```
 
+The semantic suite also checks that protected discovery offers the tool to a
+permitted principal and does not offer it to a principal without permission.
+Those two authorization cases assert native tool selection only, so they do not
+pay for unrelated answer-meaning judgments.
+
 If Claude is not already signed in, run `claude auth login` first.

package/initializer-dist/template/README.md

@@ -1,4 +1,28 @@
-# Your First Public Tool
+# 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.
+
+## Your First Public Tool
 
 Choose this example when you want the smallest working server with one public,
 read-only tool and no web page.
@@ -14,8 +38,9 @@ See Pea checks the input and result before returning them through the public
 - checks for tool input and output
 - local use on your computer only
 
-It does not include sign-in, saved sessions, live progress, changes to data, or
-production network setup.
+It does not include saved sessions, live progress, changes to data, or
+production network setup. The protected-access test shows how to add an
+application-supplied authentication adapter.
 
 ## Run
 
@@ -30,6 +55,13 @@ npm start
 The endpoint is `http://127.0.0.1:3000/mcp` and the health check is
 `http://127.0.0.1:3000/healthz`.
 
+## 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/`.
@@ -48,4 +80,9 @@ Check that Claude chooses the variety tool and understands its result:
 npm run test:llm
 ```
 
+The semantic suite also checks that protected discovery offers the tool to a
+permitted principal and does not offer it to a principal without permission.
+Those two authorization cases assert native tool selection only, so they do not
+pay for unrelated answer-meaning judgments.
+
 If Claude is not already signed in, run `claude auth login` first.

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

@@ -1,14 +1,24 @@
 import test from "node:test";
 import {
+  assertNoToolCalls,
+  assertNoNegativeFeedback,
   assertResponseContains,
   assertResponseMeaning,
-  assertToolCalls,
+  assertToolCallsWithOptionalFeedback,
   createConversation,
 } from "@emseepea/testing/semantic";
 
+const protectedServer = new URL("./protected-server.mjs", import.meta.url);
+const server = new URL(import.meta.resolve("@emseepea/feedback/testing-server"));
+const environment = {
+  EMSEEPEA_EVAL_APP_MODULE: new URL("../dist/app.js", import.meta.url).href,
+  EMSEEPEA_EVAL_APP_FACTORY: "createToolServer",
+};
+
 test("looks up pea varieties and compares a follow-up", async (t) => {
   const chat = await createConversation(t, {
-    server: new URL("../dist/server.js", import.meta.url),
+    server,
+    environment,
   });
 
   // The first turn's flexible prose needs the one model judge. The follow-up's
@@ -17,7 +27,7 @@ test("looks up pea varieties and compares a follow-up", async (t) => {
     "Describe the pea type, growth habit, maturity time, and traits of Highland Snap.",
   );
 
-  assertToolCalls(highland, [{
+  await assertToolCallsWithOptionalFeedback(highland, [{
     name: "get-pea-variety",
     arguments: { name: "Highland Snap" },
   }]);
@@ -32,9 +42,50 @@ test("looks up pea varieties and compares a follow-up", async (t) => {
   const comparison = await chat.send(
     "Compare that with Harbour Gem. Include its pea type, growth habit, and maturity time.",
   );
-  assertToolCalls(comparison, [{
+  await assertToolCallsWithOptionalFeedback(comparison, [{
     name: "get-pea-variety",
     arguments: { name: "Harbour Gem" },
   }]);
   assertResponseContains(comparison, "Harbour Gem");
+  assertNoNegativeFeedback(highland, comparison);
+});
+
+test("protected discovery offers a permitted tool", async (t) => {
+  const chat = await createConversation(t, {
+    server: protectedServer,
+    authToken: "test-token",
+    environment: { TEST_PERMISSIONS: "varieties:read,feedback:write" },
+  });
+
+  // This one answer check confirms that protected discovery still supports a
+  // useful answer, while keeping the authorization case to one short turn.
+  const answer = await chat.send("What type of pea is Highland Snap?");
+  await assertToolCallsWithOptionalFeedback(answer, [{
+    name: "get-pea-variety",
+    arguments: { name: "Highland Snap" },
+  }]);
+  await assertResponseMeaning(answer, {
+    expected: "The response says that Highland Snap is a snap pea.",
+  });
+  assertNoNegativeFeedback(answer);
+});
+
+test("protected discovery does not offer a hidden tool", async (t) => {
+  const chat = await createConversation(t, {
+    server: protectedServer,
+    authToken: "test-token",
+    environment: { TEST_PERMISSIONS: "other:read" },
+  });
+
+  // Ask about the visible catalogue itself so the response tests discovery,
+  // rather than whether the model can guess an answer from general knowledge.
+  const answer = await chat.send(
+    "Do you have an available tool that can look up Highland Snap?",
+  );
+  assertNoToolCalls(answer);
+  await assertResponseMeaning(answer, {
+    expected:
+      "The response explains that it has no available tool for looking up Highland Snap.",
+  });
+  assertNoNegativeFeedback(answer);
 });

package/initializer-dist/template/eval/protected-server.mjs

@@ -0,0 +1,28 @@
+import { serveEmseepea } from "@emseepea/server";
+import { insecureTestAuthentication } from "@emseepea/testing";
+import { defineFeedbackSubmission } from "@emseepea/feedback";
+import { createToolServer } from "../dist/app.js";
+
+const permissions = process.env.TEST_PERMISSIONS?.split(",").filter(Boolean) ?? [];
+const feedback = defineFeedbackSubmission({
+  access: "protected",
+  requiredScopes: ["feedback:write"],
+  backend: { submit: () => ({ id: crypto.randomUUID(), recordedAt: new Date().toISOString() }) },
+});
+const app = await createToolServer({
+  access: { access: "protected", requiredScopes: ["varieties:read"] },
+  authentication: insecureTestAuthentication(permissions),
+  additionalTools: [feedback],
+});
+const running = await serveEmseepea(app, {
+  port: Number.parseInt(process.env.PORT ?? "3000", 10),
+});
+
+console.log(`Protected tool eval server listening at ${running.url}`);
+
+async function shutdown() {
+  await running.close();
+}
+
+process.once("SIGINT", () => void shutdown());
+process.once("SIGTERM", () => void shutdown());

package/initializer-dist/template/package.json

@@ -14,7 +14,8 @@
     "lint": "oxlint src test eval"
   },
   "devDependencies": {
-    "@emseepea/testing": "0.5.3",
+    "@emseepea/feedback": "0.2.0",
+    "@emseepea/testing": "0.9.3",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
     "oxlint": "1.80.0"
@@ -24,7 +25,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

@@ -0,0 +1,21 @@
+import {
+  createEmseepea,
+  discoverCapabilities,
+  type AccessPolicy,
+  type EmseepeaExtensions,
+} from "@emseepea/server";
+
+export interface ToolServerOptions extends EmseepeaExtensions {
+  readonly access?: AccessPolicy;
+}
+
+export async function createToolServer(options: ToolServerOptions = {}) {
+  const { access = { access: "public" }, ...extensions } = options;
+  return createEmseepea({
+    name: "emseepea-tool-server",
+    version: "0.0.0",
+    instructions: "Use get-pea-variety for information about a sample pea variety.",
+    ...await discoverCapabilities(new URL("./capabilities/", import.meta.url), access),
+    ...extensions,
+  });
+}

package/initializer-dist/template/src/capabilities/tool.get-pea-variety.ts

@@ -1,4 +1,4 @@
-import { defineTool, type CapabilityModuleFactory } from "@emseepea/server";
+import { defineTool, type AccessPolicy, type CapabilityModuleFactory } from "@emseepea/server";
 import { z } from "zod";
 
 const varietyNames = ["Harbour Gem", "Highland Snap"] as const;
@@ -29,12 +29,12 @@ const varieties: Record<(typeof varietyNames)[number], z.input<typeof outputSche
   },
 };
 
-export default (() => defineTool({
+export default ((access) => defineTool({
   name: "get-pea-variety",
-  access: "public",
+  ...access,
   title: "Pea Variety Details",
   description: "Get the type, growth habit, maturity time, and traits of a sample pea variety.",
   inputSchema,
   outputSchema,
   handler: ({ name }) => ({ data: varieties[name] }),
-})) satisfies CapabilityModuleFactory;
+})) satisfies CapabilityModuleFactory<AccessPolicy>;

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

@@ -1,13 +1,7 @@
-import { createEmseepea, discoverCapabilities, serveEmseepea } from "@emseepea/server";
+import { serveEmseepea } from "@emseepea/server";
+import { createToolServer } from "./app.js";
 
-const handler = createEmseepea({
-  name: "emseepea-tool-server",
-  version: "0.0.0",
-  instructions: "Use get-pea-variety for information about a sample pea variety.",
-  ...await discoverCapabilities(new URL("./capabilities/", import.meta.url)),
-});
-
-const running = await serveEmseepea(handler, {
+const running = await serveEmseepea(await createToolServer(), {
   port: Number.parseInt(process.env.PORT ?? "3000", 10),
 });
 

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

@@ -1,7 +1,12 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 
-import { startMcpServer } from "@emseepea/testing";
+import {
+  insecureTestAuthentication,
+  startEmseepea,
+  startMcpServer,
+} from "@emseepea/testing";
+import { createToolServer } from "../dist/app.js";
 
 test("advertises and returns understandable pea variety details", async (t) => {
   const running = await startMcpServer(t, new URL("../dist/server.js", import.meta.url));
@@ -31,3 +36,21 @@ test("advertises and returns understandable pea variety details", async (t) => {
   });
   assert.equal(result.content[0].text, JSON.stringify(result.structuredContent));
 });
+
+test("the same template composes protected access and observability", async (t) => {
+  const events = [];
+  const permissions = ["varieties:read"];
+  const running = await startEmseepea(t, await createToolServer({
+    access: { access: "protected", requiredScopes: permissions },
+    authentication: insecureTestAuthentication(permissions),
+    observability: [{ id: "test-log", emit: (event) => events.push(event) }],
+  }));
+  const client = await running.connect("test-token");
+  assert.deepEqual((await client.listTools()).tools.map(({ name }) => name), ["get-pea-variety"]);
+  const result = await client.callTool({
+    name: "get-pea-variety",
+    arguments: { name: "Harbour Gem" },
+  });
+  assert.equal(result.structuredContent.name, "Harbour Gem");
+  assert.ok(events.some(({ capability }) => capability === "get-pea-variety"));
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@emseepea/create-tool-server",
-  "version": "0.0.14",
+  "version": "0.0.20",
   "description": "Create an Em See Pea server with one public tool.",
   "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",
     "@types/node": "24.13.3",
     "typescript": "6.0.3",
     "oxlint": "1.80.0"