mountly-mcp 4.3.0 → 4.5.0

package/dist/events/index.d.ts

@@ -0,0 +1,97 @@
+import { z } from "zod";
+type MaybePromise<T> = T | Promise<T>;
+export interface EventDefinition<I extends z.ZodType = z.ZodType, P extends z.ZodType = z.ZodType> {
+    description?: string;
+    /** Subscription arguments (e.g. `{ document_id }`). */
+    input: I;
+    /** Event `data`. Validated on `emit` when set. */
+    payload?: P;
+}
+export interface EventSubscription {
+    id: string;
+    name: string;
+    arguments: Record<string, unknown>;
+    url: string;
+    secret: string;
+    /** Epoch ms. */
+    expiresAt: number;
+    /** Principal captured at subscribe time; re-checked before every delivery. */
+    authInfo?: unknown;
+}
+/** A `Map` works. Persist across restarts in production (the spec requires it). */
+export interface SubscriptionStore {
+    get(key: string): MaybePromise<EventSubscription | undefined>;
+    set(key: string, subscription: EventSubscription): unknown;
+    delete(key: string): unknown;
+    values(): MaybePromise<Iterable<EventSubscription>>;
+}
+export interface AuthorizeRequest {
+    name: string;
+    arguments: Record<string, unknown>;
+    authInfo?: unknown;
+}
+export interface DefineEventsOptions<E extends Record<string, EventDefinition>> {
+    events: E;
+    store?: SubscriptionStore;
+    /**
+     * Called on subscribe/unsubscribe with the caller, and before each delivery with
+     * the principal stored at subscribe time. Return `false` to deny; a denied
+     * delivery deletes the subscription.
+     */
+    authorize?: (request: AuthorizeRequest) => MaybePromise<boolean>;
+    /** Default: `https:` only. Narrow further to block SSRF to internal hosts. */
+    allowCallbackUrl?: (url: URL) => boolean;
+    /** Default and maximum subscription lifetime. Default 30 days. */
+    maxTtlMs?: number;
+    /** Delivery attempts per event. Default 5. */
+    maxAttempts?: number;
+    /** First retry delay; doubles each attempt. Default 1000. */
+    retryBaseMs?: number;
+    fetch?: typeof fetch;
+}
+export interface EmitResult {
+    subscriptionId: string;
+    status: number;
+    delivered: boolean;
+}
+/** JSON-RPC error; `code` is honoured by the MCP SDK when thrown from a handler. */
+export declare class McpEventsError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+/** Standard Webhooks `v1` signature (what ChatGPT verifies). */
+export declare function signWebhook(input: {
+    secret: string;
+    id: string;
+    timestamp: number;
+    body: string;
+}): string;
+export declare function defineEvents<E extends Record<string, EventDefinition>>(options: DefineEventsOptions<E>): {
+    /** `events/list` result. */
+    list(): {
+        events: {
+            name: string;
+            description?: string | undefined;
+            delivery: string[];
+            inputSchema: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>>;
+            payloadSchema?: z.core.ZodStandardJSONSchemaPayload<z.ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>> | undefined;
+        }[];
+        nextCursor: null;
+    };
+    /** `events/subscribe`, idempotent per (name, arguments, url). */
+    subscribe(params: unknown, ctx?: {
+        authInfo?: unknown;
+    }): Promise<{
+        id: string;
+        refreshBefore: string;
+        cursor: null;
+        truncated: boolean;
+    }>;
+    /** `events/unsubscribe`, idempotent. */
+    unsubscribe(params: unknown, ctx?: {
+        authInfo?: unknown;
+    }): Promise<{}>;
+    /** Deliver one event to every live subscription for `name` whose arguments `match`. */
+    emit<N extends keyof E & string>(name: N, data: E[N]["payload"] extends z.ZodType ? z.input<E[N]["payload"]> : unknown, match?: (args: z.output<E[N]["input"]>) => boolean): Promise<EmitResult[]>;
+};
+export {};

package/dist/events/index.js

