@maravilla-labs/platform 0.10.0 → 0.10.1

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # @maravilla-labs/platform
 
+## 0.10.1
+
+### Patch Changes
+
+- ea995f6: Document the externalUrl model for MCP UI mini-app templates. The runtime now
+  serves a `uiTemplate`'s `route` to hosts as a `text/uri-list` externalUrl they
+  frame directly (one iframe), instead of a nested-iframe shell — so MCP Apps
+  hosts (ChatGPT, Claude) render it without a `frame-src 'none'` violation.
+
 ## 0.10.0
 
 ### Minor Changes

package/dist/mcp.d.ts

@@ -148,7 +148,13 @@ interface McpServerSpec {
      * works on an otherwise-private server. Defaults to `false`.
      */
     public?: boolean;
-    /** Iframe mini-app templates referenced by tools via `ui.template`. */
+    /**
+     * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
+     * template `name` to a `route` in your app that renders the widget. The runtime
+     * hands the host that route as an `externalUrl` (`text/uri-list`) resource, so
+     * the host frames it directly — one iframe, no nesting. `csp` overrides the
+     * resource's framing policy.
+     */
     uiTemplates?: Array<{
         name: string;
         route: string;

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  /** Iframe mini-app templates referenced by tools via `ui.template`. */\n  uiTemplates?: Array<{ name: string; route: string; csp?: 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;AA0D1B,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 a `route` in your app that renders the widget. The runtime\n   * hands the host that route as an `externalUrl` (`text/uri-list`) resource, so\n   * the host frames it directly — one iframe, no nesting. `csp` overrides the\n   * resource's framing policy.\n   */\n  uiTemplates?: Array<{ name: string; route: string; csp?: 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;AAgE1B,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.10.0",
+  "version": "0.10.1",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",

package/src/mcp.ts

@@ -139,7 +139,13 @@ export interface McpServerSpec {
    * works on an otherwise-private server. Defaults to `false`.
    */
   public?: boolean;
-  /** Iframe mini-app templates referenced by tools via `ui.template`. */
+  /**
+   * Mini-app UI templates referenced by tools via `ui.template`. Each maps a
+   * template `name` to a `route` in your app that renders the widget. The runtime
+   * hands the host that route as an `externalUrl` (`text/uri-list`) resource, so
+   * the host frames it directly — one iframe, no nesting. `csp` overrides the
+   * resource's framing policy.
+   */
   uiTemplates?: Array<{ name: string; route: string; csp?: string }>;
 }