@hcu-lab.me/mcp-device 1.0.0

package/dist/ui/resources.d.ts

@@ -0,0 +1,28 @@
+export declare const FILE_PREVIEW_RESOURCE: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+};
+export declare const CONFIG_EDITOR_RESOURCE: {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+};
+export declare function getFilePreviewResourceText(): Promise<string>;
+export declare function getConfigEditorResourceText(): Promise<string>;
+export declare function listUiResources(): {
+    uri: string;
+    name: string;
+    description: string;
+    mimeType: string;
+}[];
+export declare function readUiResource(uri: string): Promise<{
+    contents: {
+        _meta?: Record<string, unknown> | undefined;
+        uri: string;
+        mimeType: string;
+        text: string;
+    }[];
+} | null>;

package/dist/ui/resources.js

@@ -0,0 +1,86 @@
+/**
+ * Server-side UI resource loading helpers for MCP responses. It resolves packaged UI assets, reads files safely, and exposes structured resource payloads to clients.
+ */
+import fs from 'fs/promises';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { CONFIG_EDITOR_RESOURCE_URI, FILE_PREVIEW_RESOURCE_URI } from './contracts.js';
+const UI_RESOURCE_MIME_TYPE = 'text/html;profile=mcp-app';
+export const FILE_PREVIEW_RESOURCE = {
+    uri: FILE_PREVIEW_RESOURCE_URI,
+    name: 'MCP Device File Preview',
+    description: 'Markdown-first preview surface for read_file structured content.',
+    mimeType: UI_RESOURCE_MIME_TYPE
+};
+export const CONFIG_EDITOR_RESOURCE = {
+    uri: CONFIG_EDITOR_RESOURCE_URI,
+    name: 'MCP Device Config Editor',
+    description: 'Interactive editor for MCP Device configuration values.',
+    mimeType: UI_RESOURCE_MIME_TYPE
+};
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+const DIST_FILE_PREVIEW_DIR = path.resolve(__dirname, 'file-preview');
+const DIST_CONFIG_EDITOR_DIR = path.resolve(__dirname, 'config-editor');
+function replaceOrThrow(source, pattern, replacement, context) {
+    if (!pattern.test(source)) {
+        throw new Error(`UI template is missing expected ${context}`);
+    }
+    return source.replace(pattern, () => replacement);
+}
+function inlineTemplateAssets(templateHtml, css, runtime) {
+    const safeCss = css.replace(/<\/style/gi, '<\\/style');
+    const safeRuntime = runtime.replace(/<\/script/gi, '<\\/script');
+    const cssInlined = replaceOrThrow(templateHtml, /<link[^>]*href=["']\.\/styles\.css["'][^>]*>/i, `<style>${safeCss}</style>`, 'styles.css link tag');
+    const runtimeInlined = replaceOrThrow(cssInlined, /<script[^>]*src=["']\.\/[^"']+["'][^>]*>\s*<\/script>/i, `<script>${safeRuntime}</script>`, 'runtime script tag');
+    if (/href=["']\.\/styles\.css["']/i.test(runtimeInlined) ||
+        /<script[^>]*src=["']\.\/[^"']+["']/i.test(runtimeInlined)) {
+        throw new Error('UI template still contains external static asset references after inlining');
+    }
+    return runtimeInlined;
+}
+async function readInlinedResourceHtml(distDir, runtimeFileName) {
+    const [templateHtml, css, runtime] = await Promise.all([
+        fs.readFile(path.join(distDir, 'index.html'), 'utf8'),
+        fs.readFile(path.join(distDir, 'styles.css'), 'utf8'),
+        fs.readFile(path.join(distDir, runtimeFileName), 'utf8')
+    ]);
+    return inlineTemplateAssets(templateHtml, css, runtime);
+}
+export async function getFilePreviewResourceText() {
+    return readInlinedResourceHtml(DIST_FILE_PREVIEW_DIR, 'preview-runtime.js');
+}
+export async function getConfigEditorResourceText() {
+    return readInlinedResourceHtml(DIST_CONFIG_EDITOR_DIR, 'config-editor-runtime.js');
+}
+const READABLE_UI_RESOURCES = {
+    [FILE_PREVIEW_RESOURCE_URI]: {
+        mimeType: FILE_PREVIEW_RESOURCE.mimeType,
+        getText: getFilePreviewResourceText
+    },
+    [CONFIG_EDITOR_RESOURCE_URI]: {
+        mimeType: CONFIG_EDITOR_RESOURCE.mimeType,
+        getText: getConfigEditorResourceText
+    }
+};
+export function listUiResources() {
+    return [FILE_PREVIEW_RESOURCE, CONFIG_EDITOR_RESOURCE];
+}
+export async function readUiResource(uri) {
+    const resource = READABLE_UI_RESOURCES[uri];
+    if (!resource) {
+        return null;
+    }
+    const resourceText = await resource.getText();
+    const resourceMeta = resource.getMeta?.();
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: resource.mimeType,
+                text: resourceText,
+                ...(resourceMeta ? { _meta: resourceMeta } : {})
+            }
+        ]
+    };
+}

