holon-ui 0.0.0-stage → 0.0.1-dev.1

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,139 @@
-# Temporary Holding Version
+# holon-ui
 
-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.
+Typed MCP clients for browser pages: views that run inside an MCP Apps host, or standalone pages that talk to MCP servers directly. The [`holon` CLI](https://github.com/holon-sh/cli) generates the clients into this package's `generated/` directory, so `import { createApps } from "holon-ui"` resolves to your app's own types. Clients validate arguments before each call and results after it, and can expose tools to the page's WebMCP agent.
+
+`holon-ui` contains only browser code. Server code uses `holon-sh` ([Node.js](https://github.com/holon-sh/sdk-ts) or [Python](https://github.com/holon-sh/sdk-py)). Start with the [CLI README](https://github.com/holon-sh/cli) for the walkthrough.
+
+## Install
+
+In the app's root directory, next to its `server.json`:
+
+```sh
+npm install holon-ui@dev
+```
+
+Declare `holon-ui` in the app root's `package.json` even when the view's sources live in a subdirectory: `holon types generate` writes browser clients into `node_modules/holon-ui/generated/` whenever that `package.json` declares `holon-ui` (and into `holon-sh` as well when it declares both).
+
+## The generated module
+
+```typescript
+import { App, ToolCallError, createApps, exposeTools, registerPageTools, type Inputs, type Outputs, type Resources } from "holon-ui";
+```
+
+| Export | What it is |
+|---|---|
+| `App` | The `App` from `@modelcontextprotocol/ext-apps` with your own server's `tools`, `resources` and `callTool` typed. Calls go through the host that embeds the page. |
+| `createApps(bindings, options?)` | Clients for servers you reach by endpoint, keyed like `bindings`. |
+| `ToolCallError` | Thrown by `tools.<tool>` when a tool reports an error or asks for more input. |
+| `exposeTools(client, options?)` | Registers a client's tools with the page's WebMCP agent. |
+| `registerPageTools(tools, options?)` | Registers tools implemented by the page itself. |
+| `Inputs`, `Outputs`, `Resources` | Argument, result and resource value types, as `Inputs["dep"]["tool"]`. |
+
+Your own server appears under the last segment of its `server.json` name, e.g. `example.com/checkout` → `checkout`: `Inputs["checkout"]`, `Outputs["checkout"]`, and `createApps({ checkout: { endpoint } })` for a standalone page. Every other key is a dependency declared in `server.json`.
+
+## Bind a client
+
+### Inside an MCP Apps host
+
+A view embedded in an MCP Apps host calls its own server through the host, which owns the connection and the credentials. Construct and connect `App` exactly as you would the one from `@modelcontextprotocol/ext-apps`; it is that class with typed members added:
+
+```typescript
+import { App } from "holon-ui";
+
+const view = new App({ name: "checkout-view", version: "1.0.0" });
+view.ontoolresult = ({ structuredContent }) => render(structuredContent);
+await view.connect();
+
+const { total } = await view.tools.total({ id: "A-1" });
+```
+
+The host owns the tool catalog, so `listTools`, `exposeTools` and `watch` need an endpoint binding instead.
+
+### Directly to an endpoint
+
+```typescript
+const apps = createApps({
+  checkout: { endpoint: new URL("/mcp", location.origin) },
+  orders: { endpoint: "https://orders.example.com/mcp" },
+});
+
+const order = await apps.orders.tools.lookup({ id: "A-1" }, { timeout: 5000 });
+```
+
+An endpoint binding takes `endpoint`, and optionally `authProvider`, `fetch`, and `scoped: true` to close the session after every call. Otherwise a client keeps one session open; call `close()` when the page no longer needs it.
+
+## Read and watch resources
+
+A server types a JSON resource by registering it with `mimeType: "application/json"` and an `"sh.holon/outputSchema"` JSON Schema in its `_meta`:
+
+```typescript
+const summary = await apps.orders.resources["orders://summary"].read();
+
+const lifetime = new AbortController();
+await apps.orders.resources["orders://summary"].watch(value => render(value.open), { signal: lifetime.signal });
+```
+
+`watch` calls back with the current value and then on every update, until the signal aborts; the server must support resource subscriptions.
+
+## Give tools to the page's agent
+
+`exposeTools` registers every tool of an endpoint-bound client with the page's WebMCP context (`navigator.modelContext`). Calls from the agent go through the client, so they are validated. It returns `false` when the browser has no WebMCP context.
+
+```typescript
+await exposeTools(apps.orders, { signal: lifetime.signal });
+```
+
+`registerPageTools` registers tools the page implements itself. Input schemas are Standard Schema validators that can produce JSON Schema, such as Zod 4. Pass `view` to register with the MCP Apps host; without it they go to WebMCP. Aborting the signal unregisters them.
+
+```typescript
+import { z } from "zod";
+
+await registerPageTools(
+  {
+    highlight: {
+      description: "Highlight an order on the page",
+      inputSchema: z.object({ id: z.string() }),
+      execute: ({ id }) => {
+        select(id);
+        return { content: [{ type: "text", text: `Highlighted ${id}` }] };
+      },
+    },
+  },
+  { view, signal: lifetime.signal },
+);
+```
+
+## Build and serve a view
+
+The server serves the view as one HTML file, so bundle it into a single file. With Vite, in the app root:
+
+```typescript
+// vite.config.ts
+import { defineConfig } from "vite";
+import { viteSingleFile } from "vite-plugin-singlefile";
+
+export default defineConfig({ root: "ui", plugins: [viteSingleFile()], build: { outDir: "../dist", emptyOutDir: true } });
+```
+
+```sh
+npm install --save-dev vite vite-plugin-singlefile
+npm install @modelcontextprotocol/ext-apps
+npx vite build
+```
+
+Then serve `dist/index.html` from the server with `appView` from `holon-sh/view` (Node.js) or `app_view` from `holon.view` (Python); both are documented in their runtime READMEs.
+
+## Low-level runtime
+
+`holon-ui/runtime` exports what the generated module calls: `createApps(identity, contracts, bindings?, options?)`, `bindApps`, `appClass(identity, contracts, own)`, `exposeTools`, `registerPageTools`, `ToolCallError`, and the `EndpointBinding`, `View` and page-tool types. Apps use the generated module instead.
+
+## Develop
+
+```sh
+npm ci
+npm test
+```
+
+## License
+
+MIT

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 "holon-sh/protocol";
+export type { EndpointBinding, CreateOptions } from "../runtime.js";
+export { exposeTools, registerPageTools } from "../runtime.js";
+import type { CreateOptions } from "../runtime.js";
+export declare function createApps(bindings: Record<string, never>, options?: CreateOptions): Apps;

package/generated/index.js

@@ -0,0 +1,4 @@
+// holon-generated-apps-v1 placeholder
+import {bindApps} from "../runtime.mjs";
+export {ToolCallError,exposeTools,registerPageTools} from "../runtime.mjs";
+export function createApps(bindings, options) { return bindApps({name:"unconfigured",version:"0",requires:{}}, {}, bindings, options); }

package/package.json

@@ -1,6 +1,55 @@
 {
   "name": "holon-ui",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.0.1-dev.1",
+  "description": "Typed MCP clients for browser views: MCP Apps host bindings and WebMCP tool exposure.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/holon-sh/sdk-ui.git"
+  },
+  "license": "MIT",
+  "type": "module",
+  "sideEffects": false,
+  "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"
+    }
+  },
+  "files": [
+    "runtime.mjs",
+    "runtime.d.ts",
+    "generated/",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "prepack": "npm run build",
+    "test": "npm run build && node --test tests/*.test.mjs",
+    "fixtures": "node scripts/fixtures.mjs"
+  },
+  "dependencies": {
+    "holon-sh": "^0.0.1-dev.2"
+  },
+  "peerDependencies": {
+    "@modelcontextprotocol/ext-apps": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@modelcontextprotocol/ext-apps": "^1.7.5",
+    "@modelcontextprotocol/node": "2.1.1",
+    "@modelcontextprotocol/server": "2.3.1",
+    "@types/node": "^22.0.0",
+    "typescript": "~5.9.3",
+    "zod": "4.6.6"
+  }
+}

