@nifrajs/mcp 1.0.0

package/src/protocol.ts

@@ -0,0 +1,397 @@
+/**
+ * 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 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 const UI_MIME = "text/html;profile=mcp-app"
+/** The `capabilities.extensions` key advertising UI support in the `initialize` result (SEP-1865). */
+export 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 const rpcResult = (id: JsonRpcId, value: unknown): JsonRpcResponse => ({
+  jsonrpc: "2.0",
+  id,
+  result: value,
+})
+export const rpcError = (id: JsonRpcId, code: number, message: string): JsonRpcResponse => ({
+  jsonrpc: "2.0",
+  id,
+  error: { code, message },
+})
+
+export interface McpProtocolState {
+  readonly activeRequests: Map<string, AbortController>
+}
+
+export interface McpProtocolOptions {
+  readonly state?: McpProtocolState
+  readonly signal?: AbortSignal
+  readonly sendNotification?: (notification: JsonRpcNotification) => void
+}
+
+export function createMcpProtocolState(): McpProtocolState {
+  return { activeRequests: new Map() }
+}
+
+function requestKey(id: unknown): string | undefined {
+  if (typeof id === "string") return `s:${id}`
+  return typeof id === "number" && Number.isFinite(id) ? `n:${id}` : undefined
+}
+
+function progressTokenOf(params: Record<string, unknown> | undefined): ProgressToken | undefined {
+  const meta = params?._meta
+  if (typeof meta !== "object" || meta === null || Array.isArray(meta)) return undefined
+  const token = (meta as Record<string, unknown>).progressToken
+  return typeof token === "string" || (typeof token === "number" && Number.isFinite(token))
+    ? token
+    : undefined
+}
+
+function cancellationReason(params: Record<string, unknown> | undefined): string | undefined {
+  const reason = params?.reason
+  return typeof reason === "string" && reason.length > 0 ? reason : undefined
+}
+
+function linkAbortSignal(parent: AbortSignal | undefined, child: AbortController): () => void {
+  if (parent === undefined) return () => {}
+  if (parent.aborted) {
+    child.abort(parent.reason)
+    return () => {}
+  }
+  const abort = (): void => child.abort(parent.reason)
+  parent.addEventListener("abort", abort, { once: true })
+  return () => parent.removeEventListener("abort", abort)
+}
+
+function abortMessage(signal: AbortSignal): string {
+  const reason = signal.reason
+  if (typeof reason === "string" && reason.length > 0) return `Cancelled: ${reason}`
+  return "Cancelled"
+}
+
+function compactDescription(description: string): string {
+  const text = description.replace(/\s+/g, " ").trim()
+  const sentenceEnd = text.search(/[.!?](?:\s|$)/)
+  const sentence = sentenceEnd === -1 ? text : text.slice(0, sentenceEnd + 1)
+  if (sentence.length <= 120) return sentence
+  return `${sentence.slice(0, 117).trimEnd()}...`
+}
+
+/** Normalize a handler's return into the `tools/call` result object. A `string` becomes a single text
+ * block (base-MCP behavior, unchanged); a {@link McpToolResult} passes `content`/`structuredContent`
+ * through, and inherits the tool descriptor's `_meta` (the `ui.resourceUri` link) when it sets none. */
+function toolCallResult(result: string | McpToolResult, tool: McpTool): Record<string, unknown> {
+  if (typeof result === "string") return { content: [{ type: "text", text: result }] }
+  const meta =
+    tool._meta !== undefined || result._meta !== undefined
+      ? { ...(tool._meta ?? {}), ...(result._meta ?? {}) }
+      : undefined
+  return {
+    content: result.content ?? [],
+    ...(result.structuredContent !== undefined
+      ? { structuredContent: result.structuredContent }
+      : {}),
+    ...(meta !== undefined ? { _meta: meta } : {}),
+    ...(result.isError === true ? { isError: true } : {}),
+  }
+}
+
+/**
+ * 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 async function handleRpc(
+  message: JsonRpcRequest,
+  tools: readonly McpTool[],
+  serverInfo: { name: string; version: string },
+  features: McpServerFeatures = {},
+  options: McpProtocolOptions = {},
+): Promise<JsonRpcResponse | null> {
+  const { id, method, params } = message
+  const isNotification = id === undefined
+  const rid = id ?? null
+  const resources = features.resources ?? []
+  const prompts = features.prompts ?? []
+  const state = options.state ?? createMcpProtocolState()
+
+  switch (method) {
+    case "initialize":
+      return rpcResult(rid, {
+        protocolVersion: PROTOCOL_VERSION,
+        capabilities: {
+          tools: {},
+          ...(resources.length > 0 ? { resources: {} } : {}),
+          ...(prompts.length > 0 ? { prompts: {} } : {}),
+          ...(features.ui !== undefined
+            ? {
+                extensions: {
+                  [UI_EXTENSION_KEY]: { mimeTypes: features.ui.mimeTypes ?? [UI_MIME] },
+                },
+              }
+            : {}),
+        },
+        serverInfo,
+      })
+    case "notifications/initialized":
+      return null
+    case "notifications/cancelled": {
+      const key = requestKey(params?.requestId)
+      if (key !== undefined) state.activeRequests.get(key)?.abort(cancellationReason(params))
+      return null
+    }
+    case "ping":
+      return rpcResult(rid, {})
+    case "tools/list":
+      return rpcResult(
+        rid,
+        params?.compact === true
+          ? {
+              tools: tools.map((t) => ({
+                name: t.name,
+                description: compactDescription(t.description),
+              })),
+            }
+          : {
+              tools: tools.map((t) => ({
+                name: t.name,
+                description: t.description,
+                inputSchema: t.inputSchema,
+                ...(t._meta !== undefined ? { _meta: t._meta } : {}),
+              })),
+            },
+      )
+    case "tools/describe": {
+      const name = params?.name
+      const tool = tools.find((t) => t.name === name)
+      if (!tool) return rpcError(rid, -32602, `unknown tool: ${String(name)}`)
+      return rpcResult(rid, {
+        tool: {
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+          ...(tool._meta !== undefined ? { _meta: tool._meta } : {}),
+        },
+      })
+    }
+    case "tools/call": {
+      const name = params?.name
+      const tool = tools.find((t) => t.name === name)
+      if (!tool) return rpcError(rid, -32602, `unknown tool: ${String(name)}`)
+      const args = (params?.arguments as Record<string, unknown>) ?? {}
+      const controller = new AbortController()
+      const key = requestKey(id)
+      const cleanupAbort = linkAbortSignal(options.signal, controller)
+      if (key !== undefined) state.activeRequests.set(key, controller)
+      const progressToken = progressTokenOf(params)
+      let lastProgress = Number.NEGATIVE_INFINITY
+      const reportProgress = (progress: number, total?: number): void => {
+        if (
+          progressToken === undefined ||
+          !Number.isFinite(progress) ||
+          progress <= lastProgress ||
+          (total !== undefined && !Number.isFinite(total))
+        ) {
+          return
+        }
+        lastProgress = progress
+        options.sendNotification?.({
+          jsonrpc: "2.0",
+          method: "notifications/progress",
+          params: {
+            progressToken,
+            progress,
+            ...(total !== undefined ? { total } : {}),
+          },
+        })
+      }
+      try {
+        reportProgress(0, 1)
+        if (controller.signal.aborted) throw new DOMException("cancelled", "AbortError")
+        const result = await tool.handler(args, {
+          signal: controller.signal,
+          requestId: rid,
+          ...(progressToken !== undefined ? { progressToken } : {}),
+          reportProgress,
+        })
+        if (controller.signal.aborted) throw new DOMException("cancelled", "AbortError")
+        reportProgress(1, 1)
+        return rpcResult(rid, toolCallResult(result, tool))
+      } catch (err) {
+        if (controller.signal.aborted) {
+          return rpcResult(rid, {
+            content: [{ type: "text", text: abortMessage(controller.signal) }],
+            isError: true,
+          })
+        }
+        const msg = err instanceof Error ? err.message : String(err)
+        return rpcResult(rid, { content: [{ type: "text", text: `Error: ${msg}` }], isError: true })
+      } finally {
+        cleanupAbort()
+        if (key !== undefined && state.activeRequests.get(key) === controller) {
+          state.activeRequests.delete(key)
+        }
+      }
+    }
+    case "resources/list":
+      return rpcResult(rid, {
+        resources: resources.map((r) => ({
+          uri: r.uri,
+          name: r.name,
+          ...(r.description !== undefined ? { description: r.description } : {}),
+          ...(r.mimeType !== undefined ? { mimeType: r.mimeType } : {}),
+          ...(r._meta !== undefined ? { _meta: r._meta } : {}),
+        })),
+      })
+    case "resources/read": {
+      const uri = params?.uri
+      const resource = resources.find((r) => r.uri === uri)
+      if (!resource) return rpcError(rid, -32602, `unknown resource: ${String(uri)}`)
+      try {
+        const content = await resource.read()
+        return rpcResult(rid, {
+          contents: [
+            {
+              uri: resource.uri,
+              mimeType: content.mimeType ?? resource.mimeType ?? "text/plain",
+              text: content.text,
+              ...(resource._meta !== undefined ? { _meta: resource._meta } : {}),
+            },
+          ],
+        })
+      } catch {
+        // 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)}`)
+      }
+    }
+    case "prompts/list":
+      return rpcResult(rid, {
+        prompts: prompts.map((p) => ({
+          name: p.name,
+          description: p.description,
+          ...(p.arguments !== undefined ? { arguments: p.arguments } : {}),
+        })),
+      })
+    case "prompts/get": {
+      const name = params?.name
+      const prompt = prompts.find((p) => p.name === name)
+      if (!prompt) return rpcError(rid, -32602, `unknown prompt: ${String(name)}`)
+      const args = (params?.arguments as Record<string, unknown>) ?? {}
+      try {
+        return rpcResult(rid, {
+          description: prompt.description,
+          messages: await prompt.handler(args),
+        })
+      } catch (err) {
+        const msg = err instanceof Error ? err.message : String(err)
+        return rpcError(rid, -32000, msg)
+      }
+    }
+    default:
+      if (isNotification) return null
+      return rpcError(rid, -32601, `method not found: ${String(method)}`)
+  }
+}

package/src/react.ts

@@ -0,0 +1,87 @@
+/**
+ * `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}/>))`.
+ * 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
+ * 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.
+ */
+import { randomBytes } from "node:crypto"
+import { rm, writeFile } from "node:fs/promises"
+import { basename, dirname, join } from "node:path"
+import { defineMcpWidget, type McpWidget } from "./widget.ts"
+
+export interface ReactWidgetOptions {
+  /** The widget's `ui://` resource URI, e.g. `ui://orders/table`. */
+  readonly uri: string
+  readonly name: string
+  readonly description?: string
+  readonly title?: string
+  /** Absolute path to a `.tsx`/`.jsx` module whose DEFAULT export is a React component. It receives the
+   * tool's `structuredContent` as props. */
+  readonly component: string
+  /** Extra `<head>` content (styles, fonts). The bridge + component bundle are injected for you. */
+  readonly head?: string
+  /** Minify the client bundle (default true). */
+  readonly minify?: boolean
+}
+
+/** 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`.
+  const bootPath = join(dir, `.nifra-mcp-widget.${randomBytes(6).toString("hex")}.tsx`)
+  const boot = `import { createElement } from "react"
+import { createRoot } from "react-dom/client"
+import Component from ${JSON.stringify(`./${basename(componentPath)}`)}
+const el = document.getElementById("root")
+if (el) {
+  const root = createRoot(el)
+  const draw = (data) => root.render(createElement(Component, data || {}))
+  const api = window.mcpApp
+  if (api) api.onData(draw); else draw({})
+}`
+  try {
+    await writeFile(bootPath, boot)
+    const out = await Bun.build({
+      entrypoints: [bootPath],
+      target: "browser",
+      format: "iife",
+      minify,
+      define: { "process.env.NODE_ENV": JSON.stringify("production") },
+    })
+    if (!out.success) {
+      throw new Error(
+        `reactWidget: failed to bundle ${componentPath}:\n${out.logs.map((l) => String(l)).join("\n")}`,
+      )
+    }
+    const output = out.outputs[0]
+    if (output === undefined) throw new Error(`reactWidget: empty bundle for ${componentPath}`)
+    return await output.text()
+  } finally {
+    await rm(bootPath, { force: true })
+  }
+}
+
+/** 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.
+  const safe = bundle.replace(/<\/(script)/gi, "<\\/$1")
+  return defineMcpWidget({
+    uri: opts.uri,
+    name: opts.name,
+    ...(opts.description !== undefined ? { description: opts.description } : {}),
+    ...(opts.title !== undefined ? { title: opts.title } : {}),
+    ...(opts.head !== undefined ? { head: opts.head } : {}),
+    html: `<div id="root"></div>\n<script>${safe}</script>`,
+  })
+}

package/src/server.ts

@@ -0,0 +1,85 @@
+/**
+ * `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
+ * is advertised automatically. Mount it in a nifra backend by handing the raw request to {@link McpServer.fetch}:
+ *
+ * ```ts
+ * const mcp = createMcpServer({ name: "orders", version: "1.0.0", tools, widgets })
+ * export const backend = server()
+ *   .get("/mcp", (c) => mcp.fetch(c.req))
+ *   .post("/mcp", (c) => mcp.fetch(c.req))
+ * ```
+ *
+ * {@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
+ * 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`).
+ */
+
+import { respondMcpHttp } from "./http.ts"
+import {
+  handleRpc,
+  type JsonRpcRequest,
+  type JsonRpcResponse,
+  type McpPrompt,
+  type McpResource,
+  type McpServerFeatures,
+  type McpTool,
+  UI_MIME,
+} from "./protocol.ts"
+import type { McpWidget } from "./widget.ts"
+
+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. */
+  readonly widgets?: readonly McpWidget[]
+  /** Extra (non-widget) resources to expose. */
+  readonly resources?: readonly McpResource[]
+  readonly prompts?: readonly McpPrompt[]
+  /** GET health-page text. */
+  readonly health?: string
+  /** Max JSON-RPC body size in bytes (default 1 MB). */
+  readonly maxBodyBytes?: number
+}
+
+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). */
+  fetch(request: Request): Promise<Response>
+  /** Dispatch one JSON-RPC message directly (no HTTP) — for headless verification and unit tests. */
+  handle(message: JsonRpcRequest): Promise<JsonRpcResponse | null>
+}
+
+export function createMcpServer(opts: CreateMcpServerOptions): McpServer {
+  const tools = [...(opts.tools ?? [])]
+  const widgets = opts.widgets ?? []
+  // Widget resources first (a widget is discovered through its tool's _meta, but listing it is harmless
+  // and lets a host fetch it via resources/read).
+  const resources: McpResource[] = [...widgets.map((w) => w.resource), ...(opts.resources ?? [])]
+  const serverInfo = { name: opts.name, version: opts.version }
+  const features: McpServerFeatures = {
+    ...(resources.length > 0 ? { resources } : {}),
+    ...(opts.prompts !== undefined ? { prompts: opts.prompts } : {}),
+    ...(widgets.length > 0 ? { ui: { mimeTypes: [UI_MIME] } } : {}),
+  }
+  return {
+    tools,
+    features,
+    serverInfo,
+    fetch: (request) =>
+      respondMcpHttp(request, tools, serverInfo, {
+        features,
+        ...(opts.health !== undefined ? { health: opts.health } : {}),
+        ...(opts.maxBodyBytes !== undefined ? { maxBodyBytes: opts.maxBodyBytes } : {}),
+      }),
+    handle: (message) => handleRpc(message, tools, serverInfo, features),
+  }
+}

