@frontmcp/uipack

@frontmcp/uipack is the React-free core FrontMCP builds widget pages with, on the server. It renders a tool's template into a full HTML page with a Content Security Policy, the call's data and the bridge script that talks to the host; resolves a widget's imports to CDN URLs; and bundles React widget files. @frontmcp/sdk depends on it, so a FrontMCP server already has it. Import it yourself to split a template into functions with html, to test a template without a server with renderToolTemplate(), or to build widget pages for a host of your own.

Install

npm install @frontmcp/uipack

• No React dependency. The runtime dependencies are zod and entities (the HTML character reference decoder sanitizeHtml() uses); npm 7 and later also install the peer @frontmcp/lazy-zod, at the same version.
• esbuild is an optional peer, needed only to bundle .tsx and .jsx widget files. Install it as a dependency, not a dev dependency, since it's loaded when a widget is rendered.
• highlight.js is an optional peer, needed only for markdown.highlightTheme (ui.runtimeOptions.markdown.highlightTheme). It's loaded from your project when a template uses it.
• @mdx-js/mdx, react and react-dom are optional peers, needed only to render an MDX template (mdxComponents) on the server, and remark-gfm for one with markdown.gfm. react and react-dom also render a component on the server (uiType: 'react') and a widget to hydrate (hydrate). They're loaded from your project, so the template's components and the renderer share one React.
• It runs on Node.js 24 or later.

Usage

Render a template the way a tool call does, without a server:

import { html, renderToolTemplate, type TemplateContext } from '@frontmcp/uipack';

type Weather = { city: string; tempC: number };

const badge = (text: string) => html`<span class="badge">${text}</span>`;

const result = renderToolTemplate({
  toolName: 'get_weather',
  input: { city: 'Oslo' },
  output: { city: 'Oslo', tempC: 21 },
  template: (ctx: TemplateContext<{ city: string }, Weather>) =>
    html`<h2>${ctx.output.city} ${badge(`${ctx.output.tempC}°C`)}</h2>`,
});

result.html is a whole HTML document whose body is <h2>Oslo <span class="badge">21°C</span></h2>, result.uiType is "html", and result.meta["ui/mimeType"] is "text/html;profile=mcp-app". Values interpolated into html are escaped, so a city of <script> renders as <script>; markup built with html or trustedHtml() isn't escaped twice. html is the same builder as a tool template's ctx.helpers.html, so pieces of a widget can live in their own file and be tested on their own (Splitting a template into functions).

Building a page around your own markup

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

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

hash is a short, non-cryptographic hash of the page, for cache keys, and size its length in bytes. The page looks like this, with the bridge script shortened:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <meta
      http-equiv="Content-Security-Policy"
      content="default-src 'none'; script-src 'self' 'unsafe-inline' https://cdn.jsdelivr.net ... https://esm.sh; ... connect-src https://cdn.jsdelivr.net ... https://esm.sh https://api.weather.com; ..."
    />
    <script>
      window.__mcpAppsEnabled = true;
      window.__mcpToolName = 'get_weather';
      window.__mcpToolInput = { city: 'London' };
      window.__mcpToolOutput = { temp: 18 };
      window.__mcpStructuredContent = null;
    </script>
    <script>
      /* the bridge: picks an adapter for the host and sets window.FrontMcpBridge */
    </script>
  </head>
  <body>
    <div id="root"></div>
  </body>
</html>

Resolving imports to CDN URLs

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

const resolver = createEsmShResolver({ providerOrder: ['cloudflare', 'jsdelivr'] });

resolver.resolve('chart.js');
// { value: 'https://cdnjs.cloudflare.com/ajax/libs/Chart.js/4.5.1/chart.umd.min.js', type: 'url' }

rewriteImports("import { format } from 'date-fns';", { resolver }).code;
// "import { format } from 'https://esm.sh/date-fns';"

A package in the CDN registry (react, react-dom, chart.js, d3, lodash) resolves to its registered URL, trying the providers in providerOrder; any other package resolves to https://esm.sh/<specifier>.

Rendering a component from npm

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

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

renderComponent() is synchronous. The page imports the component from https://esm.sh/my-weather-widget, loads React from esm.sh through an import map, and renders the component into #root with the tool's output as its props. The source can be any of these:

Generating the bridge script

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

const everyHost = BRIDGE_SCRIPT_TAGS.universal;
const openAiOnly = `<script>${generateBridgeIIFE({ adapters: ['openai', 'generic'], minify: true })}</script>`;

The script detects the host and sets window.FrontMcpBridge:

Fetching TypeScript definitions

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

const fetcher = createTypeFetcher({ allowedPackages: ['@myorg/*'], maxDepth: 3 });
const { results, errors } = await fetcher.fetchBatch({ imports: ["import { z } from 'zod'"] });
// results[0].files: the .d.ts files, at virtual node_modules/ paths

It fetches the .d.ts files of each import from esm.sh, following their own imports up to maxDepth (default 2). Only allowed packages are fetched: react, react-dom, react/jsx-runtime, zod and @frontmcp/*, plus allowedPackages, or any package with allowedPackages: false.

Entry points

@frontmcp/uipack exports everything below. Each module is also its own entry point:

Adapters

Shell

Resolver

Component

Bridge runtime

Typings

Utils

Docs

• Widget components: @frontmcp/uipack in a server, html and renderToolTemplate()
• The ui option: templates, serving modes, Content Security Policy
• Hosts and platforms: the bridge, window.FrontMcpBridge, and what each host gets
• Choosing how a widget is served: inline and static pages, and what a widget can load

Related packages

• @frontmcp/sdk: the server framework; it renders a tool's ui with this package.
• @frontmcp/ui: the React components, hooks and renderers for widget files.
• @frontmcp/testing: test helpers, with matchers for a tool's rendered widget.

Contributing

Source: libs/uipack. Issues and pull requests are welcome; see CONTRIBUTING.md.

The source has one folder per entry point under src/: adapters/, shell/, resolver/, component/, bridge-runtime/, typings/, types/ and utils/. utils and bridge-runtime depend on nothing else; resolver uses utils; shell uses utils, resolver and bridge-runtime; component builds on shell; adapters uses them all; typings stands alone, and types only imports types. Test escaping and Content Security Policy changes with hostile input. In the monorepo:

nx build uipack
nx test uipack
nx lint uipack

License

Apache-2.0. See LICENSE.