@gjermundgaraba/effect-actions 0.10.0 → 0.12.0

package/examples/mcp-tools/src/printers/Printers.ts

@@ -0,0 +1,119 @@
+import { Schema } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+
+export const Printer = Schema.Struct({
+  id: Schema.String,
+  name: Schema.String,
+  state: Schema.Literals(["idle", "printing", "paused", "offline"]),
+  job: Schema.NullOr(
+    Schema.Struct({
+      file: Schema.String,
+      progress: Schema.Finite.annotate({ description: "Percent done, 0 to 100." }),
+    }),
+  ),
+});
+
+export type Printer = typeof Printer.Type;
+
+// The one error every tool declares: the farm could not do what was asked. A model reads its
+// `message` and decides what to do next, so the message says what went wrong in plain words.
+// A handler failing with an error its action does not declare does not compile.
+export class PrintFarmError extends Schema.TaggedError<PrintFarmError>()("PrintFarmError", {
+  message: Schema.String,
+}) {}
+
+// A field's description is part of the tool's input schema, which is all a model knows of it.
+// The pattern is there for safety: an id becomes a segment of the farm's URL, and it comes
+// from a model. An id that does not match is refused as invalid input, on every surface,
+// before a handler runs, so `..` or `a/b` never reaches the farm. The `u` flag is what puts the
+// pattern in the tool's schema, where the model reads it.
+const PrinterId = Schema.String.check(Schema.isPattern(/^[A-Za-z0-9_-]+$/u)).annotate({
+  description: "A printer's id, as list_printers gives it, such as mk4-1.",
+});
+
+// What every tool here shares. `caller: Action.Anyone` makes an action public: this server
+// authenticates nobody, so it is reachable by whoever can reach the process.
+const tool = { caller: Action.Anyone, error: PrintFarmError } as const;
+
+// The names are snake_case because this server is tools only, and that is the convention MCP
+// tool names usually follow. An application whose actions are also typed client methods or CLI
+// commands names them in camelCase, as notes-service does.
+//
+// A description is written for the model that picks the tool: what it does, when to call it,
+// and what it answers. `readOnly` is sent as the tool's read-only hint; `mcp` holds the other
+// hints and the title a client shows its user.
+export const ListPrinters = Action.make("list_printers", {
+  ...tool,
+  description:
+    "List every printer of the farm: its id, name, state (idle, printing, paused or offline) " +
+    "and, when it has a job, the file being printed and its progress. Call this first: every " +
+    "other tool takes a printer id from this list.",
+  success: { printers: Schema.Array(Printer) },
+  readOnly: true,
+  mcp: { title: "List printers" },
+});
+
+// `image` is an `Action.Image` beside an ordinary field. Over MCP it is sent as an image block
+// the model can look at, after the JSON of `{ printer }`.
+export const GetCameraSnapshot = Action.make("get_camera_snapshot", {
+  ...tool,
+  description:
+    "Take a picture with a printer's camera, to judge a print by eye before pausing or " +
+    "cancelling it. Answers with the printer's state at that moment and the picture. An " +
+    "offline printer has no picture.",
+  input: { printer_id: PrinterId },
+  success: { printer: Printer, image: Action.Image },
+  readOnly: true,
+  mcp: { title: "Camera snapshot" },
+});
+
+// A write that adds something and removes nothing says so: MCP assumes a write is destructive
+// unless `destructiveHint` is false. A second call is refused, so it is not idempotent.
+export const StartPrint = Action.make("start_print", {
+  ...tool,
+  description:
+    "Start printing a file on an idle printer. The file is one already uploaded to the farm, " +
+    "named as the farm stores it. Refused when the printer is not idle.",
+  input: {
+    printer_id: PrinterId,
+    file: Schema.String.annotate({ description: "A G-code file's name, such as bracket.gcode." }),
+  },
+  success: Printer,
+  readOnly: false,
+  mcp: { title: "Start a print", destructiveHint: false },
+});
+
+// Idempotent: the same call again leaves the printer as the first left it.
+export const SetPaused = Action.make("set_paused", {
+  ...tool,
+  description:
+    "Pause a printer's job, or resume a paused one. A paused job keeps its progress, so " +
+    "pausing is the safe move while deciding what to do with a print that looks wrong.",
+  input: {
+    printer_id: PrinterId,
+    paused: Schema.Boolean.annotate({ description: "true to pause the job, false to resume it." }),
+  },
+  success: Printer,
+  readOnly: false,
+  mcp: { title: "Pause or resume a print", destructiveHint: false, idempotentHint: true },
+});
+
+// Destructive, which is MCP's default for a write, so no `destructiveHint` is stated.
+export const CancelPrint = Action.make("cancel_print", {
+  ...tool,
+  description:
+    "Cancel a printer's job for good. The print is abandoned and cannot be resumed, only " +
+    "started again from the beginning. A printer without a job is left as it is.",
+  input: { printer_id: PrinterId },
+  success: Printer,
+  readOnly: false,
+  mcp: { title: "Cancel a print", idempotentHint: true },
+});
+
+export const Printers = [
+  ListPrinters,
+  GetCameraSnapshot,
+  StartPrint,
+  SetPaused,
+  CancelPrint,
+] as const;