package/dist/ui/shared/compact-row.d.ts

@@ -0,0 +1,11 @@
+interface RenderCompactRowOptions {
+    id?: string;
+    label: string;
+    filename?: string;
+    variant?: 'ready' | 'loading' | 'status';
+    expandable?: boolean;
+    expanded?: boolean;
+    interactive?: boolean;
+}
+export declare function renderCompactRow(options: RenderCompactRowOptions): string;
+export {};

package/dist/ui/shared/compact-row.js

@@ -0,0 +1,18 @@
+import { escapeHtml } from './escape-html.js';
+export function renderCompactRow(options) {
+    const variant = options.variant ?? 'ready';
+    const classNames = `compact-row compact-row--${variant}`;
+    const id = options.id ? ` id="${escapeHtml(options.id)}"` : '';
+    const interactive = options.interactive ?? variant === 'ready';
+    const role = interactive ? ' role="button" tabindex="0"' : '';
+    const ariaExpanded = typeof options.expanded === 'boolean'
+        ? ` aria-expanded="${String(options.expanded)}"`
+        : '';
+    const chevron = options.expandable
+        ? '<svg class="compact-chevron" viewBox="0 0 24 24" aria-hidden="true"><path d="M10 6l6 6-6 6z"/></svg>'
+        : '';
+    const filename = options.filename
+        ? `<span class="compact-filename">${escapeHtml(options.filename)}</span>`
+        : '';
+    return `<div class="${classNames}"${id}${role}${ariaExpanded}>${chevron}<span class="compact-label">${escapeHtml(options.label)}</span>${filename}</div>`;
+}

package/dist/ui/shared/escape-html.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Shared HTML escaping helper for UI string interpolation.
+ */
+export declare function escapeHtml(value: string): string;

package/dist/ui/shared/escape-html.js

@@ -0,0 +1,11 @@
+/**
+ * Shared HTML escaping helper for UI string interpolation.
+ */
+export function escapeHtml(value) {
+    return value
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}

package/dist/ui/shared/host-context.d.ts

@@ -0,0 +1,15 @@
+import { App } from '@modelcontextprotocol/ext-apps';
+export interface UiChromeState {
+    expanded: boolean;
+    hideSummaryRow: boolean;
+    compact?: boolean;
+}
+export interface ConnectWithSharedHostContextOptions {
+    app: App;
+    chrome: UiChromeState;
+    onContextApplied?: () => void;
+    onConnected?: () => void | Promise<void>;
+}
+export declare function isObjectRecord(value: unknown): value is Record<string, unknown>;
+export declare function applySharedHostContext(context: unknown, chrome: UiChromeState): void;
+export declare function connectWithSharedHostContext(options: ConnectWithSharedHostContextOptions): Promise<void>;

package/dist/ui/shared/host-context.js

