@maravilla-labs/platform 0.8.1 → 0.9.0

package/dist/mcp.d.ts

@@ -0,0 +1,177 @@
+/**
+ * @fileoverview MCP tool authoring helpers for Maravilla.
+ *
+ * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:
+ *
+ * ```ts
+ * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';
+ *
+ * export const server = defineMcpServer({
+ *   name: 'Acme Tools',
+ *   version: '1.0.0',
+ *   instructions: 'Tools for managing Acme orders.',
+ *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],
+ * });
+ *
+ * export const getOrder = defineMcpTool(
+ *   {
+ *     name: 'get_order',
+ *     description: 'Look up an order by id.',
+ *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+ *     scopes: ['acme:read'],
+ *     ui: { template: 'order-card' },
+ *   },
+ *   async (args, ctx) => {
+ *     const order = await ctx.database.findOne('orders', { _id: args.id });
+ *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };
+ *   },
+ * );
+ * ```
+ *
+ * These helpers are pure factories. `defineMcpTool` produces a
+ * `RegisteredMcpTool` marker object that the build pipeline
+ * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`
+ * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by
+ * `__maravilla_mcp_server`. The generated bundle exposes
+ * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher
+ * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request
+ * whose body is `{ tool_id, args, identity }`.
+ */
+/**
+ * Context handed to every MCP tool handler. The first seven services mirror
+ * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`
+ * carry the authenticated identity behind the OAuth token or API key so the
+ * handler — and the platform ops it calls — run as the real end-user.
+ */
+interface McpToolContext {
+    /** Per-tenant env vars. */
+    env: Record<string, string>;
+    /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */
+    kv?: unknown;
+    /** MongoDB-style database — same shape as `getPlatform().env.DB`. */
+    database?: unknown;
+    /** Object storage. */
+    storage?: unknown;
+    /** Durable queue producer (`.send(name, payload, opts?)`). */
+    queue?: {
+        send: (name: string, payload: unknown, opts?: unknown) => Promise<string>;
+    };
+    /** Auth service — register/login/logout/user CRUD/etc. */
+    auth?: unknown;
+    /** Web Push service. */
+    push?: unknown;
+    /** Full platform object — escape hatch for services not surfaced above. */
+    platform?: unknown;
+    /** Tenant identifier. */
+    tenant: string;
+    /** Trace correlation id — propagate through logs. */
+    traceId: string;
+    /** The end-user behind the token/key, or `null` for a client-only call. */
+    user: {
+        id: string;
+        email: string;
+        groups: string[];
+        scopes: string[];
+    } | null;
+    /** The OAuth client (agent) that authenticated, when known. */
+    client: {
+        id: string;
+    } | null;
+}
+/** A single content item returned by a tool. */
+type McpContentItem = {
+    type: 'text';
+    text: string;
+} | {
+    type: 'json';
+    json: unknown;
+} | {
+    type: 'resource';
+    resource: Record<string, unknown>;
+};
+/**
+ * What a tool handler may return:
+ * - `{ content }` — explicit MCP content items.
+ * - `{ ui }` — render an iframe mini-app template (§7); optional `content`
+ *   is shown alongside for clients that don't support the UI.
+ * - any other value — wrapped as a single `text` content item.
+ */
+type McpToolResult = {
+    content: McpContentItem[];
+} | {
+    ui: {
+        template: string;
+        data?: unknown;
+    };
+    content?: McpContentItem[];
+} | unknown;
+declare const MCP_TOOL_SYMBOL: "__maravilla_mcp";
+declare const MCP_SERVER_SYMBOL: "__maravilla_mcp_server";
+/** Spec passed to {@link defineMcpTool}. */
+interface McpToolSpec {
+    /** Tool name surfaced to the client (defaults to the export name). */
+    name: string;
+    /** Human-readable description sent in `tools/list`. */
+    description: string;
+    /** JSON Schema for the tool input, sent verbatim in `tools/list`. */
+    inputSchema: Record<string, unknown>;
+    /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */
+    scopes?: string[];
+    /**
+     * Per-tool public opt-in. When `true`, this tool is callable with an
+     * anonymous identity (no bearer) even on an otherwise-private server — its
+     * `scopes` must still be a subset of the caller's, so an anonymous caller can
+     * only reach it when it declares no scopes. Defaults to `false`.
+     */
+    public?: boolean;
+    /** Links this tool to a UI template declared on the server (§7). */
+    ui?: {
+        template: string;
+    };
+}
+interface RegisteredMcpTool {
+    readonly [MCP_TOOL_SYMBOL]: McpToolSpec;
+    readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;
+}
+/** Spec passed to {@link defineMcpServer}. */
+interface McpServerSpec {
+    /** Human-readable server name (e.g. "Acme Tools"). */
+    name: string;
+    /** Optional semantic version. */
+    version?: string;
+    /** Optional natural-language usage instructions for the client/model. */
+    instructions?: string;
+    /**
+     * Server-level public flag. When `true`, unauthenticated MCP requests build
+     * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and
+     * any no-scope tool work without a bearer. Per-tool `public` opt-in still
+     * works on an otherwise-private server. Defaults to `false`.
+     */
+    public?: boolean;
+    /** Iframe mini-app templates referenced by tools via `ui.template`. */
+    uiTemplates?: Array<{
+        name: string;
+        route: string;
+        csp?: string;
+    }>;
+}
+interface RegisteredMcpServer {
+    readonly [MCP_SERVER_SYMBOL]: McpServerSpec;
+}
+/**
+ * Declare an MCP tool. The runtime advertises it in `tools/list` (using
+ * `name`, `description`, `inputSchema`) and dispatches `tools/call` to
+ * `handler`, enforcing `scopes` against the caller's granted scopes.
+ */
+declare function defineMcpTool(spec: McpToolSpec, handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>): RegisteredMcpTool;
+/**
+ * Declare the MCP server identity and its iframe mini-app templates.
+ * Optional — at most one per app; the last one discovered wins.
+ */
+declare function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer;
+/** Type guard used by the build-time discoverer and the runtime registry. */
+declare function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool;
+/** Type guard for a registered MCP server descriptor. */
+declare function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer;
+
+export { MCP_SERVER_SYMBOL, MCP_TOOL_SYMBOL, type McpContentItem, type McpServerSpec, type McpToolContext, type McpToolResult, type McpToolSpec, type RegisteredMcpServer, type RegisteredMcpTool, defineMcpServer, defineMcpTool, isRegisteredMcpServer, isRegisteredMcpTool };