package/examples/mcp-tools/src/printers/fake.ts

@@ -0,0 +1,115 @@
+import { Buffer } from "node:buffer";
+import { Effect, Layer, Option, Schema } from "effect";
+import { HttpClient, HttpClientRequest, HttpClientResponse } from "effect/http";
+import type { Printer } from "./Printers.js";
+
+// DEMO ONLY: the farm's HTTP API answered in memory, so the example and its tests run without
+// a farm. It is an `HttpClient`, so `PrintFarm.layer` sends it the requests it would send over
+// the network. A real application has no such file: its entrypoints provide a real client,
+// `FetchHttpClient.layer` from `effect/http`.
+
+// A one-pixel PNG stands in for a camera's picture.
+export const picture = Uint8Array.from(
+  Buffer.from(
+    "iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAQAAAC1HAwCAAAAC0lEQVR42mNkYAAAAAYAAjCB0C8AAAAASUVORK5CYII=",
+    "base64",
+  ),
+);
+
+const token = "demo-session";
+
+const Login = Schema.fromJsonString(
+  Schema.Struct({ user: Schema.NonEmptyString, password: Schema.NonEmptyString }),
+);
+
+const Job = Schema.fromJsonString(Schema.Struct({ file: Schema.NonEmptyString }));
+
+const refuse = (status: number, error: string) => Response.json({ error }, { status });
+
+export const fakeFarm = Layer.sync(HttpClient.HttpClient, () => {
+  const printers = new Map<string, Printer>([
+    [
+      "mk4-1",
+      {
+        id: "mk4-1",
+        name: "MK4 by the door",
+        state: "printing",
+        job: { file: "bracket.gcode", progress: 62 },
+      },
+    ],
+    ["mk4-2", { id: "mk4-2", name: "MK4 by the window", state: "idle", job: null }],
+    ["mini-1", { id: "mini-1", name: "Mini on the shelf", state: "offline", job: null }],
+  ]);
+
+  const answer = (
+    method: string,
+    path: string,
+    authorization: string | undefined,
+    body: string,
+  ): Response => {
+    if (method === "POST" && path === "/api/login") {
+      return Option.match(Schema.decodeUnknownOption(Login)(body), {
+        onNone: () => refuse(400, "Give a user and a password."),
+        onSome: () => Response.json({ token }),
+      });
+    }
+
+    if (authorization !== `Bearer ${token}`) return refuse(401, "Sign in first.");
+
+    if (method === "GET" && path === "/api/printers") {
+      return Response.json({ printers: Array.from(printers.values()) });
+    }
+
+    const [id = "", action = ""] = path.replace("/api/printers/", "").split("/");
+    const printer = printers.get(id);
+
+    if (printer === undefined) return refuse(404, `No printer has the id ${id}.`);
+
+    const becomes = (state: Printer["state"], job: Printer["job"]) => {
+      const changed = { ...printer, state, job };
+
+      printers.set(printer.id, changed);
+
+      return Response.json(changed);
+    };
+
+    if (printer.state === "offline" && action !== "") {
+      return refuse(409, `${printer.name} is offline.`);
+    }
+
+    switch (`${method} ${action}`) {
+      case "GET ":
+        return Response.json(printer);
+      case "GET camera":
+        return new Response(picture, { headers: { "content-type": "image/png" } });
+      case "POST job":
+        return printer.job === null
+          ? Option.match(Schema.decodeUnknownOption(Job)(body), {
+              onNone: () => refuse(400, "Name the file to print."),
+              onSome: ({ file }) => becomes("printing", { file, progress: 0 }),
+            })
+          : refuse(409, `${printer.name} is busy with ${printer.job.file}.`);
+      case "POST pause":
+      case "POST resume":
+        return printer.job === null
+          ? refuse(409, `${printer.name} has no job.`)
+          : becomes(action === "pause" ? "paused" : "printing", printer.job);
+      case "DELETE job":
+        return becomes("idle", null);
+      default:
+        return refuse(404, `No such route: ${method} ${path}.`);
+    }
+  };
+
+  return HttpClient.make((request, url) =>
+    Effect.gen(function* () {
+      const sent = yield* Effect.orDie(HttpClientRequest.toWeb(request));
+      const body = yield* Effect.promise(() => sent.text());
+
+      return HttpClientResponse.fromWeb(
+        request,
+        answer(request.method, url.pathname, request.headers["authorization"], body),
+      );
+    }),
+  );
+});

