@nifrajs/mcp 1.0.0

package/dist/widget.d.ts

@@ -0,0 +1,43 @@
+/**
+ * `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
+ * 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
+ * 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`. */
+    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. */
+    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. */
+    readonly html: string;
+}
+/** The MCP Apps `_meta.ui.resourceUri` link, emitted nested (current spec) AND flat (the deprecated
+ * `ui/resourceUri`, still read by some hosts) so a tool renders across the transition. */
+export declare function uiResourceMeta(uri: string): Record<string, unknown>;
+/** A widget: the resource to register on the server, its `ui://` URI, and the `_meta` link for its tool. */
+export interface McpWidget {
+    readonly uri: string;
+    readonly resource: McpResource;
+    readonly meta: Record<string, unknown>;
+}
+/** Assemble the full self-contained widget document (bridge inlined in `<head>` so body scripts can use
+ * `mcpApp` immediately). */
+export declare function widgetDocument(opts: DefineMcpWidgetOptions): string;
+export declare function defineMcpWidget(opts: DefineMcpWidgetOptions): McpWidget;
+//# sourceMappingURL=widget.d.ts.map

package/dist/widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.d.ts","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAGH,OAAO,EAAE,KAAK,WAAW,EAAW,MAAM,eAAe,CAAA;AAEzD,MAAM,WAAW,sBAAsB;IACrC,yFAAyF;IACzF,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAA;IAC7B,2CAA2C;IAC3C,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,sGAAsG;IACtG,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAA;IACtB;gFAC4E;IAC5E,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;CACtB;AAED;0FAC0F;AAC1F,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAEnE;AAED,4GAA4G;AAC5G,MAAM,WAAW,SAAS;IACxB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,QAAQ,EAAE,WAAW,CAAA;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CACvC;AAMD;4BAC4B;AAC5B,wBAAgB,cAAc,CAAC,IAAI,EAAE,sBAAsB,GAAG,MAAM,CAgBnE;AAED,wBAAgB,eAAe,CAAC,IAAI,EAAE,sBAAsB,GAAG,SAAS,CAavE"}

package/dist/widget.js

@@ -0,0 +1,58 @@
+/**
+ * `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
+ * 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
+ * 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 { bridgeScript } from "./bridge.js";
+import { UI_MIME } from "./protocol.js";
+/** The MCP Apps `_meta.ui.resourceUri` link, emitted nested (current spec) AND flat (the deprecated
+ * `ui/resourceUri`, still read by some hosts) so a tool renders across the transition. */
+export function uiResourceMeta(uri) {
+    return { ui: { resourceUri: uri }, "ui/resourceUri": uri };
+}
+function escapeHtml(text) {
+    return text.replace(/[&<>]/g, (c) => (c === "&" ? "&amp;" : c === "<" ? "&lt;" : "&gt;"));
+}
+/** Assemble the full self-contained widget document (bridge inlined in `<head>` so body scripts can use
+ * `mcpApp` immediately). */
+export function widgetDocument(opts) {
+    const title = escapeHtml(opts.title ?? opts.name);
+    return `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8" />
+<meta name="viewport" content="width=device-width, initial-scale=1" />
+<title>${title}</title>
+<script>${bridgeScript()}</script>
+${opts.head ?? ""}
+</head>
+<body>
+${opts.html}
+</body>
+</html>
+`;
+}
+export function defineMcpWidget(opts) {
+    if (!opts.uri.startsWith("ui://")) {
+        throw new Error(`defineMcpWidget: uri must use the ui:// scheme (got "${opts.uri}")`);
+    }
+    const html = widgetDocument(opts);
+    const resource = {
+        uri: opts.uri,
+        name: opts.name,
+        ...(opts.description !== undefined ? { description: opts.description } : {}),
+        mimeType: UI_MIME,
+        read: () => Promise.resolve({ text: html, mimeType: UI_MIME }),
+    };
+    return { uri: opts.uri, resource, meta: uiResourceMeta(opts.uri) };
+}
+//# sourceMappingURL=widget.js.map

