holon-sh 0.0.1-dev.14 → 0.0.1-dev.16

package/README.md

@@ -122,6 +122,50 @@ A refused subscription is answered Forbidden, and access is checked again at eac
 
 Poll and push delivery are here, with targeted emits, subscription hooks, authorization, ending subscriptions, limits, paged listing and removing event types. Webhook delivery and check functions, which read a source that keeps its own history, are not, and neither are typed event names. Clients are not told when the event types change: they list them again.
 
+## Run an app without Holon
+
+`holon-sh/serve` serves an app's module at the paths Holon gives it, so the app also runs wherever Node does:
+
+```ts
+import { serve } from "holon-sh/serve";
+
+await serve(await import("./server.ts"));
+```
+
+The MCP endpoint is at `/mcp` and `/mcp/<app>`, and the files of `frontend` are at every other path. `PORT` and `HOST` change where it listens, 127.0.0.1:3000 unless they are set. Holon answers clients of the 2025 MCP versions in front of an app, and here the app's handler answers them, so create it without `legacy: "reject"`.
+
+## The caller and the origin
+
+`getContext` reads who called a tool, and where the app was reached, so a link the app makes works wherever it runs:
+
+```ts
+import { getContext } from "holon-sh/context";
+
+server.registerTool("share", { description: "Links to the page" }, ctx => {
+  const { principal, origin } = getContext(ctx.http);
+  return { content: [{ type: "text", text: `${origin}/?by=${principal?.subject}` }] };
+});
+```
+
+`principal` is the user Holon admitted, or null. `origin` is the one Holon or a proxy forwards, or else the one the request reached.
+
+## A page in MCP Apps hosts
+
+`holon-sh/page` offers an app's page, built as one HTML file, as the view an MCP Apps host shows with a tool's result:
+
+```ts
+import { createPage } from "holon-sh/page";
+
+const page = createPage(new URL("./dist/mcp/index.html", import.meta.url));
+
+function createServer() {
+  const server = new McpServer({ name: "foo", version: "0.1.0" });
+  server.registerTool("open", { description: "Opens the page", _meta: page.meta }, open);
+  page.serve(server);
+  return server;
+}
+```
+
 ## Community
 
 Ask questions and share what you're building on the [Holon Discord](https://discord.gg/jXExyBdy).

package/dist/context.d.ts

@@ -40,16 +40,19 @@ export interface Principal {
     claims: IdentityClaims;
     actor?: Record<string, unknown>;
 }
-/** The caller of the current MCP request. principal is null for anonymous requests. */
+/** The caller of the current MCP request, and the origin it reached the app at. principal is null for anonymous requests, and origin without HTTP. */
 export interface RequestContext {
     principal: Principal | null;
+    origin: string | null;
 }
