@frontmcp/uipack

@frontmcp/uipack

HTML shell builder, pluggable import resolver, and NPM component loader for MCP UI development. React-free core.

Install

npm install @frontmcp/uipack

No React required. The only runtime dependency is zod.

Quick Start

Build an HTML Shell

import { buildShell } from '@frontmcp/uipack/shell';

const result = buildShell('<div id="root"></div>', {
  toolName: 'get_weather',
  input: { city: 'London' },
  output: { temp: 18 },
  includeBridge: true,
  csp: { connectDomains: ['https://api.weather.com'] },
});

// result.html  -> full HTML document with CSP, data injection, bridge IIFE
// result.hash  -> fast 32-bit content hash
// result.size  -> byte length

Render an NPM Component

import { renderComponent } from '@frontmcp/uipack/component';

const result = await renderComponent(
  { source: { npm: 'my-weather-widget', exportName: 'WeatherCard' } },
  { toolName: 'get_weather', output: { temp: 18 }, includeBridge: true },
);

Resolve Imports to CDN URLs

import { createEsmShResolver, createImportMap } from '@frontmcp/uipack/resolver';

const resolver = createEsmShResolver({ providerOrder: ['cloudflare', 'jsdelivr'] });
const result = resolver.resolve('chart.js');
// -> { value: 'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.5.1/chart.umd.min.js', type: 'url' }

Generate Bridge IIFE

import { generateBridgeIIFE, UNIVERSAL_BRIDGE_SCRIPT } from '@frontmcp/uipack/bridge-runtime';

// Use pre-generated universal script
const script = `<script>${UNIVERSAL_BRIDGE_SCRIPT}</script>`;

// Or generate with custom options
const iife = generateBridgeIIFE({ debug: true, minify: false });

Fetch TypeScript Definitions

import { createTypeFetcher } from '@frontmcp/uipack/typings';

const fetcher = createTypeFetcher({
  allowedPackages: ['react', 'zod', '@frontmcp/*'],
  maxDepth: 3,
});

const result = await fetcher.fetchBatch({
  imports: ["import { z } from 'zod'"],
});
// result.results[0].files -> TypeFile[] with virtual node_modules/ paths

Features

• Shell builder — Full HTML documents with CSP, data injection, and bridge runtime
• Import resolver — Pluggable CDN resolution (esm.sh, Cloudflare, jsDelivr, unpkg)
• Component loader — 4 source modes: npm, file, URL, inline function
• Bridge IIFE — Platform-aware vanilla JS bridge (OpenAI, ExtApps, Claude, Gemini, Generic)
• Type fetching — Download .d.ts from esm.sh with recursive dependency resolution
• XSS utilities — escapeHtml, safeJsonForScript, escapeScriptClose, and more
• Custom shells — Load shell templates from npm, URL, or inline HTML
• Standalone types — SDK-independent type definitions for widget configuration

Entry Points

Path	Purpose
@frontmcp/uipack	Main barrel (re-exports all modules)
@frontmcp/uipack/resolver	Pluggable import resolution
@frontmcp/uipack/shell	HTML shell builder
@frontmcp/uipack/component	Polymorphic component loader
@frontmcp/uipack/bridge-runtime	Platform bridge IIFE generator
@frontmcp/uipack/typings	TypeScript .d.ts fetching engine
@frontmcp/uipack/types	Standalone type definitions
@frontmcp/uipack/utils	XSS-safe escaping utilities

Module Exports

Resolver

Export	Type	Purpose
createEsmShResolver(opts?)	function	Default resolver using esm.sh with CDN registry fallback
DEFAULT_CDN_REGISTRY	constant	Pre-configured entries for react, react-dom, chart.js, d3, lodash
parseImports(source)	function	Parse source code for named, default, namespace, dynamic imports
rewriteImports(source, resolver, overrides?)	function	Rewrite bare specifiers to CDN URLs
createImportMap(overrides?)	function	Generate browser-standard import map
mergeImportMaps(...maps)	function	Deep-merge multiple import maps
generateImportMapScriptTag(map)	function	<script type="importmap"> generation
lookupPackage(name)	function	Query the CDN registry for a package
getPackageCDNUrl(name, provider?)	function	Resolve package to best CDN URL
extractExternalPackages(code)	function	Extract external package names from source

Shell

Export	Type	Purpose
buildShell(content, config)	function	Main entry point -> ShellResult
buildCSPMetaTag(config?)	function	Generate <meta> CSP tag
buildCSPDirectives(config?)	function	Merge custom domains with defaults
buildDataInjectionScript(toolName, input?, output?)	function	<script> setting window.__mcp* globals
createTemplateHelpers(toolName)	function	escapeHtml, formatDate, formatCurrency, uniqueId, jsonEmbed
resolveShellTemplate(opts)	function	Resolve custom shell from npm/URL/inline
applyShellTemplate(template, values)	function	Apply values to resolved template
validateShellTemplate(template)	function	Validate a custom shell template
DEFAULT_CDN_DOMAINS	constant	jsDelivr, Cloudflare, Google Fonts