package/dist/widget.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget.js","sourceRoot":"","sources":["../src/widget.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,aAAa,CAAA;AAC1C,OAAO,EAAoB,OAAO,EAAE,MAAM,eAAe,CAAA;AAiBzD;0FAC0F;AAC1F,MAAM,UAAU,cAAc,CAAC,GAAW;IACxC,OAAO,EAAE,EAAE,EAAE,EAAE,WAAW,EAAE,GAAG,EAAE,EAAE,gBAAgB,EAAE,GAAG,EAAE,CAAA;AAC5D,CAAC;AASD,SAAS,UAAU,CAAC,IAAY;IAC9B,OAAO,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,OAAO,CAAC,CAAC,CAAC,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAA;AAC3F,CAAC;AAED;4BAC4B;AAC5B,MAAM,UAAU,cAAc,CAAC,IAA4B;IACzD,MAAM,KAAK,GAAG,UAAU,CAAC,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,IAAI,CAAC,CAAA;IACjD,OAAO;;;;;SAKA,KAAK;UACJ,YAAY,EAAE;EACtB,IAAI,CAAC,IAAI,IAAI,EAAE;;;EAGf,IAAI,CAAC,IAAI;;;CAGV,CAAA;AACD,CAAC;AAED,MAAM,UAAU,eAAe,CAAC,IAA4B;IAC1D,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,UAAU,CAAC,OAAO,CAAC,EAAE,CAAC;QAClC,MAAM,IAAI,KAAK,CAAC,wDAAwD,IAAI,CAAC,GAAG,IAAI,CAAC,CAAA;IACvF,CAAC;IACD,MAAM,IAAI,GAAG,cAAc,CAAC,IAAI,CAAC,CAAA;IACjC,MAAM,QAAQ,GAAgB;QAC5B,GAAG,EAAE,IAAI,CAAC,GAAG;QACb,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,CAAC,IAAI,CAAC,WAAW,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,WAAW,EAAE,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC5E,QAAQ,EAAE,OAAO;QACjB,IAAI,EAAE,GAAG,EAAE,CAAC,OAAO,CAAC,OAAO,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,OAAO,EAAE,CAAC;KAC/D,CAAA;IACD,OAAO,EAAE,GAAG,EAAE,IAAI,CAAC,GAAG,EAAE,QAAQ,EAAE,IAAI,EAAE,cAAc,CAAC,IAAI,CAAC,GAAG,CAAC,EAAE,CAAA;AACpE,CAAC"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@nifrajs/mcp",
+  "version": "1.0.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",
+    "nifra",
+    "mcp",
+    "model-context-protocol",
+    "mcp-apps",
+    "mcp-ui",
+    "json-rpc",
+    "ai",
+    "tools",
+    "widgets"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "bun": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    },
+    "./protocol": {
+      "bun": "./src/protocol.ts",
+      "types": "./dist/protocol.d.ts",
+      "default": "./dist/protocol.js"
+    },
+    "./http": {
+      "bun": "./src/http.ts",
+      "types": "./dist/http.d.ts",
+      "default": "./dist/http.js"
+    },
+    "./react": {
+      "bun": "./src/react.ts",
+      "types": "./dist/react.d.ts",
+      "default": "./dist/react.js"
+    }
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "sideEffects": false,
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json && bun run ../../scripts/fix-dts.ts dist"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nifrajs/nifra.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/nifrajs/nifra/issues"
+  },
+  "homepage": "https://github.com/nifrajs/nifra#readme"
+}

package/src/bridge.ts

