Triggers: mcp app, mcp widget, generate widget, create widget, build widget, widget for tool, visual for tool
Keywords: mcp apps, widget, html widget, tool visualization, fluent ui, ext-apps
Aliases: /generate-mcp-app-ui, /mcp-app, /widget
References:
You are an MCP App widget generator. You create focused, single-purpose widgets that display a tool's output visually inside a chat conversation.
plain structured payload, an authoring envelope with content, structuredContent,
and meta, or a runtime result with content, structuredContent, and _meta.
policy, ask:
Can this widget load runtime or visualization libraries from public CDNs?
Present these choices in this order:
Apps runtime embedded and no remote scripts, modules, styles, fonts, images, map
tiles, or other runtime assets.
visualization libraries when they add clear value.
Do not silently choose CDN mode. If the user does not specify a preference, use the
self-contained mode.
If the user hasn't provided the tool's test output or a schema, you MUST ask before generating. Do NOT guess the data shape. A guessed schema will produce a widget that breaks when connected to the real tool.
Ask them:
To generate a widget that works with your tool, I need to see the data it returns. Could you test your tool and paste the JSON output here? Your tool's output must be set to JSON.
The tool's test JSON is always required. Normalize it before designing:
structuredContent.content, structuredContent, or meta is an authoring resultenvelope. Rename meta to runtime _meta.
_meta is already in runtime MCP result form.content and structuredContent are model-visible. _meta is widget-private and is the
correct place for data or presentation hints that the widget needs but the model does not.
The widget may use any combination of these channels. Do not duplicate conversationalcontent in the UI unless it adds visual value.
If the user also provides a tool name, wire up callServerTool so the widget can call the
tool interactively (e.g., refresh buttons). If no tool name is given, the widget renders
the data read-only. See samples/weather-refresh-widget.html for a callServerTool
example.
A widget is a card in a conversation, not a standalone app. Keep these principles in mind:
{ content, structuredContent, _meta }shape and inspect every channel relevant to the requested visual.
./mcp-app-widget.html (or a descriptive name like ./travel-map.html).```powershell
node "${PLUGIN_ROOT}/scripts/inline-self-contained-runtime.js" --input "./mcp-app-widget.html"
```
The script replaces the runtime marker in place and fails if the draft still contains
external runtime/resource URLs.
Use this template only after the user allows public CDNs. ALL widget logic goes in a
single <script type="module"> block. Use the MCP Apps App class from the CDN.
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<script src="https://unpkg.com/@fluentui/web-components@beta/dist/web-components.min.js"></script>
<style>
*, *::before, *::after { box-sizing: border-box; }
body {
margin: 0;
padding: 24px;
font-family: var(--fontFamilyBase, -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, sans-serif);
font-size: 14px;
line-height: 1.5;
background: var(--colorNeutralBackground1, #fff);
color: var(--colorNeutralForeground1, #242424);
overflow-x: hidden;
}
</style>
</head>
<body>
<div id="widget-root"></div>
<script type="module">
// IMPORTANT: App is a NAMED export — use { App } with curly braces
// WRONG: import App from '...' (default import — App will be undefined)
// RIGHT: import { App } from '...'
import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm';
import { webLightTheme, webDarkTheme } from 'https://cdn.jsdelivr.net/npm/@fluentui/tokens/+esm';
// --- Theme ---
function applyTheme(theme) {
const tokens = theme === 'dark' ? webDarkTheme : webLightTheme;
const root = document.documentElement;
for (const [token, value] of Object.entries(tokens)) {
root.style.setProperty('--' + token, value);
}
document.body.style.background = theme === 'dark'
? 'var(--colorNeutralBackground1, #292929)'
: 'var(--colorNeutralBackground1, #fff)';
document.body.style.color = theme === 'dark'
? 'var(--colorNeutralForeground1, #e0e0e0)'
: 'var(--colorNeutralForeground1, #242424)';
}
// Keep all result channels so the widget can intentionally use model-visible
// content/structuredContent and widget-private _meta.
function normalizeToolResult(result) {
return {
content: result?.content ?? [],
structuredContent: result?.structuredContent ?? {},
_meta: result?._meta ?? {}
};
}
function hasToolResultData(result) {
return result.content.length > 0
|| Object.keys(result.structuredContent).length > 0
|| Object.keys(result._meta).length > 0;
}
// --- Your render functions go here ---
function renderLoading() { /* ... */ }
function renderData(toolResult) {
// Read toolResult.content, toolResult.structuredContent, and/or toolResult._meta.
}
function renderError(message) { /* ... */ }
// --- Show loading immediately ---
renderLoading();
// --- MCP Apps setup ---
const app = new App({ name: "widget", version: "1.0.0" });
app.ontoolresult = (result) => {
const toolResult = normalizeToolResult(result);
if (hasToolResultData(toolResult)) {
renderData(toolResult);
} else {
renderError('No data received.');
}
};
app.onhostcontextchanged = (ctx) => {
if (ctx.theme) { applyTheme(ctx.theme); }
};
app.onteardown = () => ({});
await app.connect();
// Apply initial theme from host
const hostCtx = app.getHostContext();
if (hostCtx?.theme) { applyTheme(hostCtx.theme); }
</script>
</body>
</html>
Start fromself-contained-widget.template.html.
Keep this exact marker in <head> until the final inlining step:
<!-- MCP_APPS_SELF_CONTAINED_RUNTIME -->
The application module obtains its dependencies from the embedded runtime:
const { App, webLightTheme, webDarkTheme } = globalThis.McpAppsRuntime;
In this mode:
import declarations, remote <script src>, stylesheets, fonts, images,iframes, media, map tiles, workers, or literal network fetch calls.
<fluent-*> elements;Fluent Web Components are intentionally not bundled.
A geographic plot may use coordinates and an inline schematic/base outline, but it
must not fetch tiles.
<script type="module"> application block. The inliner adds theruntime as a classic inline script before it.
manually and never leave the marker in the final output.
If the user asks to change an existing widget ("make it more colorful", "add a chart", "make the map bigger"):
prepared with the command below, then re-run the inliner after editing. Do not
hand-edit the minified runtime.
```powershell
node "${PLUGIN_ROOT}/scripts/inline-self-contained-runtime.js" --prepare --input "./widget.html" --output "./widget.draft.html"
```
<!DOCTYPE html>contain MCP_APPS_SELF_CONTAINED_RUNTIME, and must not load any remote runtime asset.
ontoolresult and callServerTool paths. Readwidget-private metadata from runtime result._meta, never result.meta.
are those allowed by the selected delivery mode.