package/dist/mcp.js

@@ -0,0 +1,24 @@
+// src/mcp.ts
+var MCP_TOOL_SYMBOL = "__maravilla_mcp";
+var MCP_SERVER_SYMBOL = "__maravilla_mcp_server";
+function defineMcpTool(spec, handler) {
+  return { [MCP_TOOL_SYMBOL]: spec, handler };
+}
+function defineMcpServer(spec) {
+  return { [MCP_SERVER_SYMBOL]: spec };
+}
+function isRegisteredMcpTool(value) {
+  return typeof value === "object" && value !== null && MCP_TOOL_SYMBOL in value && typeof value.handler === "function";
+}
+function isRegisteredMcpServer(value) {
+  return typeof value === "object" && value !== null && MCP_SERVER_SYMBOL in value;
+}
+export {
+  MCP_SERVER_SYMBOL,
+  MCP_TOOL_SYMBOL,
+  defineMcpServer,
+  defineMcpTool,
+  isRegisteredMcpServer,
+  isRegisteredMcpTool
+};
+//# sourceMappingURL=mcp.js.map

package/dist/mcp.js.map

@@ -0,0 +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":[]}

package/dist/{ren-DrYefHO5.d.ts → ren-DetHRhCL.d.ts}

@@ -45,4 +45,4 @@ declare function renFetch(input: string | URL | Request, init?: RequestInit, cli
 declare function storageUpload(path: string, file: Blob | File, clientId?: string): Promise<any>;
 declare function storageDelete(path: string, clientId?: string): Promise<any>;
 
-export { RenClient as R, type RenClientOptions as a, type RenEvent as b, storageUpload as c, getOrCreateClientId as g, renFetch as r, storageDelete as s };
+export { type RenEvent as R, type RenClientOptions as a, RenClient as b, storageDelete as c, getOrCreateClientId as g, renFetch as r, storageUpload as s };

package/dist/{transforms-BkgPh93b.d.ts → transforms-DwCPOVTn.d.ts}

@@ -17,6 +17,7 @@
  * and the TS test (`packages/platform/tests/derive-key.test.ts`) to keep
  * the two in lockstep.
  */
+
 /** Video container targets supported by v1. */
 type VideoFormat = 'mp4' | 'webm';
 /** Image output formats supported by v1. */
@@ -297,4 +298,4 @@ interface TransformsPatternSpec {
  */
 type TransformsConfig = Record<string, TransformsPatternSpec>;
 
-export { type DocConvertOpts as D, type ImageFormat as I, type JobHandle as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type ThumbnailOpts as T, type VideoFormat as V, type DocFormat as a, type DocInsertQrCodeOpts as b, type DocReplaceImagesOpts as c, type DocTemplateMergeOpts as d, type DocThumbnailOpts as e, type DocToHtmlOpts as f, type DocToMarkdownOpts as g, type DocToPdfOpts as h, type ImageRef as i, type JobStatus as j, type JobStatusResponse as k, type QrPayload as l, type TranscodeOpts as m, type TransformSpec as n, type TransformsConfig as o, type TransformsPatternSpec as p, type TransformsService as q, keyFor as r, transforms as t };
+export { type DocFormat as D, type ImageFormat as I, type JobStatus as J, type MediaInfo as M, type OcrOpts as O, type QrCodeSpec as Q, type ResizeOpts as R, type TransformsConfig as T, type VideoFormat as V, type TransformsPatternSpec as a, type TranscodeOpts as b, type ThumbnailOpts as c, type DocToPdfOpts as d, type DocThumbnailOpts as e, type DocConvertOpts as f, type DocToMarkdownOpts as g, type DocToHtmlOpts as h, type ImageRef as i, type DocReplaceImagesOpts as j, type DocInsertQrCodeOpts as k, type QrPayload as l, type DocTemplateMergeOpts as m, type TransformSpec as n, type JobHandle as o, type JobStatusResponse as p, type TransformsService as q, keyFor as r, transforms as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@maravilla-labs/platform",
-  "version": "0.8.1",
+  "version": "0.9.0",
   "description": "Universal platform client for Maravilla runtime",
   "type": "module",
   "main": "./dist/index.js",
@@ -22,19 +22,16 @@
     "./events": {
       "types": "./dist/events.d.ts",
       "import": "./dist/events.js"
+    },
+    "./mcp": {
+      "types": "./dist/mcp.d.ts",
+      "import": "./dist/mcp.js"
     }
   },
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "typecheck": "tsc --noEmit",
-    "typecheck:test-d": "tsc --noEmit -p tsconfig.test.json",
-    "test": "vitest run"
-  },
   "dependencies": {
-    "@maravilla-labs/types": "^0.6.0",
     "@noble/hashes": "^1.5.0",
-    "livekit-client": "^2.18.1"
+    "livekit-client": "^2.18.1",
+    "@maravilla-labs/types": "^0.9.0"
   },
   "devDependencies": {
     "@types/node": "^22.10.6",
@@ -44,5 +41,12 @@
   },
   "publishConfig": {
     "access": "public"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit",
+    "typecheck:test-d": "tsc --noEmit -p tsconfig.test.json",
+    "test": "vitest run"
   }
-}
+}

