@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/examples/live-rpc/src/identity/members.ts

@@ -0,0 +1,8 @@
+import type { Member } from "./Identity.js";
+
+// DEMO ONLY: the people who may sign in, each under a token that is their name. A real service
+// has no such table: its verifier reads the member from a signed token.
+export const members = {
+  ada: { id: "ada", rooms: ["lobby", "ops"] },
+  grace: { id: "grace", rooms: ["lobby"] },
+} as const satisfies Readonly<Record<string, Member>>;

package/examples/live-rpc/src/identity/verifier.ts

@@ -0,0 +1,23 @@
+import { Effect, Redacted } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Authentication from "@gjermundgaraba/effect-actions/Authentication";
+import { Login } from "./Identity.js";
+import { members } from "./members.js";
+
+const isToken = (token: string): token is keyof typeof members => Object.hasOwn(members, token);
+
+// DEMO ONLY: a token is a member's name. A real verifier checks a signed token with your
+// authorization server's library, its audience included. An unknown token is the built-in
+// `Unauthenticated`, which every client decodes.
+const verify = (token: Redacted.Redacted<string>) => {
+  const name = Redacted.value(token);
+
+  return isToken(name)
+    ? Effect.succeed(members[name])
+    : Effect.fail(new Action.Unauthenticated({ message: "Unknown demo token." }));
+};
+
+// Server only: `Login`'s provider. Over RPC it runs for every message of a protected rpc, not
+// once for the connection, so a socket has no identity of its own: each call is whoever its
+// token says. It publishes no OAuth discovery, so it needs no router and no configuration.
+export const authenticate = Authentication.layer(Login, verify);

package/examples/live-rpc/src/routes.ts

@@ -0,0 +1,22 @@
+import { Layer } from "effect";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import { messages, rooms } from "./chat/handlers.js";
+import { ResolveRoom, resolveRoom } from "./chat/room.js";
+import { authenticate } from "./identity/verifier.js";
+import { Rpc } from "./Rpc.js";
+
+// The binding's rpcs on Effect's own RpcServer. A protected rpc authenticates every message
+// with `Login`'s verifier, so one connection may carry several callers; `listRooms` needs no
+// token.
+//
+// `middleware` runs around every rpc, inside authentication and before the input is decoded.
+// `ResolveRoom` provides `CurrentRoom`, which the handlers and `authorize` read. Only something
+// that runs per message can: `Layer.succeed(CurrentRoom, "lobby")` provided here would leave
+// the layer still requiring it, in its type.
+//
+// It still requires three things, each chosen by whoever serves it. The protocol and its
+// serialization: server.ts gives it a WebSocket, and a test Effect's HTTP protocol, which
+// answers in memory. And `MessageStore`.
+export const rpc = ActionRpc.layer(Rpc, [rooms, messages], { middleware: [ResolveRoom] }).pipe(
+  Layer.provide([resolveRoom, authenticate]),
+);

package/examples/live-rpc/src/server.ts