@@ -0,0 +1,51 @@
+import { applyDocumentTheme, applyHostFonts, applyHostStyleVariables } from '@modelcontextprotocol/ext-apps';
+export function isObjectRecord(value) {
+    return typeof value === 'object' && value !== null;
+}
+export function applySharedHostContext(context, chrome) {
+    if (!isObjectRecord(context)) {
+        return;
+    }
+    if (context.theme === 'light' || context.theme === 'dark') {
+        applyDocumentTheme(context.theme);
+    }
+    const styles = isObjectRecord(context.styles) ? context.styles : null;
+    const variables = isObjectRecord(styles?.variables) ? styles.variables : null;
+    const css = isObjectRecord(styles?.css) ? styles.css : null;
+    const fonts = typeof css?.fonts === 'string' ? css.fonts : null;
+    if (variables) {
+        applyHostStyleVariables(variables);
+    }
+    if (fonts) {
+        applyHostFonts(fonts);
+    }
+    if (typeof context.initiallyExpanded === 'boolean') {
+        chrome.expanded = context.initiallyExpanded;
+    }
+    if (typeof context.compact === 'boolean' && typeof chrome.compact === 'boolean') {
+        chrome.compact = context.compact;
+    }
+    if (typeof context.hideSummaryRow === 'boolean') {
+        chrome.hideSummaryRow = context.hideSummaryRow;
+        if (context.hideSummaryRow) {
+            chrome.expanded = true;
+            if (typeof chrome.compact === 'boolean') {
+                chrome.compact = true;
+            }
+        }
+    }
+}
+export async function connectWithSharedHostContext(options) {
+    const { app, chrome, onContextApplied, onConnected } = options;
+    app.onhostcontextchanged = (context) => {
+        applySharedHostContext(context, chrome);
+        onContextApplied?.();
+    };
+    await app.connect();
+    const hostContext = app.getHostContext();
+    if (hostContext) {
+        applySharedHostContext(hostContext, chrome);
+        onContextApplied?.();
+    }
+    await onConnected?.();
+}

package/dist/ui/shared/tool-bridge.d.ts

@@ -0,0 +1,30 @@
+type ToolArgs = Record<string, unknown>;
+type ToolHelper = {
+    callTool: (name: string, args: ToolArgs) => Promise<unknown> | unknown;
+};
+type MessageEventLike = {
+    data: unknown;
+    origin?: string;
+    source?: unknown;
+};
+type MessageListener = (event: MessageEventLike) => void;
+type MessageTarget = {
+    postMessage: (message: unknown, targetOrigin?: string) => void;
+};
+type BridgeHost = {
+    openai?: ToolHelper;
+    mcp?: ToolHelper;
+    parent?: MessageTarget;
+    addEventListener?: (type: 'message', listener: MessageListener) => void;
+    removeEventListener?: (type: 'message', listener: MessageListener) => void;
+};
+export interface ToolBridgeOptions {
+    host?: BridgeHost;
+    requestTimeoutMs?: number;
+    targetOrigin?: string;
+    idPrefix?: string;
+}
+export declare function createToolBridge(options?: ToolBridgeOptions): {
+    callTool: (name: string, args?: ToolArgs) => Promise<unknown>;
+};
+export {};

package/dist/ui/shared/tool-bridge.js