@@ -0,0 +1,126 @@
+/**
+ * The tiny, dependency-free client bridge injected into every `ui://` widget's HTML (MCP Apps / SEP-1865).
+ * It speaks the MCP-JSON-RPC-over-`postMessage` subset a host exposes to an embedded UI:
+ *
+ *   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.
+ *   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`,
+ * `--primary`, `--card`, `--border`, `--radius`, …). The host pushes its resolved tokens; the bridge
+ * applies them to the document root, so a widget that styles with `var(--primary)` etc. matches the host
+ * app (e.g. a ShipNow-generated app injecting its theme preset) 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.
+ *
+ * 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).
+ */
+
+/** The author-facing global injected into a widget. Kept minimal and stable. */
+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
+   * 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`). */
+  onInput(cb: (args: unknown) => void): void
+  /** Latest theme the host pushed (`{ mode, tokens }`), or `null` before the first push. */
+  theme: unknown
+  /** Register a callback for host theme pushes. The bridge ALSO auto-applies the tokens to the document
+   * root (shadcn semantic vars + `color-scheme`/`data-theme`), so most widgets need no theme code. */
+  onTheme(cb: (theme: unknown) => void): void
+  /** Invoke a tool back through the host; resolves with the tools/call result. */
+  callTool(name: string, args?: Record<string, unknown>): Promise<unknown>
+}
+
+/** The bridge source, as a string for inlining in a `<script>`. Self-contained, no imports. */
+export function bridgeScript(): string {
+  return BRIDGE_SOURCE
+}
+
+// Authored as a plain string (not a function we `.toString()`) so a bundler/minifier can't rename the
+// global or strip it, and so it has zero dependency on this module's runtime. Intentionally ES5-ish for
+// maximal host/iframe compatibility.
+const BRIDGE_SOURCE = `(function () {
+  var pending = {};
+  var nextId = 1;
+  var dataCbs = [];
+  var inputCbs = [];
+  var themeCbs = [];
+  function applyTheme(theme) {
+    if (!theme || typeof theme !== "object") return;
+    var root = document.documentElement;
+    if (theme.mode === "light" || theme.mode === "dark") {
+      root.setAttribute("data-theme", theme.mode);
+      root.style.colorScheme = theme.mode;
+    }
+    var tokens = theme.tokens;
+    if (tokens && typeof tokens === "object") {
+      for (var k in tokens) {
+        if (Object.prototype.hasOwnProperty.call(tokens, k)) {
+          root.style.setProperty(k.charAt(0) === "-" ? k : "--" + k, String(tokens[k]));
+        }
+      }
+    }
+  }
+  var api = {
+    data: null,
+    theme: null,
+    onData: function (cb) {
+      if (typeof cb !== "function") return;
+      dataCbs.push(cb);
+      if (api.data !== null) { try { cb(api.data); } catch (e) {} }
+    },
+    onInput: function (cb) { if (typeof cb === "function") inputCbs.push(cb); },
+    onTheme: function (cb) {
+      if (typeof cb !== "function") return;
+      themeCbs.push(cb);
+      if (api.theme !== null) { try { cb(api.theme); } catch (e) {} }
+    },
+    callTool: function (name, args) {
+      var id = "w" + nextId++;
+      return new Promise(function (resolve, reject) {
+        pending[id] = { resolve: resolve, reject: reject };
+        post({ jsonrpc: "2.0", id: id, method: "tools/call", params: { name: name, arguments: args || {} } });
+      });
+    }
+  };
+  function post(msg) { try { (window.parent || window).postMessage(msg, "*"); } catch (e) {} }
+  function emit(list, value) { for (var i = 0; i < list.length; i++) { try { list[i](value); } catch (e) {} } }
+  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
+    // 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;
+    if (!msg || typeof msg !== "object") return;
+    // A response to one of our tools/call requests (id-matched).
+    if (msg.id != null && pending[msg.id]) {
+      var p = pending[msg.id]; delete pending[msg.id];
+      if (msg.error) p.reject(msg.error); else p.resolve(msg.result);
+      return;
+    }
+    // A host → widget notification.
+    if (msg.method === "ui/notifications/tool-result") {
+      var params = msg.params || {};
+      var structured = params.structuredContent != null ? params.structuredContent : params;
+      api.data = structured;
+      emit(dataCbs, structured);
+    } else if (msg.method === "ui/notifications/tool-input") {
+      emit(inputCbs, (msg.params || {}).arguments);
+    } else if (msg.method === "ui/notifications/theme") {
+      var theme = msg.params || {};
+      api.theme = theme;
+      applyTheme(theme);
+      emit(themeCbs, theme);
+    }
+  });
+  window.mcpApp = api;
+  // Some hosts wait for the iframe to signal readiness before pushing data; harmless if ignored.
+  post({ jsonrpc: "2.0", method: "ui/notifications/ready" });
+})();`

package/src/http.ts

@@ -0,0 +1,131 @@
+/**
+ * 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
+ * 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.
+ */
+
+import {
+  handleRpc,
+  type JsonRpcRequest,
+  type McpServerFeatures,
+  type McpTool,
+  rpcError,
+} from "./protocol.ts"
+
+const CORS: Record<string, string> = {
+  "access-control-allow-origin": "*",
+  "access-control-allow-methods": "POST, GET, OPTIONS",
+  "access-control-allow-headers": "content-type",
+}
+
+const DEFAULT_MAX_BODY_BYTES = 1_000_000
+const TEXT_DECODER = new TextDecoder()
+
+export interface McpHttpOptions {
+  /** Maximum JSON-RPC request body size in bytes. Default 1 MB. */
+  readonly maxBodyBytes?: number
+  /** Resources / prompts / the MCP Apps UI extension served alongside the tools. */
+  readonly features?: McpServerFeatures
+  /** Shown on the GET health page so each host can describe itself. */
+  readonly health?: string
+}
+
+function parseContentLength(value: string): number | undefined {
+  if (value.length === 0) return undefined
+  let length = 0
+  for (let i = 0; i < value.length; i++) {
+    const digit = value.charCodeAt(i) - 48
+    if (digit < 0 || digit > 9) return undefined
+    length = length * 10 + digit
+    if (length > Number.MAX_SAFE_INTEGER) return Number.POSITIVE_INFINITY
+  }
+  return length
+}
+
+async function readJsonBounded(
+  request: Request,
+  maxBytes: number,
+): Promise<{ ok: true; value: unknown } | { ok: false; status: 400 | 413 }> {
+  const declared = request.headers.get("content-length")
+  if (declared !== null) {
+    const length = parseContentLength(declared)
+    if (length === undefined) return { ok: false, status: 400 }
+    if (length > maxBytes) return { ok: false, status: 413 }
+  }
+
+  const body = request.body
+  if (body === null) return { ok: false, status: 400 }
+
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  for (;;) {
+    const { done, value } = await reader.read()
+    if (done) break
+    total += value.byteLength
+    if (total > maxBytes) {
+      await reader.cancel()
+      return { ok: false, status: 413 }
+    }
+    chunks.push(value)
+  }
+
+  const bytes = new Uint8Array(total)
+  let offset = 0
+  for (const chunk of chunks) {
+    bytes.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+  try {
+    return { ok: true, value: JSON.parse(TEXT_DECODER.decode(bytes)) as unknown }
+  } catch {
+    return { ok: false, status: 400 }
+  }
+}
+
+/**
+ * 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
+ * JSON-RPC parse error. The dispatch is the shared, transport-agnostic {@link handleRpc}.
+ */
+export async function respondMcpHttp(
+  request: Request,
+  tools: McpTool[],
+  serverInfo: { name: string; version: string },
+  options: McpHttpOptions = {},
+): Promise<Response> {
+  if (request.method === "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 } },
+    )
+  }
+  if (request.method !== "POST") {
+    return new Response("method not allowed", {
+      status: 405,
+      headers: { allow: "POST, GET", ...CORS },
+    })
+  }
+  const parsed = await readJsonBounded(request, options.maxBodyBytes ?? DEFAULT_MAX_BODY_BYTES)
+  if (!parsed.ok) {
+    if (parsed.status === 413) {
+      return Response.json(rpcError(null, -32000, "payload too large"), {
+        status: 413,
+        headers: CORS,
+      })
+    }
+    return Response.json(rpcError(null, -32700, "parse error"), { status: 400, headers: CORS })
+  }
+  const message = parsed.value as JsonRpcRequest
+  const response = await handleRpc(message, tools, serverInfo, options.features ?? {}, {
+    signal: request.signal,
+  })
+  // 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

@@ -0,0 +1,28 @@
+/**
+ * `@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
+ *   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`.
+ *
+ * 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"
+export { type McpHttpOptions, respondMcpHttp } from "./http.ts"
+export * from "./protocol.ts"
+export { type CreateMcpServerOptions, createMcpServer, type McpServer } from "./server.ts"
+export {
+  type DefineMcpToolOptions,
+  defineMcpTool,
+  type McpToolHandlerResult,
+  type McpUiIntent,
+} from "./tool.ts"
+export {
+  type DefineMcpWidgetOptions,
+  defineMcpWidget,
+  type McpWidget,
+  uiResourceMeta,
+  widgetDocument,
+} from "./widget.ts"