Skip to content

Feature: UI Runtime + Vite plugin #7

Description

@znicholasbrown

We want to create a browser-safe runtime that injects tools/resources/etc into composable the UI components can use.

Additionally, a Vite plugin that pulls co-located UI components into dedicated build files that can be safely run in an iframe without losing references to server tools.

Tentative task list:

  • Host context — iframe receives HostContext on init: theme (light/dark), ~50 standardised CSS custom properties, displayMode (inline/fullscreen/pip), containerDimensions, locale, timeZone, platform, deviceCapabilities, and safeAreaInsets; View can request a display mode change and receive resize notifications
  • Bidirectional communication — View↔Host JSON-RPC 2.0 over postMessage; View calls tools/call, resources/read, sampling/createMessage, ui/message (inject a user turn into the conversation), ui/update-model-context, ui/open-link, ui/download-file, and ui/request-display-mode; app-provided tools let the View register ephemeral tools callable by the host or agent for the iframe's lifetime
  • @fastmcp/ui-runtime — client-side package for use inside app iframes; useMCPApp() hook delivers typed toolInput, hostContext, callTool(), sendMessage(), updateModelContext(), and registerTool(); useTools<typeof server>() generic derives fully-typed call signatures (tool names, argument shapes, return types) from the server's exported type — eliminates stringly-typed tool calls and gives full IntelliSense inside the iframe; framework-agnostic core with React bindings included
  • Vite plugin (@fastmcp/vite-plugin) — co-locate server handler and React component in a single .tool.tsx file; plugin extracts the default-exported component, bundles it for the browser, auto-generates the ui:// URI from the filename, registers the resource on the server, and wires _meta.ui.resourceUri — no URI strings written by hand; HMR for the UI component wired into fastmcp dev --reload

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions