@maxhealth.tech/prefab 0.3.5 → 0.3.7

package/dist/mcp/resource.d.ts

@@ -0,0 +1,250 @@
+/**
+ * MCP Apps resource helpers — register the prefab viewer as a `ui://` resource.
+ *
+ * Covers the three things every MCP Apps host checks and the two the
+ * 2026-07-28 protocol revision added:
+ *   - the `text/html;profile=mcp-app` MIME type,
+ *   - `_meta.ui` CSP / permissions on BOTH the listing and the content item,
+ *   - the viewer HTML itself (CDN-pinned to this exact package version),
+ *   - `ttlMs` / `cacheScope` on the read result (SEP-2549 `CacheableResult`),
+ *   - the `io.modelcontextprotocol/ui` extension capability (SEP-2133).
+ */
+import type { McpCacheHint, McpResourceReadResult, McpTextResourceContents } from './types.js';
+import { type ThemeBridge } from './theme-bridge.js';
+/** CSP configuration for MCP Apps resources. */
+export interface McpAppCsp {
+    /** Origins allowed for scripts, styles, images, fonts, media. */
+    resourceDomains?: string[];
+    /** Origins allowed for fetch/XHR/WebSocket. */
+    connectDomains?: string[];
+    /** Origins allowed for nested iframes. */
+    frameDomains?: string[];
+    /** Additional allowed base URIs. */
+    baseUriDomains?: string[];
+}
+/** Permission Policy requests for MCP Apps resources. */
+export interface McpAppPermissions {
+    /** Request camera access (video capture, QR scanning). */
+    camera?: boolean;
+    /** Request microphone access (audio recording, voice input). */
+    microphone?: boolean;
+    /** Request geolocation access (location-aware apps, maps). */
+    geolocation?: boolean;
+    /** Request clipboard write access (copy-to-clipboard). */
+    clipboardWrite?: boolean;
+}
+export interface ResourceMetaOptions {
+    /** CSP domains configuration. */
+    csp?: McpAppCsp;
+    /** Permission Policy requests (camera, mic, etc.). */
+    permissions?: McpAppPermissions;
+}
+/** Spec-compliant permissions shape: each granted permission is `{}`. */
+interface McpAppPermissionsWire {
+    camera?: Record<string, never>;
+    microphone?: Record<string, never>;
+    geolocation?: Record<string, never>;
+    clipboardWrite?: Record<string, never>;
+}
+/**
+ * Generate the `_meta` object for MCP Apps `ui://` resource registration.
+ *
+ * Includes CSP and Permission Policy configuration per the MCP Apps spec.
+ * Use on both the resource listing AND the content item (VS Code reads
+ * only the content item; other hosts may read either).
+ *
+ * @example
+ * ```ts
+ * const meta = resourceMeta({
+ *   csp: { resourceDomains: ['https://cdn.jsdelivr.net'] },
+ *   permissions: { camera: true },
+ * })
+ *
+ * server.registerResource('viewer', 'ui://my/viewer', {
+ *   mimeType: 'text/html;profile=mcp-app',
+ *   _meta: meta,
+ *   cacheHint: { ttlMs: 86_400_000, cacheScope: 'public' },
+ * }, (uri) => Promise.resolve({
+ *   contents: [{ uri: uri.toString(), mimeType: 'text/html;profile=mcp-app', text: html, _meta: meta }],
+ *   ttlMs: 86_400_000,
+ *   cacheScope: 'public',
+ * }))
+ *
+ * // The UI resource is associated with a tool on the tool DEFINITION, not
+ * // on its result:
+ * server.registerTool('browse', {
+ *   title: 'Browse',
+ *   inputSchema: schema,
+ *   _meta: { ui: { resourceUri: 'ui://my/viewer' } },
+ * }, (args) => display(autoTable(rows)))
+ * ```
+ */
+export declare function resourceMeta(options?: ResourceMetaOptions): {
+    ui: {
+        csp?: McpAppCsp;
+        permissions?: McpAppPermissionsWire;
+    };
+};
+/** Default CSP meta for prefab apps using jsDelivr CDN. */
+export declare const PREFAB_CDN_META: {
+    ui: {
+        csp?: McpAppCsp;
+        permissions?: McpAppPermissionsWire;
+    };
+};
+/** Default URI for the prefab viewer resource. */
+export declare const PREFAB_RESOURCE_URI = "ui://prefab/viewer";
+/** MIME type required by MCP Apps hosts. */
+export declare const MCP_APP_MIME = "text/html;profile=mcp-app";
+/**
+ * Capability key for the MCP Apps extension (versioned independently of core).
+ *
+ * The identifier is `…/ui`, and the trap here is that `…/apps` looks right and is
+ * wrong. The normative source is the MCP Apps spec, which states "This extension is
+ * identified as: `io.modelcontextprotocol/ui`" in both the current `2026-01-26`
+ * revision and the draft, and the reference implementation agrees:
+ * `ext-apps/src/server/index.ts` exports `EXTENSION_ID = "io.modelcontextprotocol/ui"`.
+ *
+ * `io.modelcontextprotocol/apps` appears only as illustrative "e.g." text in the Rust
+ * and C# SDKs' generic `ServerCapabilities.extensions` doc comments (and their test
+ * fixtures), showing the SHAPE of the extensions map rather than naming this extension.
+ * Copying it from there declares the capability under a key no host looks up, which
+ * fails silently: rendering still works, because hosts fall back to detecting apps via
+ * `_meta.ui` plus the MIME type, so only the SEP-2133 declaration is lost.
+ *
+ * Duplicated as a literal rather than imported, because prefab ships zero dependencies.
+ */
+export declare const APPS_EXTENSION = "io.modelcontextprotocol/ui";
+/**
+ * Default cache hint for the viewer resource.
+ *
+ * The HTML is a pure function of this package's `VERSION` (the CDN base pins
+ * the exact version), so it cannot change for a given server build — it is
+ * safely shared-cacheable. Without this the SDK falls back to the conservative
+ * `{ ttlMs: 0, cacheScope: 'private' }` and the viewer is re-fetched every time.
+ */
+export declare const DEFAULT_VIEWER_CACHE: Required<McpCacheHint>;
+export interface RendererHtmlOptions {
+    /** Page title. @default 'Prefab' */
+    title?: string;
+    /** Additional `<script>` URLs to load after the renderer. */
+    scripts?: string[];
+    /** Additional `<link rel="stylesheet">` URLs. */
+    stylesheets?: string[];
+    /** Override CDN base URL (no trailing slash). @default jsdelivr CDN */
+    cdnBase?: string;
+    /**
+     * Inject a theme bridge stylesheet after `prefab.css`.
+     *
+     * `'vscode'` re-declares the tokens VS Code can supply with the
+     * `--vscode-*` variable first, dropping the MCP Apps `--color-*` layer that
+     * would otherwise shadow it, so the viewer follows the user's editor theme.
+     * Emitted before `stylesheets`, which stay the outermost override.
+     */
+    themeBridge?: ThemeBridge;
+}
+/**
+ * Generate the HTML page for a prefab MCP Apps viewer resource.
+ *
+ * Returns the minimal HTML that loads `prefab.css` and `renderer.auto.min.js`
+ * from the CDN, plus any additional scripts/stylesheets you specify.
+ *
+ * @example
+ * ```ts
+ * import { rendererHtml } from '@maxhealth.tech/prefab/mcp'
+ * const html = rendererHtml()
+ * // or with extra scripts:
+ * const html = rendererHtml({ scripts: ['https://cdn.example.com/plugin.js'] })
+ * // inside VS Code, to follow the user's editor theme:
+ * const html = rendererHtml({ themeBridge: 'vscode' })
+ * ```
+ */
+export declare function rendererHtml(options?: RendererHtmlOptions): string;
+export interface ViewerResourceOptions {
+    /** Resource URI. @default PREFAB_RESOURCE_URI */
+    uri?: string;
+    /** Resource title. @default 'Prefab Viewer' */
+    title?: string;
+    /** CSP configuration. @default { resourceDomains: ['https://cdn.jsdelivr.net'] } */
+    csp?: McpAppCsp;
+    /** Permission Policy requests. */
+    permissions?: McpAppPermissions;
+    /** Additional `<script>` URLs to load after the renderer. */
+    scripts?: string[];
+    /** Additional `<link rel="stylesheet">` URLs. */
+    stylesheets?: string[];
+    /** Override CDN base URL (no trailing slash). */
+    cdnBase?: string;
+    /**
+     * Inject a theme bridge stylesheet. `'vscode'` makes the viewer follow the
+     * user's editor theme. See {@link RendererHtmlOptions.themeBridge}.
+     */
+    themeBridge?: ThemeBridge;
+    /**
+     * Cache fields for the `resources/read` result (SEP-2549).
+     * @default { ttlMs: 86_400_000, cacheScope: 'public' }
+     */
+    cache?: McpCacheHint;
+    /**
+     * Declare the `io.modelcontextprotocol/ui` extension capability on the
+     * server (SEP-2133). Must happen before the server connects; a server that
+     * is already connected keeps its existing capabilities and a warning is
+     * logged. @default true
+     */
+    declareCapability?: boolean;
+}
+/** Registration config accepted by both SDK generations. */
+export interface ResourceConfig {
+    title?: string;
+    mimeType: string;
+    description?: string;
+    _meta?: Record<string, unknown>;
+    /** Per-resource cache hint (SDK v2; ignored by servers that do not read it). */
+    cacheHint?: McpCacheHint;
+}
+/** `resources/read` handler shape passed to the server — the viewer is always HTML text. */
+export type ResourceReadHandler = (uri: URL) => Promise<McpResourceReadResult<McpTextResourceContents>>;
+/** Capability bag carrying extension declarations. */
+interface CapabilityDeclaration {
+    extensions?: Record<string, Record<string, unknown>>;
+}
+/**
+ * MCP server interface expected by registerViewerResource.
+ *
+ * Structural rather than an SDK import, so fastmcp and hand-rolled servers stay
+ * compatible. `registerResource` is preferred; `resource` is the v1 overload
+ * that v2 retired and is used only as a fallback.
+ */
+export interface McpServerLike {
+    registerResource?(name: string, uri: string, config: ResourceConfig, handler: ResourceReadHandler): unknown;
+    resource?(name: string, uri: string, config: ResourceConfig, handler: ResourceReadHandler): unknown;
+    /** Low-level server, where both SDK generations expose capability registration. */
+    server?: {
+        registerCapabilities?(capabilities: CapabilityDeclaration): void;
+    };
+    /** Some wrappers expose capability registration directly. */
+    registerCapabilities?(capabilities: CapabilityDeclaration): void;
+}
+/**
+ * Register the prefab viewer as a `ui://` resource on an MCP server.
+ *
+ * Handles the MIME type, CSP on both listing and content item, HTML generation,
+ * the `CacheableResult` fields and the Apps extension capability in one call.
+ *
+ * @example
+ * ```ts
+ * import { registerViewerResource, PREFAB_RESOURCE_URI, display } from '@maxhealth.tech/prefab/mcp'
+ *
+ * registerViewerResource(server)
+ *
+ * // The UI resource is attached to the tool DEFINITION via _meta.ui:
+ * server.registerTool('browse', {
+ *   title: 'Browse patients',
+ *   inputSchema: { query: z.string() },
+ *   _meta: { ui: { resourceUri: PREFAB_RESOURCE_URI } },
+ * }, async (args) => display(autoTable(await search(args.query))))
+ * ```
+ */
+export declare function registerViewerResource(server: McpServerLike, options?: ViewerResourceOptions): void;
+export {};
+//# sourceMappingURL=resource.d.ts.map