package/examples/mcp-tools/src/printers/farm.ts

@@ -0,0 +1,136 @@
+import { Config, Context, Effect, Layer, Redacted, Schema } from "effect";
+import {
+  HttpBody,
+  HttpClient,
+  type HttpClientError,
+  HttpClientRequest,
+  HttpClientResponse,
+} from "effect/http";
+import type * as Action from "@gjermundgaraba/effect-actions/Action";
+import { Printer, PrintFarmError } from "./Printers.js";
+
+const fail = (message: string) => Effect.fail(new PrintFarmError({ message }));
+
+const unreadable = "The print farm sent an answer this server could not read.";
+
+// The farm answers a request it refuses with a status that is not 2xx and `{ "error": "..." }`.
+// Its reason is passed on to the model, which can act on "The printer is busy with a job".
+const refuseUnlessOk = HttpClientResponse.matchStatus({
+  "2xx": (response) => Effect.succeed(response),
+  orElse: (response) =>
+    HttpClientResponse.schemaBodyJson(Schema.Struct({ error: Schema.String }))(response).pipe(
+      Effect.matchEffect({
+        onFailure: () => fail(`The print farm refused the request (HTTP ${response.status}).`),
+        onSuccess: ({ error }) => fail(`The print farm refused: ${error}`),
+      }),
+    ),
+});
+
+// Every other way a call to the farm fails, as the same declared error: no connection, an
+// answer of another shape than expected, or none in time. Nothing of the HTTP client's own
+// errors leaves this file, so no tool can fail with something its contract does not declare.
+const asPrintFarmError = <A>(
+  effect: Effect.Effect<A, PrintFarmError | HttpClientError.HttpClientError | Schema.SchemaError>,
+) =>
+  effect.pipe(
+    Effect.catchTag("HttpClientError", ({ response }) =>
+      fail(response === undefined ? "The print farm could not be reached." : unreadable),
+    ),
+    Effect.catchTag("SchemaError", () => fail(unreadable)),
+    Effect.timeoutOrElse({
+      duration: "30 seconds",
+      orElse: () => fail("The print farm did not answer in time."),
+    }),
+  );
+
+const asImage = (response: HttpClientResponse.HttpClientResponse) =>
+  Effect.gen(function* () {
+    const mimeType = response.headers["content-type"];
+
+    if (mimeType === undefined || !mimeType.startsWith("image/")) return yield* fail(unreadable);
+
+    return { data: new Uint8Array(yield* response.arrayBuffer), mimeType };
+  });
+
+/**
+ * The print farm's HTTP API, the one upstream of this server. Its methods require nothing and
+ * fail only with the error the tools declare: the layer has captured the HTTP client, the
+ * farm's URL and the session.
+ */
+export class PrintFarm extends Context.Service<
+  PrintFarm,
+  {
+    readonly printers: Effect.Effect<ReadonlyArray<Printer>, PrintFarmError>;
+    readonly printer: (id: string) => Effect.Effect<Printer, PrintFarmError>;
+    readonly snapshot: (id: string) => Effect.Effect<typeof Action.Image.Type, PrintFarmError>;
+    readonly start: (id: string, file: string) => Effect.Effect<Printer, PrintFarmError>;
+    readonly setPaused: (id: string, paused: boolean) => Effect.Effect<Printer, PrintFarmError>;
+    readonly cancel: (id: string) => Effect.Effect<Printer, PrintFarmError>;
+  }
+>()("mcp-tools/PrintFarm") {
+  // Built once, when the process starts. It requires an `HttpClient` and reads its settings
+  // from `Config`: the entrypoint decides which client, and the environment says which farm.
+  // Not `fetch`: as a service, a test replaces the network alone and opens no port
+  // (test/printers/printers.test.ts).
+  static readonly layer = Layer.effect(
+    PrintFarm,
+    Effect.gen(function* () {
+      const { url, user, password } = yield* Config.all({
+        url: Config.URL("FARM_URL"),
+        user: Config.NonEmptyString("FARM_USER"),
+        password: Config.Redacted("FARM_PASSWORD"),
+      });
+
+      const http = (yield* HttpClient.HttpClient).pipe(
+        HttpClient.mapRequest(HttpClientRequest.prependUrl(url.href)),
+        HttpClient.transformResponse(Effect.flatMap(refuseUnlessOk)),
+      );
+
+      // Signs in once, here, and every call below reuses the token, kept `Redacted` so no log
+      // prints it. A farm that refuses the sign-in stops the process at startup, with its
+      // reason, before any tool is listed. A real client also signs in again when a call
+      // answers 401, as tokens expire.
+      const session = yield* http
+        .post("/api/login", {
+          body: HttpBody.jsonUnsafe({ user, password: Redacted.value(password) }),
+        })
+        .pipe(
+          Effect.flatMap(
+            HttpClientResponse.schemaBodyJson(
+              Schema.Struct({ token: Schema.RedactedFromValue(Schema.String) }),
+            ),
+          ),
+          asPrintFarmError,
+        );
+
+      yield* Effect.logInfo(`Signed in to the print farm at ${url.host} as ${user}.`);
+
+      const api = HttpClient.mapRequest(http, HttpClientRequest.bearerToken(session.token));
+
+      // An id is written into the path as it is: the contract admits only letters, digits,
+      // `_` and `-`, so it is always one segment. Encoding would not make other text safe:
+      // `encodeURIComponent` leaves `..` alone, and a URL parser then walks up the path.
+      const at = (id: string, rest = "") => `/api/printers/${id}${rest}`;
+
+      const printer = (answer: ReturnType<typeof api.get>) =>
+        answer.pipe(Effect.flatMap(HttpClientResponse.schemaBodyJson(Printer)), asPrintFarmError);
+
+      return PrintFarm.of({
+        printers: api.get("/api/printers").pipe(
+          Effect.flatMap(
+            HttpClientResponse.schemaBodyJson(Schema.Struct({ printers: Schema.Array(Printer) })),
+          ),
+          Effect.map(({ printers }) => printers),
+          asPrintFarmError,
+        ),
+        printer: (id) => printer(api.get(at(id))),
+        snapshot: (id) =>
+          api.get(at(id, "/camera")).pipe(Effect.flatMap(asImage), asPrintFarmError),
+        start: (id, file) =>
+          printer(api.post(at(id, "/job"), { body: HttpBody.jsonUnsafe({ file }) })),
+        setPaused: (id, paused) => printer(api.post(at(id, paused ? "/pause" : "/resume"))),
+        cancel: (id) => printer(api.del(at(id, "/job"))),
+      });
+    }),
+  );
+}