@@ -0,0 +1,215 @@
+// src/events/index.ts
+import { createHmac, randomBytes, timingSafeEqual } from "crypto";
+import { z } from "zod";
+var McpEventsError = class extends Error {
+  constructor(code, message) {
+    super(message);
+    this.name = "McpEventsError";
+    this.code = code;
+  }
+};
+var INVALID_PARAMS = -32602;
+var MAX_BODY_BYTES = 262144;
+var SECRET = /^whsec_([A-Za-z0-9+/]+={0,2})$/;
+var SubscribeParams = z.object({
+  name: z.string(),
+  arguments: z.record(z.string(), z.unknown()).default({}),
+  delivery: z.object({ mode: z.literal("webhook"), url: z.string(), secret: z.string() }),
+  cursor: z.string().nullish(),
+  ttlMs: z.number().int().positive().nullish()
+});
+var UnsubscribeParams = z.object({
+  name: z.string(),
+  arguments: z.record(z.string(), z.unknown()).default({}),
+  delivery: z.object({ mode: z.literal("webhook"), url: z.string() })
+});
+function signWebhook(input) {
+  const key = Buffer.from(input.secret.replace(/^whsec_/, ""), "base64");
+  const mac = createHmac("sha256", key).update(`${input.id}.${input.timestamp}.${input.body}`);
+  return `v1,${mac.digest("base64")}`;
+}
+function canonical(value) {
+  if (Array.isArray(value)) return `[${value.map(canonical).join(",")}]`;
+  if (value && typeof value === "object") {
+    const obj = value;
+    return `{${Object.keys(obj).sort().map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`).join(",")}}`;
+  }
+  return JSON.stringify(value);
+}
+function parse(schema, value, what) {
+  const result = schema.safeParse(value);
+  if (!result.success)
+    throw new McpEventsError(INVALID_PARAMS, `Invalid ${what}: ${z.prettifyError(result.error)}`);
+  return result.data;
+}
+var id = (prefix) => `${prefix}_${randomBytes(12).toString("hex")}`;
+var keyOf = (name, args, url) => `${name}
+${canonical(args)}
+${url}`;
+function defineEvents(options) {
+  const {
+    events,
+    store = /* @__PURE__ */ new Map(),
+    authorize,
+    allowCallbackUrl = (url) => url.protocol === "https:",
+    maxTtlMs = 30 * 24 * 60 * 60 * 1e3,
+    maxAttempts = 5,
+    retryBaseMs = 1e3,
+    fetch: fetchFn = fetch
+  } = options;
+  function definition(name) {
+    const def = Object.prototype.hasOwnProperty.call(events, name) ? events[name] : void 0;
+    if (!def) throw new McpEventsError(INVALID_PARAMS, `Unknown event: ${name}`);
+    return def;
+  }
+  async function allowed(request) {
+    return !authorize || await authorize(request);
+  }
+  function post(sub, webhookId, body) {
+    const timestamp = Math.floor(Date.now() / 1e3);
+    return fetchFn(sub.url, {
+      method: "POST",
+      redirect: "error",
+      signal: AbortSignal.timeout(1e4),
+      headers: {
+        "content-type": "application/json",
+        "webhook-id": webhookId,
+        "webhook-timestamp": String(timestamp),
+        "webhook-signature": signWebhook({ secret: sub.secret, id: webhookId, timestamp, body }),
+        "x-mcp-subscription-id": sub.id
+      },
+      body
+    });
+  }
+  async function verify(sub) {
+    const challenge = randomBytes(32).toString("base64url");
+    const res = await post(
+      sub,
+      id("msg_verification"),
+      JSON.stringify({ type: "verification", challenge })
+    ).catch(() => void 0);
+    const echoed = res?.ok ? (await res.json().catch(() => ({}))).challenge : void 0;
+    const ok = typeof echoed === "string" && echoed.length === challenge.length && timingSafeEqual(Buffer.from(echoed), Buffer.from(challenge));
+    if (!ok) throw new McpEventsError(INVALID_PARAMS, "Callback verification failed");
+  }
+  async function deliver(key, sub, eventId, body) {
+    let status = 0;
+    for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+      status = (await post(sub, eventId, body).catch(() => void 0))?.status ?? 0;
+      if (status >= 200 && status < 300) return { subscriptionId: sub.id, status, delivered: true };
+      if (status === 410) await store.delete(key);
+      const transient = status === 0 || status === 408 || status === 429 || status >= 500;
+      if (!transient) break;
+      if (attempt < maxAttempts)
+        await new Promise((r) => setTimeout(r, retryBaseMs * 2 ** (attempt - 1)));
+    }
+    return { subscriptionId: sub.id, status, delivered: false };
+  }
+  return {
+    /** `events/list` result. */
+    list() {
+      return {
+        events: Object.entries(events).map(([name, def]) => ({
+          name,
+          ...def.description ? { description: def.description } : {},
+          delivery: ["webhook"],
+          inputSchema: z.toJSONSchema(def.input),
+          ...def.payload ? { payloadSchema: z.toJSONSchema(def.payload) } : {}
+        })),
+        nextCursor: null
+      };
+    },
+    /** `events/subscribe`, idempotent per (name, arguments, url). */
+    async subscribe(params, ctx = {}) {
+      const p = parse(SubscribeParams, params, "events/subscribe params");
+      const args = parse(
+        definition(p.name).input,
+        p.arguments,
+        `arguments for ${p.name}`
+      );
+      const url = URL.parse(p.delivery.url);
+      if (!url || !allowCallbackUrl(url))
+        throw new McpEventsError(INVALID_PARAMS, "Callback URL not allowed");
+      const secret = SECRET.exec(p.delivery.secret)?.[1];
+      const keyBytes = secret ? Buffer.from(secret, "base64").length : 0;
+      if (keyBytes < 24 || keyBytes > 64)
+        throw new McpEventsError(INVALID_PARAMS, "Secret must be whsec_ + base64 of 24\u201364 bytes");
+      if (!await allowed({ name: p.name, arguments: args, authInfo: ctx.authInfo })) {
+        throw new McpEventsError(INVALID_PARAMS, "Not authorized to subscribe");
+      }
+      const key = keyOf(p.name, args, url.href);
+      const existing = await store.get(key);
+      const ttl = Math.min(p.ttlMs ?? maxTtlMs, maxTtlMs);
+      const sub = {
+        id: existing?.id ?? id("sub"),
+        name: p.name,
+        arguments: args,
+        url: url.href,
+        secret: p.delivery.secret,
+        expiresAt: Date.now() + ttl,
+        authInfo: ctx.authInfo
+      };
+      if (existing?.secret !== sub.secret) await verify(sub);
+      await store.set(key, sub);
+      return {
+        id: sub.id,
+        refreshBefore: new Date(sub.expiresAt).toISOString(),
+        cursor: null,
+        truncated: false
+      };
+    },
+    /** `events/unsubscribe`, idempotent. */
+    async unsubscribe(params, ctx = {}) {
+      const p = parse(UnsubscribeParams, params, "events/unsubscribe params");
+      const args = parse(
+        definition(p.name).input,
+        p.arguments,
+        `arguments for ${p.name}`
+      );
+      if (!await allowed({ name: p.name, arguments: args, authInfo: ctx.authInfo })) {
+        throw new McpEventsError(INVALID_PARAMS, "Not authorized to unsubscribe");
+      }
+      const url = URL.parse(p.delivery.url);
+      if (url) await store.delete(keyOf(p.name, args, url.href));
+      return {};
+    },
+    /** Deliver one event to every live subscription for `name` whose arguments `match`. */
+    async emit(name, data, match = () => true) {
+      const def = definition(name);
+      const payload = def.payload ? parse(def.payload, data, `payload for ${name}`) : data;
+      const eventId = id("evt");
+      const body = JSON.stringify({
+        eventId,
+        name,
+        timestamp: (/* @__PURE__ */ new Date()).toISOString(),
+        data: payload,
+        cursor: null
+      });
+      if (Buffer.byteLength(body) > MAX_BODY_BYTES)
+        throw new McpEventsError(INVALID_PARAMS, "Event body exceeds 256 KiB");
+      const now = Date.now();
+      const deliveries = [];
+      for (const sub of [...await store.values()]) {
+        if (sub.name !== name) continue;
+        const key = keyOf(sub.name, sub.arguments, sub.url);
+        if (sub.expiresAt <= now) {
+          await store.delete(key);
+          continue;
+        }
+        if (!match(sub.arguments)) continue;
+        if (!await allowed({ name, arguments: sub.arguments, authInfo: sub.authInfo })) {
+          await store.delete(key);
+          continue;
+        }
+        deliveries.push(deliver(key, sub, eventId, body));
+      }
+      return Promise.all(deliveries);
+    }
+  };
+}
+export {
+  McpEventsError,
+  defineEvents,
+  signWebhook
+};
+//# sourceMappingURL=index.js.map

package/dist/events/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/events/index.ts"],"sourcesContent":["/**\n * MCP Events over webhooks (protocol `2026-07-28`), the delivery mode ChatGPT uses.\n *\n * Wire `list`, `subscribe` and `unsubscribe` into any MCP 2.0 server as `events/*`\n * request handlers, then call `emit` when something changes. This entry tracks the\n * draft spec and stays experimental until the spec settles.\n */\nimport { createHmac, randomBytes, timingSafeEqual } from \"node:crypto\";\nimport { z } from \"zod\";\n\ntype MaybePromise<T> = T | Promise<T>;\n\nexport interface EventDefinition<I extends z.ZodType = z.ZodType, P extends z.ZodType = z.ZodType> {\n  description?: string;\n  /** Subscription arguments (e.g. `{ document_id }`). */\n  input: I;\n  /** Event `data`. Validated on `emit` when set. */\n  payload?: P;\n}\n\nexport interface EventSubscription {\n  id: string;\n  name: string;\n  arguments: Record<string, unknown>;\n  url: string;\n  secret: string;\n  /** Epoch ms. */\n  expiresAt: number;\n  /** Principal captured at subscribe time; re-checked before every delivery. */\n  authInfo?: unknown;\n}\n\n/** A `Map` works. Persist across restarts in production (the spec requires it). */\nexport interface SubscriptionStore {\n  get(key: string): MaybePromise<EventSubscription | undefined>;\n  set(key: string, subscription: EventSubscription): unknown;\n  delete(key: string): unknown;\n  values(): MaybePromise<Iterable<EventSubscription>>;\n}\n\nexport interface AuthorizeRequest {\n  name: string;\n  arguments: Record<string, unknown>;\n  authInfo?: unknown;\n}\n\nexport interface DefineEventsOptions<E extends Record<string, EventDefinition>> {\n  events: E;\n  store?: SubscriptionStore;\n  /**\n   * Called on subscribe/unsubscribe with the caller, and before each delivery with\n   * the principal stored at subscribe time. Return `false` to deny; a denied\n   * delivery deletes the subscription.\n   */\n  authorize?: (request: AuthorizeRequest) => MaybePromise<boolean>;\n  /** Default: `https:` only. Narrow further to block SSRF to internal hosts. */\n  allowCallbackUrl?: (url: URL) => boolean;\n  /** Default and maximum subscription lifetime. Default 30 days. */\n  maxTtlMs?: number;\n  /** Delivery attempts per event. Default 5. */\n  maxAttempts?: number;\n  /** First retry delay; doubles each attempt. Default 1000. */\n  retryBaseMs?: number;\n  fetch?: typeof fetch;\n}\n\nexport interface EmitResult {\n  subscriptionId: string;\n  status: number;\n  delivered: boolean;\n}\n\n/** JSON-RPC error; `code` is honoured by the MCP SDK when thrown from a handler. */\nexport class McpEventsError extends Error {\n  readonly code: number;\n  constructor(code: number, message: string) {\n    super(message);\n    this.name = \"McpEventsError\";\n    this.code = code;\n  }\n}\n\nconst INVALID_PARAMS = -32602;\nconst MAX_BODY_BYTES = 262_144;\nconst SECRET = /^whsec_([A-Za-z0-9+/]+={0,2})$/;\n\nconst SubscribeParams = z.object({\n  name: z.string(),\n  arguments: z.record(z.string(), z.unknown()).default({}),\n  delivery: z.object({ mode: z.literal(\"webhook\"), url: z.string(), secret: z.string() }),\n  cursor: z.string().nullish(),\n  ttlMs: z.number().int().positive().nullish(),\n});\n\nconst UnsubscribeParams = z.object({\n  name: z.string(),\n  arguments: z.record(z.string(), z.unknown()).default({}),\n  delivery: z.object({ mode: z.literal(\"webhook\"), url: z.string() }),\n});\n\n/** Standard Webhooks `v1` signature (what ChatGPT verifies). */\nexport function signWebhook(input: {\n  secret: string;\n  id: string;\n  timestamp: number;\n  body: string;\n}): string {\n  const key = Buffer.from(input.secret.replace(/^whsec_/, \"\"), \"base64\");\n  const mac = createHmac(\"sha256\", key).update(`${input.id}.${input.timestamp}.${input.body}`);\n  return `v1,${mac.digest(\"base64\")}`;\n}\n\nfunction canonical(value: unknown): string {\n  if (Array.isArray(value)) return `[${value.map(canonical).join(\",\")}]`;\n  if (value && typeof value === \"object\") {\n    const obj = value as Record<string, unknown>;\n    return `{${Object.keys(obj)\n      .sort()\n      .map((k) => `${JSON.stringify(k)}:${canonical(obj[k])}`)\n      .join(\",\")}}`;\n  }\n  return JSON.stringify(value);\n}\n\nfunction parse<S extends z.ZodType>(schema: S, value: unknown, what: string): z.output<S> {\n  const result = schema.safeParse(value);\n  if (!result.success)\n    throw new McpEventsError(INVALID_PARAMS, `Invalid ${what}: ${z.prettifyError(result.error)}`);\n  return result.data;\n}\n\nconst id = (prefix: string) => `${prefix}_${randomBytes(12).toString(\"hex\")}`;\n\nconst keyOf = (name: string, args: unknown, url: string) => `${name}\\n${canonical(args)}\\n${url}`;\n\nexport function defineEvents<E extends Record<string, EventDefinition>>(\n  options: DefineEventsOptions<E>,\n) {\n  const {\n    events,\n    store = new Map<string, EventSubscription>(),\n    authorize,\n    allowCallbackUrl = (url) => url.protocol === \"https:\",\n    maxTtlMs = 30 * 24 * 60 * 60 * 1000,\n    maxAttempts = 5,\n    retryBaseMs = 1000,\n    fetch: fetchFn = fetch,\n  } = options;\n\n  function definition(name: string): EventDefinition {\n    const def = Object.prototype.hasOwnProperty.call(events, name) ? events[name] : undefined;\n    if (!def) throw new McpEventsError(INVALID_PARAMS, `Unknown event: ${name}`);\n    return def;\n  }\n\n  async function allowed(request: AuthorizeRequest) {\n    return !authorize || (await authorize(request));\n  }\n\n  function post(sub: EventSubscription, webhookId: string, body: string) {\n    const timestamp = Math.floor(Date.now() / 1000);\n    return fetchFn(sub.url, {\n      method: \"POST\",\n      redirect: \"error\",\n      signal: AbortSignal.timeout(10_000),\n      headers: {\n        \"content-type\": \"application/json\",\n        \"webhook-id\": webhookId,\n        \"webhook-timestamp\": String(timestamp),\n        \"webhook-signature\": signWebhook({ secret: sub.secret, id: webhookId, timestamp, body }),\n        \"x-mcp-subscription-id\": sub.id,\n      },\n      body,\n    });\n  }\n\n  async function verify(sub: EventSubscription) {\n    const challenge = randomBytes(32).toString(\"base64url\");\n    const res = await post(\n      sub,\n      id(\"msg_verification\"),\n      JSON.stringify({ type: \"verification\", challenge }),\n    ).catch(() => undefined);\n    const echoed = res?.ok\n      ? ((await res.json().catch(() => ({}))) as { challenge?: unknown }).challenge\n      : undefined;\n    const ok =\n      typeof echoed === \"string\" &&\n      echoed.length === challenge.length &&\n      timingSafeEqual(Buffer.from(echoed), Buffer.from(challenge));\n    if (!ok) throw new McpEventsError(INVALID_PARAMS, \"Callback verification failed\");\n  }\n\n  async function deliver(\n    key: string,\n    sub: EventSubscription,\n    eventId: string,\n    body: string,\n  ): Promise<EmitResult> {\n    let status = 0;\n    for (let attempt = 1; attempt <= maxAttempts; attempt++) {\n      // Fresh timestamp + signature per attempt; same event id and body bytes.\n      status = (await post(sub, eventId, body).catch(() => undefined))?.status ?? 0;\n      if (status >= 200 && status < 300) return { subscriptionId: sub.id, status, delivered: true };\n      if (status === 410) await store.delete(key);\n      const transient = status === 0 || status === 408 || status === 429 || status >= 500;\n      if (!transient) break;\n      if (attempt < maxAttempts)\n        await new Promise((r) => setTimeout(r, retryBaseMs * 2 ** (attempt - 1)));\n    }\n    return { subscriptionId: sub.id, status, delivered: false };\n  }\n\n  return {\n    /** `events/list` result. */\n    list() {\n      return {\n        events: Object.entries(events).map(([name, def]) => ({\n          name,\n          ...(def.description ? { description: def.description } : {}),\n          delivery: [\"webhook\"],\n          inputSchema: z.toJSONSchema(def.input),\n          ...(def.payload ? { payloadSchema: z.toJSONSchema(def.payload) } : {}),\n        })),\n        nextCursor: null,\n      };\n    },\n\n    /** `events/subscribe`, idempotent per (name, arguments, url). */\n    async subscribe(params: unknown, ctx: { authInfo?: unknown } = {}) {\n      const p = parse(SubscribeParams, params, \"events/subscribe params\");\n      const args = parse(\n        definition(p.name).input,\n        p.arguments,\n        `arguments for ${p.name}`,\n      ) as Record<string, unknown>;\n\n      const url = URL.parse(p.delivery.url);\n      if (!url || !allowCallbackUrl(url))\n        throw new McpEventsError(INVALID_PARAMS, \"Callback URL not allowed\");\n      const secret = SECRET.exec(p.delivery.secret)?.[1];\n      const keyBytes = secret ? Buffer.from(secret, \"base64\").length : 0;\n      if (keyBytes < 24 || keyBytes > 64)\n        throw new McpEventsError(INVALID_PARAMS, \"Secret must be whsec_ + base64 of 24–64 bytes\");\n      if (!(await allowed({ name: p.name, arguments: args, authInfo: ctx.authInfo }))) {\n        throw new McpEventsError(INVALID_PARAMS, \"Not authorized to subscribe\");\n      }\n\n      const key = keyOf(p.name, args, url.href);\n      const existing = await store.get(key);\n      const ttl = Math.min(p.ttlMs ?? maxTtlMs, maxTtlMs);\n      const sub: EventSubscription = {\n        id: existing?.id ?? id(\"sub\"),\n        name: p.name,\n        arguments: args,\n        url: url.href,\n        secret: p.delivery.secret,\n        expiresAt: Date.now() + ttl,\n        authInfo: ctx.authInfo,\n      };\n      if (existing?.secret !== sub.secret) await verify(sub);\n      await store.set(key, sub);\n      return {\n        id: sub.id,\n        refreshBefore: new Date(sub.expiresAt).toISOString(),\n        cursor: null,\n        truncated: false,\n      };\n    },\n\n    /** `events/unsubscribe`, idempotent. */\n    async unsubscribe(params: unknown, ctx: { authInfo?: unknown } = {}) {\n      const p = parse(UnsubscribeParams, params, \"events/unsubscribe params\");\n      const args = parse(\n        definition(p.name).input,\n        p.arguments,\n        `arguments for ${p.name}`,\n      ) as Record<string, unknown>;\n      if (!(await allowed({ name: p.name, arguments: args, authInfo: ctx.authInfo }))) {\n        throw new McpEventsError(INVALID_PARAMS, \"Not authorized to unsubscribe\");\n      }\n      const url = URL.parse(p.delivery.url);\n      if (url) await store.delete(keyOf(p.name, args, url.href));\n      return {};\n    },\n\n    /** Deliver one event to every live subscription for `name` whose arguments `match`. */\n    async emit<N extends keyof E & string>(\n      name: N,\n      data: E[N][\"payload\"] extends z.ZodType ? z.input<E[N][\"payload\"]> : unknown,\n      match: (args: z.output<E[N][\"input\"]>) => boolean = () => true,\n    ): Promise<EmitResult[]> {\n      const def = definition(name);\n      const payload = def.payload ? parse(def.payload, data, `payload for ${name}`) : data;\n      const eventId = id(\"evt\");\n      const body = JSON.stringify({\n        eventId,\n        name,\n        timestamp: new Date().toISOString(),\n        data: payload,\n        cursor: null,\n      });\n      if (Buffer.byteLength(body) > MAX_BODY_BYTES)\n        throw new McpEventsError(INVALID_PARAMS, \"Event body exceeds 256 KiB\");\n\n      const now = Date.now();\n      const deliveries: Promise<EmitResult>[] = [];\n      for (const sub of [...(await store.values())]) {\n        if (sub.name !== name) continue;\n        const key = keyOf(sub.name, sub.arguments, sub.url);\n        if (sub.expiresAt <= now) {\n          await store.delete(key);\n          continue;\n        }\n        if (!match(sub.arguments as z.output<E[N][\"input\"]>)) continue;\n        if (!(await allowed({ name, arguments: sub.arguments, authInfo: sub.authInfo }))) {\n          await store.delete(key);\n          continue;\n        }\n        deliveries.push(deliver(key, sub, eventId, body));\n      }\n      return Promise.all(deliveries);\n    },\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -2,6 +2,7 @@ export * from "./types.js";
 export * from "./schema.js";
 export * from "./publish.js";
 export { runBridge, App, PostMessageTransport } from "./bridge/index.js";