package/runtime.d.ts

@@ -0,0 +1,20 @@
+import type { App } from "@modelcontextprotocol/ext-apps";
+import type { Binding as EndpointBinding, Identity, Contract, RuntimeClient } from "holon-sh/runtime";
+export type { Binding as EndpointBinding, Identity, Contract, RuntimeClient, AuthProvider, CallOptions, CallMetadata, ToolResult, ToolClient } from "holon-sh/runtime";
+export { ToolCallError } from "holon-sh/runtime";
+
+export interface CreateOptions { validator?: (schema: object) => (value: unknown) => boolean }
+export declare function createApps(identity: Identity, contracts: Record<string, Contract | null>, bindings?: Record<string, EndpointBinding>, options?: CreateOptions): Readonly<Record<string, RuntimeClient>>;
+export declare function bindApps(identity: Identity, contracts: Record<string, Contract | null>, bindings: Record<string, EndpointBinding>, options?: CreateOptions): Readonly<Record<string, RuntimeClient>>;
+/** The ext-apps App with the app's own tools and resources typed; calls go through the host that embeds the page. */
+export type View = App & Pick<RuntimeClient, "tools" | "resources" | "callTool">;
+export declare function appClass(identity: Identity, contracts: Record<string, Contract | null>, own: string): new (...args: ConstructorParameters<typeof App>) => View;
+export interface ExposeOptions { signal?: AbortSignal; execute?: (name: string, args: Record<string, unknown>) => Promise<unknown> }
+export declare function exposeTools(app: Pick<RuntimeClient, "callTool" | "listTools">, options?: ExposeOptions): Promise<boolean>;
+export type PageResult<I> = { readonly value: I; readonly issues?: undefined } | { readonly issues: ReadonlyArray<{ readonly message: string }> };
+export interface PageSchema<I = unknown> { readonly "~standard": { readonly version: 1; readonly vendor: string; readonly types?: { readonly input: unknown; readonly output: I }; readonly validate: (value: unknown) => PageResult<I> | Promise<PageResult<I>>; readonly jsonSchema: { readonly input: (options: { target: "draft-2020-12" }) => object } } }
+export type PageInput<S> = S extends PageSchema<infer I> ? I : never;
+export interface PageAnnotations { title?: string; readOnlyHint?: boolean; destructiveHint?: boolean; idempotentHint?: boolean; openWorldHint?: boolean }
+export interface PageTool<S extends PageSchema = PageSchema> { description: string; inputSchema: S; annotations?: PageAnnotations; execute: (args: PageInput<S>) => unknown }
+export interface PageHost { registerTool(name: string, config: { description: string; inputSchema: PageSchema; annotations?: PageAnnotations }, callback: (args: any, extra: any) => any): { remove(): void } }
+export declare function registerPageTools<S extends { [name: string]: PageSchema }>(tools: { [K in keyof S]: PageTool<S[K]> }, options?: { view?: PageHost; signal?: AbortSignal }): Promise<boolean>;

