holon-sh 0.0.0-stage → 0.0.1-dev.3

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Holon Systems, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,109 @@
-# Temporary Holding Version
+# Holon TypeScript SDK
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[![CI](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/holon-sh/sdk-ts/actions/workflows/ci.yml)
+[![Node.js](https://img.shields.io/badge/Node.js-22%2B-5FA04E?logo=node.js&logoColor=white)](https://nodejs.org/en/download)
+[![MIT License](https://img.shields.io/badge/license-MIT-green)](https://github.com/holon-sh/sdk-ts/blob/main/LICENSE)
+
+This repository contains the Node.js runtime for [`holon`](https://github.com/holon-sh/cli).
+
+## Install
+
+```sh
+npm install holon-sh@dev
+npm install -D holon-types
+```
+
+`holon-types` is the `holon` CLI. `holon types check` brings its own TypeScript compiler and uses the project's `typescript` when one is installed.
+
+## Invoking MCP Servers
+
+The Holon TypeScript SDK allows generation of type-safe MCP clients. See [Example](https://github.com/holon-sh/cli#example) for an explanation, or [Dependencies](https://github.com/holon-sh/cli#dependencies) to understand dependency resolution.
+
+### Type-checking MCP invocations
+
+```sh
+npx holon types check
+```
+
+<details open>
+<summary><h3>Call a tool</h3></summary>
+
+```ts
+import { apps } from "holon-sh";
+
+export async function greet(name: string): Promise<string> {
+  const greeting = await apps.bar.tools.greet({ name }, { timeout: 5000 });
+  return greeting.result;
+}
+```
+
+Arguments are validated before sending; the result is validated against the output schema and returned.
+
+</details>
+
+<details open>
+<summary><h3>Handle errors</h3></summary>
+
+```ts
+import { ToolCallError, apps } from "holon-sh";
+
+try {
+  await apps.bar.tools.greet({ name: "world" });
+} catch (error) {
+  if (!(error instanceof ToolCallError)) throw error;
+  error.code;   // "tool_error" | "input_required"
+  error.result; // the original MCP result
+}
+```
+
+</details>
+
+<details open>
+<summary><h3>Read the whole result</h3></summary>
+
+`callTool` returns the full MCP result instead of throwing:
+
+```ts
+const result = await apps.bar.callTool({ name: "greet", arguments: { name: "world" } });
+if (result.resultType === "input_required") {
+  // call again with inputResponses and requestState
+} else if (result.isError) {
+  // inspect result.content
+} else {
+  result.structuredContent; // typed as Outputs["bar"]["greet"]
+}
+```
+
+</details>
+
+<details open>
+<summary><h3>Read a resource</h3></summary>
+
+A provider types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`, as the `orders` server in `tests/fixtures` does. The client then offers `read` and `watch`:
+
+```ts
+const summary = await apps.orders.resources["orders://summary"].read();
+
+const controller = new AbortController();
+await apps.orders.resources["orders://summary"].watch(value => console.log(value.total), {
+  signal: controller.signal,
+});
+```
+
+`watch` calls back with the current value, then on every update, until the signal aborts. It needs an endpoint binding and a server that supports resource subscriptions.
+
+</details>
+
+## Serve an [MCP App](https://modelcontextprotocol.io/extensions/apps/overview) view
+
+```ts
+import { appView } from "holon-sh/view";
+
+server.registerResource(
+  ...appView("Foo", "ui://foo/index.html", new URL("./dist/index.html", import.meta.url), {
+    csp: { connectDomains: ["https://bar.example.com"] },
+  }),
+);
+```
+
+The page itself uses [`holon-ui`](https://github.com/holon-sh/sdk-ui).

package/generated/holon-generated.json

@@ -0,0 +1,4 @@
+{
+  "marker": "holon-generated-apps-v1",
+  "placeholder": true
+}

package/generated/index.d.ts

@@ -0,0 +1,12 @@
+// holon-generated-apps-v1 placeholder
+export type Apps = Record<never, never>;
+export type Inputs = Record<never, never>;
+export type Outputs = Record<never, never>;
+export type InputTypes = Inputs;
+export type OutputTypes = Outputs;
+export type Resources = Record<never, never>;
+export { ToolCallError } from "../protocol.js";
+export type { Binding, EndpointBinding, CreateOptions } from "../runtime.js";
+import type { CreateOptions } from "../runtime.js";
+export declare function createApps(bindings: Record<string, never>, options?: CreateOptions): Apps;
+export declare const apps: Apps;

package/generated/index.js

@@ -0,0 +1,5 @@
+// holon-generated-apps-v1 placeholder
+import {createApps as create} from "../runtime.mjs";
+export {ToolCallError} from "../runtime.mjs";
+export const apps = create({name:"unconfigured",version:"0",requires:{}}, {});
+export function createApps(bindings, options) { if (Object.keys(bindings).length) throw new Error("Run holon types generate to configure app bindings."); return apps; }

package/package.json

@@ -1,6 +1,59 @@
 {
   "name": "holon-sh",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-dev.3",
+  "description": "Typed MCP clients and app view resources for Node.js.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holon-sh/sdk-ts.git",
+    "directory": "packages/node"
+  },
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=22"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "holon": {
+    "slot": "generated",
+    "contractVersion": 1
+  },
+  "exports": {
+    ".": {
+      "types": "./generated/index.d.ts",
+      "import": "./generated/index.js"
+    },
+    "./runtime": {
+      "types": "./runtime.d.ts",
+      "import": "./runtime.mjs"
+    },
+    "./view": {
+      "types": "./view.d.ts",
+      "import": "./view.js"
+    },
+    "./protocol": {
+      "types": "./protocol.d.ts"
+    }
+  },
+  "files": [
+    "runtime.mjs",
+    "runtime.d.ts",
+    "validate.mjs",
+    "protocol.d.ts",
+    "view.js",
+    "view.d.ts",
+    "generated/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "docs:build": "node scripts/build-reference.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/client": "^2.3.1",
+    "ajv": "^8.20.0",
+    "ajv-formats": "^3.0.1"
+  }
+}

package/protocol.d.ts

@@ -0,0 +1,44 @@
+import type { CallToolRequest, CallToolResult, InputRequiredResult, InputResponses, ListToolsResult, RequestOptions } from "@modelcontextprotocol/client";
+
+/** Bearer-token or OAuth provider accepted by the MCP transport. */
+export type AuthProvider =
+  | { token(): Promise<string | undefined>; onUnauthorized?(context: unknown): Promise<void> }
+  | { tokens(): unknown; redirectUrl: unknown; clientMetadata: unknown };
+
+/** MCP request options, including AbortSignal and timeout in milliseconds. Input-required responses are enabled by the runtime. */
+export type CallOptions = Omit<RequestOptions, "allowInputRequired">;
+/** MCP request metadata and input continuation fields. Pass inputResponses and requestState when continuing an input-required result. */
+export type CallMetadata = Omit<CallToolRequest["params"], "name" | "arguments"> & { inputResponses?: InputResponses; requestState?: string };
+/** @internal */
+type Fields<T> = { [K in keyof T as string extends K ? never : number extends K ? never : K]: T[K] };
+/** Full tool result: successful typed output, an application error, or an input-required continuation. */
+export type ToolResult<Output> =
+  | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & { resultType: "complete"; isError?: false; structuredContent: Output })
+  | (Omit<Fields<CallToolResult>, "structuredContent" | "isError"> & { resultType: "complete"; isError: true; structuredContent?: unknown })
+  | InputRequiredResult;
+
+/** Error thrown by the tools convenience methods for tool_error or input_required results. Inspect app, tool, code, and the original result; use callTool for continuation workflows. */
+export declare class ToolCallError extends Error {
+  readonly code: "tool_error" | "input_required";
+  readonly app: string;
+  readonly tool: string;
+  readonly result: Extract<ToolResult<unknown>, { isError: true } | { resultType: "input_required" }>;
+  constructor(app: string, tool: string, result: ToolCallError["result"]);
+}
+
+/** Client operations shared by generated app clients. Transport, validation, and protocol errors reject the returned promises. */
+export interface ToolClient<I, O, R> {
+  /** Close the cached endpoint session. Scoped calls close their own session; a host-owned session is closed by its host. */
+  readonly close: () => Promise<void>;
+  /** Fetch the live tool catalog. */
+  readonly listTools: (options?: CallOptions) => Promise<ListToolsResult>;
+  /** Contracted JSON resources. read validates the first text content as JSON. watch requires an endpoint binding to a server that supports subscriptions; it reads the initial value, then listens for updates until aborted. */
+  readonly resources: { readonly [U in keyof R]: {
+    readonly read: (options?: CallOptions) => Promise<R[U]>;
+    readonly watch: (onChange: (value: R[U]) => void | Promise<void>, options?: { signal?: AbortSignal }) => Promise<void>;
+  } };
+  /** Convenience methods returning structured output. Error or input-required results throw ToolCallError. Reserved object method names remain callable through callTool. */
+  readonly tools: { readonly [K in Exclude<keyof I, "then" | "toJSON" | "toString" | "valueOf" | "toLocaleString">]: (input: I[K], options?: CallOptions) => Promise<K extends keyof O ? O[K] : unknown> };
+  /** Return the full MCP result, preserving error and input-required results. Arguments and successful output are contract-validated. */
+  readonly callTool: <K extends keyof I & string>(request: CallMetadata & { name: K; arguments: I[K] }, options?: CallOptions) => Promise<ToolResult<K extends keyof O ? O[K] : unknown>>;
+}

package/runtime.d.ts

@@ -0,0 +1,49 @@
+import type { AuthProvider, CallOptions, ToolClient } from "./protocol.js";
+export { ToolCallError } from "./protocol.js";
+export type { AuthProvider, CallOptions, CallMetadata, ToolResult, ToolClient } from "./protocol.js";
+
+/** Connection settings for an MCP endpoint. */
+export interface Binding {
+  /** Streamable HTTP MCP endpoint. */
+  endpoint: URL | string;
+  /** Authentication provider; use application-owned credentials. */
+  authProvider?: AuthProvider;
+  /** Custom fetch implementation, for example for an in-process transport. */
+  fetch?: typeof fetch;
+  /** Optional X-Holon-Installation-UID routing header. */
+  installationUID?: string;
+  /** Close the session after every call instead of keeping one connection open. */
+  scoped?: boolean;
+}
+/** Alias for an endpoint binding. */
+export type EndpointBinding = Binding;
+/** Calling application identity and its declared dependencies. */
+export interface Identity { name: string; version: string; requires?: Record<string, { name?: string; version?: string }> }
+/** Generation-time tool and JSON resource schemas. A null contract permits unvalidated callTool requests. */
+export interface Contract {
+  tools: Array<{ name: string; inputSchema: Record<string, unknown>; outputSchema?: Record<string, unknown> }>;
+  resources?: Array<{ uri: string; outputSchema: Record<string, unknown> }>;
+}
+/** Untyped client returned by the low-level runtime. Generated clients specialize its inputs, outputs, and resources. */
+export type RuntimeClient = ToolClient<Record<string, Record<string, unknown>>, Record<string, unknown>, Record<string, unknown>>;
+/** The subset of an MCP client a session must provide. */
+export interface ToolSession {
+  callTool(request: { name: string; arguments?: Record<string, unknown> }, options?: Record<string, unknown>): Promise<any>;
+  readResource(request: { uri: string }, options?: Record<string, unknown>): Promise<any>;
+  listTools(params?: undefined, options?: Record<string, unknown>): Promise<any>;
+}
+/** Optional validation, binding resolution, and host-session hooks. */
+export interface CreateOptions<B = Binding> {
+  /** JSON Schema validator factory. The default uses Ajv. */
+  validator?: (schema: object) => (value: unknown) => boolean;
+  /** Binding of an app created without explicit bindings; consulted on every call. */
+  resolve?: (app: string) => Binding | undefined;
+  /** Session for a binding the runtime does not connect to itself (anything without an endpoint). */
+  session?: (app: string, binding: B) => ToolSession | undefined;
+}
+/** Construct runtime clients from identity and contracts. Connections open lazily. Explicit and resolved endpoint bindings reuse one session unless scoped is true; <NAME>_MCP_URL bindings use one session per call. Close persistent clients on shutdown. Most callers use the generated package root. */
+export declare function createApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings?: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>>;
+/** Construct only the explicitly bound dependencies. Unknown names throw; an empty binding map selects none. Used by generated createApps factories. */
+export declare function bindApps<B = Binding>(identity: Identity, contracts: Record<string, Contract | null>, bindings: Record<string, B>, options?: CreateOptions<B>): Readonly<Record<string, RuntimeClient>>;
+/** For hosts: register a process-wide resolver for clients created without explicit bindings. Explicit bindings take precedence; return undefined to fall back to the <NAME>_MCP_URL environment variable. Register during startup. */
+export declare function setDefaultBinding(resolve: (app: string) => Binding | undefined): void;

package/runtime.mjs

@@ -0,0 +1,180 @@
+import { Client, StreamableHTTPClientTransport } from "@modelcontextprotocol/client";
+import { validator as defaultValidator } from "./validate.mjs";
+
+// Shared with the private @holon-sh/sdk and existing hosts.
+const DEFAULT_BINDING = Symbol.for("@holon-sh/sdk/default-binding");
+
+// Unbound clients fall back to <NAME>_MCP_URL when the resolver returns undefined.
+export function setDefaultBinding(resolve) {
+  if (typeof resolve !== "function") throw new TypeError("Binding resolver must be a function.");
+  globalThis[DEFAULT_BINDING] = resolve;
+}
+
+function environment(identity, name) {
+  if (!Object.hasOwn(identity.requires ?? {}, name)) return undefined;
+  const variable = `${name.toUpperCase().replaceAll("-", "_")}_MCP_URL`;
+  const endpoint = process.env[variable];
+  // Environment-bound dependencies connect for one call at a time.
+  if (endpoint) return { endpoint, scoped: true };
+  throw new Error(`Dependency ${name} is unavailable (${variable}). Provide a binding or set the environment variable.`);
+}
+
+export class ToolCallError extends Error {
+  constructor(app, tool, result) {
+    const [code, message] = result.resultType === "input_required"
+      ? ["input_required", "additional input required"] : ["tool_error", "tool failed"];
+    super(`${app}.${tool}: ${message}.`);
+    this.name = "ToolCallError";
+    this.code = code;
+    this.app = app;
+    this.tool = tool;
+    this.result = result;
+  }
+}
+
+function validate(check, value, label) {
+  if (!check(value)) throw new Error(`Invalid ${label}: ${JSON.stringify(check.errors)}`);
+}
+
+function untilAborted(promise, signal) {
+  if (!signal) return promise;
+  return new Promise((resolve, reject) => {
+    const aborted = () => reject(signal.reason);
+    signal.addEventListener("abort", aborted, { once: true });
+    promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", aborted));
+  });
+}
+
+function delay(milliseconds, signal) {
+  return new Promise(resolve => {
+    const timer = setTimeout(resolve, milliseconds);
+    signal?.addEventListener("abort", () => { clearTimeout(timer); resolve(); }, { once: true });
+  });
+}
+
+export function bindApps(identity, contracts, bindings, options) {
+  const selected = Object.fromEntries(Object.keys(bindings).map(name => {
+    if (!Object.hasOwn(contracts, name) && !Object.hasOwn(identity.requires ?? {}, name)) throw new Error("Unknown app binding: " + name);
+    return [name, contracts[name] ?? null];
+  }));
+  return createApps(identity, selected, bindings, options);
+}
+
+export function createApps(identity, contracts, bindings, options) {
+  const { validator = defaultValidator, resolve = name => globalThis[DEFAULT_BINDING]?.(name) ?? environment(identity, name), session: hosted } = options ?? {};
+  const apps = Object.create(null);
+  // Without explicit bindings, every declared dependency gets a client; those without a contract are untyped.
+  const members = { ...(bindings ? {} : Object.fromEntries(Object.keys(identity.requires ?? {}).map(name => [name, null]))), ...contracts };
+  for (const [name, contract] of Object.entries(members)) {
+    const binding = bindings?.[name];
+    // Without explicit bindings, the resolve hook supplies the binding on every call.
+    const current = () => binding ?? (bindings ? undefined : resolve(name));
+    let connection;
+    const connect = resolved => {
+      const client = new Client({ name: identity.name, version: identity.version }, { versionNegotiation: { mode: "auto" } });
+      const transport = new StreamableHTTPClientTransport(new URL(resolved.endpoint), { authProvider: resolved.authProvider, fetch: resolved.fetch, requestInit: { credentials: "include", redirect: "error", headers: resolved.installationUID ? { "X-Holon-Installation-UID": resolved.installationUID } : {} } });
+      const current = { client, close: async () => {
+        await transport.close();
+        await current.ready.catch(() => {});
+      } };
+      transport.onclose = () => { if (connection === current) connection = undefined; };
+      current.ready = client.connect(transport).catch(async error => {
+        await transport.close();
+        throw error;
+      });
+      return current;
+    };
+    // The session hook serves bindings the runtime does not connect to itself.
+    const host = binding && hosted?.(name, binding);
+    const session = async (options, run) => {
+      options?.signal?.throwIfAborted();
+      if (host) return run(host);
+      const resolved = current();
+      if (!resolved) throw new Error(Object.hasOwn(identity.requires ?? {}, name)
+        ? `Dependency ${name} is unavailable. Provide a binding.`
+        : `Dependency ${name} is not declared by this application.`);
+      if (!resolved.endpoint) throw new Error(`Dependency ${name} binding has no endpoint.`);
+      // Bindings marked scoped connect for one call at a time.
+      const scoped = resolved.scoped === true;
+      const active = scoped ? connect(resolved) : (connection ??= connect(resolved));
+      try {
+        await untilAborted(active.ready, options?.signal);
+        return await run(active.client);
+      } finally { if (scoped) await active.close(); }
+    };
+    const tools = Object.create(null);
+    const definitions = new Map((contract?.tools ?? []).map(definition => [definition.name, { definition }]));
+    const callTool = async (request, options) => {
+      const tool = definitions.get(request.name);
+      if (!tool && contract) throw new Error(`Unknown tool ${name}.${request.name}.`);
+      let validation;
+      if (tool) {
+        const { definition } = tool;
+        validation = tool.validation ??= {
+          input: validator(definition.inputSchema),
+          output: definition.outputSchema ? validator(definition.outputSchema) : undefined,
+        };
+        validate(validation.input, request.arguments, `arguments for ${name}.${request.name}`);
+      }
+      const result = await session(options, client => client.callTool(request, {
+        ...options, allowInputRequired: true,
+        ...(tool && { toolDefinition: { ...tool.definition, outputSchema: undefined } }),
+      }));
+      if (result.resultType === "input_required") return result;
+      if (!result.isError && validation?.output) {
+        validate(validation.output, result.structuredContent, `structured output from ${name}.${request.name}`);
+      }
+      return { ...result, resultType: "complete" };
+    };
+    const listTools = options => session(options, client => client.listTools(undefined, options));
+    for (const tool of contract?.tools ?? []) if (!["then", "toJSON", "toString", "valueOf", "toLocaleString"].includes(tool.name)) {
+      tools[tool.name] = async (input, options) => {
+        const result = await callTool({ name: tool.name, arguments: input }, options);
+        if (result.resultType === "input_required" || result.isError) throw new ToolCallError(name, tool.name, result);
+        return result.structuredContent;
+      };
+    }
+    const resources = Object.create(null);
+    for (const resource of contract?.resources ?? []) {
+      let valid;
+      const parse = result => {
+        const value = JSON.parse(result.contents[0].text);
+        valid ??= validator(resource.outputSchema);
+        validate(valid, value, `contents from ${name} ${resource.uri}`);
+        return value;
+      };
+      const read = async options => parse(await session(options, client => client.readResource({ uri: resource.uri }, options)));
+      const watch = async (onChange, { signal } = {}) => {
+        const resolved = current();
+        if (!resolved?.endpoint) throw new Error(`Watching ${name} ${resource.uri} requires an endpoint binding.`);
+        for (let established = false; !signal?.aborted; await delay(1000, signal)) {
+          const current = connect(resolved);
+          let failure;
+          try {
+            await untilAborted(current.ready, signal);
+            const { client } = current;
+            if (!client.getServerCapabilities()?.resources?.subscribe) throw new Error(`${name} does not advertise resource subscriptions.`);
+            let reads = Promise.resolve();
+            const refresh = () => (reads = reads.then(async () => onChange(parse(await client.readResource({ uri: resource.uri }, { signal, cacheMode: "bypass" }))))
+              .catch(error => { failure ??= error; return current.close(); }));
+            client.setNotificationHandler("notifications/resources/updated", ({ params }) => { if (params.uri === resource.uri) void refresh(); });
+            const subscription = await client.listen({ resourceSubscriptions: [resource.uri] }, { signal });
+            if (!subscription.honoredFilter.resourceSubscriptions?.includes(resource.uri)) throw new Error(`${name} did not accept a subscription to ${resource.uri}.`);
+            established = true;
+            await refresh();
+            await subscription.closed;
+          } catch (error) {
+            failure ??= error;
+          } finally {
+            await current.close();
+          }
+          if (signal?.aborted) return;
+          if (failure && !established) throw failure;
+        }
+      };
+      resources[resource.uri] = Object.freeze({ read, watch });
+    }
+    apps[name] = Object.freeze({ callTool, listTools, resources: Object.freeze(resources), close: async () => { await connection?.close(); }, tools: Object.freeze(tools) });
+  }
+  return Object.freeze(apps);
+}

package/validate.mjs

@@ -0,0 +1,10 @@
+import Ajv from "ajv";
+import { Ajv2020 } from "ajv/dist/2020.js";
+import addFormats from "ajv-formats";
+
+export function validator(schema) {
+  const constructor = schema.$schema?.includes("draft-07") ? Ajv : Ajv2020;
+  const ajv = new constructor({ strict: false, ownProperties: true, allErrors: true });
+  addFormats(ajv);
+  return ajv.compile(schema);
+}

package/view.d.ts

@@ -0,0 +1,47 @@
+/** MIME type of an MCP App HTML resource. */
+export declare const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
+/** Allowed network and asset domains for the view content security policy. */
+export interface ViewOptions {
+    csp?: {
+        connectDomains?: string[];
+        resourceDomains?: string[];
+    };
+}
+type ViewRegistration = [
+    name: string,
+    uri: string,
+    metadata: {
+        mimeType: string;
+        _meta: {
+            ui: {
+                csp: {
+                    connectDomains: string[];
+                    resourceDomains: string[];
+                };
+            };
+        };
+    },
+    read: () => Promise<{
+        ttlMs: number;
+        cacheScope: "private";
+        contents: {
+            uri: string;
+            mimeType: string;
+            text: string;
+        }[];
+    }>
+];
+/**
+ * Create a registration tuple for server.registerResource(...appView(...)).
+ * Node only: the HTML file is read once when this helper is called.
+ * Resource reads reuse that promise; file read failures reject resource requests.
+ * @param name Human-readable resource name.
+ * @param uri Resource URI, usually starting with ui://.
+ * @param file Built HTML file path or file URL.
+ * @param options View content security policy.
+ * @returns Name, URI, metadata, and resource-read callback.
+ * @example
+ * server.registerResource(...appView("App", "ui://app/index.html", new URL("./index.html", import.meta.url)));
+ */
+export declare function appView(name: string, uri: string, file: URL | string, options?: ViewOptions): ViewRegistration;
+export {};

package/view.js

@@ -0,0 +1,30 @@
+import { readFile } from "node:fs/promises";
+/** MIME type of an MCP App HTML resource. */
+export const VIEW_MIME_TYPE = "text/html;profile=mcp-app";
+/**
+ * Create a registration tuple for server.registerResource(...appView(...)).
+ * Node only: the HTML file is read once when this helper is called.
+ * Resource reads reuse that promise; file read failures reject resource requests.
+ * @param name Human-readable resource name.
+ * @param uri Resource URI, usually starting with ui://.
+ * @param file Built HTML file path or file URL.
+ * @param options View content security policy.
+ * @returns Name, URI, metadata, and resource-read callback.
+ * @example
+ * server.registerResource(...appView("App", "ui://app/index.html", new URL("./index.html", import.meta.url)));
+ */
+export function appView(name, uri, file, options = {}) {
+    const csp = { connectDomains: [], resourceDomains: [], ...options.csp };
+    const page = readFile(file, "utf8");
+    page.catch(() => { });
+    return [
+        name,
+        uri,
+        { mimeType: VIEW_MIME_TYPE, _meta: { ui: { csp } } },
+        async () => ({
+            ttlMs: 0,
+            cacheScope: "private",
+            contents: [{ uri, mimeType: VIEW_MIME_TYPE, text: await page }],
+        }),
+    ];
+}