@@ -0,0 +1,137 @@
+const DEFAULT_TIMEOUT_MS = 5000;
+function getDefaultTargetOrigin() {
+    if (typeof document === 'undefined') {
+        return '*';
+    }
+    const referrer = document.referrer;
+    if (typeof referrer !== 'string' || referrer.trim().length === 0) {
+        return '*';
+    }
+    try {
+        return new URL(referrer).origin;
+    }
+    catch {
+        return '*';
+    }
+}
+function normalizeTargetOrigin(value) {
+    if (value === '*') {
+        return value;
+    }
+    try {
+        return new URL(value).origin;
+    }
+    catch {
+        throw new Error(`Invalid targetOrigin: ${value}`);
+    }
+}
+function isObject(value) {
+    return typeof value === 'object' && value !== null;
+}
+function normalizeToolArgs(args) {
+    return args ?? {};
+}
+function extractErrorMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
+    }
+    return String(error);
+}
+function isHelperUnavailableError(error) {
+    if (!isObject(error)) {
+        return false;
+    }
+    const code = typeof error.code === 'string' ? error.code.toLowerCase() : '';
+    if (code === 'not_implemented' || code === 'not_supported' || code === 'unavailable') {
+        return true;
+    }
+    const message = extractErrorMessage(error).toLowerCase();
+    return message.includes('not implemented')
+        || message.includes('not supported')
+        || message.includes('unavailable')
+        || message.includes('not available');
+}
+export function createToolBridge(options = {}) {
+    const host = options.host ?? globalThis;
+    const timeoutMs = options.requestTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const targetOrigin = normalizeTargetOrigin(options.targetOrigin ?? getDefaultTargetOrigin());
+    const idPrefix = options.idPrefix ?? 'tool-bridge';
+    let requestCounter = 0;
+    async function callViaFallback(name, args) {
+        if (!host.parent || !host.addEventListener || !host.removeEventListener) {
+            throw new Error('JSON-RPC fallback is unavailable in this host environment.');
+        }
+        const parent = host.parent;
+        const addListener = (type, listener) => {
+            host.addEventListener?.(type, listener);
+        };
+        const removeListener = (type, listener) => {
+            host.removeEventListener?.(type, listener);
+        };
+        requestCounter += 1;
+        const requestId = `${idPrefix}:${requestCounter}`;
+        return new Promise((resolve, reject) => {
+            const timeoutHandle = setTimeout(() => {
+                removeListener('message', onMessage);
+                reject(new Error(`Tool call fallback timed out after ${timeoutMs}ms (request: ${requestId})`));
+            }, timeoutMs);
+            const onMessage = (event) => {
+                const payload = event.data;
+                if (event.source !== parent) {
+                    return;
+                }
+                if (targetOrigin !== '*' && event.origin !== targetOrigin) {
+                    return;
+                }
+                if (!isObject(payload) || payload.id !== requestId) {
+                    return;
+                }
+                clearTimeout(timeoutHandle);
+                removeListener('message', onMessage);
+                if (isObject(payload.error)) {
+                    const rawMessage = payload.error.message;
+                    const message = typeof rawMessage === 'string'
+                        ? rawMessage
+                        : 'Unknown tools/call fallback error';
+                    reject(new Error(`Tool call fallback failed: ${message}`));
+                    return;
+                }
+                resolve(payload.result);
+            };
+            addListener('message', onMessage);
+            parent.postMessage({
+                jsonrpc: '2.0',
+                id: requestId,
+                method: 'tools/call',
+                params: {
+                    name,
+                    arguments: args,
+                },
+            }, targetOrigin);
+        });
+    }
+    async function callTool(name, args) {
+        const normalizedArgs = normalizeToolArgs(args);
+        const helperCandidates = [host.openai, host.mcp].filter((candidate) => Boolean(candidate?.callTool));
+        for (const helper of helperCandidates) {
+            try {
+                return await helper.callTool(name, normalizedArgs);
+            }
+            catch (error) {
+                if (isHelperUnavailableError(error)) {
+                    continue;
+                }
+                throw new Error(`Tool helper call failed: ${extractErrorMessage(error)}`);
+            }
+        }
+        try {
+            return await callViaFallback(name, normalizedArgs);
+        }
+        catch (fallbackError) {
+            throw fallbackError;
+        }
+    }
+    return {
+        callTool,
+    };
+}

package/dist/ui/shared/tool-shell.d.ts