-/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+/** Read the caller and the app's origin from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
 export declare function getContext(context?: {
     authInfo?: {
         clientId: string;
         scopes: string[];
         extra?: Record<string, unknown>;
     };
+    req?: Request;
+    requestInfo?: Request;
 }): RequestContext;
 //# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yHAAyH;AACzH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAClG,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IACrG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AAC3J,uFAAuF;AACvF,MAAM,WAAW,cAAc;IAAG,SAAS,EAAE,SAAS,GAAG,IAAI,CAAA;CAAE;AAM/D,mJAAmJ;AACnJ,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAA;CAAO,GAAG,cAAc,CAK/I"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA,8CAA8C;AAC9C,MAAM,WAAW,aAAa;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,cAAc,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IACxH,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yHAAyH;AACzH,MAAM,WAAW,cAAc;IAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClG,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAClG,cAAc,CAAC,EAAE,OAAO,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IAClG,YAAY,CAAC,EAAE,MAAM,CAAC;IAAC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAAC,OAAO,CAAC,EAAE,aAAa,CAAC;IAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IACrG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC;CAC1B;AACD,yDAAyD;AACzD,MAAM,WAAW,SAAS;IAAG,MAAM,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,cAAc,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAAE;AAC3J,sJAAsJ;AACtJ,MAAM,WAAW,cAAc;IAAG,SAAS,EAAE,SAAS,GAAG,IAAI,CAAC;IAAC,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE;AAMtF,wKAAwK;AACxK,wBAAgB,UAAU,CAAC,OAAO,GAAE;IAAE,QAAQ,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;KAAE,CAAC;IAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IAAC,WAAW,CAAC,EAAE,OAAO,CAAA;CAAO,GAAG,cAAc,CAMrL"}

package/dist/context.js

@@ -1,9 +1,15 @@
-/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+/** Read the caller and the app's origin from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
 export function getContext(context = {}) {
-    const { authInfo } = context;
+    const { authInfo, req = context.requestInfo } = context;
     const { iss, sub, claims, act } = (authInfo?.extra ?? {});
-    if (!authInfo || typeof iss !== "string" || typeof sub !== "string")
-        return { principal: null };
-    return { principal: { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) } };
+    const principal = !authInfo || typeof iss !== "string" || typeof sub !== "string" ? null
+        : { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) };
+    return { principal, origin: req ? origin(req) : null };
+}
+// Holon forwards the origin it serves the app at, as a proxy in front may. Otherwise the request reached the app where it
+// listens.
+function origin({ url, headers }) {
+    const { protocol, host } = new URL(url);
+    return `${headers.get("x-forwarded-proto") ?? protocol.slice(0, -1)}://${headers.get("x-forwarded-host") ?? host}`;
 }
 //# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAsBA,mJAAmJ;AACnJ,MAAM,UAAU,UAAU,CAAC,OAAO,GAA2F,EAAE;IAC7H,MAAM,EAAE,QAAQ,EAAE,GAAG,OAAO,CAAC;IAC7B,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAa,CAAC;IACtE,IAAI,CAAC,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ;QAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC;IAChG,OAAO,EAAE,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,EAAE,CAAC;AAC9J,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAsBA,wKAAwK;AACxK,MAAM,UAAU,UAAU,CAAC,OAAO,GAAiI,EAAE;IACnK,MAAM,EAAE,QAAQ,EAAE,GAAG,GAAG,OAAO,CAAC,WAAW,EAAE,GAAG,OAAO,CAAC;IACxD,MAAM,EAAE,GAAG,EAAE,GAAG,EAAE,MAAM,EAAE,GAAG,EAAE,GAAG,CAAC,QAAQ,EAAE,KAAK,IAAI,EAAE,CAAa,CAAC;IACtE,MAAM,SAAS,GAAG,CAAC,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,IAAI,OAAO,GAAG,KAAK,QAAQ,CAAC,CAAC,CAAC,IAAI;QACtF,CAAC,CAAC,EAAE,MAAM,EAAE,GAAG,EAAE,OAAO,EAAE,GAAG,EAAE,QAAQ,EAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,EAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,EAAE,MAAM,IAAI,EAAE,EAAE,GAAG,CAAC,GAAG,IAAI,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,EAAE,CAAC;IAC1I,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC;AACzD,CAAC;AAED,0HAA0H;AAC1H,WAAW;AACX,SAAS,MAAM,CAAC,EAAE,GAAG,EAAE,OAAO,EAAW;IACvC,MAAM,EAAE,QAAQ,EAAE,IAAI,EAAE,GAAG,IAAI,GAAG,CAAC,GAAG,CAAC,CAAC;IACxC,OAAO,GAAG,OAAO,CAAC,GAAG,CAAC,mBAAmB,CAAC,IAAI,QAAQ,CAAC,KAAK,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,OAAO,CAAC,GAAG,CAAC,kBAAkB,CAAC,IAAI,IAAI,EAAE,CAAC;AACrH,CAAC"}

package/dist/page.d.ts

@@ -0,0 +1,24 @@
+import type { McpServer } from "@modelcontextprotocol/server";
+/** An app's page, as the view an MCP Apps host shows with a tool's result. */
+export interface Page {
+    /** A tool's `_meta`, so that hosts show the page with what the tool returns. */
+    meta: {
+        ui: {
+            resourceUri: string;
+        };
+    };
+    /** Offers the page to a server's clients as its view. */
+    serve(server: Pick<McpServer, "registerResource">): void;
+}
+/**
+ * Makes an app's page a view: `file` is the page built as one HTML file, and `ui` the view's `_meta.ui`, such as its
+ * `csp`.
+ *
+ * ```ts
+ * const page = createPage(new URL("../dist/mcp/index.html", import.meta.url));
+ * server.registerTool("open", { description: "Opens it", _meta: page.meta }, open);
+ * page.serve(server);
+ * ```
+ */
+export declare function createPage(file: URL, ui?: Record<string, unknown>): Page;
+//# sourceMappingURL=page.d.ts.map