package/dist/mcp/resource.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.d.ts","sourceRoot":"","sources":["../../src/mcp/resource.ts"],"names":[],"mappings":"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"}

package/dist/mcp/resource.js

@@ -0,0 +1,282 @@
+/**
+ * MCP Apps resource helpers — register the prefab viewer as a `ui://` resource.
+ *
+ * Covers the three things every MCP Apps host checks and the two the
+ * 2026-07-28 protocol revision added:
+ *   - the `text/html;profile=mcp-app` MIME type,
+ *   - `_meta.ui` CSP / permissions on BOTH the listing and the content item,
+ *   - the viewer HTML itself (CDN-pinned to this exact package version),
+ *   - `ttlMs` / `cacheScope` on the read result (SEP-2549 `CacheableResult`),
+ *   - the `io.modelcontextprotocol/ui` extension capability (SEP-2133).
+ */
+import { VERSION } from '../app.js';
+import { createLogger } from '../core/logger.js';
+import { themeBridgeCss } from './theme-bridge.js';
+const log = createLogger('mcp');
+/**
+ * Generate the `_meta` object for MCP Apps `ui://` resource registration.
+ *
+ * Includes CSP and Permission Policy configuration per the MCP Apps spec.
+ * Use on both the resource listing AND the content item (VS Code reads
+ * only the content item; other hosts may read either).
+ *
+ * @example
+ * ```ts
+ * const meta = resourceMeta({
+ *   csp: { resourceDomains: ['https://cdn.jsdelivr.net'] },
+ *   permissions: { camera: true },
+ * })
+ *
+ * server.registerResource('viewer', 'ui://my/viewer', {
+ *   mimeType: 'text/html;profile=mcp-app',
+ *   _meta: meta,
+ *   cacheHint: { ttlMs: 86_400_000, cacheScope: 'public' },
+ * }, (uri) => Promise.resolve({
+ *   contents: [{ uri: uri.toString(), mimeType: 'text/html;profile=mcp-app', text: html, _meta: meta }],
+ *   ttlMs: 86_400_000,
+ *   cacheScope: 'public',
+ * }))
+ *
+ * // The UI resource is associated with a tool on the tool DEFINITION, not
+ * // on its result:
+ * server.registerTool('browse', {
+ *   title: 'Browse',
+ *   inputSchema: schema,
+ *   _meta: { ui: { resourceUri: 'ui://my/viewer' } },
+ * }, (args) => display(autoTable(rows)))
+ * ```
+ */
+export function resourceMeta(options) {
+    const ui = {};
+    if (options?.csp) {
+        ui.csp = {
+            resourceDomains: options.csp.resourceDomains ?? [],
+            connectDomains: options.csp.connectDomains ?? [],
+            frameDomains: options.csp.frameDomains ?? [],
+            baseUriDomains: options.csp.baseUriDomains ?? [],
+        };
+    }
+    if (options?.permissions) {
+        ui.permissions = {};
+        if (options.permissions.camera)
+            ui.permissions.camera = {};
+        if (options.permissions.microphone)
+            ui.permissions.microphone = {};
+        if (options.permissions.geolocation)
+            ui.permissions.geolocation = {};
+        if (options.permissions.clipboardWrite)
+            ui.permissions.clipboardWrite = {};
+    }
+    return { ui };
+}
+/** Default CSP meta for prefab apps using jsDelivr CDN. */
+export const PREFAB_CDN_META = resourceMeta({
+    csp: { resourceDomains: ['https://cdn.jsdelivr.net'] },
+});
+// ── Constants ────────────────────────────────────────────────────────────────
+/** Default URI for the prefab viewer resource. */
+export const PREFAB_RESOURCE_URI = 'ui://prefab/viewer';
+/** MIME type required by MCP Apps hosts. */
+export const MCP_APP_MIME = 'text/html;profile=mcp-app';
+/**
+ * Capability key for the MCP Apps extension (versioned independently of core).
+ *
+ * The identifier is `…/ui`, and the trap here is that `…/apps` looks right and is
+ * wrong. The normative source is the MCP Apps spec, which states "This extension is
+ * identified as: `io.modelcontextprotocol/ui`" in both the current `2026-01-26`
+ * revision and the draft, and the reference implementation agrees:
+ * `ext-apps/src/server/index.ts` exports `EXTENSION_ID = "io.modelcontextprotocol/ui"`.
+ *
+ * `io.modelcontextprotocol/apps` appears only as illustrative "e.g." text in the Rust
+ * and C# SDKs' generic `ServerCapabilities.extensions` doc comments (and their test
+ * fixtures), showing the SHAPE of the extensions map rather than naming this extension.
+ * Copying it from there declares the capability under a key no host looks up, which
+ * fails silently: rendering still works, because hosts fall back to detecting apps via
+ * `_meta.ui` plus the MIME type, so only the SEP-2133 declaration is lost.
+ *
+ * Duplicated as a literal rather than imported, because prefab ships zero dependencies.
+ */
+export const APPS_EXTENSION = 'io.modelcontextprotocol/ui';
+/**
+ * Default cache hint for the viewer resource.
+ *
+ * The HTML is a pure function of this package's `VERSION` (the CDN base pins
+ * the exact version), so it cannot change for a given server build — it is
+ * safely shared-cacheable. Without this the SDK falls back to the conservative
+ * `{ ttlMs: 0, cacheScope: 'private' }` and the viewer is re-fetched every time.
+ */
+export const DEFAULT_VIEWER_CACHE = {
+    ttlMs: 86_400_000, // 24h
+    cacheScope: 'public',
+};
+/**
+ * Runtime whitelist for {@link McpCacheScope}.
+ *
+ * Kept as a value (not just the union type) so the guard in `resolveCache` still
+ * rejects a bad scope handed over from untyped JS — a `!==` chain against the
+ * union narrows itself away and validates nothing.
+ */
+const CACHE_SCOPES = ['public', 'private'];
+/** CDN base for the @maxhealth.tech/prefab package (exact version, never stale). */
+function cdnBase() {
+    return `https://cdn.jsdelivr.net/npm/@maxhealth.tech/prefab@${VERSION}/dist`;
+}
+/**
+ * Generate the HTML page for a prefab MCP Apps viewer resource.
+ *
+ * Returns the minimal HTML that loads `prefab.css` and `renderer.auto.min.js`
+ * from the CDN, plus any additional scripts/stylesheets you specify.
+ *
+ * @example
+ * ```ts
+ * import { rendererHtml } from '@maxhealth.tech/prefab/mcp'
+ * const html = rendererHtml()
+ * // or with extra scripts:
+ * const html = rendererHtml({ scripts: ['https://cdn.example.com/plugin.js'] })
+ * // inside VS Code, to follow the user's editor theme:
+ * const html = rendererHtml({ themeBridge: 'vscode' })
+ * ```
+ */
+export function rendererHtml(options) {
+    const title = options?.title ?? 'Prefab';
+    const base = options?.cdnBase ?? cdnBase();
+    // Order in <head> is load-bearing: prefab.css, then the bridge (which must win
+    // over it), then the caller's stylesheets as the outermost override.
+    const bridge = options?.themeBridge
+        ? `  <style>\n${themeBridgeCss(options.themeBridge)}\n  </style>\n`
+        : '';
+    const extraStyles = (options?.stylesheets ?? [])
+        .map(url => `  <link rel="stylesheet" crossorigin href="${escapeAttr(url)}">`)
+        .join('\n');
+    const extraScripts = (options?.scripts ?? [])
+        .map(url => `  <script crossorigin src="${escapeAttr(url)}"></script>`)
+        .join('\n');
+    return `<!doctype html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <meta name="viewport" content="width=device-width, initial-scale=1.0">
+  <title>${escapeHtml(title)}</title>
+  <link rel="stylesheet" crossorigin href="${base}/prefab.css">
+${bridge}${extraStyles}</head>
+<body>
+  <div id="root"></div>
+  <script crossorigin src="${base}/renderer.auto.min.js"></script>
+${extraScripts}</body>
+</html>`;
+}
+/** Reject values the SDK would silently discard in favour of `ttlMs: 0`. */
+function resolveCache(hint) {
+    const ttlMs = hint?.ttlMs ?? DEFAULT_VIEWER_CACHE.ttlMs;
+    if (!Number.isSafeInteger(ttlMs) || ttlMs < 0) {
+        throw new RangeError(`cache.ttlMs must be a non-negative safe integer, got ${String(hint?.ttlMs)}`);
+    }
+    const cacheScope = hint?.cacheScope ?? DEFAULT_VIEWER_CACHE.cacheScope;
+    if (!CACHE_SCOPES.includes(cacheScope)) {
+        throw new RangeError(`cache.cacheScope must be 'public' or 'private', got ${String(hint?.cacheScope)}`);
+    }
+    return { ttlMs, cacheScope };
+}
+/** Declare the MCP Apps extension capability, tolerating servers that cannot. */
+function declareAppsExtension(server) {
+    // Not named `declare` — that is a TS modifier keyword at statement position
+    // and some transpilers refuse to parse a call to a binding of that name.
+    const declareCaps = server.registerCapabilities?.bind(server)
+        ?? server.server?.registerCapabilities?.bind(server.server);
+    if (declareCaps == null)
+        return;
+    try {
+        declareCaps({ extensions: { [APPS_EXTENSION]: {} } });
+    }
+    catch (e) {
+        // Both SDK generations throw when called after connect. The server still
+        // serves the resource — it just does not advertise the extension.
+        log.warn(`could not declare the ${APPS_EXTENSION} capability (register the viewer before connecting):`, e);
+    }
+}
+/**
+ * Register the prefab viewer as a `ui://` resource on an MCP server.
+ *
+ * Handles the MIME type, CSP on both listing and content item, HTML generation,
+ * the `CacheableResult` fields and the Apps extension capability in one call.
+ *
+ * @example
+ * ```ts
+ * import { registerViewerResource, PREFAB_RESOURCE_URI, display } from '@maxhealth.tech/prefab/mcp'
+ *
+ * registerViewerResource(server)
+ *
+ * // The UI resource is attached to the tool DEFINITION via _meta.ui:
+ * server.registerTool('browse', {
+ *   title: 'Browse patients',
+ *   inputSchema: { query: z.string() },
+ *   _meta: { ui: { resourceUri: PREFAB_RESOURCE_URI } },
+ * }, async (args) => display(autoTable(await search(args.query))))
+ * ```
+ */
+export function registerViewerResource(server, options) {
+    const uri = options?.uri ?? PREFAB_RESOURCE_URI;
+    const title = options?.title ?? 'Prefab Viewer';
+    const cache = resolveCache(options?.cache);
+    // Merge CSP: always include jsdelivr for the default renderer
+    const csp = options?.csp
+        ? {
+            resourceDomains: [...new Set([...(options.csp.resourceDomains ?? []), 'https://cdn.jsdelivr.net'])],
+            connectDomains: options.csp.connectDomains ?? [],
+            frameDomains: options.csp.frameDomains ?? [],
+            baseUriDomains: options.csp.baseUriDomains ?? [],
+        }
+        : { resourceDomains: ['https://cdn.jsdelivr.net'] };
+    // Add script origins to CSP resourceDomains
+    if (options?.scripts && options.scripts.length > 0) {
+        const scriptOrigins = options.scripts
+            .map(url => { try {
+            return new URL(url).origin;
+        }
+        catch {
+            return null;
+        } })
+            .filter((o) => o !== null);
+        csp.resourceDomains = [...new Set([...(csp.resourceDomains ?? []), ...scriptOrigins])];
+    }
+    const meta = resourceMeta({ csp, permissions: options?.permissions });
+    const html = rendererHtml({
+        title,
+        scripts: options?.scripts,
+        stylesheets: options?.stylesheets,
+        cdnBase: options?.cdnBase,
+        themeBridge: options?.themeBridge,
+    });
+    if (options?.declareCapability !== false)
+        declareAppsExtension(server);
+    // Extract name from URI: 'ui://prefab/viewer' -> 'prefab-viewer'
+    const name = uri.replace(/^ui:\/\//, '').replace(/\//g, '-');
+    const config = { title, mimeType: MCP_APP_MIME, _meta: meta, cacheHint: cache };
+    const handler = (resourceUri) => Promise.resolve({
+        contents: [{
+                uri: resourceUri.toString(),
+                mimeType: MCP_APP_MIME,
+                text: html,
+                _meta: meta,
+            }],
+        // Handler-provided cache fields take precedence over any server hint, and
+        // make the result spec-compliant on servers that fill in nothing.
+        ttlMs: cache.ttlMs,
+        cacheScope: cache.cacheScope,
+    });
+    // registerResource is the current API in both SDK generations; resource() is
+    // the v1 overload that v2 dropped.
+    const register = server.registerResource?.bind(server) ?? server.resource?.bind(server);
+    if (register == null) {
+        throw new TypeError('registerViewerResource: server exposes neither registerResource() nor resource()');
+    }
+    register(name, uri, config, handler);
+}
+// ── HTML escaping helpers ────────────────────────────────────────────────────
+function escapeHtml(s) {
+    return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+}
+function escapeAttr(s) {
+    return s.replace(/&/g, '&amp;').replace(/"/g, '&quot;');
+}
+//# sourceMappingURL=resource.js.map

package/dist/mcp/resource.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"resource.js","sourceRoot":"","sources":["../../src/mcp/resource.ts"],"names":[],"mappings":"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"}

package/dist/mcp/result.d.ts

@@ -0,0 +1,42 @@
+/**
+ * MCP tool-result envelope.
+ *
+ * Every prefab display helper returns the same shape: the wire JSON as a text
+ * content block plus `structuredContent` for MCP Apps hosts to hand to the
+ * iframe. Building that envelope in one place keeps the `display_*` builders
+ * identical by construction.
+ *
+ * `structuredContent` is typed through the generic rather than widened to
+ * `Record<string, unknown>`, so callers keep the wire type and no cast is
+ * needed anywhere (protocol revision 2026-07-28 loosened the field to any JSON
+ * value — SEP-2106).
+ *
+ * `resultType` (SEP-2322) is deliberately NOT set here. It is a wire-only
+ * discriminator owned by the SDK's protocol layer: `@modelcontextprotocol/server`
+ * stamps it at its 2026-era encode seam and strips it before results reach
+ * consumers, which is why its public result types do not declare it. The one
+ * handler-authored case is `resultType: 'input_required'` for multi-round-trip
+ * results — not something a display helper produces.
+ */
+import type { McpToolResult } from './types.js';
+export interface ToolResultOptions {
+    /** Flag the result as failed (hosts render it as a tool error). */
+    isError?: boolean;
+}
+/**
+ * Wrap a JSON payload as an MCP tool result.
+ *
+ * The payload is serialized into `content[0].text` (for hosts and models that
+ * read text) and passed through as `structuredContent` (for MCP Apps iframes,
+ * which receive it via `ui/notifications/tool-result`).
+ *
+ * @example
+ * ```ts
+ * import { toolResult } from '@maxhealth.tech/prefab/mcp'
+ *
+ * // Returning pre-built wire JSON from your own tool handler:
+ * return toolResult(wireJson)
+ * ```
+ */
+export declare function toolResult<T>(payload: T, options?: ToolResultOptions): McpToolResult<T>;
+//# sourceMappingURL=result.d.ts.map

package/dist/mcp/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../src/mcp/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,MAAM,WAAW,iBAAiB;IAChC,mEAAmE;IACnE,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,aAAa,CAAC,CAAC,CAAC,CAOvF"}

package/dist/mcp/result.js

@@ -0,0 +1,45 @@
+/**
+ * MCP tool-result envelope.
+ *
+ * Every prefab display helper returns the same shape: the wire JSON as a text
+ * content block plus `structuredContent` for MCP Apps hosts to hand to the
+ * iframe. Building that envelope in one place keeps the `display_*` builders
+ * identical by construction.
+ *
+ * `structuredContent` is typed through the generic rather than widened to
+ * `Record<string, unknown>`, so callers keep the wire type and no cast is
+ * needed anywhere (protocol revision 2026-07-28 loosened the field to any JSON
+ * value — SEP-2106).
+ *
+ * `resultType` (SEP-2322) is deliberately NOT set here. It is a wire-only
+ * discriminator owned by the SDK's protocol layer: `@modelcontextprotocol/server`
+ * stamps it at its 2026-era encode seam and strips it before results reach
+ * consumers, which is why its public result types do not declare it. The one
+ * handler-authored case is `resultType: 'input_required'` for multi-round-trip
+ * results — not something a display helper produces.
+ */
+/**
+ * Wrap a JSON payload as an MCP tool result.
+ *
+ * The payload is serialized into `content[0].text` (for hosts and models that
+ * read text) and passed through as `structuredContent` (for MCP Apps iframes,
+ * which receive it via `ui/notifications/tool-result`).
+ *
+ * @example
+ * ```ts
+ * import { toolResult } from '@maxhealth.tech/prefab/mcp'
+ *
+ * // Returning pre-built wire JSON from your own tool handler:
+ * return toolResult(wireJson)
+ * ```
+ */
+export function toolResult(payload, options) {
+    const result = {
+        content: [{ type: 'text', text: JSON.stringify(payload) }],
+        structuredContent: payload,
+    };
+    if (options?.isError)
+        result.isError = true;
+    return result;
+}
+//# sourceMappingURL=result.js.map

package/dist/mcp/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../src/mcp/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AASH;;;;;;;;;;;;;;GAcG;AACH,MAAM,UAAU,UAAU,CAAI,OAAU,EAAE,OAA2B;IACnE,MAAM,MAAM,GAAqB;QAC/B,OAAO,EAAE,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,EAAE,CAAC;QAC1D,iBAAiB,EAAE,OAAO;KAC3B,CAAA;IACD,IAAI,OAAO,EAAE,OAAO;QAAE,MAAM,CAAC,OAAO,GAAG,IAAI,CAAA;IAC3C,OAAO,MAAM,CAAA;AACf,CAAC"}