@@ -0,0 +1,25 @@
+export interface ToolShellController {
+    getExpanded: () => boolean;
+    setExpanded: (nextExpanded: boolean) => void;
+    toggle: () => void;
+    dispose: () => void;
+}
+interface CreateToolShellControllerOptions {
+    shell: HTMLElement | null;
+    toggleButton: HTMLButtonElement | null;
+    initialExpanded: boolean;
+    onToggle?: (expanded: boolean) => void;
+    onScrollAfterExpand?: () => void;
+    onRender?: () => void;
+}
+interface CreateCompactRowShellControllerOptions {
+    shell: HTMLElement | null;
+    compactRow: HTMLElement | null;
+    initialExpanded: boolean;
+    onToggle?: (expanded: boolean) => void;
+    onScrollAfterExpand?: () => void;
+    onRender?: () => void;
+}
+export declare function createToolShellController(options: CreateToolShellControllerOptions): ToolShellController;
+export declare function createCompactRowShellController(options: CreateCompactRowShellControllerOptions): ToolShellController;
+export {};

package/dist/ui/shared/tool-shell.js

@@ -0,0 +1,107 @@
+/**
+ * Shared shell behavior for collapsible sections and common UI affordances. It keeps repeated interaction patterns consistent across tool apps.
+ */
+const EXPAND_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M7 10l5 5 5-5z"></path></svg>';
+const COLLAPSE_ICON = '<svg viewBox="0 0 24 24" aria-hidden="true" focusable="false"><path d="M7 14l5-5 5 5z"></path></svg>';
+function syncExpandButton(toggleButton, expanded) {
+    if (!toggleButton) {
+        return;
+    }
+    const label = expanded ? 'Collapse' : 'Expand';
+    toggleButton.title = label;
+    toggleButton.setAttribute('aria-label', label);
+    toggleButton.innerHTML = expanded ? COLLAPSE_ICON : EXPAND_ICON;
+}
+function syncShellClasses(shell, expanded) {
+    if (!shell) {
+        return;
+    }
+    shell.classList.toggle('expanded', expanded);
+    shell.classList.toggle('collapsed', !expanded);
+}
+export function createToolShellController(options) {
+    const { shell, toggleButton, initialExpanded, onToggle, onScrollAfterExpand, onRender } = options;
+    let isExpanded = initialExpanded;
+    let scrollTrackedForCurrentExpand = false;
+    const shouldTrackScroll = typeof onScrollAfterExpand === 'function';
+    const applyExpandedState = (nextExpanded) => {
+        const wasExpanded = isExpanded;
+        isExpanded = nextExpanded;
+        syncShellClasses(shell, isExpanded);
+        syncExpandButton(toggleButton, isExpanded);
+        if (!wasExpanded && isExpanded) {
+            scrollTrackedForCurrentExpand = false;
+        }
+    };
+    const toggle = () => {
+        applyExpandedState(!isExpanded);
+        onToggle?.(isExpanded);
+        onRender?.();
+    };
+    const handleScroll = (event) => {
+        if (!isExpanded || scrollTrackedForCurrentExpand) {
+            return;
+        }
+        const targetNode = event?.target instanceof Node ? event.target : null;
+        if (targetNode && shell && !shell.contains(targetNode)) {
+            return;
+        }
+        scrollTrackedForCurrentExpand = true;
+        onScrollAfterExpand?.();
+    };
+    applyExpandedState(isExpanded);
+    toggleButton?.addEventListener('click', toggle);
+    if (shouldTrackScroll) {
+        shell?.addEventListener('scroll', handleScroll, { passive: true });
+        document.addEventListener('scroll', handleScroll, { passive: true, capture: true });
+    }
+    return {
+        getExpanded: () => isExpanded,
+        setExpanded: applyExpandedState,
+        toggle,
+        dispose: () => {
+            toggleButton?.removeEventListener('click', toggle);
+            if (shouldTrackScroll) {
+                shell?.removeEventListener('scroll', handleScroll);
+                document.removeEventListener('scroll', handleScroll, true);
+            }
+        },
+    };
+}
+export function createCompactRowShellController(options) {
+    const { shell, compactRow, initialExpanded, onToggle, onScrollAfterExpand, onRender } = options;
+    const controller = createToolShellController({
+        shell,
+        toggleButton: null,
+        initialExpanded,
+        onToggle: (expanded) => {
+            compactRow?.setAttribute('aria-expanded', String(expanded));
+            onToggle?.(expanded);
+        },
+        onScrollAfterExpand,
+        onRender,
+    });
+    compactRow?.setAttribute('aria-expanded', String(initialExpanded));
+    const handleCompactClick = () => {
+        controller.toggle();
+    };
+    const handleCompactKeydown = (event) => {
+        if (event.key !== 'Enter' && event.key !== ' ') {
+            return;
+        }
+        event.preventDefault();
+        controller.toggle();
+    };
+    compactRow?.addEventListener('click', handleCompactClick);
+    compactRow?.addEventListener('keydown', handleCompactKeydown);
+    return {
+        getExpanded: controller.getExpanded,
+        setExpanded: controller.setExpanded,
+        toggle: controller.toggle,
+        dispose: () => {
+            compactRow?.removeEventListener('click', handleCompactClick);
+            compactRow?.removeEventListener('keydown', handleCompactKeydown);
+            controller.dispose();
+        },
+    };
+}