package/dist/page.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.d.ts","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,8BAA8B,CAAC;AAQ9D,8EAA8E;AAC9E,MAAM,WAAW,IAAI;IACnB,gFAAgF;IAChF,IAAI,EAAE;QAAE,EAAE,EAAE;YAAE,WAAW,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,CAAC;IACtC,yDAAyD;IACzD,KAAK,CAAC,MAAM,EAAE,IAAI,CAAC,SAAS,EAAE,kBAAkB,CAAC,GAAG,IAAI,CAAC;CAC1D;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,GAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAM,GAAG,IAAI,CAQ5E"}

package/dist/page.js

@@ -0,0 +1,25 @@
+import { readFile } from "node:fs/promises";
+// MCP Apps names a view with a ui:// URI and serves it as this type. An app has one page, so the URI names no app and
+// survives renaming one.
+// https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+const uri = "ui://page";
+const mimeType = "text/html;profile=mcp-app";
+/**
+ * Makes an app's page a view: `file` is the page built as one HTML file, and `ui` the view's `_meta.ui`, such as its
+ * `csp`.
+ *
+ * ```ts
+ * const page = createPage(new URL("../dist/mcp/index.html", import.meta.url));
+ * server.registerTool("open", { description: "Opens it", _meta: page.meta }, open);
+ * page.serve(server);
+ * ```
+ */
+export function createPage(file, ui = {}) {
+    return {
+        meta: { ui: { resourceUri: uri } },
+        serve: server => void server.registerResource("Page", uri, { mimeType }, async () => ({
+            contents: [{ uri, mimeType, text: await readFile(file, "utf8"), _meta: { ui } }],
+        })),
+    };
+}
+//# sourceMappingURL=page.js.map

package/dist/page.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"page.js","sourceRoot":"","sources":["../src/page.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,kBAAkB,CAAC;AAG5C,sHAAsH;AACtH,yBAAyB;AACzB,+FAA+F;AAC/F,MAAM,GAAG,GAAG,WAAW,CAAC;AACxB,MAAM,QAAQ,GAAG,2BAA2B,CAAC;AAU7C;;;;;;;;;GASG;AACH,MAAM,UAAU,UAAU,CAAC,IAAS,EAAE,EAAE,GAA4B,EAAE;IACpE,OAAO;QACL,IAAI,EAAE,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE;QAClC,KAAK,EAAE,MAAM,CAAC,EAAE,CACd,KAAK,MAAM,CAAC,gBAAgB,CAAC,MAAM,EAAE,GAAG,EAAE,EAAE,QAAQ,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC;YACnE,QAAQ,EAAE,CAAC,EAAE,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,MAAM,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,EAAE,KAAK,EAAE,EAAE,EAAE,EAAE,EAAE,CAAC;SACjF,CAAC,CAAC;KACN,CAAC;AACJ,CAAC"}

package/dist/serve.d.ts

@@ -0,0 +1,22 @@
+import { type Server } from "node:http";
+/** An app's module: the MCP handler it exports by default, and the directory of its page. */
+export interface App {
+    default: {
+        fetch(request: Request): Promise<Response>;
+    };
+    /** The directory of the page's files, as a file URL. */
+    frontend?: URL;
+}
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export declare function serve({ default: handler, frontend }: App): Promise<Server>;
+//# sourceMappingURL=serve.d.ts.map

package/dist/serve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.d.ts","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"AAEA,OAAO,EAAsC,KAAK,MAAM,EAAuB,MAAM,WAAW,CAAC;AAMjG,6FAA6F;AAC7F,MAAM,WAAW,GAAG;IAClB,OAAO,EAAE;QAAE,KAAK,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAA;KAAE,CAAC;IACxD,wDAAwD;IACxD,QAAQ,CAAC,EAAE,GAAG,CAAC;CAChB;AAED;;;;;;;;;;GAUG;AACH,wBAAsB,KAAK,CAAC,EAAE,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,EAAE,GAAG,GAAG,OAAO,CAAC,MAAM,CAAC,CAiBhF"}