package/src/tool.ts

@@ -0,0 +1,102 @@
+/**
+ * `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}.
+ */
+
+import type { McpContentBlock, McpTool, McpToolContext, McpToolResult } from "./protocol.ts"
+import type { McpWidget } from "./widget.ts"
+
+/** The ergonomic result an MCP-tool handler may return (coerced to the protocol's {@link McpToolResult}). */
+export type McpToolHandlerResult =
+  | string
+  | {
+      /** Model-facing text (becomes a single text content block when `content` is omitted). */
+      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. */
+      readonly structuredContent?: Record<string, unknown>
+      readonly _meta?: Record<string, unknown>
+      readonly isError?: boolean
+    }
+
+/**
+ * A render-intent hint for GENERATIVE hosts (e.g. the ShipNow builder): 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.
+ */
+export type McpUiIntent =
+  | "table"
+  | "list"
+  | "cards"
+  | "form"
+  | "metric"
+  | "detail"
+  | "chart"
+  | (string & {})
+
+export interface DefineMcpToolOptions {
+  readonly name: string
+  readonly description: string
+  /** JSON Schema for the arguments. Defaults to an empty object schema. */
+  readonly inputSchema?: Record<string, unknown>
+  /** 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,
+   * intent for builders like ShipNow). */
+  readonly intent?: McpUiIntent
+  readonly handler: (
+    args: Record<string, unknown>,
+    context: McpToolContext,
+  ) => McpToolHandlerResult | Promise<McpToolHandlerResult>
+}
+
+/** Build a tool's descriptor `_meta` from its widget link and/or render intent (both under `ui`). */
+function toolMeta(widget?: McpWidget, intent?: string): Record<string, unknown> | undefined {
+  if (widget === undefined && intent === undefined) return undefined
+  const ui: Record<string, unknown> = {}
+  if (widget !== undefined) ui.resourceUri = widget.uri
+  if (intent !== undefined) ui.intent = intent
+  const meta: Record<string, unknown> = { ui }
+  // Deprecated-flat alias for hosts that still read it.
+  if (widget !== undefined) meta["ui/resourceUri"] = widget.uri
+  return meta
+}
+
+const EMPTY_OBJECT_SCHEMA: Record<string, unknown> = {
+  type: "object",
+  properties: {},
+  additionalProperties: false,
+}
+
+function coerce(result: McpToolHandlerResult): string | McpToolResult {
+  if (typeof result === "string") return result
+  const content =
+    result.content ??
+    (result.text !== undefined ? [{ type: "text", text: result.text }] : undefined)
+  return {
+    ...(content !== undefined ? { content } : {}),
+    ...(result.structuredContent !== undefined
+      ? { structuredContent: result.structuredContent }
+      : {}),
+    ...(result._meta !== undefined ? { _meta: result._meta } : {}),
+    ...(result.isError === true ? { isError: true } : {}),
+  }
+}
+
+export function defineMcpTool(opts: DefineMcpToolOptions): McpTool {
+  const meta = toolMeta(opts.widget, opts.intent)
+  return {
+    name: opts.name,
+    description: opts.description,
+    inputSchema: opts.inputSchema ?? EMPTY_OBJECT_SCHEMA,
+    ...(meta !== undefined ? { _meta: meta } : {}),
+    handler: async (args, context) => coerce(await opts.handler(args, context)),
+  }
+}