@nifrajs/mcp 1.0.0

package/dist/bridge.d.ts

@@ -0,0 +1,40 @@
+/**
+ * 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 declare function bridgeScript(): string;
+//# sourceMappingURL=bridge.d.ts.map

package/dist/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,gFAAgF;AAChF,MAAM,WAAW,YAAY;IAC3B,sFAAsF;IACtF,IAAI,EAAE,OAAO,CAAA;IACb;+FAC2F;IAC3F,MAAM,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IACzC,2FAA2F;IAC3F,OAAO,CAAC,EAAE,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IAC1C,0FAA0F;IAC1F,KAAK,EAAE,OAAO,CAAA;IACd;wGACoG;IACpG,OAAO,CAAC,EAAE,EAAE,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,GAAG,IAAI,CAAA;IAC3C,gFAAgF;IAChF,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CACzE;AAED,+FAA+F;AAC/F,wBAAgB,YAAY,IAAI,MAAM,CAErC"}

package/dist/bridge.js

@@ -0,0 +1,107 @@
+/**
+ * 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 bridge source, as a string for inlining in a `<script>`. Self-contained, no imports. */
+export function bridgeScript() {
+    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" });
+})();`;
+//# sourceMappingURL=bridge.js.map

package/dist/bridge.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.js","sourceRoot":"","sources":["../src/bridge.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAoBH,+FAA+F;AAC/F,MAAM,UAAU,YAAY;IAC1B,OAAO,aAAa,CAAA;AACtB,CAAC;AAED,sGAAsG;AACtG,wGAAwG;AACxG,qCAAqC;AACrC,MAAM,aAAa,GAAG;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MA8EhB,CAAA"}

package/dist/http.d.ts

@@ -0,0 +1,27 @@
+/**
+ * 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 { type McpServerFeatures, type McpTool } from "./protocol.js";
+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;
+}
+/**
+ * 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 declare function respondMcpHttp(request: Request, tools: McpTool[], serverInfo: {
+    name: string;
+    version: string;
+}, options?: McpHttpOptions): Promise<Response>;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,EAGL,KAAK,iBAAiB,EACtB,KAAK,OAAO,EAEb,MAAM,eAAe,CAAA;AAWtB,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAA;IAC9B,kFAAkF;IAClF,QAAQ,CAAC,QAAQ,CAAC,EAAE,iBAAiB,CAAA;IACrC,qEAAqE;IACrE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAA;CACzB;AAuDD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,OAAO,EAAE,OAAO,EAChB,KAAK,EAAE,OAAO,EAAE,EAChB,UAAU,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,EAC7C,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,QAAQ,CAAC,CAgCnB"}

package/dist/http.js

@@ -0,0 +1,107 @@
+/**
+ * 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, rpcError, } from "./protocol.js";
+const CORS = {
+    "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();
+function parseContentLength(value) {
+    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, maxBytes) {
+    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 = [];
+    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)) };
+    }
+    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, tools, serverInfo, options = {}) {
+    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;
+    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 });
+}
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

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

package/dist/index.d.ts

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

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAE,KAAK,YAAY,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,KAAK,cAAc,EAAE,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAAE,KAAK,sBAAsB,EAAE,eAAe,EAAE,KAAK,SAAS,EAAE,MAAM,aAAa,CAAA;AAC1F,OAAO,EACL,KAAK,oBAAoB,EACzB,aAAa,EACb,KAAK,oBAAoB,EACzB,KAAK,WAAW,GACjB,MAAM,WAAW,CAAA;AAClB,OAAO,EACL,KAAK,sBAAsB,EAC3B,eAAe,EACf,KAAK,SAAS,EACd,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@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 } from "./bridge.js";
+export { respondMcpHttp } from "./http.js";
+export * from "./protocol.js";
+export { createMcpServer } from "./server.js";
+export { defineMcpTool, } from "./tool.js";
+export { defineMcpWidget, uiResourceMeta, widgetDocument, } from "./widget.js";
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,YAAY,EAAqB,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAuB,cAAc,EAAE,MAAM,WAAW,CAAA;AAC/D,cAAc,eAAe,CAAA;AAC7B,OAAO,EAA+B,eAAe,EAAkB,MAAM,aAAa,CAAA;AAC1F,OAAO,EAEL,aAAa,GAGd,MAAM,WAAW,CAAA;AAClB,OAAO,EAEL,eAAe,EAEf,cAAc,EACd,cAAc,GACf,MAAM,aAAa,CAAA"}

package/dist/protocol.d.ts

@@ -0,0 +1,134 @@
+/**
+ * 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://`
+ * 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.
+ */
+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). */
+export declare const UI_MIME = "text/html;profile=mcp-app";
+/** The `capabilities.extensions` key advertising UI support in the `initialize` result (SEP-1865). */
+export declare const UI_EXTENSION_KEY = "io.modelcontextprotocol/ui";
+type RequestId = string | number;
+type JsonRpcId = RequestId | null;
+type ProgressToken = string | number;
+export interface McpToolContext {
+    readonly signal: AbortSignal;
+    readonly requestId: JsonRpcId;
+    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. */
+export interface McpContentBlock {
+    readonly type: "text";
+    readonly text: string;
+}
+/**
+ * The rich result a tool handler may return instead of a bare string (MCP Apps). `content` is the
+ * model-facing text (also shown by text-only hosts); `structuredContent` is the data a linked `ui://`
+ * widget renders and is deliberately NOT added to the model's context; `_meta` carries the
+ * `ui.resourceUri` link and any render hints. Returning a `string` is shorthand for one text block.
+ */
+export interface McpToolResult {
+    readonly content?: readonly McpContentBlock[];
+    readonly structuredContent?: Record<string, unknown>;
+    readonly _meta?: Record<string, unknown>;
+    readonly isError?: boolean;
+}
+/** 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`. */
+export interface McpTool {
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: Record<string, unknown>;
+    readonly _meta?: Record<string, unknown>;
+    readonly handler: (args: Record<string, unknown>, context: McpToolContext) => Promise<string | McpToolResult>;
+}
+export interface McpResource {
+    readonly uri: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly mimeType?: string;
+    /** Descriptor `_meta` (MCP Apps: CSP / domain / border render hints under `ui`). */
+    readonly _meta?: Record<string, unknown>;
+    readonly read: () => Promise<{
+        readonly text: string;
+        readonly mimeType?: string;
+    }>;
+}
+export interface McpPromptMessage {
+    readonly role: "user" | "assistant";
+    readonly content: {
+        readonly type: "text";
+        readonly text: string;
+    };
+}
+export interface McpPrompt {
+    readonly name: string;
+    readonly description: string;
+    readonly arguments?: readonly {
+        readonly name: string;
+        readonly description?: string;
+        readonly required?: boolean;
+    }[];
+    readonly handler: (args: Record<string, unknown>) => Promise<readonly McpPromptMessage[]>;
+}
+export interface McpServerFeatures {
+    readonly resources?: readonly McpResource[];
+    readonly prompts?: readonly McpPrompt[];
+    /** Advertise the MCP Apps UI extension in `initialize`. Present when the server serves `ui://` widgets;
+     * `mimeTypes` defaults to `[UI_MIME]`. */
+    readonly ui?: {
+        readonly mimeTypes?: readonly string[];
+    };
+}
+export interface JsonRpcRequest {
+    readonly jsonrpc?: string;
+    readonly id?: JsonRpcId;
+    readonly method?: string;
+    readonly params?: Record<string, unknown>;
+}
+export interface JsonRpcNotification {
+    readonly jsonrpc: "2.0";
+    readonly method: string;
+    readonly params?: Record<string, unknown>;
+}
+export type JsonRpcResponse = {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    result: unknown;
+} | {
+    jsonrpc: "2.0";
+    id: JsonRpcId;
+    error: {
+        code: number;
+        message: string;
+    };
+};
+export declare const rpcResult: (id: JsonRpcId, value: unknown) => JsonRpcResponse;
+export declare const rpcError: (id: JsonRpcId, code: number, message: string) => JsonRpcResponse;
+export interface McpProtocolState {
+    readonly activeRequests: Map<string, AbortController>;
+}
+export interface McpProtocolOptions {
+    readonly state?: McpProtocolState;
+    readonly signal?: AbortSignal;
+    readonly sendNotification?: (notification: JsonRpcNotification) => void;
+}
+export declare function createMcpProtocolState(): McpProtocolState;
+/**
+ * Dispatch one JSON-RPC message against the given tools. Returns the response, or `null` for a
+ * notification (no reply). Tool errors are reported in-band (`isError`) so the agent can react to them.
+ */
+export declare function handleRpc(message: JsonRpcRequest, tools: readonly McpTool[], serverInfo: {
+    name: string;
+    version: string;
+}, features?: McpServerFeatures, options?: McpProtocolOptions): Promise<JsonRpcResponse | null>;
+export {};
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

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