package/dist/serve.js

@@ -0,0 +1,69 @@
+import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+import { createServer } from "node:http";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import mime from "mime";
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export async function serve({ default: handler, frontend }) {
+    const { PORT = "3000", HOST = "127.0.0.1" } = process.env;
+    // A directory's URL ends in `/`. Without it, a name would resolve beside the directory instead of in it.
+    const directory = frontend && new URL(frontend.href.replace(/\/?$/, "/"));
+    const server = createServer((req, res) => respond(handler, directory, req, res).catch((error) => {
+        console.error(error);
+        if (!res.headersSent)
+            res.writeHead(500);
+        res.end();
+    }));
+    server.listen(Number(PORT), HOST);
+    await once(server, "listening");
+    const { port } = server.address();
+    const origin = `http://${HOST.includes(":") ? `[${HOST}]` : HOST}:${port}`;
+    console.log(`Serving ${origin}/ with the MCP endpoint at ${origin}/mcp`);
+    return server;
+}
+async function respond(handler, directory, req, res) {
+    const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+    if (/^\/mcp(\/[^/]+)?$/.test(url.pathname)) {
+        const gone = new AbortController();
+        res.on("close", () => gone.abort());
+        const headers = new Headers();
+        for (const [name, values = []] of Object.entries(req.headersDistinct))
+            for (const value of values)
+                headers.append(name, value);
+        const body = req.method === "GET" || req.method === "HEAD" ? undefined : req;
+        const response = await handler.fetch(new Request(url, { method: req.method, headers, body, duplex: "half", signal: gone.signal }));
+        res.setHeaders(response.headers).writeHead(response.status);
+        // When the client leaves, pipeline cancels the body, so a stream between events ends then and not at its next
+        // write. Either side failing ends the response, which is all there is to do.
+        if (response.body)
+            await pipeline(Readable.fromWeb(response.body), res).catch(() => { });
+        else
+            res.end();
+        return;
+    }
+    if (!directory || (req.method !== "GET" && req.method !== "HEAD"))
+        return void res.writeHead(404).end();
+    const name = url.pathname.endsWith("/") ? `${url.pathname}index.html` : url.pathname;
+    // The URL parser has resolved every `..`, and a file URL may not encode `/`, so no name leads out of the directory.
+    // Like Holon, serve nothing hidden, however its dot is spelled, and treat what cannot be read, such as a directory, as
+    // not found.
+    const contents = /\/(\.|%2e)/i.test(name) ? undefined : await readFile(new URL(`.${name}`, directory)).catch(() => undefined);
+    if (!contents)
+        return void res.writeHead(404).end();
+    // Like Holon, take the type from the MIME database, and call text UTF-8, which a built page is.
+    const type = mime.getType(name) ?? "application/octet-stream";
+    const contentType = type.startsWith("text/") ? `${type}; charset=utf-8` : type;
+    res.writeHead(200, { "content-type": contentType, "x-content-type-options": "nosniff" }).end(contents);
+}
+//# sourceMappingURL=serve.js.map

package/dist/serve.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"serve.js","sourceRoot":"","sources":["../src/serve.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "holon-sh",
-  "version": "0.0.1-dev.14",
+  "version": "0.0.1-dev.16",
   "description": "Typed MCP clients, MCP Events, and the caller of an MCP request, for Node.js.",
   "repository": {
     "type": "git",
@@ -35,6 +35,14 @@
     "./ext/files": {
       "types": "./dist/ext/files.d.ts",
       "import": "./dist/ext/files.js"
+    },
+    "./serve": {
+      "types": "./dist/serve.d.ts",
+      "import": "./dist/serve.js"
+    },
+    "./page": {
+      "types": "./dist/page.d.ts",
+      "import": "./dist/page.js"
     }
   },
   "typesVersions": {
@@ -53,6 +61,12 @@
       ],
       "ext/files": [
         "./dist/ext/files.d.ts"
+      ],
+      "serve": [
+        "./dist/serve.d.ts"
+      ],
+      "page": [
+        "./dist/page.d.ts"
       ]
     }
   },