package/examples/mcp-tools/src/printers/handlers.ts

@@ -0,0 +1,29 @@
+import { Effect } from "effect";
+import * as Action from "@gjermundgaraba/effect-actions/Action";
+import { PrintFarm } from "./farm.js";
+import { Printers } from "./Printers.js";
+
+// The builder runs once, when the server starts, whichever transport serves the tools: it is
+// where the handlers get the farm, already signed in. Each handler is a step from a tool's
+// input to the service and back to the tool's success. None handles a failure: the service
+// fails only with `PrintFarmError`, which every tool declares, so it reaches the model as is.
+// Public actions take no `authorize`.
+export const printers = Action.implement(
+  Printers,
+  Effect.gen(function* () {
+    const farm = yield* PrintFarm;
+
+    return {
+      list_printers: () => Effect.map(farm.printers, (all) => ({ printers: all })),
+      // Returned as `{ data, mimeType }` like any other field: the MCP surface makes the block.
+      get_camera_snapshot: ({ printer_id }) =>
+        Effect.all(
+          { printer: farm.printer(printer_id), image: farm.snapshot(printer_id) },
+          { concurrency: "unbounded" },
+        ),
+      start_print: ({ printer_id, file }) => farm.start(printer_id, file),
+      set_paused: ({ printer_id, paused }) => farm.setPaused(printer_id, paused),
+      cancel_print: ({ printer_id }) => farm.cancel(printer_id),
+    };
+  }),
+);

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