package/runtime.mjs

@@ -0,0 +1,63 @@
+import { App } from "@modelcontextprotocol/ext-apps";
+import { createApps as create, bindApps, ToolCallError } from "holon-sh/runtime";
+
+export { bindApps, ToolCallError };
+
+// Browser clients have no process environment or host-wide default binding.
+export function createApps(identity, contracts, bindings, options) {
+  return create(identity, contracts, bindings, { ...options, resolve: () => undefined });
+}
+
+// appClass returns the ext-apps App with the app's own tools and resources (contracts[own]) typed.
+// Calls go through the host that embeds the page, so connect the App first, as with any App.
+export function appClass(identity, contracts, own) {
+  return class extends App {
+    #client = bindApps(identity, { [own]: contracts[own] }, { [own]: {} }, {
+      session: () => ({
+        callTool: (request, { signal, timeout } = {}) => this.callServerTool(request, { signal, timeout }),
+        readResource: (request, { signal, timeout } = {}) => this.readServerResource(request, { signal, timeout }),
+        listTools: () => { throw new Error("The host owns the tool catalog; bind an endpoint to list tools."); },
+      }),
+    })[own];
+    get tools() { return this.#client.tools; }
+    get resources() { return this.#client.resources; }
+    callTool(request, options) { return this.#client.callTool(request, options); }
+  };
+}
+
+export async function exposeTools(app, options = {}) {
+  const context = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
+  if (!context) return false;
+  const { signal } = options;
+  const execute = options.execute ?? ((name, args) => app.callTool({ name, arguments: args }, { signal }));
+  const { tools } = await app.listTools({ signal });
+  for (const tool of tools) {
+    await context.registerTool({
+      name: tool.name, title: tool.title, description: tool.description ?? "", inputSchema: tool.inputSchema, annotations: tool.annotations,
+      execute: args => execute(tool.name, args ?? {}),
+    }, { signal });
+  }
+  return true;
+}
+
+export async function registerPageTools(tools, { view, signal } = {}) {
+  const context = globalThis.document?.modelContext ?? globalThis.navigator?.modelContext;
+  const removals = [];
+  for (const [name, { description, inputSchema, annotations, execute }] of Object.entries(tools)) {
+    if (view) {
+      removals.push(view.registerTool(name, { description, inputSchema, annotations }, args => execute(args)).remove);
+    } else if (context) {
+      const standard = inputSchema["~standard"];
+      await context.registerTool({
+        name, description, annotations, inputSchema: standard.jsonSchema.input({ target: "draft-2020-12" }),
+        execute: async args => {
+          const parsed = await standard.validate(args ?? {});
+          if (parsed.issues) throw new Error(`Invalid arguments for ${name}: ${JSON.stringify(parsed.issues)}`);
+          return execute(parsed.value);
+        },
+      }, { signal });
+    }
+  }
+  signal?.addEventListener("abort", () => { for (const remove of removals) remove(); }, { once: true });
+  return Boolean(view || context);
+}