@@ -73,6 +87,7 @@
   "dependencies": {
     "@modelcontextprotocol/client": "^2.3.1",
     "ipaddr.js": "^2.5.0",
+    "mime": "^4.1.2",
     "undici": "^7.16.0"
   },
   "peerDependencies": {

package/src/context.ts

@@ -13,17 +13,25 @@ export interface IdentityClaims {
 }
 /** The user a request acts for, as Holon admitted it. */
 export interface Principal { issuer: string; subject: string; clientId: string; scopes: string[]; claims: IdentityClaims; actor?: Record<string, unknown> }
-/** The caller of the current MCP request. principal is null for anonymous requests. */
-export interface RequestContext { principal: Principal | null }
+/** The caller of the current MCP request, and the origin it reached the app at. principal is null for anonymous requests, and origin without HTTP. */
+export interface RequestContext { principal: Principal | null; origin: string | null }
 
 // Holon admits the caller before the request reaches the server and hands it over as MCP's authInfo, with claims and
 // act in these shapes.
 interface Admitted { iss?: unknown; sub?: unknown; claims?: IdentityClaims; act?: Record<string, unknown> }
 
-/** Read the caller from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
-export function getContext(context: { authInfo?: { clientId: string; scopes: string[]; extra?: Record<string, unknown> } } = {}): RequestContext {
-  const { authInfo } = context;
+/** Read the caller and the app's origin from the context an MCP server receives: a tool callback's ctx.http, or the McpRequestContext of a createMcpHandler factory. */
+export function getContext(context: { authInfo?: { clientId: string; scopes: string[]; extra?: Record<string, unknown> }; req?: Request; requestInfo?: Request } = {}): RequestContext {
+  const { authInfo, req = context.requestInfo } = context;
   const { iss, sub, claims, act } = (authInfo?.extra ?? {}) as Admitted;
-  if (!authInfo || typeof iss !== "string" || typeof sub !== "string") return { principal: null };
-  return { principal: { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) } };
+  const principal = !authInfo || typeof iss !== "string" || typeof sub !== "string" ? null
+    : { issuer: iss, subject: sub, clientId: authInfo.clientId, scopes: authInfo.scopes, claims: claims ?? {}, ...(act && { actor: act }) };
+  return { principal, origin: req ? origin(req) : null };
+}
+
+// Holon forwards the origin it serves the app at, as a proxy in front may. Otherwise the request reached the app where it
+// listens.
+function origin({ url, headers }: Request) {
+  const { protocol, host } = new URL(url);
+  return `${headers.get("x-forwarded-proto") ?? protocol.slice(0, -1)}://${headers.get("x-forwarded-host") ?? host}`;
 }

package/src/page.ts

@@ -0,0 +1,36 @@
+import { readFile } from "node:fs/promises";
+import type { McpServer } from "@modelcontextprotocol/server";
+
+// MCP Apps names a view with a ui:// URI and serves it as this type. An app has one page, so the URI names no app and
+// survives renaming one.
+// https://github.com/modelcontextprotocol/ext-apps/blob/main/specification/2026-01-26/apps.mdx
+const uri = "ui://page";
+const mimeType = "text/html;profile=mcp-app";
+
+/** An app's page, as the view an MCP Apps host shows with a tool's result. */
+export interface Page {
+  /** A tool's `_meta`, so that hosts show the page with what the tool returns. */
+  meta: { ui: { resourceUri: string } };
+  /** Offers the page to a server's clients as its view. */
+  serve(server: Pick<McpServer, "registerResource">): void;
+}
+
+/**
+ * Makes an app's page a view: `file` is the page built as one HTML file, and `ui` the view's `_meta.ui`, such as its
+ * `csp`.
+ *
+ * ```ts
+ * const page = createPage(new URL("../dist/mcp/index.html", import.meta.url));
+ * server.registerTool("open", { description: "Opens it", _meta: page.meta }, open);
+ * page.serve(server);
+ * ```
+ */
+export function createPage(file: URL, ui: Record<string, unknown> = {}): Page {
+  return {
+    meta: { ui: { resourceUri: uri } },
+    serve: server =>
+      void server.registerResource("Page", uri, { mimeType }, async () => ({
+        contents: [{ uri, mimeType, text: await readFile(file, "utf8"), _meta: { ui } }],
+      })),
+  };
+}