package/dist/ui/shared/ui-event-tracker.d.ts

@@ -0,0 +1,9 @@
+type UiEventParamValue = string | number | boolean | null;
+export type UiEventParams = Record<string, UiEventParamValue>;
+type ToolCaller = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+export interface UiEventTrackerOptions {
+    component: string;
+    baseParams?: UiEventParams;
+}
+export declare function createUiEventTracker(callTool: ToolCaller, options: UiEventTrackerOptions): (event: string, params?: Record<string, unknown>) => void;
+export {};

package/dist/ui/shared/ui-event-tracker.js

@@ -0,0 +1,27 @@
+function normalizeUiEventParams(params) {
+    const normalized = {};
+    if (!params) {
+        return normalized;
+    }
+    for (const [key, value] of Object.entries(params)) {
+        if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean' || value === null) {
+            normalized[key] = value;
+        }
+    }
+    return normalized;
+}
+export function createUiEventTracker(callTool, options) {
+    const baseParams = options.baseParams ?? {};
+    return (event, params = {}) => {
+        void callTool('track_ui_event', {
+            event,
+            component: options.component,
+            params: {
+                ...baseParams,
+                ...normalizeUiEventParams(params),
+            },
+        }).catch(() => {
+            // UI analytics should never block UI interactions.
+        });
+    };
+}

package/dist/ui/shared/widget-state.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Widget state persistence for MCP Apps hosts.
+ *
+ * ChatGPT has a special extension (window.openai.widgetState) for persisting
+ * widget state across page refreshes. Other hosts use the standard MCP Apps
+ * pattern where ui/notifications/tool-result is re-sent when needed.
+ *
+ * This module provides a simple abstraction:
+ * - ChatGPT: Uses window.openai.widgetState
+ * - Other hosts: No-op (rely on standard ui/notifications/tool-result)
+ */
+export interface WidgetStateStorage<T> {
+    /** Read persisted state, returns undefined if not found or not supported */
+    read(): T | undefined;
+    /** Persist state for recovery after refresh (no-op on unsupported hosts) */
+    write(state: T): void;
+}
+/**
+ * Check if we're running in ChatGPT (has special widget state API)
+ */
+export declare function isChatGPT(): boolean;
+/**
+ * Create a widget state storage adapter.
+ *
+ * On ChatGPT: Uses window.openai.widgetState for persistence
+ * On other hosts: Uses sessionStorage as a fallback so the preview can survive
+ *   transient interruptions (page refresh on hosts that don't re-send tool_result,
+ *   visibility/focus loss, etc.).
+ *   The fallback cache key is scoped by app pathname and a per-frame widget id
+ *   persisted in window.name, so different widgets in the same origin/session
+ *   do not overwrite one another's cached state.
+ */
+export declare function createWidgetStateStorage<T>(validator?: (state: unknown) => boolean): WidgetStateStorage<T>;