+export { downloadFile, type DownloadableFile } from "./download.js";
 export type { RunBridgeOptions, RunningBridge } from "./bridge/index.js";
 export { sandboxProxyHtml } from "./sandbox/index.js";
 export type { SandboxProxyHtmlOptions } from "./sandbox/index.js";

package/dist/index.js

@@ -1,11 +1,14 @@
+import {
+  sandboxProxyHtml
+} from "./chunk-6QHKKFO3.js";
+import {
+  downloadFile
+} from "./chunk-BLT2MK32.js";
 import {
   MCP_VIEW_GLOBAL_KEY,
   getPublishedMcpView,
   publishMcpView
 } from "./chunk-5L3QHYWK.js";
-import {
-  sandboxProxyHtml
-} from "./chunk-6QHKKFO3.js";
 import {
   App,
   PostMessageTransport,
@@ -30,6 +33,7 @@ export {
   MCP_VIEW_GLOBAL_KEY,
   PostMessageTransport,
   RESOURCE_URI_META_KEY,
+  downloadFile,
   getPublishedMcpView,
   publishMcpView,
   runBridge,

package/dist/json-render/index.js

@@ -19,8 +19,9 @@ import {
   createMcpView,
   useMcpApp,
   useToolResult
-} from "../chunk-HIAIQVK5.js";
+} from "../chunk-QIA76O6M.js";
 import "../chunk-4SZHJ4MK.js";
+import "../chunk-BLT2MK32.js";
 import "../chunk-5L3QHYWK.js";
 import "../chunk-YJA4H6IB.js";
 

package/dist/json-render/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../../src/json-render/generative-view.tsx","../../src/json-render/index.ts","../../src/json-render/use-spec-stream.ts"],"sourcesContent":["import { createElement } from \"react\";\nimport { type ComponentMap, createRenderer } from \"@json-render/react\";\nimport type { Catalog, SchemaDefinition, Spec } from \"@json-render/core\";\nimport { createMcpView, useMcpApp, useToolResult } from \"../react/index.js\";\nimport type { App } from \"@modelcontextprotocol/ext-apps\";\nimport type { AdapterOptions } from \"mountly/adapter\";\nimport type { McpView } from \"../types.js\";\n\n/** The catalog-data constraint createRenderer infers against. */\ntype CatalogData = { components: Record<string, { props: unknown }> };\n\n/**\n * Route a generated UI's actions back to the MCP host. Called with the action\n * name, its (resolved) params, and the view-side `App` handle.\n */\nexport type ActionRouter = (\n  name: string,\n  params: Record<string, unknown> | undefined,\n  mcp: App,\n) => void;\n\n/**\n * Default router: an `ask` action with a string `prompt` param sends a\n * follow-up user turn to the model via `App.sendMessage`. This is the agent\n * loop json-render alone cannot do — it has no concept of an MCP host.\n */\nexport const defaultActionRouter: ActionRouter = (name, params, mcp) => {\n  if (name !== \"ask\") return;\n  const prompt = params?.prompt;\n  const text = typeof prompt === \"string\" ? prompt : \"\";\n  if (text) {\n    void mcp.sendMessage({ role: \"user\", content: [{ type: \"text\", text }] });\n  }\n};\n\n/**\n * Identity helper that types a components map against a catalog (so it can be\n * defined once and reused by both `createGenerativeView` and `createRenderer`)\n * without losing per-component prop inference.\n *\n * ```ts\n * export const components = defineComponents(catalog, {\n *   Metric: ({ element }) => <span>{element.props.value}</span>,\n * });\n * ```\n */\nexport function defineComponents<TDef extends SchemaDefinition, TCatalog extends CatalogData>(\n  _catalog: Catalog<TDef, TCatalog>,\n  components: ComponentMap<TCatalog[\"components\"]>,\n): ComponentMap<TCatalog[\"components\"]> {\n  return components;\n}\n\nexport interface GenerativeViewOptions<\n  TDef extends SchemaDefinition,\n  TCatalog extends CatalogData,\n> extends AdapterOptions {\n  /** The json-render catalog — the vocabulary the agent may compose. */\n  catalog: Catalog<TDef, TCatalog>;\n  /** Native component implementations for each catalog type. */\n  components: ComponentMap<TCatalog[\"components\"]>;\n  /**\n   * How a generated UI's actions reach the agent. Defaults to\n   * {@link defaultActionRouter} (`ask` → `App.sendMessage`).\n   */\n  onAction?: ActionRouter;\n}\n\ninterface ToolResultShape {\n  structuredContent?: { spec?: Spec };\n}\n\n/**\n * Turn a json-render catalog + components into a mountly MCP Apps View.\n *\n * Reads the spec from the tool result, renders it natively (resolving `$state`\n * from `spec.state`), and routes actions back to the MCP host.\n *\n * ```ts\n * createGenerativeView({ catalog, components, styles, shadow: true });\n * ```\n */\nexport function createGenerativeView<TDef extends SchemaDefinition, TCatalog extends CatalogData>(\n  options: GenerativeViewOptions<TDef, TCatalog>,\n): McpView {\n  const { catalog, components, onAction = defaultActionRouter, ...adapter } = options;\n  const Rendered = createRenderer(catalog, components);\n\n  function GenerativeView() {\n    const mcp = useMcpApp();\n    const result = useToolResult<ToolResultShape>();\n    const spec = result?.structuredContent?.spec ?? null;\n    if (!spec) return null;\n    return createElement(Rendered, {\n      spec,\n      state: spec.state,\n      onAction: (name: string, params?: Record<string, unknown>) => onAction(name, params, mcp),\n    });\n  }\n\n  return createMcpView(GenerativeView, adapter);\n}\n","export {\n  type ActionRouter,\n  type GenerativeViewOptions,\n  createGenerativeView,\n  defaultActionRouter,\n  defineComponents,\n} from \"./generative-view.js\";\nexport {\n  type JsonRenderToolOptions,\n  type RegisterJsonRenderResourceOptions,\n  type RegisterJsonRenderToolOptions,\n  type CreateJsonRenderMcpAppOptions,\n  createJsonRenderMcpApp,\n  registerJsonRenderTool,\n  registerJsonRenderResource,\n} from \"./mcp.js\";\nexport {\n  type BuildAppHtmlOptions,\n  type UseJsonRenderAppOptions,\n  type UseJsonRenderAppReturn,\n  buildAppHtml,\n  useJsonRenderApp,\n} from \"./app.js\";\n\n// Convenience re-exports for rendering the same catalog natively (non-MCP) —\n// previews, tests, or a plain mountly feature. Pair with `mountly-react`'s\n// `createWidget` to mount a spec outside an MCP host.\nexport { createRenderer } from \"@json-render/react\";\nexport type { ComponentMap, ComponentRenderProps } from \"@json-render/react\";\n\n// Streaming primitives (json-render's own): replay a known spec as a patch\n// stream, compile patches back into a progressively-built spec, and the AI-SDK\n// transform that classifies a model's UI-message stream into spec patches.\nexport {\n  compileSpecStream,\n  compileTextStreamToSpecs,\n  createJsonRenderTransform,\n  createSpecStreamCompiler,\n  parseSpecStreamLine,\n  specToPatchLines,\n} from \"./spec-stream.js\";\nexport type { Spec } from \"@json-render/core\";\n\n// --- Two ways to stream ---\n//\n// Replay (known spec): `useSpecStream` takes a finished spec — e.g. the one an\n// MCP tool delivered as `structuredContent` — and replays it as a live build,\n// with the compiler, loading flag, and cancellation included.\nexport {\n  type SpecStreamState,\n  type UseSpecStreamOptions,\n  useSpecStream,\n} from \"./use-spec-stream.js\";\n\n// Live (from a model): `useUIStream` / `useChatUI` are json-render's own client\n// hooks — POST a prompt to an endpoint that streams JSONL patches (see\n// `streamSpec` in `mountly-mcp/json-render/server`) and render the spec as it\n// builds. Re-exported so the live path is one import away.\nexport { useChatUI, useUIStream } from \"@json-render/react\";\nexport type { UseUIStreamOptions, UseUIStreamReturn } from \"@json-render/react\";\n","import { useEffect, useState } from \"react\";\nimport type { Spec } from \"@json-render/core\";\nimport { createSpecStreamCompiler } from \"@json-render/core\";\nimport { specToPatchLines } from \"./spec-stream.js\";\n\nexport interface UseSpecStreamOptions {\n  /** Delay between patches, ms. Default 90. Set 0 to render instantly. */\n  intervalMs?: number;\n}\n\nexport interface SpecStreamState {\n  /** The progressively-built spec (partial while streaming, full when done). */\n  spec: Spec | null;\n  /** Convenience: `spec?.state`, to pass straight to the renderer. */\n  state: Record<string, unknown> | undefined;\n  /** True while patches are still being applied. */\n  loading: boolean;\n}\n\n/**\n * Replay a finished spec as a live json-render stream — and own all the\n * ceremony. Give it the target spec; it scaffolds a `createSpecStreamCompiler`,\n * replays the patches with a delay, exposes the partial spec + `loading` after\n * each step, and cancels cleanly when the target changes (so a self-driving UI\n * that swaps specs mid-stream just works). Re-streams whenever `target` changes.\n *\n * ```tsx\n * const { spec, state, loading } = useSpecStream(specs[view]);\n * return <Renderer spec={spec} state={state} loading={loading} onAction={...} />;\n * ```\n */\nexport function useSpecStream(\n  target: Spec | null | undefined,\n  options: UseSpecStreamOptions = {},\n): SpecStreamState {\n  const { intervalMs = 90 } = options;\n  const [spec, setSpec] = useState<Spec | null>(null);\n  const [loading, setLoading] = useState(false);\n\n  useEffect(() => {\n    if (!target) {\n      setSpec(null);\n      setLoading(false);\n      return;\n    }\n    let cancelled = false;\n    const compiler = createSpecStreamCompiler<Spec>();\n    const lines = specToPatchLines(target);\n    setLoading(true);\n\n    void (async () => {\n      for (const line of lines) {\n        if (cancelled) return;\n        const { result } = compiler.push(`${line}\\n`);\n        setSpec({ ...result });\n        if (intervalMs > 0) {\n          await new Promise((r) => setTimeout(r, intervalMs));\n        }\n      }\n      if (cancelled) return;\n      setSpec(compiler.getResult());\n      setLoading(false);\n    })();\n\n    return () => {\n      cancelled = true;\n    };\n  }, [target, intervalMs]);\n\n  return { spec, state: spec?.state, loading };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,SAAS,qBAAqB;AAC9B,SAA4B,sBAAsB;AAyB3C,IAAM,sBAAoC,CAAC,MAAM,QAAQ,QAAQ;AACtE,MAAI,SAAS,MAAO;AACpB,QAAM,SAAS,QAAQ;AACvB,QAAM,OAAO,OAAO,WAAW,WAAW,SAAS;AACnD,MAAI,MAAM;AACR,SAAK,IAAI,YAAY,EAAE,MAAM,QAAQ,SAAS,CAAC,EAAE,MAAM,QAAQ,KAAK,CAAC,EAAE,CAAC;AAAA,EAC1E;AACF;AAaO,SAAS,iBACd,UACA,YACsC;AACtC,SAAO;AACT;AA+BO,SAAS,qBACd,SACS;AACT,QAAM,EAAE,SAAS,YAAY,WAAW,qBAAqB,GAAG,QAAQ,IAAI;AAC5E,QAAM,WAAW,eAAe,SAAS,UAAU;AAEnD,WAAS,iBAAiB;AACxB,UAAM,MAAM,UAAU;AACtB,UAAM,SAAS,cAA+B;AAC9C,UAAM,OAAO,QAAQ,mBAAmB,QAAQ;AAChD,QAAI,CAAC,KAAM,QAAO;AAClB,WAAO,cAAc,UAAU;AAAA,MAC7B;AAAA,MACA,OAAO,KAAK;AAAA,MACZ,UAAU,CAAC,MAAc,WAAqC,SAAS,MAAM,QAAQ,GAAG;AAAA,IAC1F,CAAC;AAAA,EACH;AAEA,SAAO,cAAc,gBAAgB,OAAO;AAC9C;;;AC1EA,SAAS,kBAAAA,uBAAsB;;;AC3B/B,SAAS,WAAW,gBAAgB;AAEpC,SAAS,4BAAAC,iCAAgC;AA6BlC,SAAS,cACd,QACA,UAAgC,CAAC,GAChB;AACjB,QAAM,EAAE,aAAa,GAAG,IAAI;AAC5B,QAAM,CAAC,MAAM,OAAO,IAAI,SAAsB,IAAI;AAClD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,KAAK;AAE5C,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ;AACX,cAAQ,IAAI;AACZ,iBAAW,KAAK;AAChB;AAAA,IACF;AACA,QAAI,YAAY;AAChB,UAAM,WAAWC,0BAA+B;AAChD,UAAM,QAAQ,iBAAiB,MAAM;AACrC,eAAW,IAAI;AAEf,UAAM,YAAY;AAChB,iBAAW,QAAQ,OAAO;AACxB,YAAI,UAAW;AACf,cAAM,EAAE,OAAO,IAAI,SAAS,KAAK,GAAG,IAAI;AAAA,CAAI;AAC5C,gBAAQ,EAAE,GAAG,OAAO,CAAC;AACrB,YAAI,aAAa,GAAG;AAClB,gBAAM,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAAA,QACpD;AAAA,MACF;AACA,UAAI,UAAW;AACf,cAAQ,SAAS,UAAU,CAAC;AAC5B,iBAAW,KAAK;AAAA,IAClB,GAAG;AAEH,WAAO,MAAM;AACX,kBAAY;AAAA,IACd;AAAA,EACF,GAAG,CAAC,QAAQ,UAAU,CAAC;AAEvB,SAAO,EAAE,MAAM,OAAO,MAAM,OAAO,QAAQ;AAC7C;;;ADZA,SAAS,WAAW,mBAAmB;","names":["createRenderer","createSpecStreamCompiler","createSpecStreamCompiler"]}
+{"version":3,"sources":["../../src/json-render/generative-view.tsx","../../src/json-render/index.ts","../../src/json-render/use-spec-stream.ts"],"sourcesContent":["import { createElement } from \"react\";\nimport { type ComponentMap, createRenderer } from \"@json-render/react\";\nimport type { Catalog, SchemaDefinition, Spec } from \"@json-render/core\";\nimport { createMcpView, useMcpApp, useToolResult } from \"../react/index.js\";\nimport type { App } from \"@modelcontextprotocol/ext-apps\";\nimport type { AdapterOptions } from \"mountly/adapter\";\nimport type { McpView } from \"../types.js\";\n\n/** The catalog-data constraint createRenderer infers against. */\ntype CatalogData = { components: Record<string, { props: unknown }> };\n\n/**\n * Route a generated UI's actions back to the MCP host. Called with the action\n * name, its (resolved) params, and the view-side `App` handle.\n */\nexport type ActionRouter = (\n  name: string,\n  params: Record<string, unknown> | undefined,\n  mcp: App,\n) => void;\n\n/**\n * Default router: an `ask` action with a string `prompt` param sends a\n * follow-up user turn to the model via `App.sendMessage`. This is the agent\n * loop json-render alone cannot do — it has no concept of an MCP host.\n */\nexport const defaultActionRouter: ActionRouter = (name, params, mcp) => {\n  if (name !== \"ask\") return;\n  const prompt = params?.prompt;\n  const text = typeof prompt === \"string\" ? prompt : \"\";\n  if (text) {\n    void mcp.sendMessage({ role: \"user\", content: [{ type: \"text\", text }] });\n  }\n};\n\n/**\n * Identity helper that types a components map against a catalog (so it can be\n * defined once and reused by both `createGenerativeView` and `createRenderer`)\n * without losing per-component prop inference.\n *\n * ```ts\n * export const components = defineComponents(catalog, {\n *   Metric: ({ element }) => <span>{element.props.value}</span>,\n * });\n * ```\n */\nexport function defineComponents<TDef extends SchemaDefinition, TCatalog extends CatalogData>(\n  _catalog: Catalog<TDef, TCatalog>,\n  components: ComponentMap<TCatalog[\"components\"]>,\n): ComponentMap<TCatalog[\"components\"]> {\n  return components;\n}\n\nexport interface GenerativeViewOptions<\n  TDef extends SchemaDefinition,\n  TCatalog extends CatalogData,\n> extends AdapterOptions {\n  /** The json-render catalog — the vocabulary the agent may compose. */\n  catalog: Catalog<TDef, TCatalog>;\n  /** Native component implementations for each catalog type. */\n  components: ComponentMap<TCatalog[\"components\"]>;\n  /**\n   * How a generated UI's actions reach the agent. Defaults to\n   * {@link defaultActionRouter} (`ask` → `App.sendMessage`).\n   */\n  onAction?: ActionRouter;\n}\n\ninterface ToolResultShape {\n  structuredContent?: { spec?: Spec };\n}\n\n/**\n * Turn a json-render catalog + components into a mountly MCP Apps View.\n *\n * Reads the spec from the tool result, renders it natively (resolving `$state`\n * from `spec.state`), and routes actions back to the MCP host.\n *\n * ```ts\n * createGenerativeView({ catalog, components, styles, shadow: true });\n * ```\n */\nexport function createGenerativeView<TDef extends SchemaDefinition, TCatalog extends CatalogData>(\n  options: GenerativeViewOptions<TDef, TCatalog>,\n): McpView {\n  const { catalog, components, onAction = defaultActionRouter, ...adapter } = options;\n  const Rendered = createRenderer(catalog, components);\n\n  function GenerativeView() {\n    const mcp = useMcpApp();\n    const result = useToolResult<ToolResultShape>();\n    const spec = result?.structuredContent?.spec ?? null;\n    if (!spec) return null;\n    return createElement(Rendered, {\n      spec,\n      state: spec.state,\n      onAction: (name: string, params?: Record<string, unknown>) => onAction(name, params, mcp),\n    });\n  }\n\n  return createMcpView(GenerativeView, adapter);\n}\n","export {\n  type ActionRouter,\n  type GenerativeViewOptions,\n  createGenerativeView,\n  defaultActionRouter,\n  defineComponents,\n} from \"./generative-view.js\";\nexport {\n  type JsonRenderToolOptions,\n  type RegisterJsonRenderResourceOptions,\n  type RegisterJsonRenderToolOptions,\n  type CreateJsonRenderMcpAppOptions,\n  createJsonRenderMcpApp,\n  registerJsonRenderTool,\n  registerJsonRenderResource,\n} from \"./mcp.js\";\nexport {\n  type BuildAppHtmlOptions,\n  type UseJsonRenderAppOptions,\n  type UseJsonRenderAppReturn,\n  buildAppHtml,\n  useJsonRenderApp,\n} from \"./app.js\";\n\n// Convenience re-exports for rendering the same catalog natively (non-MCP) —\n// previews, tests, or a plain mountly feature. Pair with `mountly-react`'s\n// `createWidget` to mount a spec outside an MCP host.\nexport { createRenderer } from \"@json-render/react\";\nexport type { ComponentMap, ComponentRenderProps } from \"@json-render/react\";\n\n// Streaming primitives (json-render's own): replay a known spec as a patch\n// stream, compile patches back into a progressively-built spec, and the AI-SDK\n// transform that classifies a model's UI-message stream into spec patches.\nexport {\n  compileSpecStream,\n  compileTextStreamToSpecs,\n  createJsonRenderTransform,\n  createSpecStreamCompiler,\n  parseSpecStreamLine,\n  specToPatchLines,\n} from \"./spec-stream.js\";\nexport type { Spec } from \"@json-render/core\";\n\n// --- Two ways to stream ---\n//\n// Replay (known spec): `useSpecStream` takes a finished spec — e.g. the one an\n// MCP tool delivered as `structuredContent` — and replays it as a live build,\n// with the compiler, loading flag, and cancellation included.\nexport {\n  type SpecStreamState,\n  type UseSpecStreamOptions,\n  useSpecStream,\n} from \"./use-spec-stream.js\";\n\n// Live (from a model): `useUIStream` / `useChatUI` are json-render's own client\n// hooks — POST a prompt to an endpoint that streams JSONL patches (see\n// `streamSpec` in `mountly-mcp/json-render/server`) and render the spec as it\n// builds. Re-exported so the live path is one import away.\nexport { useChatUI, useUIStream } from \"@json-render/react\";\nexport type { UseUIStreamOptions, UseUIStreamReturn } from \"@json-render/react\";\n","import { useEffect, useState } from \"react\";\nimport type { Spec } from \"@json-render/core\";\nimport { createSpecStreamCompiler } from \"@json-render/core\";\nimport { specToPatchLines } from \"./spec-stream.js\";\n\nexport interface UseSpecStreamOptions {\n  /** Delay between patches, ms. Default 90. Set 0 to render instantly. */\n  intervalMs?: number;\n}\n\nexport interface SpecStreamState {\n  /** The progressively-built spec (partial while streaming, full when done). */\n  spec: Spec | null;\n  /** Convenience: `spec?.state`, to pass straight to the renderer. */\n  state: Record<string, unknown> | undefined;\n  /** True while patches are still being applied. */\n  loading: boolean;\n}\n\n/**\n * Replay a finished spec as a live json-render stream — and own all the\n * ceremony. Give it the target spec; it scaffolds a `createSpecStreamCompiler`,\n * replays the patches with a delay, exposes the partial spec + `loading` after\n * each step, and cancels cleanly when the target changes (so a self-driving UI\n * that swaps specs mid-stream just works). Re-streams whenever `target` changes.\n *\n * ```tsx\n * const { spec, state, loading } = useSpecStream(specs[view]);\n * return <Renderer spec={spec} state={state} loading={loading} onAction={...} />;\n * ```\n */\nexport function useSpecStream(\n  target: Spec | null | undefined,\n  options: UseSpecStreamOptions = {},\n): SpecStreamState {\n  const { intervalMs = 90 } = options;\n  const [spec, setSpec] = useState<Spec | null>(null);\n  const [loading, setLoading] = useState(false);\n\n  useEffect(() => {\n    if (!target) {\n      setSpec(null);\n      setLoading(false);\n      return;\n    }\n    let cancelled = false;\n    const compiler = createSpecStreamCompiler<Spec>();\n    const lines = specToPatchLines(target);\n    setLoading(true);\n\n    void (async () => {\n      for (const line of lines) {\n        if (cancelled) return;\n        const { result } = compiler.push(`${line}\\n`);\n        setSpec({ ...result });\n        if (intervalMs > 0) {\n          await new Promise((r) => setTimeout(r, intervalMs));\n        }\n      }\n      if (cancelled) return;\n      setSpec(compiler.getResult());\n      setLoading(false);\n    })();\n\n    return () => {\n      cancelled = true;\n    };\n  }, [target, intervalMs]);\n\n  return { spec, state: spec?.state, loading };\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,SAAS,qBAAqB;AAC9B,SAA4B,sBAAsB;AAyB3C,IAAM,sBAAoC,CAAC,MAAM,QAAQ,QAAQ;AACtE,MAAI,SAAS,MAAO;AACpB,QAAM,SAAS,QAAQ;AACvB,QAAM,OAAO,OAAO,WAAW,WAAW,SAAS;AACnD,MAAI,MAAM;AACR,SAAK,IAAI,YAAY,EAAE,MAAM,QAAQ,SAAS,CAAC,EAAE,MAAM,QAAQ,KAAK,CAAC,EAAE,CAAC;AAAA,EAC1E;AACF;AAaO,SAAS,iBACd,UACA,YACsC;AACtC,SAAO;AACT;AA+BO,SAAS,qBACd,SACS;AACT,QAAM,EAAE,SAAS,YAAY,WAAW,qBAAqB,GAAG,QAAQ,IAAI;AAC5E,QAAM,WAAW,eAAe,SAAS,UAAU;AAEnD,WAAS,iBAAiB;AACxB,UAAM,MAAM,UAAU;AACtB,UAAM,SAAS,cAA+B;AAC9C,UAAM,OAAO,QAAQ,mBAAmB,QAAQ;AAChD,QAAI,CAAC,KAAM,QAAO;AAClB,WAAO,cAAc,UAAU;AAAA,MAC7B;AAAA,MACA,OAAO,KAAK;AAAA,MACZ,UAAU,CAAC,MAAc,WAAqC,SAAS,MAAM,QAAQ,GAAG;AAAA,IAC1F,CAAC;AAAA,EACH;AAEA,SAAO,cAAc,gBAAgB,OAAO;AAC9C;;;AC1EA,SAAS,kBAAAA,uBAAsB;;;AC3B/B,SAAS,WAAW,gBAAgB;AAEpC,SAAS,4BAAAC,iCAAgC;AA6BlC,SAAS,cACd,QACA,UAAgC,CAAC,GAChB;AACjB,QAAM,EAAE,aAAa,GAAG,IAAI;AAC5B,QAAM,CAAC,MAAM,OAAO,IAAI,SAAsB,IAAI;AAClD,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,KAAK;AAE5C,YAAU,MAAM;AACd,QAAI,CAAC,QAAQ;AACX,cAAQ,IAAI;AACZ,iBAAW,KAAK;AAChB;AAAA,IACF;AACA,QAAI,YAAY;AAChB,UAAM,WAAWC,0BAA+B;AAChD,UAAM,QAAQ,iBAAiB,MAAM;AACrC,eAAW,IAAI;AAEf,UAAM,YAAY;AAChB,iBAAW,QAAQ,OAAO;AACxB,YAAI,UAAW;AACf,cAAM,EAAE,OAAO,IAAI,SAAS,KAAK,GAAG,IAAI;AAAA,CAAI;AAC5C,gBAAQ,EAAE,GAAG,OAAO,CAAC;AACrB,YAAI,aAAa,GAAG;AAClB,gBAAM,IAAI,QAAQ,CAAC,MAAM,WAAW,GAAG,UAAU,CAAC;AAAA,QACpD;AAAA,MACF;AACA,UAAI,UAAW;AACf,cAAQ,SAAS,UAAU,CAAC;AAC5B,iBAAW,KAAK;AAAA,IAClB,GAAG;AAEH,WAAO,MAAM;AACX,kBAAY;AAAA,IACd;AAAA,EACF,GAAG,CAAC,QAAQ,UAAU,CAAC;AAEvB,SAAO,EAAE,MAAM,OAAO,MAAM,OAAO,QAAQ;AAC7C;;;ADZA,SAAS,WAAW,mBAAmB;","names":["createRenderer","createSpecStreamCompiler","createSpecStreamCompiler"]}

package/dist/react/hooks.d.ts

@@ -1,5 +1,6 @@
 import { useAutoResize as useAutoResizeBase } from "@modelcontextprotocol/ext-apps/react";
 import type { App, McpUiDisplayMode, McpUiHostContext, McpUiUpdateModelContextRequest } from "@modelcontextprotocol/ext-apps";
+import { type DownloadableFile } from "../download.js";
 /** The view-side ext-apps App. Use this to call server tools, send messages, open links, etc. */
 export declare function useMcpApp(): App;
 /** Complete notification params; read the tool arguments from `.arguments`. */
@@ -42,5 +43,11 @@ export declare function useDocumentTheme(): import("@modelcontextprotocol/ext-ap
  * triggering an immediate response. Only the last update is kept.
  */
 export declare function useUpdateModelContext(): (params: McpUiUpdateModelContextRequest["params"]) => Promise<void>;
+/**
+ * Return a function that hands the user a file: through the host's
+ * `ui/download-file` where it has one, else an ordinary `<a download>`.
+ * Resolves `false` when the host declined or the user cancelled.
+ */
+export declare function useDownload(): (file: DownloadableFile) => Promise<boolean>;
 /** Manually control auto-resize (rarely needed — the bridge calls setupSizeChangedNotifications by default). */
 export declare function useAutoResize(...args: Parameters<typeof useAutoResizeBase>): void;

package/dist/react/index.js

@@ -3,6 +3,7 @@ import {
   useAutoResize,
   useDisplayMode,
   useDocumentTheme,
+  useDownload,
   useHostContext,
   useHostFonts,
   useHostStyleVariables,
@@ -13,10 +14,11 @@ import {
   useToolInputPartial,
   useToolResult,
   useUpdateModelContext
-} from "../chunk-HIAIQVK5.js";
+} from "../chunk-QIA76O6M.js";
 import {
   McpContext
 } from "../chunk-4SZHJ4MK.js";
+import "../chunk-BLT2MK32.js";
 import "../chunk-5L3QHYWK.js";
 export {
   McpContext,
@@ -24,6 +26,7 @@ export {
   useAutoResize,
   useDisplayMode,
   useDocumentTheme,
+  useDownload,
   useHostContext,
   useHostFonts,
   useHostStyleVariables,

package/dist/server/core.d.ts

@@ -0,0 +1,84 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+import { EXTENSION_ID, RESOURCE_MIME_TYPE, type McpUiAppToolConfig } from "@modelcontextprotocol/ext-apps/server";
+import type { McpUiToolVisibility } from "@modelcontextprotocol/ext-apps";
+import { type McpAppArtifact, type McpAppSource } from "../artifact/declaration.js";
+export interface McpAppToolResult {
+    structuredContent?: unknown;
+    content?: ReadonlyArray<{
+        type: string;
+        [key: string]: unknown;
+    }>;
+    isError?: boolean;
+}
+/** Complete official tool configuration, plus JSON Schema support at Mountly's seam. */
+export interface McpAppToolConfig extends Omit<McpUiAppToolConfig, "_meta" | "inputSchema" | "outputSchema"> {
+    inputSchema?: object;
+    outputSchema?: object;
+    /** Additional metadata is preserved; Mountly only merges `_meta.ui`. */
+    _meta?: Record<string, unknown>;
+}
+/** A View is independent of the tools that reference it. */
+export interface McpAppViewRegistration {
+    /**
+     * Built artifact or the path to its self-contained HTML — or, on a runtime
+     * with no filesystem such as Cloudflare Workers, the View itself, as
+     * `mountly-mcp.views.js` exports it.
+     */
+    artifact: McpAppArtifact | McpAppSource | string;
+    /** Optional assertion used by migration adapters; artifacts already own identity. */
+    uri?: string;
+}
+/** A tool links to a separately declared View through the protocol resource URI. */
+export interface McpAppToolRegistration<Args = unknown> {
+    name: string;
+    resourceUri: string;
+    config?: McpAppToolConfig;
+    /** Convenience override for `_meta.ui.visibility`. */
+    visibility?: McpUiToolVisibility | ReadonlyArray<McpUiToolVisibility>;
+    handler: (args: Args, extra?: unknown) => Promise<McpAppToolResult>;
+}
+export interface RegisterMcpAppsOptions {
+    views: ReadonlyArray<McpAppViewRegistration>;
+    tools?: ReadonlyArray<McpAppToolRegistration>;
+}
+/**
+ * `createMcpAppServer` declares Views and tools exactly as `registerMcpApps`
+ * does; it only owns the `McpServer` for you. One vocabulary, two entry points.
+ */
+export interface CreateMcpAppServerOptions extends RegisterMcpAppsOptions {
+    name: string;
+    version: string;
+}
+export interface RegisteredMcpApps {
+    /** File-backed Views carry `htmlPath`; in-memory ones carry `html`. */
+    artifacts: ReadonlyArray<McpAppArtifact | McpAppSource>;
+    /** Remove every resource and tool installed by this registration. */
+    remove(): void;
+}
+/** Reads a View from disk. Only the Node entry installs one; a Worker has no disk. */
+export type DiskViewLoader = (artifact: McpAppArtifact | string, uri: string | undefined) => Promise<{
+    artifact: McpAppArtifact;
+    html: string;
+}>;
+/** @internal Called once by the Node entry. */
+export declare function installDiskViewLoader(loader: DiskViewLoader): void;
+/**
+ * Install Mountly Views and their independently declared tools into an existing,
+ * unconnected MCP server. The caller retains ownership of identity, auth,
+ * transports, prompts, ordinary tools, and deployment.
+ */
+export declare function registerMcpApps(server: McpServer, options: RegisterMcpAppsOptions): Promise<RegisteredMcpApps>;
+export interface RunningMcpAppServer {
+    connectInProcess(options?: {
+        ui?: boolean;
+    }): Promise<{
+        client: Client;
+    }>;
+    listen(transport: Transport): Promise<void>;
+    close(): Promise<void>;
+}
+/** Convenience adapter that retains the original one-call server experience. */
+export declare function createMcpAppServer(options: CreateMcpAppServerOptions): RunningMcpAppServer;
+export { EXTENSION_ID, RESOURCE_MIME_TYPE };