@@ -0,0 +1,43 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { Config, Effect, Layer } from "effect";
+import { HttpRouter } from "effect/http";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+import { MessageStore } from "./chat/store.js";
+import { rpc } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/live-rpc/src/server.ts`.
+// The composition root of the server. It chooses the protocol, the store and the port, and
+// starts Node's HTTP server. It provides no caller and no room: those arrive with each message.
+
+// The rpcs over a WebSocket at `/rpc`, the router's one route: Node's HTTP server answers the
+// upgrade. `ActionRpc.layer` serves a protocol speaking JSON, and the client must speak the
+// same one.
+const socket = rpc.pipe(
+  Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerJson),
+);
+
+const server = Layer.unwrap(
+  Effect.gen(function* () {
+    const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+
+    return HttpRouter.serve(socket).pipe(
+      Layer.provide(
+        NodeHttpServer.layer(createServer, {
+          // This machine alone. A server others reach reads its host from config:
+          // `Config.String("HOST").pipe(Config.withDefault("127.0.0.1"))`.
+          host: "127.0.0.1",
+          port,
+          // A message on a WebSocket is no request body, so `HttpServerRequest.MaxBodySize`
+          // does not bound it: Node's WebSocket server reads one of up to 100 MiB whole unless
+          // told otherwise. A chat message is short, and a larger one closes the socket (1009).
+          websocket: { maxPayload: 64 * 1024 },
+        }),
+      ),
+      Layer.provide(MessageStore.layerMemory),
+    );
+  }),
+);
+
+Layer.launch(server).pipe(NodeRuntime.runMain);

package/examples/live-rpc/test/browser.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { RpcClient, RpcSerialization, RpcServer } from "effect/rpc";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { chatOver, openChat } from "../src/browser.js";
+import { MessageStore } from "../src/chat/store.js";
+import { rpc } from "../src/routes.js";
+
+// The page's client against the real rpcs, in memory. `openChat` needs a client protocol and
+// does not care which: a page gives it `connection(url)`, a WebSocket, and this test Effect's
+// HTTP protocol, answered by `Testing.layer`, which cannot upgrade a WebSocket.
+const served = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
+  Layer.provide(RpcSerialization.layerJson),
+  Layer.provide(
+    Testing.layer(
+      rpc.pipe(
+        Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
+        Layer.provide(RpcSerialization.layerJson),
+      ),
+    ),
+  ),
+  Layer.provide(MessageStore.layerMemory),
+);
+
+describe("the page's client", () => {
+  it.effect("posts and reads in the room it names, as the member its token names", () =>
+    Effect.gen(function* () {
+      const chat = yield* openChat;
+      const first = yield* chat.room("lobby", "ada").post("Deploying at noon.");
+      const second = yield* chat.room("lobby", "grace").post("Ready.");
+
+      yield* chat.room("ops", "ada").post("Disk is full.");
+
+      expect(first).toEqual({ id: 1, author: "ada", text: "Deploying at noon." });
+      expect(yield* chat.room("lobby", "grace").read(first.id)).toEqual({
+        access: "member",
+        messages: [second],
+      });
+      expect(yield* chat.rooms).toEqual([
+        { name: "lobby", messages: 2 },
+        { name: "ops", messages: 1 },
+      ]);
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("turns each declared error of a removal into what the page shows", () =>
+    Effect.gen(function* () {
+      const chat = yield* openChat;
+      const ada = chat.room("lobby", "ada");
+      const grace = chat.room("lobby", "grace");
+      const { id } = yield* ada.post("Oops.");
+
+      expect(yield* grace.remove(id)).toBe("not-yours");
+      expect(yield* grace.read(0)).toMatchObject({ messages: [{ id }] });
+      expect(yield* ada.remove(id)).toBe("removed");
+      expect(yield* grace.read(0)).toEqual({ access: "member", messages: [] });
+      expect(yield* ada.remove(id)).toBe("removed");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("turns each refusal of a read into the access the page shows", () =>
+    Effect.gen(function* () {
+      const chat = yield* openChat;
+
+      yield* chat.room("ops", "ada").post("Disk is full.");
+
+      expect(yield* chat.room("ops", "grace").read(0)).toEqual({
+        access: "not-a-member",
+        messages: [],
+      });
+      expect(yield* chat.room("ops", "expired").read(0)).toEqual({
+        access: "signed-out",
+        messages: [],
+      });
+    }).pipe(Effect.provide(served)),
+  );
+
+  // `connect(url)` is this with a WebSocket. Each test's runtime builds its own layer, and so
+  // its own store.
+  it("answers a page that is not an Effect program with promises, on one connection", async () => {
+    const chat = chatOver(served);
+
+    const posted = await chat.room("lobby", "ada").post("Deploying at noon.");
+
+    expect(posted).toEqual({ id: 1, author: "ada", text: "Deploying at noon." });
+    expect(await chat.room("lobby", "grace").read(0)).toEqual({
+      access: "member",
+      messages: [posted],
+    });
+    expect(await chat.room("lobby", "grace").remove(posted.id)).toBe("not-yours");
+    expect(await chat.room("ops", "expired").read(0)).toEqual({
+      access: "signed-out",
+      messages: [],
+    });
+    expect(await chat.rooms()).toEqual([{ name: "lobby", messages: 1 }]);
+
+    // A failure `openChat` does not handle rejects: here, a text the contract refuses.
+    await expect(chat.room("lobby", "ada").post("")).rejects.toBeInstanceOf(Action.InvalidInput);
+
+    await chat.close();
+
+    await expect(chat.rooms()).rejects.toThrow();
+  });
+});

package/examples/live-rpc/test/chat/chat.test.ts

@@ -0,0 +1,69 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, flow } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { NotAuthor } from "../../src/chat/Chat.js";
+import { messages } from "../../src/chat/handlers.js";
+import { CurrentRoom } from "../../src/chat/room.js";
+import { MessageStore } from "../../src/chat/store.js";
+import { CurrentMember } from "../../src/identity/Identity.js";
+import { members } from "../../src/identity/members.js";
+
+// What the implementation does, with no transport: `Action.client` runs the same decoding,
+// `authorize` and handler a server runs. No authentication and no middleware run here, so
+// each call is given what they would provide: its caller and its room. Neither is provided
+// around the client or beside the store: a request-time service belongs to one call.
+const as = (member: keyof typeof members, room: string) =>
+  flow(
+    Effect.provideService(CurrentMember, members[member]),
+    Effect.provideService(CurrentRoom, room),
+  );
+
+describe("messages, in process", () => {
+  it.effect("keeps each room's messages its own, numbered from 1", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(messages);
+
+      yield* client.postMessage({ text: "Deploying at noon." }).pipe(as("ada", "lobby"));
+      yield* client.postMessage({ text: "Disk is full." }).pipe(as("ada", "ops"));
+      yield* client.postMessage({ text: "Ready." }).pipe(as("grace", "lobby"));
+
+      expect(yield* client.readMessages({ after: 1 }).pipe(as("grace", "lobby"))).toEqual({
+        messages: [{ id: 2, author: "grace", text: "Ready." }],
+      });
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("ada", "ops"))).toEqual({
+        messages: [{ id: 1, author: "ada", text: "Disk is full." }],
+      });
+    }).pipe(Effect.provide(MessageStore.layerMemory)),
+  );
+
+  it.effect("lets only its author delete a message", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(messages);
+      const { id } = yield* client.postMessage({ text: "Oops." }).pipe(as("ada", "lobby"));
+
+      expect(yield* Effect.flip(client.deleteMessage({ id }).pipe(as("grace", "lobby")))).toEqual(
+        new NotAuthor({ id, author: "ada" }),
+      );
+
+      yield* client.deleteMessage({ id }).pipe(as("ada", "lobby"));
+
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("grace", "lobby"))).toEqual({
+        messages: [],
+      });
+    }).pipe(Effect.provide(MessageStore.layerMemory)),
+  );
+
+  it.effect("refuses a member a room they have not joined, before the handler runs", () =>
+    Effect.gen(function* () {
+      const client = yield* Action.client(messages);
+      const post = client.postMessage({ text: "Hello?" }).pipe(as("grace", "ops"));
+      const refused = yield* Effect.flip(post);
+
+      expect(refused).toBeInstanceOf(Action.Forbidden);
+      expect(refused.message).toBe("Not a member of ops.");
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("ada", "ops"))).toEqual({
+        messages: [],
+      });
+    }).pipe(Effect.provide(MessageStore.layerMemory)),
+  );
+});

package/examples/live-rpc/test/routes.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { RpcClient, RpcSerialization, RpcServer } from "effect/rpc";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import * as ActionRpc from "@gjermundgaraba/effect-actions/ActionRpc";
+import * as Testing from "@gjermundgaraba/effect-actions/Testing";
+import { roomHeader } from "../src/chat/Chat.js";
+import { MessageStore } from "../src/chat/store.js";
+import { rpc } from "../src/routes.js";
+import { Rpc } from "../src/Rpc.js";
+
+// What the wire adds: the real rpcs, behind their real authentication and middleware,
+// answering in memory. The server gives them a WebSocket, which `Testing.layer` cannot
+// upgrade: it answers HTTP requests alone. So the test gives the same layer Effect's HTTP
+// protocol, and its client posts to it. No port is opened.
+const server = rpc.pipe(
+  Layer.provide(RpcServer.layerProtocolHttp({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerJson),
+);
+
+const served = RpcClient.layerProtocolHttp({ url: "/rpc" }).pipe(
+  Layer.provide(RpcSerialization.layerJson),
+  Layer.provide(Testing.layer(server)),
+  Layer.provide(MessageStore.layerMemory),
+);
+
+// Each call carries its caller's token, so one client serves every caller of a test.
+const as = (token: string) => RpcClient.withHeaders({ authorization: `Bearer ${token}` });
+
+const inRoom = (room: string) => RpcClient.withHeaders({ [roomHeader]: room });
+
+describe("the chat, over RPC", () => {
+  it.effect("answers the public rpc without a token and refuses the rest", () =>
+    Effect.gen(function* () {
+      const client = yield* ActionRpc.client(Rpc);
+      const signedOut = yield* Effect.flip(client.readMessages({ after: 0 }));
+      const stranger = yield* Effect.flip(client.readMessages({ after: 0 }).pipe(as("mallory")));
+
+      expect(yield* client.listRooms()).toEqual({ rooms: [] });
+      expect(signedOut).toBeInstanceOf(Action.Unauthenticated);
+      expect(signedOut.message).toBe("A bearer token is required.");
+      expect(stranger).toBeInstanceOf(Action.Unauthenticated);
+      expect(stranger.message).toBe("Unknown demo token.");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("authenticates each call by its own token: two callers on one client", () =>
+    Effect.gen(function* () {
+      const client = yield* ActionRpc.client(Rpc);
+
+      yield* client.postMessage({ text: "Deploying at noon." }).pipe(as("ada"));
+      yield* client.postMessage({ text: "Ready." }).pipe(as("grace"));
+
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("grace"))).toEqual({
+        messages: [
+          { id: 1, author: "ada", text: "Deploying at noon." },
+          { id: 2, author: "grace", text: "Ready." },
+        ],
+      });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("gives each call the room its header names, and the lobby when it names none", () =>
+    Effect.gen(function* () {
+      const client = yield* ActionRpc.client(Rpc);
+
+      yield* client.postMessage({ text: "Disk is full." }).pipe(as("ada"), inRoom("ops"));
+      yield* client.postMessage({ text: "Hello." }).pipe(as("ada"));
+
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("ada"), inRoom("ops"))).toEqual({
+        messages: [{ id: 1, author: "ada", text: "Disk is full." }],
+      });
+      expect(yield* client.readMessages({ after: 0 }).pipe(as("ada"), inRoom("lobby"))).toEqual({
+        messages: [{ id: 1, author: "ada", text: "Hello." }],
+      });
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("refuses a member a room they have not joined, naming it", () =>
+    Effect.gen(function* () {
+      const client = yield* ActionRpc.client(Rpc);
+      const read = client.readMessages({ after: 0 }).pipe(as("grace"), inRoom("ops"));
+      const refused = yield* Effect.flip(read);
+
+      expect(refused).toBeInstanceOf(Action.Forbidden);
+      expect(refused.message).toBe("Not a member of ops.");
+    }).pipe(Effect.provide(served)),
+  );
+
+  it.effect("serves a native RpcGroup: Effect's own client calls the same rpcs", () =>
+    Effect.gen(function* () {
+      // `Rpc.group` is what Effect's RPC tooling takes. Its methods take the payload as sent,
+      // `{}` included; `ActionRpc.client` is the one to write an application with.
+      const native = yield* RpcClient.make(Rpc.group);
+
+      expect(yield* native.listRooms({})).toEqual({ rooms: [] });
+    }).pipe(Effect.provide(served)),
+  );
+});

package/examples/live-rpc/test/server.test.ts

@@ -0,0 +1,75 @@
+import { createServer } from "node:http";
+import { NodeHttpServer } from "@effect/platform-node";
+import { describe, expect, it } from "@effect/vitest";
+import { Effect, Layer } from "effect";
+import { HttpRouter, HttpServer } from "effect/http";
+import { RpcSerialization, RpcServer } from "effect/rpc";
+import { connect } from "../src/browser.js";
+import { MessageStore } from "../src/chat/store.js";
+import { rpc } from "../src/routes.js";
+
+// What the socket adds, which no in-memory test reaches: the upgrade, the page's `connect(url)`
+// and the bound on a message. The rpcs are served as server.ts serves them, over a WebSocket
+// at `/rpc` on Node's HTTP server, on port 0: the system picks a free one, so tests run side
+// by side. The server closes with the test's scope.
+const socket = rpc.pipe(
+  Layer.provide(RpcServer.layerProtocolWebsocket({ path: "/rpc" })),
+  Layer.provide(RpcSerialization.layerJson),
+);
+
+// server.ts allows 64 KiB. A bound this small is passed by a message the contract accepts.
+const maxPayload = 256;
+
+const listening = HttpRouter.serve(socket, { disableLogger: true, disableListenLog: true }).pipe(
+  // `provideMerge` keeps `HttpServer` for the test, which reads the port from it.
+  Layer.provideMerge(
+    NodeHttpServer.layer(createServer, { host: "127.0.0.1", port: 0, websocket: { maxPayload } }),
+  ),
+  Layer.provide(MessageStore.layerMemory),
+);
+
+// The page's client, on Node's global `WebSocket`. Each test closes it with `Effect.scoped`,
+// before the server stops: a server that is stopping waits for its open sockets.
+const chat = Effect.gen(function* () {
+  const server = yield* HttpServer.HttpServer;
+  const url = HttpServer.formatAddress(server.address).replace("http", "ws");
+
+  return yield* Effect.acquireRelease(
+    Effect.sync(() => connect(`${url}/rpc`)),
+    (page) => Effect.promise(() => page.close()),
+  );
+});
+
+describe("the chat, over a WebSocket", () => {
+  it.effect("answers the page's client on a listening port, each call as its token names", () =>
+    Effect.gen(function* () {
+      const page = yield* chat;
+
+      const posted = yield* Effect.promise(() =>
+        page.room("lobby", "ada").post("Deploying at noon."),
+      );
+
+      expect(posted).toEqual({ id: 1, author: "ada", text: "Deploying at noon." });
+      expect(yield* Effect.promise(() => page.room("lobby", "grace").read(0))).toEqual({
+        access: "member",
+        messages: [posted],
+      });
+    }).pipe(Effect.scoped, Effect.provide(listening)),
+  );
+
+  it.effect("closes the socket on a message over the bound, failing the call that sent it", () =>
+    Effect.gen(function* () {
+      const page = yield* chat;
+      const ada = page.room("lobby", "ada");
+
+      yield* Effect.promise(() => ada.post("Short."));
+
+      // 400 characters are a text the contract accepts and a message over 256 bytes. The server
+      // reads none of it: it closes the socket with 1009, "message too big", and the call fails
+      // with Effect's `RpcClientError`, its reason the socket's close, which no action declares.
+      yield* Effect.promise(() =>
+        expect(ada.post("x".repeat(400))).rejects.toMatchObject({ reason: { code: 1009 } }),
+      );
+    }).pipe(Effect.scoped, Effect.provide(listening)),
+  );
+});

package/examples/mcp-tools/README.md

@@ -0,0 +1,136 @@
+# mcp-tools
+
+An MCP server whose tools wrap one upstream HTTP API: here, a 3D print farm's. It has no
+authentication of its own. It signs in to the farm once, with its own account, and whoever can
+reach it may call every tool, so it runs as a local subprocess of an agent or on a network only
+trusted clients are on.
+
+Start here if you are putting an existing API in front of a model. For tools that belong to the
+signed-in user, start from [notes-service](../notes-service/).
+
+## Run it
+
+From the repository root, after `vp install` (from an installed package, see
+[Run one](../README.md#run-one)):
+
+```sh
+export FARM_URL=https://farm.example.test FARM_USER=demo FARM_PASSWORD=demo
+
+node --import tsx examples/mcp-tools/src/server.ts      # MCP at 127.0.0.1:3000/mcp, PORT to change
+curl http://127.0.0.1:3000/healthz                      # ok
+
+# The subprocess, given one request on stdin. An agent's host starts it the same way.
+echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"shell","version":"0"}}}' |
+  node --import tsx examples/mcp-tools/src/stdio.ts
+
+vp test examples/mcp-tools
+```
+
+The farm is a fake, answered in memory, so any URL, user and password work: replace it with a
+real HTTP client before deploying anything. `ALLOWED_ORIGINS` lists the browser origins the HTTP
+endpoint accepts and answers with CORS headers, comma-separated; `HOST` is the interface it listens on.
+
+## Connect a client
+
+Claude Code, to the running HTTP server or starting the subprocess itself; add one of the two:
+
+```sh
+claude mcp add --transport http print-farm http://127.0.0.1:3000/mcp
+
+claude mcp add print-farm \
+  -e FARM_URL=https://farm.example.test -e FARM_USER=demo -e FARM_PASSWORD=demo \
+  -- "$PWD/node_modules/.bin/tsx" "$PWD/examples/mcp-tools/src/stdio.ts"
+```
+
+`node --import tsx` finds `tsx` from the directory the process starts in, which the host
+chooses. So the line names both files by their full path, which `$PWD` gives it when run from
+the repository root; `tsx` runs the `node` on the host's `PATH`. Claude Desktop takes the same
+command as an entry of `mcpServers` in its `claude_desktop_config.json`, the paths written out:
+
+```json
+{
+  "mcpServers": {
+    "print-farm": {
+      "command": "/path/to/effect-actions/node_modules/.bin/tsx",
+      "args": ["/path/to/effect-actions/examples/mcp-tools/src/stdio.ts"],
+      "env": {
+        "FARM_URL": "https://farm.example.test",
+        "FARM_USER": "demo",
+        "FARM_PASSWORD": "demo"
+      }
+    }
+  }
+}
+```
+
+By hand, a tool is called with one request, which states its protocol revision, its method
+and its tool's name twice: in the body and in the three `MCP-` headers.
+
+```sh
+curl http://127.0.0.1:3000/mcp \
+  -H 'Content-Type: application/json' \
+  -H 'Accept: application/json, text/event-stream' \
+  -H 'MCP-Protocol-Version: 2026-07-28' \
+  -H 'MCP-Method: tools/call' \
+  -H 'MCP-Name: list_printers' \
+  -d '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"list_printers","arguments":{},"_meta":{"io.modelcontextprotocol/protocolVersion":"2026-07-28","io.modelcontextprotocol/clientInfo":{"name":"curl","version":"0"},"io.modelcontextprotocol/clientCapabilities":{}}}}'
+```
+
+It answers `{"jsonrpc":"2.0","id":1,"result":{…,"structuredContent":{"printers":[…]},"isError":false}}`.
+Every header is needed: without `Accept` naming both types the answer is an empty 406, without
+`Content-Type` a 415, and without an `MCP-` header, or with one that differs from the body, a
+400 saying which. `tools/list` takes the same request with that method, no `MCP-Name` header,
+and no `name` or `arguments`.
+
+## Layout
+
+```text
+src/
+├── printers/
+│   ├── Printers.ts    contract: the printer, the one declared error, the five tools
+│   ├── farm.ts        PrintFarm, the upstream API as a service, and its Layer
+│   ├── fake.ts        DEMO ONLY: the farm's API answered in memory, as an HttpClient
+│   └── handlers.ts    Action.implement: tool to service
+├── instructions.ts    the server's name, version and its instructions for the model
+├── routes.ts          the HTTP surface: /mcp and /healthz
+├── server.ts          entrypoint: MCP over HTTP
+└── stdio.ts           entrypoint: MCP for a local agent
+test/
+├── printers/          in process, with Action.client, over fake upstreams
+└── routes.test.ts     over MCP in memory, with Testing.layer
+```
+
+- **The upstream is a service, built once.** `PrintFarm.layer` reads its URL and credentials
+  from `Config`, takes whichever `HttpClient` the entrypoint provides, and signs in while it is
+  built. The handlers get it already signed in and only delegate.
+- **One declared error, mapped in one place.** A refusal, an unreachable farm, an answer of
+  another shape and one that never comes each leave `farm.ts` as a `PrintFarmError` with a
+  message a model can act on. No handler catches anything.
+- **What a model sends is checked by the contract.** A printer id becomes part of the farm's
+  URL, so its schema admits only what is safe there, and anything else is refused before a
+  handler runs.
+- **One implementation, two transports.** `server.ts` and `stdio.ts` serve the same `printers`
+  with the same `serverInfo`; they differ in what they provide around it.
+- **The contract is the tool.** A tool's name, description, input schema, hints and title all
+  come from `Printers.ts`.
+
+## Where to look
+
+| To see                                                          | Read                             |
+| --------------------------------------------------------------- | -------------------------------- |
+| Public tools described for a model, with field descriptions     | `src/printers/Printers.ts`       |
+| `readOnly`, `title`, `destructiveHint` and `idempotentHint`     | `src/printers/Printers.ts`       |
+| One declared error shared by every tool                         | `src/printers/Printers.ts`       |
+| An input a model cannot use to reach another URL                | `src/printers/Printers.ts`       |
+| A tool answering an image beside other fields                   | `src/printers/Printers.ts`       |
+| An upstream client reading `Config`, signing in once            | `src/printers/farm.ts`           |
+| An upstream's failures mapped to the declared error             | `src/printers/farm.ts`           |
+| A builder yielding a service, and handlers that only delegate   | `src/printers/handlers.ts`       |
+| Server `instructions`, shared by both transports                | `src/instructions.ts`            |
+| Allowed origins from `Config`, their CORS, and `/healthz`       | `src/routes.ts`                  |
+| A request body limit, and where an unauthenticated server binds | `src/server.ts`                  |
+| A stdio server whose logs go to stderr                          | `src/stdio.ts`                   |
+| A fake upstream provided as a Layer, to a test or an entrypoint | `src/printers/fake.ts`           |
+| Testing tools and each upstream failure's message in process    | `test/printers/printers.test.ts` |
+| Testing listed hints, an image and the origin check in memory   | `test/routes.test.ts`            |
+| Testing CORS for one configured origin and for several          | `test/routes.test.ts`            |

package/examples/mcp-tools/src/instructions.ts

@@ -0,0 +1,12 @@
+// What the server tells a client of itself, on either transport: `server.ts` and `stdio.ts`
+// both give it. `instructions` are for the model, as the tools' descriptions are: what the
+// tools are for together, and what to be careful with. A client shows them to the model once,
+// when it connects.
+export const serverInfo = {
+  name: "print-farm",
+  version: "1.0.0",
+  instructions:
+    "Tools for one 3D print farm. Printer ids come from list_printers; call it first. When a " +
+    "print may have failed, look at it with get_camera_snapshot and pause it with set_paused " +
+    "while deciding. cancel_print cannot be undone: ask the user before cancelling.",
+};