@@ -0,0 +1,52 @@
+import { Config, Effect, Layer, Schema } from "effect";
+import { HttpRouter, HttpServerResponse } from "effect/http";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { serverInfo } from "./instructions.js";
+import { printers } from "./printers/handlers.js";
+
+// The tools at `/mcp` and the host's own route beside them. It is a Layer built from `Config`
+// because the origins are known only where the server is deployed.
+export const routes = Layer.unwrap(
+  Effect.gen(function* () {
+    // A browser sends its page's `Origin`, and the endpoint refuses every origin not listed
+    // here, so a web page a user happens to visit cannot call the tools. Other MCP clients
+    // send none and pass. `ALLOWED_ORIGINS=https://a.example,https://b.example`; none by default.
+    const allowedOrigins = yield* Config.Array(Schema.String, "ALLOWED_ORIGINS").pipe(
+      Config.withDefault([]),
+    );
+
+    // The Origin check only refuses. A browser also needs CORS: an answer to its preflight, and
+    // headers on the endpoint's answers. `HttpRouter.cors` is global to the router and, given
+    // no origin, allows every one, so it is added only where an origin is configured. The
+    // methods are the endpoint's, the headers those an MCP client sends and must be able to
+    // read; an endpoint with authentication adds `Authorization` and exposes `WWW-Authenticate`.
+    //
+    // Given several origins it names the request's own in `Access-Control-Allow-Origin` when
+    // it is listed, and sends no such header otherwise. Given exactly one it compares nothing:
+    // every answer names that origin, a preflight from elsewhere included. Both refuse a page
+    // elsewhere, whose browser allows a call only where the header names the page's own origin,
+    // and the Origin check above has answered its request 403 either way. So a test of one
+    // configured origin asserts which origin is named, never that the header is absent.
+    const cors =
+      allowedOrigins.length === 0
+        ? Layer.empty
+        : HttpRouter.cors({
+            allowedOrigins,
+            allowedMethods: ["POST", "DELETE"],
+            allowedHeaders: [
+              "Content-Type",
+              "MCP-Protocol-Version",
+              "MCP-Method",
+              "MCP-Name",
+              "Mcp-Session-Id",
+            ],
+            exposedHeaders: ["MCP-Protocol-Version", "Mcp-Session-Id"],
+          });
+
+    return Layer.mergeAll(
+      // No `authentication`: every tool is public, so the endpoint authenticates nothing.
+      ActionMcp.layerHttp(printers, { ...serverInfo, allowedOrigins }),
+      HttpRouter.add("GET", "/healthz", HttpServerResponse.text("ok")),
+    ).pipe(Layer.provide(cors));
+  }),
+);

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