package/src/config.ts

@@ -419,6 +419,45 @@ export interface BrandingConfig {
   custom_css?: string;
 }
 
+// ── Email ──
+
+/**
+ * Transactional email settings for the hosted `_auth` flows (currently the
+ * password-reset email). Reconciled server-side on deploy.
+ *
+ * The visible `From` *address* is always the platform's verified sender
+ * (Maravilla Cloud) and is not configurable. The `From` display *name* is safe
+ * to customise via `from_name`; surface your own address via `reply_to`.
+ */
+export interface EmailConfig {
+  /** Master switch. When `false`, the reset flow still mints a token but no email is sent. Defaults to `true`. */
+  enabled?: boolean;
+  /** `From` display name (e.g. `"Acme Support"`) → `Acme Support <noreply@maravilla.cloud>`. The address is fixed; only the name is yours. */
+  from_name?: string;
+  /** Reply-To address. The visible `From` is always the platform sender; replies go here. */
+  reply_to?: string;
+  /** Override the password-reset email subject line. */
+  password_reset_subject?: string;
+  /** Full custom HTML body. Use the literal `{{reset_url}}` placeholder for the link. */
+  password_reset_html?: string;
+  /** Full custom plain-text body (same `{{reset_url}}` placeholder). */
+  password_reset_text?: string;
+  /** Enable passwordless "magic link" email login on the hosted `/_auth/login` page. Off by default; requires `enabled` to send. */
+  magic_link_enabled?: boolean;
+  /** Override the magic-link email subject line. */
+  magic_link_subject?: string;
+  /** Full custom HTML body for the magic-link email. Use the literal `{{magic_link_url}}` placeholder. */
+  magic_link_html?: string;
+  /** Full custom plain-text body for the magic-link email (same `{{magic_link_url}}` placeholder). */
+  magic_link_text?: string;
+  /** Override the email-verification email subject line. */
+  verification_subject?: string;
+  /** Full custom HTML body for the verification email. Use the literal `{{verify_url}}` placeholder. */
+  verification_html?: string;
+  /** Full custom plain-text body for the verification email (same `{{verify_url}}` placeholder). */
+  verification_text?: string;
+}
+
 // ── Top-level shape ──
 
 export interface AuthConfigBlock {
@@ -429,6 +468,8 @@ export interface AuthConfigBlock {
   oauth?: OAuthProvidersConfig;
   security?: SecurityConfig;
   branding?: BrandingConfig;
+  /** Transactional email settings for the hosted `_auth` flows. */
+  email?: EmailConfig;
   /**
    * Named, reusable policy fragments. Reference a fragment from any
    * resource policy with `fragment('name')`; {@link defineConfig} expands
@@ -460,6 +501,11 @@ export interface MaravillaConfig {
    * matching upload. See {@link TransformsConfig}.
    */
   transforms?: TransformsConfig;
+  /**
+   * MCP server block — turns the app's `mcp/` folder into an MCP server at
+   * `<app-url>/_mcp`. See {@link McpConfigBlock}.
+   */
+  mcp?: McpConfigBlock;
 }
 
 // ── Database block ──
@@ -517,6 +563,56 @@ export interface DatabaseConfigBlock {
   vectorIndexes?: VectorIndexDeclaration[];
 }
 
+// ── MCP block ──
+//
+// The `mcp` block turns the app's `mcp/` folder into an MCP server hosted at
+// `<app-url>/_mcp`. It is the master switch (`enabled`) plus the scope set
+// agents are offered at login — the runtime is the OAuth Authorization Server,
+// so agents authenticate with the app's own accounts (or a headless `mk_…`
+// key). Tools, server identity, and UI templates themselves are authored in
+// `mcp/*.ts` via `defineMcpServer` / `defineMcpTool`. Mirrors the Rust
+// `platform::mcp::McpConfig`.
+
+/** Server identity advertised to agents in the MCP `initialize` handshake. */
+export interface McpServerConfig {
+  /** Human-readable server name (e.g. "Notes"). */
+  name: string;
+  /** Optional semantic version. */
+  version?: string;
+  /** Optional natural-language usage instructions for the client/model. */
+  instructions?: string;
+}
+
+/** Allow-list of routes that may be framed as MCP UI mini-apps. */
+export interface McpUiConfig {
+  /** Route globs allowed to render as iframe mini-apps (e.g. `/_mcp/ui/*`). */
+  routes: string[];
+}
+
+/** Whether to persist a user's scope grant so they aren't re-prompted. */
+export interface McpConsentConfig {
+  remember?: boolean;
+}
+
+export interface McpConfigBlock {
+  /** Master switch. With `false` (the default) the `/_mcp` endpoint is off. */
+  enabled: boolean;
+  /** Server identity advertised to agents. */
+  server?: McpServerConfig;
+  /**
+   * Every scope any tool can require, advertised to agents at login / Dynamic
+   * Client Registration. A tool whose `scopes` aren't listed here can never be
+   * granted. A tool with no scopes is public (callable without a login).
+   */
+  scopes?: string[];
+  /** Allow-list of UI mini-app routes (frame-ancestors / loopback gate). */
+  ui?: McpUiConfig;
+  /** Public origin agents connect to, when it differs from the request host. */
+  publicUrl?: string;
+  /** Consent persistence toggle. */
+  consent?: McpConsentConfig;
+}
+
 /**
  * Recursively expand `fragment(name)` sentinels in `expr` against the
  * declared `fragments` map. Each expansion is wrapped in parens so it

package/src/mcp.ts

@@ -0,0 +1,189 @@
+/**
+ * @fileoverview MCP tool authoring helpers for Maravilla.
+ *
+ * User apps declare MCP tools in `mcp.ts` or `mcp/*.ts`:
+ *
+ * ```ts
+ * import { defineMcpTool, defineMcpServer } from '@maravilla-labs/platform/mcp';
+ *
+ * export const server = defineMcpServer({
+ *   name: 'Acme Tools',
+ *   version: '1.0.0',
+ *   instructions: 'Tools for managing Acme orders.',
+ *   uiTemplates: [{ name: 'order-card', route: '/_mcp/ui/order-card' }],
+ * });
+ *
+ * export const getOrder = defineMcpTool(
+ *   {
+ *     name: 'get_order',
+ *     description: 'Look up an order by id.',
+ *     inputSchema: { type: 'object', properties: { id: { type: 'string' } }, required: ['id'] },
+ *     scopes: ['acme:read'],
+ *     ui: { template: 'order-card' },
+ *   },
+ *   async (args, ctx) => {
+ *     const order = await ctx.database.findOne('orders', { _id: args.id });
+ *     return { content: [{ type: 'text', text: JSON.stringify(order) }] };
+ *   },
+ * );
+ * ```
+ *
+ * These helpers are pure factories. `defineMcpTool` produces a
+ * `RegisteredMcpTool` marker object that the build pipeline
+ * (`@maravilla-labs/functions` `buildMcp`) detects by its `__maravilla_mcp`
+ * property; `defineMcpServer` produces a `RegisteredMcpServer` detected by
+ * `__maravilla_mcp_server`. The generated bundle exposes
+ * `globalThis.handleMcpTool(toolId, args, ctx)`; the Rust MCP dispatcher
+ * (`crates/platform/src/mcp/dispatch.rs`) drives it via a synthetic request
+ * whose body is `{ tool_id, args, identity }`.
+ */
+
+// ============ Tool handler context ============
+
+/**
+ * Context handed to every MCP tool handler. The first seven services mirror
+ * the events `EventCtx` (and `globalThis.platform`) exactly. `user`/`client`
+ * carry the authenticated identity behind the OAuth token or API key so the
+ * handler — and the platform ops it calls — run as the real end-user.
+ */
+export interface McpToolContext {
+  /** Per-tenant env vars. */
+  env: Record<string, string>;
+  /** KV store — same shape as `getPlatform().env.KV` / `platform.kv`. */
+  kv?: unknown;
+  /** MongoDB-style database — same shape as `getPlatform().env.DB`. */
+  database?: unknown;
+  /** Object storage. */
+  storage?: unknown;
+  /** Durable queue producer (`.send(name, payload, opts?)`). */
+  queue?: { send: (name: string, payload: unknown, opts?: unknown) => Promise<string> };
+  /** Auth service — register/login/logout/user CRUD/etc. */
+  auth?: unknown;
+  /** Web Push service. */
+  push?: unknown;
+  /** Full platform object — escape hatch for services not surfaced above. */
+  platform?: unknown;
+  /** Tenant identifier. */
+  tenant: string;
+  /** Trace correlation id — propagate through logs. */
+  traceId: string;
+  /** The end-user behind the token/key, or `null` for a client-only call. */
+  user: { id: string; email: string; groups: string[]; scopes: string[] } | null;
+  /** The OAuth client (agent) that authenticated, when known. */
+  client: { id: string } | null;
+}
+
+// ============ Tool result shapes ============
+
+/** A single content item returned by a tool. */
+export type McpContentItem =
+  | { type: 'text'; text: string }
+  | { type: 'json'; json: unknown }
+  | { type: 'resource'; resource: Record<string, unknown> };
+
+/**
+ * What a tool handler may return:
+ * - `{ content }` — explicit MCP content items.
+ * - `{ ui }` — render an iframe mini-app template (§7); optional `content`
+ *   is shown alongside for clients that don't support the UI.
+ * - any other value — wrapped as a single `text` content item.
+ */
+export type McpToolResult =
+  | { content: McpContentItem[] }
+  | { ui: { template: string; data?: unknown }; content?: McpContentItem[] }
+  | unknown;
+
+// ============ Registered markers ============
+
+export const MCP_TOOL_SYMBOL = '__maravilla_mcp' as const;
+export const MCP_SERVER_SYMBOL = '__maravilla_mcp_server' as const;
+
+/** Spec passed to {@link defineMcpTool}. */
+export interface McpToolSpec {
+  /** Tool name surfaced to the client (defaults to the export name). */
+  name: string;
+  /** Human-readable description sent in `tools/list`. */
+  description: string;
+  /** JSON Schema for the tool input, sent verbatim in `tools/list`. */
+  inputSchema: Record<string, unknown>;
+  /** Required scopes; dispatch enforces `scopes ⊆ identity.scopes`. */
+  scopes?: string[];
+  /**
+   * Per-tool public opt-in. When `true`, this tool is callable with an
+   * anonymous identity (no bearer) even on an otherwise-private server — its
+   * `scopes` must still be a subset of the caller's, so an anonymous caller can
+   * only reach it when it declares no scopes. Defaults to `false`.
+   */
+  public?: boolean;
+  /** Links this tool to a UI template declared on the server (§7). */
+  ui?: { template: string };
+}
+
+export interface RegisteredMcpTool {
+  readonly [MCP_TOOL_SYMBOL]: McpToolSpec;
+  readonly handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>;
+}
+
+/** Spec passed to {@link defineMcpServer}. */
+export interface McpServerSpec {
+  /** Human-readable server name (e.g. "Acme Tools"). */
+  name: string;
+  /** Optional semantic version. */
+  version?: string;
+  /** Optional natural-language usage instructions for the client/model. */
+  instructions?: string;
+  /**
+   * Server-level public flag. When `true`, unauthenticated MCP requests build
+   * an anonymous identity (instead of a 401) so `initialize` / `tools/list` and
+   * any no-scope tool work without a bearer. Per-tool `public` opt-in still
+   * works on an otherwise-private server. Defaults to `false`.
+   */
+  public?: boolean;
+  /** Iframe mini-app templates referenced by tools via `ui.template`. */
+  uiTemplates?: Array<{ name: string; route: string; csp?: string }>;
+}
+
+export interface RegisteredMcpServer {
+  readonly [MCP_SERVER_SYMBOL]: McpServerSpec;
+}
+
+// ============ Public factory helpers ============
+
+/**
+ * Declare an MCP tool. The runtime advertises it in `tools/list` (using
+ * `name`, `description`, `inputSchema`) and dispatches `tools/call` to
+ * `handler`, enforcing `scopes` against the caller's granted scopes.
+ */
+export function defineMcpTool(
+  spec: McpToolSpec,
+  handler: (args: any, ctx: McpToolContext) => McpToolResult | Promise<McpToolResult>,
+): RegisteredMcpTool {
+  return { [MCP_TOOL_SYMBOL]: spec, handler };
+}
+
+/**
+ * Declare the MCP server identity and its iframe mini-app templates.
+ * Optional — at most one per app; the last one discovered wins.
+ */
+export function defineMcpServer(spec: McpServerSpec): RegisteredMcpServer {
+  return { [MCP_SERVER_SYMBOL]: spec };
+}
+
+/** Type guard used by the build-time discoverer and the runtime registry. */
+export function isRegisteredMcpTool(value: unknown): value is RegisteredMcpTool {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    MCP_TOOL_SYMBOL in value &&
+    typeof (value as Record<string, unknown>).handler === 'function'
+  );
+}
+
+/** Type guard for a registered MCP server descriptor. */
+export function isRegisteredMcpServer(value: unknown): value is RegisteredMcpServer {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    MCP_SERVER_SYMBOL in value
+  );
+}