@nifrajs/mcp 2.2.0 → 2.4.0

package/README.md

@@ -26,7 +26,7 @@ hosts.
 
 ## For AI agents
 
-Start with [`LLM.md`](./LLM.md) — this package's contract card (the exports you call + its footguns),
+Start with [`LLM.md`](./LLM.md) - this package's contract card (the exports you call + its footguns),
 one cheap read instead of the whole corpus. For the wider framework: the repo's
 [`AGENTS.md`](../../AGENTS.md) is the copy-paste quick reference, and
 [`llms-full.txt`](../../llms-full.txt) is the full machine-readable corpus. Run `nifra check` as the

package/dist/bridge.d.ts

@@ -4,7 +4,7 @@
  *
  *   host → widget : `ui/notifications/tool-result` (the tools/call result incl. `structuredContent`),
  *                   `ui/notifications/tool-input` (the call arguments), and `ui/notifications/theme`
- *                   (the host's design tokens) — pushed as JSON-RPC notifications.
+ *                   (the host's design tokens) - pushed as JSON-RPC notifications.
  *   widget → host : `tools/call` requests (id-matched) so a button can re-invoke a tool through the host.
  *
  * Theming follows the shadcn/Tailwind semantic-token convention (`--background`, `--foreground`,
@@ -13,7 +13,7 @@
  * app with zero per-widget work.
  *
  * It exposes a small global the widget author scripts against, so authoring a widget is just
- * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` — no postMessage plumbing.
+ * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` - no postMessage plumbing.
  *
  * Returned as a string so {@link ./widget.ts} can inline it in the resource HTML (a widget ships as ONE
  * self-contained document; the host renders it in a sandboxed iframe with no network of its own).
@@ -22,7 +22,7 @@
 export interface McpAppBridge {
     /** Latest `structuredContent` the host pushed (or `null` before the first result). */
     data: unknown;
-    /** Register a callback for `structuredContent` — fired immediately if data already arrived, then on
+    /** Register a callback for `structuredContent` - fired immediately if data already arrived, then on
      * every later `ui/notifications/tool-result`. The common case: `mcpApp.onData(render)`. */
     onData(cb: (data: unknown) => void): void;
     /** Register a callback for the raw tool-call arguments (`ui/notifications/tool-input`). */

package/dist/bridge.js

@@ -4,7 +4,7 @@
  *
  *   host → widget : `ui/notifications/tool-result` (the tools/call result incl. `structuredContent`),
  *                   `ui/notifications/tool-input` (the call arguments), and `ui/notifications/theme`
- *                   (the host's design tokens) — pushed as JSON-RPC notifications.
+ *                   (the host's design tokens) - pushed as JSON-RPC notifications.
  *   widget → host : `tools/call` requests (id-matched) so a button can re-invoke a tool through the host.
  *
  * Theming follows the shadcn/Tailwind semantic-token convention (`--background`, `--foreground`,
@@ -13,7 +13,7 @@
  * app with zero per-widget work.
  *
  * It exposes a small global the widget author scripts against, so authoring a widget is just
- * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` — no postMessage plumbing.
+ * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` - no postMessage plumbing.
  *
  * Returned as a string so {@link ./widget.ts} can inline it in the resource HTML (a widget ships as ONE
  * self-contained document; the host renders it in a sandboxed iframe with no network of its own).
@@ -74,7 +74,7 @@ const BRIDGE_SOURCE = `(function () {
   window.addEventListener("message", function (event) {
     // Only trust the embedding host (the parent window). A widget renders in a sandboxed iframe whose host
     // posts via the parent (or a sandbox-proxy parent), so event.source === window.parent. Reject anything
-    // else — including a null source (synthetic/dispatched events) — so a sibling/opener frame or in-page
+    // else - including a null source (synthetic/dispatched events) - so a sibling/opener frame or in-page
     // script can't spoof tool-results, tool-call responses, or theme. (A top-level widget has no host.)
     if (event.source !== window.parent || window.parent === window) return;
     var msg = event.data;

package/dist/http.d.ts

@@ -1,8 +1,8 @@
 /**
- * The transport core shared by every HTTP host of an MCP server — the dev/docs MCP in `@nifrajs/cli`
+ * The transport core shared by every HTTP host of an MCP server - the dev/docs MCP in `@nifrajs/cli`
  * (`nifra docs-mcp`), the site's edge worker, and a nifra app mounting `POST /mcp` via
  * {@link ./server.ts}. {@link respondMcpHttp} is a plain Web `fetch` handler: POST a JSON-RPC body →
- * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws — a bad body
+ * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws - a bad body
  * becomes a JSON-RPC parse error. Pass the tools (and optional {@link McpServerFeatures} for resources /
  * prompts / the MCP Apps `ui://` widgets) so each host supplies its own corpus/source behind one core.
  */
@@ -17,7 +17,7 @@ export interface McpHttpOptions {
 }
 /**
  * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC
- * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws — a bad body becomes a
+ * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a
  * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.
  */
 export declare function respondMcpHttp(request: Request, tools: McpTool[], serverInfo: {

package/dist/http.js

@@ -1,8 +1,8 @@
 /**
- * The transport core shared by every HTTP host of an MCP server — the dev/docs MCP in `@nifrajs/cli`
+ * The transport core shared by every HTTP host of an MCP server - the dev/docs MCP in `@nifrajs/cli`
  * (`nifra docs-mcp`), the site's edge worker, and a nifra app mounting `POST /mcp` via
  * {@link ./server.ts}. {@link respondMcpHttp} is a plain Web `fetch` handler: POST a JSON-RPC body →
- * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws — a bad body
+ * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws - a bad body
  * becomes a JSON-RPC parse error. Pass the tools (and optional {@link McpServerFeatures} for resources /
  * prompts / the MCP Apps `ui://` widgets) so each host supplies its own corpus/source behind one core.
  */
@@ -69,7 +69,7 @@ async function readJsonBounded(request, maxBytes) {
 }
 /**
  * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC
- * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws — a bad body becomes a
+ * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a
  * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.
  */
 export async function respondMcpHttp(request, tools, serverInfo, options = {}) {
@@ -77,7 +77,7 @@ export async function respondMcpHttp(request, tools, serverInfo, options = {}) {
         return new Response(null, { status: 204, headers: CORS });
     if (request.method === "GET") {
         return new Response(options.health ??
-            "MCP server — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call).", { headers: { "content-type": "text/plain; charset=utf-8", ...CORS } });
+            "MCP server - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call).", { headers: { "content-type": "text/plain; charset=utf-8", ...CORS } });
     }
     if (request.method !== "POST") {
         return new Response("method not allowed", {
@@ -99,7 +99,7 @@ export async function respondMcpHttp(request, tools, serverInfo, options = {}) {
     const response = await handleRpc(message, tools, serverInfo, options.features ?? {}, {
         signal: request.signal,
     });
-    // A notification (no id) yields null — acknowledge with 204, no body.
+    // A notification (no id) yields null - acknowledge with 204, no body.
     if (response === null)
         return new Response(null, { status: 204, headers: CORS });
     return Response.json(response, { headers: CORS });

package/dist/index.d.ts

@@ -1,12 +1,12 @@
 /**
- * `@nifrajs/mcp` — build MCP servers (and MCP Apps) for a nifra app.
+ * `@nifrajs/mcp` - build MCP servers (and MCP Apps) for a nifra app.
  *
- * - {@link ./protocol.ts} — the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
+ * - {@link ./protocol.ts} - the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
  *   the MCP Apps (SEP-1865) extension (`structuredContent`, `_meta.ui.resourceUri`, the UI capability).
- * - {@link ./http.ts} — {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
+ * - {@link ./http.ts} - {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
  *
- * Higher-level authoring helpers — {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
- * — build MCP Apps servers whose tool results render real UI.
+ * Higher-level authoring helpers - {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
+ * - build MCP Apps servers whose tool results render real UI.
  */
 export { bridgeScript, type McpAppBridge } from "./bridge.js";
 export { type McpHttpOptions, respondMcpHttp } from "./http.js";

package/dist/index.js

@@ -1,12 +1,12 @@
 /**
- * `@nifrajs/mcp` — build MCP servers (and MCP Apps) for a nifra app.
+ * `@nifrajs/mcp` - build MCP servers (and MCP Apps) for a nifra app.
  *
- * - {@link ./protocol.ts} — the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
+ * - {@link ./protocol.ts} - the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
  *   the MCP Apps (SEP-1865) extension (`structuredContent`, `_meta.ui.resourceUri`, the UI capability).
- * - {@link ./http.ts} — {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
+ * - {@link ./http.ts} - {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
  *
- * Higher-level authoring helpers — {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
- * — build MCP Apps servers whose tool results render real UI.
+ * Higher-level authoring helpers - {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
+ * - build MCP Apps servers whose tool results render real UI.
  */
 export { bridgeScript } from "./bridge.js";
 export { respondMcpHttp } from "./http.js";

package/dist/protocol.d.ts

@@ -1,13 +1,13 @@
 /**
- * The pure MCP (Model Context Protocol) JSON-RPC dispatch — no I/O, no `Bun.*`, no side effects, so it
+ * The pure MCP (Model Context Protocol) JSON-RPC dispatch - no I/O, no `Bun.*`, no side effects, so it
  * unit-tests cleanly. A transport (stdio in `@nifrajs/cli`'s `mcp.ts`, Streamable-HTTP in {@link ./http.ts})
  * wires this to a byte stream; the tools/resources are injected, so the protocol logic is exercised
  * without spawning or reading streams.
  *
- * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** — interactive `ui://`
+ * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** - interactive `ui://`
  * widgets: a tool links a UI resource via `_meta.ui.resourceUri`, `tools/call` returns `structuredContent`
  * for the widget to render, and `initialize` advertises the `io.modelcontextprotocol/ui` extension. All of
- * it is additive — a tool whose handler returns a plain `string` behaves exactly as before.
+ * it is additive - a tool whose handler returns a plain `string` behaves exactly as before.
  */
 export declare const PROTOCOL_VERSION = "2024-11-05";
 /** The MIME type a UI resource MUST use so a host recognizes it as an MCP App widget (SEP-1865). */
@@ -23,7 +23,7 @@ export interface McpToolContext {
     readonly progressToken?: ProgressToken;
     readonly reportProgress: (progress: number, total?: number) => void;
 }
-/** A single content block in a tool result. Today only text — the model-facing representation. */
+/** A single content block in a tool result. Today only text - the model-facing representation. */
 export interface McpContentBlock {
     readonly type: "text";
     readonly text: string;
@@ -42,7 +42,7 @@ export interface McpToolResult {
 }
 /** A tool the agent can call. `handler` returns the text shown to the agent, or a rich {@link McpToolResult}
  * (for MCP Apps: structured data + a `ui://` widget link). `_meta` is the per-tool descriptor metadata
- * surfaced in `tools/list` — for a widget tool it carries `ui.resourceUri`. */
+ * surfaced in `tools/list` - for a widget tool it carries `ui.resourceUri`. */
 /** MCP tool safety hints (`readOnlyHint`/`destructiveHint`/…) surfaced in `tools/list`, per the MCP spec. */
 export interface McpToolAnnotations {
     readonly title?: string;

package/dist/protocol.js

@@ -1,13 +1,13 @@
 /**
- * The pure MCP (Model Context Protocol) JSON-RPC dispatch — no I/O, no `Bun.*`, no side effects, so it
+ * The pure MCP (Model Context Protocol) JSON-RPC dispatch - no I/O, no `Bun.*`, no side effects, so it
  * unit-tests cleanly. A transport (stdio in `@nifrajs/cli`'s `mcp.ts`, Streamable-HTTP in {@link ./http.ts})
  * wires this to a byte stream; the tools/resources are injected, so the protocol logic is exercised
  * without spawning or reading streams.
  *
- * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** — interactive `ui://`
+ * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** - interactive `ui://`
  * widgets: a tool links a UI resource via `_meta.ui.resourceUri`, `tools/call` returns `structuredContent`
  * for the widget to render, and `initialize` advertises the `io.modelcontextprotocol/ui` extension. All of
- * it is additive — a tool whose handler returns a plain `string` behaves exactly as before.
+ * it is additive - a tool whose handler returns a plain `string` behaves exactly as before.
  */
 export const PROTOCOL_VERSION = "2024-11-05";
 /** The MIME type a UI resource MUST use so a host recognizes it as an MCP App widget (SEP-1865). */
@@ -251,7 +251,7 @@ export async function handleRpc(message, tools, serverInfo, features = {}, optio
                 });
             }
             catch {
-                // Don't surface the raw read error — it can leak a filesystem path. Return a generic message.
+                // Don't surface the raw read error - it can leak a filesystem path. Return a generic message.
                 return rpcError(rid, -32000, `failed to read resource: ${String(uri)}`);
             }
         }

package/dist/react.d.ts

@@ -13,7 +13,7 @@ export interface ReactWidgetOptions {
     /** Minify the client bundle (default true). */
     readonly minify?: boolean;
 }
-/** Build a {@link McpWidget} from a React component. Async — it bundles the component at definition time
+/** Build a {@link McpWidget} from a React component. Async - it bundles the component at definition time
  * (a one-time cost at server start); pass the result to `createMcpServer({ widgets })` / a tool's `widget`. */
 export declare function reactWidget(opts: ReactWidgetOptions): Promise<McpWidget>;
 //# sourceMappingURL=react.d.ts.map

package/dist/react.js

@@ -1,13 +1,13 @@
 /**
- * `reactWidget` — author an MCP Apps (`ui://`) widget from a React component instead of hand-written HTML.
+ * `reactWidget` - author an MCP Apps (`ui://`) widget from a React component instead of hand-written HTML.
  *
  * The component is bundled for the browser (via `Bun.build`) together with a bootstrap that mounts it and
- * re-renders on every `structuredContent` the host pushes — `mcpApp.onData(data => root.render(<C {...data}/>))`.
+ * re-renders on every `structuredContent` the host pushes - `mcpApp.onData(data => root.render(<C {...data}/>))`.
  * So a widget author writes a normal nifra/React component that takes the tool's structured data as props;
  * the bridge wiring and bundling are handled here. Client-rendered (the widget shell is the resource the
  * host fetches once; data arrives over the bridge), which matches how a host renders MCP App widgets.
  *
- * `react` + `react-dom` resolve from the CONSUMER's `node_modules` at bundle time — they are NOT a
+ * `react` + `react-dom` resolve from the CONSUMER's `node_modules` at bundle time - they are NOT a
  * dependency of `@nifrajs/mcp`. This entry is Bun-only (it calls `Bun.build`); import it from
  * `@nifrajs/mcp/react`, not the package root, so the core stays runtime-agnostic and dependency-free.
  */
@@ -18,8 +18,8 @@ import { defineMcpWidget } from "./widget.js";
 /** Bundle `component` + a bootstrap into a self-contained browser IIFE that renders on pushed data. */
 async function bundleComponent(componentPath, minify) {
     const dir = dirname(componentPath);
-    // The bootstrap must sit next to the component so its relative import — and `react`/`react-dom`
-    // resolution up the tree — work against the consumer's node_modules. Unique name; removed in `finally`.
+    // The bootstrap must sit next to the component so its relative import - and `react`/`react-dom`
+    // resolution up the tree - work against the consumer's node_modules. Unique name; removed in `finally`.
     const bootPath = join(dir, `.nifra-mcp-widget.${randomBytes(6).toString("hex")}.tsx`);
     const boot = `import { createElement } from "react"
 import { createRoot } from "react-dom/client"
@@ -52,12 +52,12 @@ if (el) {
         await rm(bootPath, { force: true });
     }
 }
-/** Build a {@link McpWidget} from a React component. Async — it bundles the component at definition time
+/** Build a {@link McpWidget} from a React component. Async - it bundles the component at definition time
  * (a one-time cost at server start); pass the result to `createMcpServer({ widgets })` / a tool's `widget`. */
 export async function reactWidget(opts) {
     const bundle = await bundleComponent(opts.component, opts.minify ?? true);
     // Escape any `</script` the bundle may contain (inside string/regex literals) so it can't terminate
-    // this inline <script> early — `<\/script` is equivalent JS but invisible to the HTML parser.
+    // this inline <script> early - `<\/script` is equivalent JS but invisible to the HTML parser.
     const safe = bundle.replace(/<\/(script)/gi, "<\\/$1");
     return defineMcpWidget({
         uri: opts.uri,

package/dist/server.d.ts

@@ -1,5 +1,5 @@
 /**
- * `createMcpServer` — assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
+ * `createMcpServer` - assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
  *
  * Pass tools (ideally from {@link ./tool.ts | defineMcpTool}) and widgets (from {@link ./widget.ts |
  * defineMcpWidget}); the widgets' resources are registered and the `io.modelcontextprotocol/ui` capability
@@ -14,7 +14,7 @@
  *
  * {@link McpServer.handle} dispatches a single JSON-RPC message directly (for headless verification / tests).
  *
- * SECURITY: this has NO built-in authentication — once mounted, every tool is callable by anyone who can
+ * SECURITY: this has NO built-in authentication - once mounted, every tool is callable by anyone who can
  * reach the route (the CORS header is `*` and no credentials are used, so it is effectively public). That
  * is fine for read-only/public tools; if any tool mutates state or returns private data, gate the route
  * yourself (check an `Authorization` header / session in the nifra handler before calling `mcp.fetch`).
@@ -25,7 +25,7 @@ export interface CreateMcpServerOptions {
     readonly name: string;
     readonly version: string;
     readonly tools?: readonly McpTool[];
-    /** MCP Apps widgets — their resources are registered and the UI capability is advertised. */
+    /** MCP Apps widgets - their resources are registered and the UI capability is advertised. */
     readonly widgets?: readonly McpWidget[];
     /** Extra (non-widget) resources to expose. */
     readonly resources?: readonly McpResource[];
@@ -42,9 +42,9 @@ export interface McpServer {
         name: string;
         version: string;
     };
-    /** Web `fetch` handler — mount at `POST /mcp` (GET is a health page, OPTIONS the CORS preflight). */
+    /** Web `fetch` handler - mount at `POST /mcp` (GET is a health page, OPTIONS the CORS preflight). */
     fetch(request: Request): Promise<Response>;
-    /** Dispatch one JSON-RPC message directly (no HTTP) — for headless verification and unit tests. */
+    /** Dispatch one JSON-RPC message directly (no HTTP) - for headless verification and unit tests. */
     handle(message: JsonRpcRequest): Promise<JsonRpcResponse | null>;
 }
 export declare function createMcpServer(opts: CreateMcpServerOptions): McpServer;

package/dist/server.js

@@ -1,5 +1,5 @@
 /**
- * `createMcpServer` — assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
+ * `createMcpServer` - assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
  *
  * Pass tools (ideally from {@link ./tool.ts | defineMcpTool}) and widgets (from {@link ./widget.ts |
  * defineMcpWidget}); the widgets' resources are registered and the `io.modelcontextprotocol/ui` capability
@@ -14,7 +14,7 @@
  *
  * {@link McpServer.handle} dispatches a single JSON-RPC message directly (for headless verification / tests).
  *
- * SECURITY: this has NO built-in authentication — once mounted, every tool is callable by anyone who can
+ * SECURITY: this has NO built-in authentication - once mounted, every tool is callable by anyone who can
  * reach the route (the CORS header is `*` and no credentials are used, so it is effectively public). That
  * is fine for read-only/public tools; if any tool mutates state or returns private data, gate the route
  * yourself (check an `Authorization` header / session in the nifra handler before calling `mcp.fetch`).

package/dist/tool.d.ts

@@ -1,10 +1,10 @@
 /**
- * `defineMcpTool` — author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
+ * `defineMcpTool` - author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
  *
  * The handler returns either a `string` (a plain text result, base MCP) or an object with `structuredContent`
  * (the data a linked {@link ./widget.ts | widget} renders) and/or `text` (the model-facing summary). When a
  * `widget` is passed, the tool advertises it via `_meta.ui.resourceUri` on both `tools/list` and each
- * `tools/call` result, so the host knows to render the widget — see {@link ../protocol.ts}.
+ * `tools/call` result, so the host knows to render the widget - see {@link ../protocol.ts}.
  */
 import type { McpContentBlock, McpTool, McpToolContext } from "./protocol.js";
 import type { InferOutput, StandardSchemaV1 } from "./standard.js";
@@ -15,7 +15,7 @@ export type McpToolHandlerResult = string | {
     readonly text?: string;
     /** Explicit content blocks (overrides `text`). */
     readonly content?: readonly McpContentBlock[];
-    /** Structured data for the linked widget — NOT added to the model's context. */
+    /** Structured data for the linked widget - NOT added to the model's context. */
     readonly structuredContent?: Record<string, unknown>;
     readonly _meta?: Record<string, unknown>;
     readonly isError?: boolean;
@@ -24,7 +24,7 @@ export type McpToolHandlerResult = string | {
  * A render-intent hint for GENERATIVE hosts: how to present the result's
  * `structuredContent` when the host renders its OWN themed UI rather than an iframe widget. The host maps
  * the intent to a component in its design system (a shadcn/Tailwind table, form, metric card, …). Open
- * union — pick a known tag or a custom one.
+ * union - pick a known tag or a custom one.
  */
 export type McpUiIntent = "table" | "list" | "cards" | "form" | "metric" | "detail" | "chart" | (string & {});
 /** The default when no `input` schema is given: arguments arrive untyped and unvalidated. */
@@ -48,7 +48,7 @@ export interface DefineMcpToolOptions<S extends StandardSchemaV1 = UntypedArgs>
     /** Link a widget so the tool's result renders as interactive UI in MCP Apps hosts (iframe). */
     readonly widget?: McpWidget;
     /** Render-intent for generative hosts that build their own themed UI from `structuredContent`. Lands
-     * in `_meta.ui.intent`. Independent of `widget` — a tool can offer both (widget for MCP Apps hosts,
+     * in `_meta.ui.intent`. Independent of `widget` - a tool can offer both (widget for MCP Apps hosts,
      * intent for generative builders). */
     readonly intent?: McpUiIntent;
     readonly handler: (args: InferOutput<S>, context: McpToolContext) => McpToolHandlerResult | Promise<McpToolHandlerResult>;

package/dist/tool.js

@@ -1,10 +1,10 @@
 /**
- * `defineMcpTool` — author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
+ * `defineMcpTool` - author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
  *
  * The handler returns either a `string` (a plain text result, base MCP) or an object with `structuredContent`
  * (the data a linked {@link ./widget.ts | widget} renders) and/or `text` (the model-facing summary). When a
  * `widget` is passed, the tool advertises it via `_meta.ui.resourceUri` on both `tools/list` and each
- * `tools/call` result, so the host knows to render the widget — see {@link ../protocol.ts}.
+ * `tools/call` result, so the host knows to render the widget - see {@link ../protocol.ts}.
  */
 import { formatIssues, jsonSchemaOf } from "./standard.js";
 /** Build a tool's descriptor `_meta` from its widget link and/or render intent (both under `ui`). */

package/dist/widget.d.ts

@@ -1,27 +1,27 @@
 /**
- * `defineMcpWidget` — author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
+ * `defineMcpWidget` - author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
  *
  * A widget is ONE self-contained HTML document, served as an MCP resource with MIME {@link UI_MIME}. The
  * host renders it in a sandboxed iframe and pushes the linked tool's `structuredContent` in over the
- * {@link ./bridge.ts} bridge — so the author writes plain markup + `mcpApp.onData(render)`, no transport
+ * {@link ./bridge.ts} bridge - so the author writes plain markup + `mcpApp.onData(render)`, no transport
  * glue. Link it to a tool with {@link ./tool.ts | defineMcpTool({ widget })}, which stamps the tool's
  * `_meta.ui.resourceUri` from {@link McpWidget.meta}.
  *
- * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED — escape it before
+ * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED - escape it before
  * writing to `innerHTML`, or render with a framework that escapes (React/Preact, or `@nifrajs/mcp/react`).
  * The sandboxed iframe limits blast radius, but a widget that builds markup by string concatenation can
  * still XSS itself; the bridge passes data through, it does not sanitize.
  */
 import { type McpResource } from "./protocol.js";
 export interface DefineMcpWidgetOptions {
-    /** The widget's resource URI — MUST use the `ui://` scheme, e.g. `ui://orders/table`. */
+    /** The widget's resource URI - MUST use the `ui://` scheme, e.g. `ui://orders/table`. */
     readonly uri: string;
     /** Human-readable name (shown by hosts that list resources). */
     readonly name: string;
     readonly description?: string;
     /** Document title (defaults to `name`). */
     readonly title?: string;
-    /** Extra `<head>` content — `<style>`, `<meta>`, fonts. The bridge `<script>` is injected for you. */
+    /** Extra `<head>` content - `<style>`, `<meta>`, fonts. The bridge `<script>` is injected for you. */
     readonly head?: string;
     /** The widget body: markup plus a `<script>` that renders from `mcpApp.onData(...)` and may
      * `mcpApp.callTool(...)`. The bridge global is defined before this runs. */

package/dist/widget.js

@@ -1,13 +1,13 @@
 /**
- * `defineMcpWidget` — author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
+ * `defineMcpWidget` - author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
  *
  * A widget is ONE self-contained HTML document, served as an MCP resource with MIME {@link UI_MIME}. The
  * host renders it in a sandboxed iframe and pushes the linked tool's `structuredContent` in over the
- * {@link ./bridge.ts} bridge — so the author writes plain markup + `mcpApp.onData(render)`, no transport
+ * {@link ./bridge.ts} bridge - so the author writes plain markup + `mcpApp.onData(render)`, no transport
  * glue. Link it to a tool with {@link ./tool.ts | defineMcpTool({ widget })}, which stamps the tool's
  * `_meta.ui.resourceUri` from {@link McpWidget.meta}.
  *
- * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED — escape it before
+ * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED - escape it before
  * writing to `innerHTML`, or render with a framework that escapes (React/Preact, or `@nifrajs/mcp/react`).
  * The sandboxed iframe limits blast radius, but a widget that builds markup by string concatenation can
  * still XSS itself; the bridge passes data through, it does not sanitize.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@nifrajs/mcp",
-  "version": "2.2.0",
-  "description": "Build MCP servers — and MCP Apps (interactive `ui://` widgets, SEP-1865) — for a nifra app. The transport-agnostic JSON-RPC core (also used by `@nifrajs/cli`'s dev MCP), a Streamable-HTTP handler you mount at `POST /mcp`, and `defineMcpWidget`/`defineMcpTool` for tool results that render real UI in MCP hosts.",
+  "version": "2.4.0",
+  "description": "Build MCP servers - and MCP Apps (interactive `ui://` widgets, SEP-1865) - for a nifra app. The transport-agnostic JSON-RPC core (also used by `@nifrajs/cli`'s dev MCP), a Streamable-HTTP handler you mount at `POST /mcp`, and `defineMcpWidget`/`defineMcpTool` for tool results that render real UI in MCP hosts.",
   "keywords": [
     "bun",
     "typescript",

package/src/bridge.ts

@@ -4,7 +4,7 @@
  *
  *   host → widget : `ui/notifications/tool-result` (the tools/call result incl. `structuredContent`),
  *                   `ui/notifications/tool-input` (the call arguments), and `ui/notifications/theme`
- *                   (the host's design tokens) — pushed as JSON-RPC notifications.
+ *                   (the host's design tokens) - pushed as JSON-RPC notifications.
  *   widget → host : `tools/call` requests (id-matched) so a button can re-invoke a tool through the host.
  *
  * Theming follows the shadcn/Tailwind semantic-token convention (`--background`, `--foreground`,
@@ -13,7 +13,7 @@
  * app with zero per-widget work.
  *
  * It exposes a small global the widget author scripts against, so authoring a widget is just
- * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` — no postMessage plumbing.
+ * `mcpApp.onData(render)` + (optionally) `mcpApp.callTool(name, args)` - no postMessage plumbing.
  *
  * Returned as a string so {@link ./widget.ts} can inline it in the resource HTML (a widget ships as ONE
  * self-contained document; the host renders it in a sandboxed iframe with no network of its own).
@@ -23,7 +23,7 @@
 export interface McpAppBridge {
   /** Latest `structuredContent` the host pushed (or `null` before the first result). */
   data: unknown
-  /** Register a callback for `structuredContent` — fired immediately if data already arrived, then on
+  /** Register a callback for `structuredContent` - fired immediately if data already arrived, then on
    * every later `ui/notifications/tool-result`. The common case: `mcpApp.onData(render)`. */
   onData(cb: (data: unknown) => void): void
   /** Register a callback for the raw tool-call arguments (`ui/notifications/tool-input`). */
@@ -94,7 +94,7 @@ const BRIDGE_SOURCE = `(function () {
   window.addEventListener("message", function (event) {
     // Only trust the embedding host (the parent window). A widget renders in a sandboxed iframe whose host
     // posts via the parent (or a sandbox-proxy parent), so event.source === window.parent. Reject anything
-    // else — including a null source (synthetic/dispatched events) — so a sibling/opener frame or in-page
+    // else - including a null source (synthetic/dispatched events) - so a sibling/opener frame or in-page
     // script can't spoof tool-results, tool-call responses, or theme. (A top-level widget has no host.)
     if (event.source !== window.parent || window.parent === window) return;
     var msg = event.data;

package/src/http.ts

@@ -1,8 +1,8 @@
 /**
- * The transport core shared by every HTTP host of an MCP server — the dev/docs MCP in `@nifrajs/cli`
+ * The transport core shared by every HTTP host of an MCP server - the dev/docs MCP in `@nifrajs/cli`
  * (`nifra docs-mcp`), the site's edge worker, and a nifra app mounting `POST /mcp` via
  * {@link ./server.ts}. {@link respondMcpHttp} is a plain Web `fetch` handler: POST a JSON-RPC body →
- * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws — a bad body
+ * JSON-RPC response; GET is a health page; OPTIONS is the CORS preflight. It never throws - a bad body
  * becomes a JSON-RPC parse error. Pass the tools (and optional {@link McpServerFeatures} for resources /
  * prompts / the MCP Apps `ui://` widgets) so each host supplies its own corpus/source behind one core.
  */
@@ -88,7 +88,7 @@ async function readJsonBounded(
 
 /**
  * Handle one MCP request over HTTP against the given `tools`/`features`. POST a JSON-RPC body → JSON-RPC
- * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws — a bad body becomes a
+ * response; GET → a plain-text health page; OPTIONS → CORS preflight. Never throws - a bad body becomes a
  * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.
  */
 export async function respondMcpHttp(
@@ -101,7 +101,7 @@ export async function respondMcpHttp(
   if (request.method === "GET") {
     return new Response(
       options.health ??
-        "MCP server — POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call).",
+        "MCP server - POST JSON-RPC 2.0 here (methods: initialize, tools/list, tools/call).",
       { headers: { "content-type": "text/plain; charset=utf-8", ...CORS } },
     )
   }
@@ -125,7 +125,7 @@ export async function respondMcpHttp(
   const response = await handleRpc(message, tools, serverInfo, options.features ?? {}, {
     signal: request.signal,
   })
-  // A notification (no id) yields null — acknowledge with 204, no body.
+  // A notification (no id) yields null - acknowledge with 204, no body.
   if (response === null) return new Response(null, { status: 204, headers: CORS })
   return Response.json(response, { headers: CORS })
 }

package/src/index.ts

@@ -1,12 +1,12 @@
 /**
- * `@nifrajs/mcp` — build MCP servers (and MCP Apps) for a nifra app.
+ * `@nifrajs/mcp` - build MCP servers (and MCP Apps) for a nifra app.
  *
- * - {@link ./protocol.ts} — the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
+ * - {@link ./protocol.ts} - the transport-agnostic JSON-RPC dispatch ({@link handleRpc}) + types, plus
  *   the MCP Apps (SEP-1865) extension (`structuredContent`, `_meta.ui.resourceUri`, the UI capability).
- * - {@link ./http.ts} — {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
+ * - {@link ./http.ts} - {@link respondMcpHttp}, a Web `fetch` handler you mount at `POST /mcp`.
  *
- * Higher-level authoring helpers — {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
- * — build MCP Apps servers whose tool results render real UI.
+ * Higher-level authoring helpers - {@link defineMcpWidget}, {@link defineMcpTool}, {@link createMcpServer}
+ * - build MCP Apps servers whose tool results render real UI.
  */
 
 export { bridgeScript, type McpAppBridge } from "./bridge.ts"

package/src/protocol.ts

@@ -1,13 +1,13 @@
 /**
- * The pure MCP (Model Context Protocol) JSON-RPC dispatch — no I/O, no `Bun.*`, no side effects, so it
+ * The pure MCP (Model Context Protocol) JSON-RPC dispatch - no I/O, no `Bun.*`, no side effects, so it
  * unit-tests cleanly. A transport (stdio in `@nifrajs/cli`'s `mcp.ts`, Streamable-HTTP in {@link ./http.ts})
  * wires this to a byte stream; the tools/resources are injected, so the protocol logic is exercised
  * without spawning or reading streams.
  *
- * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** — interactive `ui://`
+ * Beyond base MCP this also implements the server half of **MCP Apps (SEP-1865)** - interactive `ui://`
  * widgets: a tool links a UI resource via `_meta.ui.resourceUri`, `tools/call` returns `structuredContent`
  * for the widget to render, and `initialize` advertises the `io.modelcontextprotocol/ui` extension. All of
- * it is additive — a tool whose handler returns a plain `string` behaves exactly as before.
+ * it is additive - a tool whose handler returns a plain `string` behaves exactly as before.
  */
 
 export const PROTOCOL_VERSION = "2024-11-05"
@@ -28,7 +28,7 @@ export interface McpToolContext {
   readonly reportProgress: (progress: number, total?: number) => void
 }
 
-/** A single content block in a tool result. Today only text — the model-facing representation. */
+/** A single content block in a tool result. Today only text - the model-facing representation. */
 export interface McpContentBlock {
   readonly type: "text"
   readonly text: string
@@ -49,7 +49,7 @@ export interface McpToolResult {
 
 /** A tool the agent can call. `handler` returns the text shown to the agent, or a rich {@link McpToolResult}
  * (for MCP Apps: structured data + a `ui://` widget link). `_meta` is the per-tool descriptor metadata
- * surfaced in `tools/list` — for a widget tool it carries `ui.resourceUri`. */
+ * surfaced in `tools/list` - for a widget tool it carries `ui.resourceUri`. */
 /** MCP tool safety hints (`readOnlyHint`/`destructiveHint`/…) surfaced in `tools/list`, per the MCP spec. */
 export interface McpToolAnnotations {
   readonly title?: string
@@ -375,7 +375,7 @@ export async function handleRpc(
           ],
         })
       } catch {
-        // Don't surface the raw read error — it can leak a filesystem path. Return a generic message.
+        // Don't surface the raw read error - it can leak a filesystem path. Return a generic message.
         return rpcError(rid, -32000, `failed to read resource: ${String(uri)}`)
       }
     }

package/src/react.ts

@@ -1,13 +1,13 @@
 /**
- * `reactWidget` — author an MCP Apps (`ui://`) widget from a React component instead of hand-written HTML.
+ * `reactWidget` - author an MCP Apps (`ui://`) widget from a React component instead of hand-written HTML.
  *
  * The component is bundled for the browser (via `Bun.build`) together with a bootstrap that mounts it and
- * re-renders on every `structuredContent` the host pushes — `mcpApp.onData(data => root.render(<C {...data}/>))`.
+ * re-renders on every `structuredContent` the host pushes - `mcpApp.onData(data => root.render(<C {...data}/>))`.
  * So a widget author writes a normal nifra/React component that takes the tool's structured data as props;
  * the bridge wiring and bundling are handled here. Client-rendered (the widget shell is the resource the
  * host fetches once; data arrives over the bridge), which matches how a host renders MCP App widgets.
  *
- * `react` + `react-dom` resolve from the CONSUMER's `node_modules` at bundle time — they are NOT a
+ * `react` + `react-dom` resolve from the CONSUMER's `node_modules` at bundle time - they are NOT a
  * dependency of `@nifrajs/mcp`. This entry is Bun-only (it calls `Bun.build`); import it from
  * `@nifrajs/mcp/react`, not the package root, so the core stays runtime-agnostic and dependency-free.
  */
@@ -34,8 +34,8 @@ export interface ReactWidgetOptions {
 /** Bundle `component` + a bootstrap into a self-contained browser IIFE that renders on pushed data. */
 async function bundleComponent(componentPath: string, minify: boolean): Promise<string> {
   const dir = dirname(componentPath)
-  // The bootstrap must sit next to the component so its relative import — and `react`/`react-dom`
-  // resolution up the tree — work against the consumer's node_modules. Unique name; removed in `finally`.
+  // The bootstrap must sit next to the component so its relative import - and `react`/`react-dom`
+  // resolution up the tree - work against the consumer's node_modules. Unique name; removed in `finally`.
   const bootPath = join(dir, `.nifra-mcp-widget.${randomBytes(6).toString("hex")}.tsx`)
   const boot = `import { createElement } from "react"
 import { createRoot } from "react-dom/client"
@@ -69,12 +69,12 @@ if (el) {
   }
 }
 
-/** Build a {@link McpWidget} from a React component. Async — it bundles the component at definition time
+/** Build a {@link McpWidget} from a React component. Async - it bundles the component at definition time
  * (a one-time cost at server start); pass the result to `createMcpServer({ widgets })` / a tool's `widget`. */
 export async function reactWidget(opts: ReactWidgetOptions): Promise<McpWidget> {
   const bundle = await bundleComponent(opts.component, opts.minify ?? true)
   // Escape any `</script` the bundle may contain (inside string/regex literals) so it can't terminate
-  // this inline <script> early — `<\/script` is equivalent JS but invisible to the HTML parser.
+  // this inline <script> early - `<\/script` is equivalent JS but invisible to the HTML parser.
   const safe = bundle.replace(/<\/(script)/gi, "<\\/$1")
   return defineMcpWidget({
     uri: opts.uri,

package/src/server.ts

@@ -1,5 +1,5 @@
 /**
- * `createMcpServer` — assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
+ * `createMcpServer` - assemble a mountable MCP server for a nifra app, with MCP Apps (`ui://`) widgets.
  *
  * Pass tools (ideally from {@link ./tool.ts | defineMcpTool}) and widgets (from {@link ./widget.ts |
  * defineMcpWidget}); the widgets' resources are registered and the `io.modelcontextprotocol/ui` capability
@@ -14,7 +14,7 @@
  *
  * {@link McpServer.handle} dispatches a single JSON-RPC message directly (for headless verification / tests).
  *
- * SECURITY: this has NO built-in authentication — once mounted, every tool is callable by anyone who can
+ * SECURITY: this has NO built-in authentication - once mounted, every tool is callable by anyone who can
  * reach the route (the CORS header is `*` and no credentials are used, so it is effectively public). That
  * is fine for read-only/public tools; if any tool mutates state or returns private data, gate the route
  * yourself (check an `Authorization` header / session in the nifra handler before calling `mcp.fetch`).
@@ -37,7 +37,7 @@ export interface CreateMcpServerOptions {
   readonly name: string
   readonly version: string
   readonly tools?: readonly McpTool[]
-  /** MCP Apps widgets — their resources are registered and the UI capability is advertised. */
+  /** MCP Apps widgets - their resources are registered and the UI capability is advertised. */
   readonly widgets?: readonly McpWidget[]
   /** Extra (non-widget) resources to expose. */
   readonly resources?: readonly McpResource[]
@@ -52,9 +52,9 @@ export interface McpServer {
   readonly tools: McpTool[]
   readonly features: McpServerFeatures
   readonly serverInfo: { name: string; version: string }
-  /** Web `fetch` handler — mount at `POST /mcp` (GET is a health page, OPTIONS the CORS preflight). */
+  /** Web `fetch` handler - mount at `POST /mcp` (GET is a health page, OPTIONS the CORS preflight). */
   fetch(request: Request): Promise<Response>
-  /** Dispatch one JSON-RPC message directly (no HTTP) — for headless verification and unit tests. */
+  /** Dispatch one JSON-RPC message directly (no HTTP) - for headless verification and unit tests. */
   handle(message: JsonRpcRequest): Promise<JsonRpcResponse | null>
 }
 

package/src/tool.ts

@@ -1,10 +1,10 @@
 /**
- * `defineMcpTool` — author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
+ * `defineMcpTool` - author a tool for a nifra MCP server, optionally backed by an MCP Apps widget.
  *
  * The handler returns either a `string` (a plain text result, base MCP) or an object with `structuredContent`
  * (the data a linked {@link ./widget.ts | widget} renders) and/or `text` (the model-facing summary). When a
  * `widget` is passed, the tool advertises it via `_meta.ui.resourceUri` on both `tools/list` and each
- * `tools/call` result, so the host knows to render the widget — see {@link ../protocol.ts}.
+ * `tools/call` result, so the host knows to render the widget - see {@link ../protocol.ts}.
  */
 
 import type { McpContentBlock, McpTool, McpToolContext, McpToolResult } from "./protocol.ts"
@@ -20,7 +20,7 @@ export type McpToolHandlerResult =
       readonly text?: string
       /** Explicit content blocks (overrides `text`). */
       readonly content?: readonly McpContentBlock[]
-      /** Structured data for the linked widget — NOT added to the model's context. */
+      /** Structured data for the linked widget - NOT added to the model's context. */
       readonly structuredContent?: Record<string, unknown>
       readonly _meta?: Record<string, unknown>
       readonly isError?: boolean
@@ -30,7 +30,7 @@ export type McpToolHandlerResult =
  * A render-intent hint for GENERATIVE hosts: how to present the result's
  * `structuredContent` when the host renders its OWN themed UI rather than an iframe widget. The host maps
  * the intent to a component in its design system (a shadcn/Tailwind table, form, metric card, …). Open
- * union — pick a known tag or a custom one.
+ * union - pick a known tag or a custom one.
  */
 export type McpUiIntent =
   | "table"
@@ -64,7 +64,7 @@ export interface DefineMcpToolOptions<S extends StandardSchemaV1 = UntypedArgs>
   /** Link a widget so the tool's result renders as interactive UI in MCP Apps hosts (iframe). */
   readonly widget?: McpWidget
   /** Render-intent for generative hosts that build their own themed UI from `structuredContent`. Lands
-   * in `_meta.ui.intent`. Independent of `widget` — a tool can offer both (widget for MCP Apps hosts,
+   * in `_meta.ui.intent`. Independent of `widget` - a tool can offer both (widget for MCP Apps hosts,
    * intent for generative builders). */
   readonly intent?: McpUiIntent
   readonly handler: (

package/src/widget.ts

@@ -1,13 +1,13 @@
 /**
- * `defineMcpWidget` — author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
+ * `defineMcpWidget` - author an MCP Apps (`ui://`) interactive widget for a nifra MCP server.
  *
  * A widget is ONE self-contained HTML document, served as an MCP resource with MIME {@link UI_MIME}. The
  * host renders it in a sandboxed iframe and pushes the linked tool's `structuredContent` in over the
- * {@link ./bridge.ts} bridge — so the author writes plain markup + `mcpApp.onData(render)`, no transport
+ * {@link ./bridge.ts} bridge - so the author writes plain markup + `mcpApp.onData(render)`, no transport
  * glue. Link it to a tool with {@link ./tool.ts | defineMcpTool({ widget })}, which stamps the tool's
  * `_meta.ui.resourceUri` from {@link McpWidget.meta}.
  *
- * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED — escape it before
+ * SECURITY: `structuredContent` (and any theme) arriving over the bridge is UNTRUSTED - escape it before
  * writing to `innerHTML`, or render with a framework that escapes (React/Preact, or `@nifrajs/mcp/react`).
  * The sandboxed iframe limits blast radius, but a widget that builds markup by string concatenation can
  * still XSS itself; the bridge passes data through, it does not sanitize.
@@ -17,14 +17,14 @@ import { bridgeScript } from "./bridge.ts"
 import { type McpResource, UI_MIME } from "./protocol.ts"
 
 export interface DefineMcpWidgetOptions {
-  /** The widget's resource URI — MUST use the `ui://` scheme, e.g. `ui://orders/table`. */
+  /** The widget's resource URI - MUST use the `ui://` scheme, e.g. `ui://orders/table`. */
   readonly uri: string
   /** Human-readable name (shown by hosts that list resources). */
   readonly name: string
   readonly description?: string
   /** Document title (defaults to `name`). */
   readonly title?: string
-  /** Extra `<head>` content — `<style>`, `<meta>`, fonts. The bridge `<script>` is injected for you. */
+  /** Extra `<head>` content - `<style>`, `<meta>`, fonts. The bridge `<script>` is injected for you. */
   readonly head?: string
   /** The widget body: markup plus a `<script>` that renders from `mcpApp.onData(...)` and may
    * `mcpApp.callTool(...)`. The bridge global is defined before this runs. */