package/src/serve.ts

@@ -0,0 +1,73 @@
+import { once } from "node:events";
+import { readFile } from "node:fs/promises";
+import { createServer, type IncomingMessage, type Server, type ServerResponse } from "node:http";
+import type { AddressInfo } from "node:net";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import mime from "mime";
+
+/** An app's module: the MCP handler it exports by default, and the directory of its page. */
+export interface App {
+  default: { fetch(request: Request): Promise<Response> };
+  /** The directory of the page's files, as a file URL. */
+  frontend?: URL;
+}
+
+/**
+ * Runs an app without Holon, at the paths Holon gives it: the MCP endpoint at `/mcp` and `/mcp/<app>`, and the page's
+ * files everywhere else. Listens on `PORT` and `HOST`, or else on 127.0.0.1:3000.
+ *
+ * ```ts
+ * await serve(await import("./server.ts"));
+ * ```
+ *
+ * Holon answers clients of the 2025 MCP versions in front of an app. Here the handler answers them, so create it
+ * without `legacy: "reject"`.
+ */
+export async function serve({ default: handler, frontend }: App): Promise<Server> {
+  const { PORT = "3000", HOST = "127.0.0.1" } = process.env;
+  // A directory's URL ends in `/`. Without it, a name would resolve beside the directory instead of in it.
+  const directory = frontend && new URL(frontend.href.replace(/\/?$/, "/"));
+  const server = createServer((req, res) =>
+    respond(handler, directory, req, res).catch((error: unknown) => {
+      console.error(error);
+      if (!res.headersSent) res.writeHead(500);
+      res.end();
+    }),
+  );
+  server.listen(Number(PORT), HOST);
+  await once(server, "listening");
+  const { port } = server.address() as AddressInfo;
+  const origin = `http://${HOST.includes(":") ? `[${HOST}]` : HOST}:${port}`;
+  console.log(`Serving ${origin}/ with the MCP endpoint at ${origin}/mcp`);
+  return server;
+}
+
+async function respond(handler: App["default"], directory: URL | undefined, req: IncomingMessage, res: ServerResponse) {
+  const url = new URL(req.url ?? "/", `http://${req.headers.host ?? "localhost"}`);
+  if (/^\/mcp(\/[^/]+)?$/.test(url.pathname)) {
+    const gone = new AbortController();
+    res.on("close", () => gone.abort());
+    const headers = new Headers();
+    for (const [name, values = []] of Object.entries(req.headersDistinct)) for (const value of values) headers.append(name, value);
+    const body = req.method === "GET" || req.method === "HEAD" ? undefined : req;
+    const response = await handler.fetch(new Request(url, { method: req.method, headers, body, duplex: "half", signal: gone.signal }));
+    res.setHeaders(response.headers).writeHead(response.status);
+    // When the client leaves, pipeline cancels the body, so a stream between events ends then and not at its next
+    // write. Either side failing ends the response, which is all there is to do.
+    if (response.body) await pipeline(Readable.fromWeb(response.body), res).catch(() => {});
+    else res.end();
+    return;
+  }
+  if (!directory || (req.method !== "GET" && req.method !== "HEAD")) return void res.writeHead(404).end();
+  const name = url.pathname.endsWith("/") ? `${url.pathname}index.html` : url.pathname;
+  // The URL parser has resolved every `..`, and a file URL may not encode `/`, so no name leads out of the directory.
+  // Like Holon, serve nothing hidden, however its dot is spelled, and treat what cannot be read, such as a directory, as
+  // not found.
+  const contents = /\/(\.|%2e)/i.test(name) ? undefined : await readFile(new URL(`.${name}`, directory)).catch(() => undefined);
+  if (!contents) return void res.writeHead(404).end();
+  // Like Holon, take the type from the MIME database, and call text UTF-8, which a built page is.
+  const type = mime.getType(name) ?? "application/octet-stream";
+  const contentType = type.startsWith("text/") ? `${type}; charset=utf-8` : type;
+  res.writeHead(200, { "content-type": contentType, "x-content-type-options": "nosniff" }).end(contents);
+}