@@ -0,0 +1,30 @@
+import { createServer } from "node:http";
+import { NodeHttpServer, NodeRuntime } from "@effect/platform-node";
+import { ByteSize, Config, Effect, Layer } from "effect";
+import { HttpRouter, HttpServerRequest } from "effect/http";
+import { fakeFarm } from "./printers/fake.js";
+import { PrintFarm } from "./printers/farm.js";
+import { routes } from "./routes.js";
+
+// Entrypoint: `node --import tsx examples/mcp-tools/src/server.ts`, with FARM_URL, FARM_USER
+// and FARM_PASSWORD set. MCP over HTTP, for clients that connect to a URL.
+// Nothing here authenticates a caller, so where it listens is its access control: the loopback
+// interface by default, or a network only trusted clients are on.
+const server = Layer.unwrap(
+  Effect.gen(function* () {
+    const host = yield* Config.String("HOST").pipe(Config.withDefault("127.0.0.1"));
+    const port = yield* Config.Port("PORT").pipe(Config.withDefault(3000));
+
+    return HttpRouter.serve(routes).pipe(
+      Layer.provide(NodeHttpServer.layer(createServer, { host, port })),
+      // Request bodies have no size limit unless the host sets one. A tool call is a few
+      // short fields, so anything larger is not one.
+      Layer.provide(Layer.succeed(HttpServerRequest.MaxBodySize, ByteSize.kibibytes(64))),
+      // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
+      // `FetchHttpClient.layer` in its place, and `PrintFarm.layer` calls the farm at FARM_URL.
+      Layer.provide(PrintFarm.layer.pipe(Layer.provide(fakeFarm))),
+    );
+  }),
+);
+
+Layer.launch(server).pipe(NodeRuntime.runMain);

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

@@ -0,0 +1,26 @@
+import { NodeRuntime, NodeStdio } from "@effect/platform-node";
+import { Effect, Layer } from "effect";
+import * as ActionCli from "@gjermundgaraba/effect-actions/ActionCli";
+import * as ActionMcp from "@gjermundgaraba/effect-actions/ActionMcp";
+import { serverInfo } from "./instructions.js";
+import { fakeFarm } from "./printers/fake.js";
+import { PrintFarm } from "./printers/farm.js";
+import { printers } from "./printers/handlers.js";
+
+// Entrypoint: an MCP server a local agent starts as a subprocess, with FARM_URL, FARM_USER and
+// FARM_PASSWORD in its environment. The README has the line that adds it to Claude Code and
+// its entry in Claude Desktop's configuration.
+// The same implementation and the same server information as the HTTP server, and no port:
+// the agent's host starts the process, writes requests to its stdin, and closes it to stop it.
+ActionMcp.runStdio(printers, serverInfo).pipe(
+  Effect.provide([
+    NodeStdio.layer,
+    // DEMO ONLY: `fakeFarm` answers the farm's API in memory. A real server provides
+    // `FetchHttpClient.layer` in its place.
+    PrintFarm.layer.pipe(Layer.provide(fakeFarm)),
+  ]),
+  // stdout carries the protocol alone. Applied last, this sends every log to stderr, the
+  // sign-in line `PrintFarm.layer` logs included, and a startup failure too.
+  ActionCli.logToStderr,
+  NodeRuntime.runMain,
+);