Component

Export	Type	Purpose
renderComponent(config, shell)	function	Top-level compositor -> ShellResult
resolveUISource(source, opts)	function	Resolve any source to ResolvedComponent
generateMountScript(resolved, data)	function	ES module mount script for React/module components
isNpmSource, isFileSource, isImportSource, isFunctionSource	guards	Type narrowing helpers

Bridge Runtime

Export	Type	Purpose
generateBridgeIIFE(opts?)	function	Generate the bridge IIFE string
generatePlatformBundle(platform)	function	Platform-specific bundles (chatgpt, claude, gemini, universal)
UNIVERSAL_BRIDGE_SCRIPT	constant	Pre-generated script with all adapters
BRIDGE_SCRIPT_TAGS	constant	{ universal, chatgpt, claude, gemini } pre-wrapped <script> tags

Typings

Export	Type	Purpose
createTypeFetcher(opts?)	function	Factory creating a TypeFetcher instance
TypeFetcher	class	Main fetcher with caching and recursive dependency resolution
MemoryTypeCache	class	LRU cache with TTL support
globalTypeCache	constant	Module-level singleton cache (500 entries, 1h TTL)
parseDtsImports(content)	function	Parse .d.ts files for imports/references
combineDtsContents(results)	function	Combine multiple .d.ts files into one

Utils

Export	Type	Purpose
escapeHtml(str)	function	Escape &, <, >, ", ', U+2028/2029
escapeHtmlAttr(str)	function	Lighter escape for attributes
escapeJsString(str)	function	Escape for JS string literals
escapeScriptClose(str)	function	Replace </ with <\/ to prevent </script> breakout
safeJsonForScript(value)	function	JSON serialize safe for <script> embedding (handles BigInt, circular refs)
safeStringify(value, space?)	function	JSON.stringify with circular reference detection

Shell HTML Structure

Annotated output of buildShell with withShell: true and includeBridge: true:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>get_weather</title>

    <!-- CSP: default CDN domains + custom connectDomains/resourceDomains -->
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'self'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net ..."
    />

    <!-- Data injection: tool context as window globals -->
    <script>
      window.__mcpToolName = 'get_weather';
      window.__mcpToolInput = { city: 'London' };
      window.__mcpToolOutput = { temp: 18 };
      window.__mcpStructuredContent = null;
    </script>

    <!-- Bridge IIFE: auto-detects platform, exposes window.FrontMcpBridge -->
    <script>
      (function () {
        /* ... adapters, FrontMcpBridge class ... */
      })();
    </script>
  </head>
  <body>
    <!-- Content from resolver + component -->
    <script type="importmap">
      { "imports": { "react": "https://esm.sh/react@19" } }
    </script>
    <div id="root"></div>
    <script type="module">
      import { WeatherCard } from 'https://esm.sh/my-weather-widget';
      /* mount logic */
    </script>
  </body>
</html>

Component Source Modes

Mode	Config Shape	Description
npm	{ npm: 'my-chart', exportName?, version? }	Resolved via CDN registry / esm.sh
file	{ file: './widget.html', inline? }	Local file path
import	{ import: 'https://cdn.example.com/widget.js' }	Direct URL passthrough
inline	(input, output) => '<div>...</div>'	Function returning HTML string

Bridge API

The bridge IIFE exposes window.FrontMcpBridge with the following API:

Method	Description
callTool(name, args)	Invoke an MCP tool from the widget
getToolOutput()	Read injected tool output data
getToolInput()	Read injected tool input data
sendMessage(content)	Send message to host
openLink(url)	Open a URL via platform adapter
requestDisplayMode(mode)	Switch inline / fullscreen / pip
setWidgetState(state)	Persist widget state to localStorage
onContextChange(callback)	Subscribe to host context changes
onToolResult(callback)	Subscribe to tool result events
hasCapability(cap)	Check adapter capabilities
getTheme()	Get current theme from host
getDisplayMode()	Get current display mode
getHostContext()	Get host context metadata

Contributing

Architecture

