@maravilla-labs/platform 0.11.0 → 0.11.1

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @maravilla-labs/platform
 
+## 0.11.1
+
+### Patch Changes
+
+- d9b06d4: MCP UI widgets are now referenced as **static assets** instead of copied to the
+  build root. `buildMcp` records `htmlPath` (e.g. `static/mcp-ui/reader.html`) as
+  the deploy-relative `htmlAsset` verbatim rather than copying the file to
+  `mcp-ui/<name>.html` — a build-root copy was never listed in `routing.assets` nor
+  registered as a bundle, so the deploy pipeline never shipped it and the runtime
+  couldn't resolve it. Output your single-file widget into your app's `static/`
+  directory (built before the app build) so the framework deploys it normally.
+
 ## 0.11.0
 
 ### Minor Changes

package/dist/mcp.d.ts

@@ -151,11 +151,14 @@ interface McpServerSpec {
     /**
      * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
      * template `name` to `htmlPath` — a **self-contained single-file HTML widget**
-     * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`), relative to the
-     * project root. The runtime serves its contents as the `ui://<tool>/<template>`
-     * resource (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT)
-     * renders inline — the MCP Apps standard. The widget receives its data over the
-     * MCP Apps channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
+     * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the
+     * build into your app's **static assets** and point `htmlPath` at that
+     * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app
+     * build — so the framework ships it as a normal static asset. The runtime reads
+     * those bytes and serves them as the `ui://<tool>/<template>` resource
+     * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline
+     * — the MCP Apps standard. The widget receives its data over the MCP Apps
+     * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
      * `structuredContent`), not via cookies.
      *
      * `csp` declares the resource's Content-Security-Policy as

package/dist/mcp.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/mcp.ts"],"sourcesContent":["/**\n * @fileoverview MCP tool authoring helpers for Maravilla.\n *\n * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:\n *\n * ```ts\n * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';\n *\n * export const server = defineMcpServer({\n *   name: 'Acme Tools',\n *   version: '1.0.0',\n *   instructions: 'Tools for managing Acme orders.',\n *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],\n * });\n *\n * export const getOrder = defineMcpTool(\n *   {\n *     name: 'get_order',\n *     description: 'Look up an order by id.',\n *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },\n *     scopes: ['acme:read'],\n *     ui: { template: 'order-card' },\n *   },\n *   async (args, ctx) => {\n *     const order = await ctx.database.findOne('orders', { _id: args.id });\n *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };\n *   },\n * );\n * ```\n *\n * These helpers are pure factories. `defineMcpTool` produces a\n * `RegisteredMcpTool` marker object that the build pipeline\n * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`\n * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by\n * `__maravilla_mcp_server`. The generated bundle exposes\n * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher\n * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request\n * whose body is `{ tool_id, args, identity }`.\n */\n\n// ============ Tool handler context ============\n\n/**\n * Context handed to every MCP tool handler. The first seven services mirror\n * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`\n * carry the authenticated identity behind the OAuth token or API key so the\n * handler — and the platform ops it calls — run as the real end-user.\n */\nexport interface McpToolContext {\n  /** Per-tenant env vars. */\n  env: Record<string, string>;\n  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */\n  kv?: unknown;\n  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */\n  database?: unknown;\n  /** Object storage. */\n  storage?: unknown;\n  /** Durable queue producer (`.send(name, payload, opts?)`). */\n  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };\n  /** Auth service — register/login/logout/user CRUD/etc. */\n  auth?: unknown;\n  /** Web Push service. */\n  push?: unknown;\n  /** Full platform object — escape hatch for services not surfaced above. */\n  platform?: unknown;\n  /** Tenant identifier. */\n  tenant: string;\n  /** Trace correlation id — propagate through logs. */\n  traceId: string;\n  /** The end-user behind the token/key, or `null` for a client-only call. */\n  user: { id: string; email: string; groups: string[]; scopes: string[] } | null;\n  /** The OAuth client (agent) that authenticated, when known. */\n  client: { id: string } | null;\n}\n\n// ============ Tool result shapes ============\n\n/** A single content item returned by a tool. */\nexport type McpContentItem =\n  | { type: 'text'; text: string }\n  | { type: 'json'; json: unknown }\n  | { type: 'resource'; resource: Record<string, unknown> };\n\n/**\n * What a tool handler may return:\n * - `{ content }` — explicit MCP content items.\n * - `{ ui }` — render an iframe mini-app template (§7); optional `content`\n *   is shown alongside for clients that don't support the UI.\n * - any other value — wrapped as a single `text` content item.\n */\nexport type McpToolResult =\n  | { content: McpContentItem[] }\n  | { ui: { template: string; data?: unknown }; content?: McpContentItem[] }\n  | unknown;\n\n// ============ Registered markers ============\n\nexport const MCP_TOOL_SYMBOL = '__maravilla_mcp' as const;\nexport const MCP_SERVER_SYMBOL = '__maravilla_mcp_server' as const;\n\n/** Spec passed to {@link defineMcpTool}. */\nexport interface McpToolSpec {\n  /** Tool name surfaced to the client (defaults to the export name). */\n  name: string;\n  /** Human-readable description sent in `tools/list`. */\n  description: string;\n  /** JSON Schema for the tool input, sent verbatim in `tools/list`. */\n  inputSchema: Record<string, unknown>;\n  /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */\n  scopes?: string[];\n  /**\n   * Per-tool public opt-in. When `true`, this tool is callable with an\n   * anonymous identity (no bearer) even on an otherwise-private server — its\n   * `scopes` must still be a subset of the caller's, so an anonymous caller can\n   * only reach it when it declares no scopes. Defaults to `false`.\n   */\n  public?: boolean;\n  /** Links this tool to a UI template declared on the server (§7). */\n  ui?: { template: string };\n}\n\nexport interface RegisteredMcpTool {\n  readonly [MCP_TOOL_SYMBOL]: McpToolSpec;\n  readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;\n}\n\n/** Spec passed to {@link defineMcpServer}. */\nexport interface McpServerSpec {\n  /** Human-readable server name (e.g. \"Acme Tools\"). */\n  name: string;\n  /** Optional semantic version. */\n  version?: string;\n  /** Optional natural-language usage instructions for the client/model. */\n  instructions?: string;\n  /**\n   * Server-level public flag. When `true`, unauthenticated MCP requests build\n   * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and\n   * any no-scope tool work without a bearer. Per-tool `public` opt-in still\n   * works on an otherwise-private server. Defaults to `false`.\n   */\n  public?: boolean;\n  /**\n   * Mini-app UI templates referenced by tools via `ui.template`. Each maps a\n   * template `name` to `htmlPath` — a **self-contained single-file HTML widget**\n   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`), relative to the\n   * project root. The runtime serves its contents as the `ui://<tool>/<template>`\n   * resource (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT)\n   * renders inline — the MCP Apps standard. The widget receives its data over the\n   * MCP Apps channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →\n   * `structuredContent`), not via cookies.\n   *\n   * `csp` declares the resource's Content-Security-Policy as\n   * {@link McpUiResourceCsp} (emitted at `_meta.ui.csp`): list the external\n   * origins the widget may load — e.g. `resourceDomains` for images/fonts the\n   * widget references. Omit for a fully self-contained widget.\n   */\n  uiTemplates?: Array<{ name: string; htmlPath: string; csp?: McpUiResourceCsp }>;\n}\n\n/**\n * Content-Security-Policy for a UI template resource, emitted at the resource's\n * `_meta.ui.csp` (the MCP Apps contract). The host derives CSP directives from\n * these origin lists; omitting a list blocks that class of request.\n */\nexport interface McpUiResourceCsp {\n  /** `connect-src` — fetch / XHR / WebSocket origins. */\n  connectDomains?: string[];\n  /** `img-src` / `script-src` / `style-src` / `font-src` / `media-src` — static\n   *  resource origins. Supports wildcard subdomains, e.g. `https://*.example.com`. */\n  resourceDomains?: string[];\n  /** `frame-src` — origins allowed in nested iframes. */\n  frameDomains?: string[];\n  /** `base-uri` — allowed document base URIs. */\n  baseUriDomains?: string[];\n}\n\nexport interface RegisteredMcpServer {\n  readonly [MCP_SERVER_SYMBOL]: McpServerSpec;\n}\n\n// ============ Public factory helpers ============\n\n/**\n * Declare an MCP tool. The runtime advertises it in `tools/list` (using\n * `name`, `description`, `inputSchema`) and dispatches `tools/call` to\n * `handler`, enforcing `scopes` against the caller's granted scopes.\n */\nexport function defineMcpTool(\n  spec: McpToolSpec,\n  handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>,\n): RegisteredMcpTool {\n  return { [MCP_TOOL_SYMBOL]: spec, handler };\n}\n\n/**\n * Declare the MCP server identity and its iframe mini-app templates.\n * Optional — at most one per app; the last one discovered wins.\n */\nexport function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer {\n  return { [MCP_SERVER_SYMBOL]: spec };\n}\n\n/** Type guard used by the build-time discoverer and the runtime registry. */\nexport function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_TOOL_SYMBOL in value &&\n    typeof (value as Record<string, unknown>).handler === 'function'\n  );\n}\n\n/** Type guard for a registered MCP server descriptor. */\nexport function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_SERVER_SYMBOL in value\n  );\n}\n"],"mappings":";AAiGO,IAAM,kBAAkB;AACxB,IAAM,oBAAoB;AAyF1B,SAAS,cACd,MACA,SACmB;AACnB,SAAO,EAAE,CAAC,eAAe,GAAG,MAAM,QAAQ;AAC5C;AAMO,SAAS,gBAAgB,MAA0C;AACxE,SAAO,EAAE,CAAC,iBAAiB,GAAG,KAAK;AACrC;AAGO,SAAS,oBAAoB,OAA4C;AAC9E,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,SACnB,OAAQ,MAAkC,YAAY;AAE1D;AAGO,SAAS,sBAAsB,OAA8C;AAClF,SACE,OAAO,UAAU,YACjB,UAAU,QACV,qBAAqB;AAEzB;","names":[]}
+{"version":3,"sources":["../src/mcp.ts"],"sourcesContent":["/**\n * @fileoverview MCP tool authoring helpers for Maravilla.\n *\n * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:\n *\n * ```ts\n * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';\n *\n * export const server = defineMcpServer({\n *   name: 'Acme Tools',\n *   version: '1.0.0',\n *   instructions: 'Tools for managing Acme orders.',\n *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],\n * });\n *\n * export const getOrder = defineMcpTool(\n *   {\n *     name: 'get_order',\n *     description: 'Look up an order by id.',\n *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },\n *     scopes: ['acme:read'],\n *     ui: { template: 'order-card' },\n *   },\n *   async (args, ctx) => {\n *     const order = await ctx.database.findOne('orders', { _id: args.id });\n *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };\n *   },\n * );\n * ```\n *\n * These helpers are pure factories. `defineMcpTool` produces a\n * `RegisteredMcpTool` marker object that the build pipeline\n * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`\n * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by\n * `__maravilla_mcp_server`. The generated bundle exposes\n * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher\n * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request\n * whose body is `{ tool_id, args, identity }`.\n */\n\n// ============ Tool handler context ============\n\n/**\n * Context handed to every MCP tool handler. The first seven services mirror\n * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`\n * carry the authenticated identity behind the OAuth token or API key so the\n * handler — and the platform ops it calls — run as the real end-user.\n */\nexport interface McpToolContext {\n  /** Per-tenant env vars. */\n  env: Record<string, string>;\n  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */\n  kv?: unknown;\n  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */\n  database?: unknown;\n  /** Object storage. */\n  storage?: unknown;\n  /** Durable queue producer (`.send(name, payload, opts?)`). */\n  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };\n  /** Auth service — register/login/logout/user CRUD/etc. */\n  auth?: unknown;\n  /** Web Push service. */\n  push?: unknown;\n  /** Full platform object — escape hatch for services not surfaced above. */\n  platform?: unknown;\n  /** Tenant identifier. */\n  tenant: string;\n  /** Trace correlation id — propagate through logs. */\n  traceId: string;\n  /** The end-user behind the token/key, or `null` for a client-only call. */\n  user: { id: string; email: string; groups: string[]; scopes: string[] } | null;\n  /** The OAuth client (agent) that authenticated, when known. */\n  client: { id: string } | null;\n}\n\n// ============ Tool result shapes ============\n\n/** A single content item returned by a tool. */\nexport type McpContentItem =\n  | { type: 'text'; text: string }\n  | { type: 'json'; json: unknown }\n  | { type: 'resource'; resource: Record<string, unknown> };\n\n/**\n * What a tool handler may return:\n * - `{ content }` — explicit MCP content items.\n * - `{ ui }` — render an iframe mini-app template (§7); optional `content`\n *   is shown alongside for clients that don't support the UI.\n * - any other value — wrapped as a single `text` content item.\n */\nexport type McpToolResult =\n  | { content: McpContentItem[] }\n  | { ui: { template: string; data?: unknown }; content?: McpContentItem[] }\n  | unknown;\n\n// ============ Registered markers ============\n\nexport const MCP_TOOL_SYMBOL = '__maravilla_mcp' as const;\nexport const MCP_SERVER_SYMBOL = '__maravilla_mcp_server' as const;\n\n/** Spec passed to {@link defineMcpTool}. */\nexport interface McpToolSpec {\n  /** Tool name surfaced to the client (defaults to the export name). */\n  name: string;\n  /** Human-readable description sent in `tools/list`. */\n  description: string;\n  /** JSON Schema for the tool input, sent verbatim in `tools/list`. */\n  inputSchema: Record<string, unknown>;\n  /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */\n  scopes?: string[];\n  /**\n   * Per-tool public opt-in. When `true`, this tool is callable with an\n   * anonymous identity (no bearer) even on an otherwise-private server — its\n   * `scopes` must still be a subset of the caller's, so an anonymous caller can\n   * only reach it when it declares no scopes. Defaults to `false`.\n   */\n  public?: boolean;\n  /** Links this tool to a UI template declared on the server (§7). */\n  ui?: { template: string };\n}\n\nexport interface RegisteredMcpTool {\n  readonly [MCP_TOOL_SYMBOL]: McpToolSpec;\n  readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;\n}\n\n/** Spec passed to {@link defineMcpServer}. */\nexport interface McpServerSpec {\n  /** Human-readable server name (e.g. \"Acme Tools\"). */\n  name: string;\n  /** Optional semantic version. */\n  version?: string;\n  /** Optional natural-language usage instructions for the client/model. */\n  instructions?: string;\n  /**\n   * Server-level public flag. When `true`, unauthenticated MCP requests build\n   * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and\n   * any no-scope tool work without a bearer. Per-tool `public` opt-in still\n   * works on an otherwise-private server. Defaults to `false`.\n   */\n  public?: boolean;\n  /**\n   * Mini-app UI templates referenced by tools via `ui.template`. Each maps a\n   * template `name` to `htmlPath` — a **self-contained single-file HTML widget**\n   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the\n   * build into your app's **static assets** and point `htmlPath` at that\n   * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app\n   * build — so the framework ships it as a normal static asset. The runtime reads\n   * those bytes and serves them as the `ui://<tool>/<template>` resource\n   * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline\n   * — the MCP Apps standard. The widget receives its data over the MCP Apps\n   * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →\n   * `structuredContent`), not via cookies.\n   *\n   * `csp` declares the resource's Content-Security-Policy as\n   * {@link McpUiResourceCsp} (emitted at `_meta.ui.csp`): list the external\n   * origins the widget may load — e.g. `resourceDomains` for images/fonts the\n   * widget references. Omit for a fully self-contained widget.\n   */\n  uiTemplates?: Array<{ name: string; htmlPath: string; csp?: McpUiResourceCsp }>;\n}\n\n/**\n * Content-Security-Policy for a UI template resource, emitted at the resource's\n * `_meta.ui.csp` (the MCP Apps contract). The host derives CSP directives from\n * these origin lists; omitting a list blocks that class of request.\n */\nexport interface McpUiResourceCsp {\n  /** `connect-src` — fetch / XHR / WebSocket origins. */\n  connectDomains?: string[];\n  /** `img-src` / `script-src` / `style-src` / `font-src` / `media-src` — static\n   *  resource origins. Supports wildcard subdomains, e.g. `https://*.example.com`. */\n  resourceDomains?: string[];\n  /** `frame-src` — origins allowed in nested iframes. */\n  frameDomains?: string[];\n  /** `base-uri` — allowed document base URIs. */\n  baseUriDomains?: string[];\n}\n\nexport interface RegisteredMcpServer {\n  readonly [MCP_SERVER_SYMBOL]: McpServerSpec;\n}\n\n// ============ Public factory helpers ============\n\n/**\n * Declare an MCP tool. The runtime advertises it in `tools/list` (using\n * `name`, `description`, `inputSchema`) and dispatches `tools/call` to\n * `handler`, enforcing `scopes` against the caller's granted scopes.\n */\nexport function defineMcpTool(\n  spec: McpToolSpec,\n  handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>,\n): RegisteredMcpTool {\n  return { [MCP_TOOL_SYMBOL]: spec, handler };\n}\n\n/**\n * Declare the MCP server identity and its iframe mini-app templates.\n * Optional — at most one per app; the last one discovered wins.\n */\nexport function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer {\n  return { [MCP_SERVER_SYMBOL]: spec };\n}\n\n/** Type guard used by the build-time discoverer and the runtime registry. */\nexport function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_TOOL_SYMBOL in value &&\n    typeof (value as Record<string, unknown>).handler === 'function'\n  );\n}\n\n/** Type guard for a registered MCP server descriptor. */\nexport function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer {\n  return (\n    typeof value === 'object' &&\n    value !== null &&\n    MCP_SERVER_SYMBOL in value\n  );\n}\n"],"mappings":";AAiGO,IAAM,kBAAkB;AACxB,IAAM,oBAAoB;AA4F1B,SAAS,cACd,MACA,SACmB;AACnB,SAAO,EAAE,CAAC,eAAe,GAAG,MAAM,QAAQ;AAC5C;AAMO,SAAS,gBAAgB,MAA0C;AACxE,SAAO,EAAE,CAAC,iBAAiB,GAAG,KAAK;AACrC;AAGO,SAAS,oBAAoB,OAA4C;AAC9E,SACE,OAAO,UAAU,YACjB,UAAU,QACV,mBAAmB,SACnB,OAAQ,MAAkC,YAAY;AAE1D;AAGO,SAAS,sBAAsB,OAA8C;AAClF,SACE,OAAO,UAAU,YACjB,UAAU,QACV,qBAAqB;AAEzB;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.11.0",
+  "version": "0.11.1",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/mcp.ts

@@ -142,11 +142,14 @@ export interface McpServerSpec {
   /**
    * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
    * template `name` to `htmlPath` — a **self-contained single-file HTML widget**
-   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`), relative to the
-   * project root. The runtime serves its contents as the `ui://<tool>/<template>`
-   * resource (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT)
-   * renders inline — the MCP Apps standard. The widget receives its data over the
-   * MCP Apps channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
+   * (JS/CSS inlined; build it with e.g. `vite-plugin-singlefile`). Output the
+   * build into your app's **static assets** and point `htmlPath` at that
+   * deploy-relative path (e.g. `static/mcp-ui/reader.html`), built BEFORE the app
+   * build — so the framework ships it as a normal static asset. The runtime reads
+   * those bytes and serves them as the `ui://<tool>/<template>` resource
+   * (`text/html;profile=mcp-app`), which the host (Claude, ChatGPT) renders inline
+   * — the MCP Apps standard. The widget receives its data over the MCP Apps
+   * channel (`@modelcontextprotocol/ext-apps`, `ontoolresult` →
    * `structuredContent`), not via cookies.
    *
    * `csp` declares the resource's Content-Security-Policy as