graph TD
    subgraph "@frontmcp/uipack"
        IDX["index.ts<br/><i>Main barrel exports</i>"]

        subgraph bridge-runtime["bridge-runtime/"]
            BR_IIFE["iife-generator.ts<br/>5 platform adapters:<br/>OpenAI, ExtApps, Claude,<br/>Gemini, Generic"]
        end

        subgraph component["component/"]
            CO_TYPES["types.ts<br/>NpmSource, FileSource,<br/>ImportSource, FunctionSource"]
            CO_LOAD["loader.ts<br/>resolveUISource(),<br/>generateMountScript()"]
            CO_REND["renderer.ts<br/>renderComponent()"]
        end

        subgraph resolver["resolver/"]
            RE_CDN["cdn-registry.ts<br/>DEFAULT_CDN_REGISTRY,<br/>lookupPackage()"]
            RE_ESM["esm-sh.resolver.ts<br/>createEsmShResolver()"]
            RE_PARSE["import-parser.ts<br/>parseImports()"]
            RE_REWRITE["import-rewriter.ts<br/>rewriteImports()"]
            RE_MAP["import-map.ts<br/>createImportMap(),<br/>mergeImportMaps()"]
        end

        subgraph shell["shell/"]
            SH_BUILD["builder.ts<br/>buildShell()"]
            SH_CSP["csp.ts<br/>CSP directives + meta tag"]
            SH_DATA["data-injector.ts<br/>window.__mcp* globals"]
            SH_CUSTOM["custom-shell-*.ts<br/>Resolve, validate, apply<br/>custom shell templates"]
        end

        subgraph types["types/"]
            TY_CFG["ui-config.ts<br/>UITemplateConfig,<br/>WidgetServingMode"]
            TY_RT["ui-runtime.ts<br/>UIType, WidgetManifest,<br/>WidgetConfig"]
        end

        subgraph typings["typings/"]
            TP_FETCH["type-fetcher.ts<br/>TypeFetcher class"]
            TP_DTS["dts-parser.ts<br/>parseDtsImports()"]
            TP_SCHEMA["schemas.ts<br/>Zod validation"]
            TP_CACHE["cache/<br/>MemoryTypeCache (LRU + TTL)"]
        end

        subgraph utils["utils/"]
            UT["escapeHtml, safeJsonForScript,<br/>escapeScriptClose, safeStringify"]
        end
    end

Module Dependency Graph

graph BT
    utils["utils<br/><i>foundation, zero deps</i>"]
    resolver["resolver<br/><i>import resolution</i>"]
    shell["shell<br/><i>HTML shell builder</i>"]
    bridge["bridge-runtime<br/><i>IIFE generator, standalone</i>"]
    component["component<br/><i>polymorphic loader</i>"]
    types["types<br/><i>standalone, no internal deps</i>"]
    typings["typings<br/><i>standalone, uses zod</i>"]

    resolver --> utils
    shell --> utils
    shell --> resolver
    shell --> bridge
    component --> utils
    component --> resolver
    component --> shell

How @frontmcp/uipack works with @frontmcp/ui

@frontmcp/uipack runs server-side (Node.js) and produces complete HTML documents. @frontmcp/ui runs browser-side and provides React components and hooks that mount inside those documents.

Bridge contract: uipack generates a vanilla JS IIFE that creates window.FrontMcpBridge. The @frontmcp/ui bridge module wraps this same API in a React-friendly class and hooks (useCallTool, etc.). The ui package re-exports bridge IIFE generators from uipack via @frontmcp/ui/bridge/runtime.

Dependency direction: @frontmcp/ui optionally depends on @frontmcp/uipack (optional dependency). They can be used independently — uipack alone for vanilla JS widgets, or together for React-based widgets.

End-to-end data flow:

sequenceDiagram
    participant Dev as Developer
    participant SDK as @frontmcp/sdk
    participant UP as @frontmcp/uipack
    participant Browser
    participant UI as @frontmcp/ui

    Dev->>SDK: @Tool({ ui: { npm: '...' } })
    SDK->>UP: renderComponent(config, shellConfig)
    UP->>UP: resolve deps (esm.sh)
    UP->>UP: build shell (CSP + data injection)
    UP->>UP: inject bridge IIFE
    UP-->>SDK: ShellResult { html, hash, size }

    Browser->>SDK: readResource("ui://widget/tool.html")
    SDK-->>Browser: cached HTML

    Browser->>Browser: Load @frontmcp/ui via esm.sh
    Browser->>UI: Mount React components
    UI->>UI: Bridge hooks read window.__mcp* globals
    UI->>Browser: Interactive widget rendered

Development

# Build
nx build uipack

# Test
nx test uipack

# Lint
nx lint uipack

Testing

• 95%+ coverage required across statements, branches, functions, lines
• XSS tests are critical — test all escaping functions with malicious input
• CSP tests — verify generated Content-Security-Policy headers are correct
• Test all 4 component source modes (npm, file, import, inline)
• Test bridge IIFE generation for each platform

Requirements

• Node.js >= 22.0.0

Related Packages

• @frontmcp/ui — React components, hooks, and renderers that consume uipack output
• @frontmcp/sdk — Core FrontMCP SDK with ToolUIRegistry
• @frontmcp/testing — UI test assertions

License

Apache-2.0 — see LICENSE.