mirror of
https://github.com/PrefectHQ/fastmcp.git
synced 2026-08-09 23:29:10 +02:00
366 lines
12 KiB
Text
366 lines
12 KiB
Text
---
|
|
title: Prefab UI
|
|
sidebarTitle: Prefab UI
|
|
description: The component library behind FastMCP apps — charts, tables, dashboards, forms, and reactive displays.
|
|
icon: palette
|
|
tag: NEW
|
|
---
|
|
|
|
import { VersionBadge } from '/snippets/version-badge.mdx'
|
|
|
|
<VersionBadge version="3.1.0" />
|
|
|
|
<Warning>
|
|
[Prefab](https://prefab.prefect.io) is in early, active development — breaking changes can occur with any release. FastMCP pins a minimum version of `prefab-ui` for compatibility but does not pin an upper bound. If you are deploying to production, **pin `prefab-ui` to a specific version** in your own dependencies (e.g. `prefab-ui==0.15.0`).
|
|
</Warning>
|
|
|
|
[Prefab UI](https://prefab.prefect.io) is the component library behind all FastMCP app features. You describe layouts, charts, tables, and forms in Python, and Prefab compiles them to interactive UIs that render in the host's conversation.
|
|
|
|
The simplest way to use it: add `app=True` to a tool and return Prefab components. The host renders an interactive UI instead of text. This works for everything from static charts to reactive dashboards with client-side state — no server round-trips needed.
|
|
|
|
For apps that need server interaction (forms, search, CRUD), see [FastMCPApp](/apps/interactive-apps) which adds managed tool binding on top of Prefab UI. For LLM-generated UIs, see [Generative UI](/apps/generative).
|
|
|
|
## Getting Started
|
|
|
|
Here's a tool that returns a bar chart:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Heading
|
|
from prefab_ui.components.charts import BarChart, ChartSeries
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("Dashboard")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def revenue_chart(year: int) -> PrefabApp:
|
|
"""Show annual revenue as an interactive bar chart."""
|
|
data = [
|
|
{"quarter": "Q1", "revenue": 42000},
|
|
{"quarter": "Q2", "revenue": 51000},
|
|
{"quarter": "Q3", "revenue": 47000},
|
|
{"quarter": "Q4", "revenue": 63000},
|
|
]
|
|
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Heading(f"{year} Revenue")
|
|
BarChart(
|
|
data=data,
|
|
series=[ChartSeries(data_key="revenue", label="Revenue")],
|
|
x_axis="quarter",
|
|
)
|
|
|
|
return PrefabApp(view=view)
|
|
```
|
|
|
|
The `app=True` flag tells FastMCP this tool returns a UI. When a host calls the tool, the user sees an interactive chart instead of a JSON blob. The [Patterns](/apps/patterns) page has more examples.
|
|
|
|
## Layout and Components
|
|
|
|
Prefab uses Python's `with` statement to express nesting. Containers like `Column`, `Row`, and `Grid` collect their children automatically:
|
|
|
|
```python
|
|
from prefab_ui.components import (
|
|
Column, Row, Grid, Heading, Text, Muted, Badge,
|
|
Card, CardContent, Separator,
|
|
)
|
|
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Heading("Team Status")
|
|
Separator()
|
|
with Grid(columns=2, gap=4):
|
|
with Card():
|
|
with CardContent():
|
|
Text("API Gateway", css_class="font-medium")
|
|
Badge("healthy", variant="success")
|
|
with Card():
|
|
with CardContent():
|
|
Text("Cache", css_class="font-medium")
|
|
Badge("degraded", variant="destructive")
|
|
```
|
|
|
|
You can also use Python loops to generate components at build time:
|
|
|
|
```python
|
|
services = [
|
|
{"name": "API", "status": "healthy", "ok": True},
|
|
{"name": "Cache", "status": "degraded", "ok": False},
|
|
]
|
|
|
|
with Grid(columns=2, gap=4):
|
|
for svc in services:
|
|
with Card():
|
|
with CardContent():
|
|
Text(svc["name"])
|
|
Badge(
|
|
svc["status"],
|
|
variant="success" if svc["ok"] else "destructive",
|
|
)
|
|
```
|
|
|
|
Build-time loops produce static content — the data is baked into the component tree at construction time. For dynamic iteration over state that changes at render time, use `ForEach` (covered below).
|
|
|
|
The full component library — layout containers, data display, charts, forms, overlays — is documented in the [Prefab component reference](https://prefab.prefect.io/docs/components).
|
|
|
|
## State and Reactivity
|
|
|
|
Display tools can be interactive without calling the server. The key is **state** — a client-side key-value store that lives in the browser. Components read from state, actions mutate it, and the UI re-renders automatically.
|
|
|
|
### Declaring State
|
|
|
|
Pass a `state` dict to `PrefabApp` to declare initial state, then use `Rx("key")` to create reactive references:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Heading, Switch, Alert, If
|
|
from prefab_ui.rx import Rx
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("Flags")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def feature_flags() -> PrefabApp:
|
|
"""Toggle feature flags with live preview."""
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Heading("Feature Flags")
|
|
Switch(name="dark_mode", label="Dark Mode")
|
|
Switch(name="beta", label="Beta Features")
|
|
|
|
with If(Rx("dark_mode")):
|
|
Alert(title="Dark mode enabled")
|
|
with If(Rx("beta")):
|
|
Alert(title="Beta features active", variant="warning")
|
|
|
|
return PrefabApp(view=view, state={"dark_mode": False, "beta": False})
|
|
```
|
|
|
|
Three things to notice here:
|
|
|
|
The `state` dict on `PrefabApp` declares the keys and their starting values. `Rx("dark_mode")` creates a reactive reference that compiles to `{{ dark_mode }}` in the wire protocol.
|
|
|
|
Interactive components with a `name` prop automatically bind to state. The `Switch(name="dark_mode")` syncs its on/off value to the `dark_mode` state key on every toggle — no event wiring needed.
|
|
|
|
`If(Rx("dark_mode"))` shows its children only when the state key is truthy. When the switch flips, the condition re-evaluates instantly in the browser.
|
|
|
|
### Reactive References with Rx
|
|
|
|
The `Rx` class is how you reference state in component props:
|
|
|
|
```python
|
|
from prefab_ui.rx import Rx
|
|
|
|
count = Rx("count")
|
|
```
|
|
|
|
Rx objects support arithmetic, comparisons, and formatting — they compile to expressions the renderer evaluates at render time:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Text, Slider
|
|
from prefab_ui.rx import Rx
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("Calculator")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def tip_calculator() -> PrefabApp:
|
|
"""Calculate tip with a slider."""
|
|
tip_pct = Rx("tip_pct")
|
|
bill = Rx("bill")
|
|
|
|
tip_amount = tip_pct / 100 * bill
|
|
total = bill + tip_amount
|
|
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Slider(name="bill", label="Bill Amount", min=0, max=500, step=0.5)
|
|
Slider(name="tip_pct", label="Tip %", min=0, max=50)
|
|
Text(f"Tip: {tip_amount.currency()}")
|
|
Text(f"Total: {total.currency()}")
|
|
|
|
return PrefabApp(view=view, state={"bill": 50.00, "tip_pct": 18})
|
|
```
|
|
|
|
`Rx("tip_pct") / 100 * Rx("bill")` builds a compound expression — it doesn't do the math in Python. The renderer evaluates it live as the sliders move. The `.currency()` pipe formats the result as currency.
|
|
|
|
#### Pipes
|
|
|
|
Rx objects support formatting pipes that transform values at render time:
|
|
|
|
```python
|
|
from prefab_ui.rx import Rx
|
|
|
|
price = Rx("price")
|
|
ratio = Rx("ratio")
|
|
name = Rx("name")
|
|
|
|
price.currency() # $42.50
|
|
price.currency("EUR") # EUR format
|
|
ratio.percent() # 85%
|
|
name.upper() # ALICE
|
|
name.truncate(10) # alice (or truncated if longer)
|
|
```
|
|
|
|
Number pipes include `currency`, `percent`, `number`, `compact`, `round`, and `abs`. String pipes include `upper`, `lower`, and `truncate`. See the [Prefab expression docs](https://prefab.prefect.io/docs/concepts/expressions) for the full list.
|
|
|
|
#### Conditionals
|
|
|
|
The `.then()` method creates ternary expressions:
|
|
|
|
```python
|
|
from prefab_ui.rx import Rx
|
|
|
|
connected = Rx("connected")
|
|
|
|
Badge(
|
|
connected.then("Online", "Offline"),
|
|
variant=connected.then("success", "destructive"),
|
|
)
|
|
```
|
|
|
|
### Dynamic Iteration with ForEach
|
|
|
|
Python `for` loops generate static content at build time. When you need to iterate over state that can change — a list that grows, items that get filtered — use `ForEach`:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Heading, ForEach, Row, Text, Badge
|
|
from fastmcp import FastMCP
|
|
|
|
mcp = FastMCP("Directory")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def team_list() -> PrefabApp:
|
|
"""Show the current team."""
|
|
members = [
|
|
{"name": "Alice", "role": "Engineering"},
|
|
{"name": "Bob", "role": "Design"},
|
|
]
|
|
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Heading("Team")
|
|
with ForEach("members") as member:
|
|
with Row(gap=2, align="center"):
|
|
Text(member.name, css_class="font-medium")
|
|
Badge(member.role)
|
|
|
|
return PrefabApp(view=view, state={"members": members})
|
|
```
|
|
|
|
`ForEach("members")` iterates over the `members` state key. The `as member` gives you an Rx proxy scoped to each item, so `member.name` resolves to `{{ $item.name }}` in the wire protocol. If the `members` state changes (e.g., through an action), the list re-renders automatically.
|
|
|
|
### Conditional Rendering
|
|
|
|
`If`, `Elif`, and `Else` control what's visible based on state:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Select, SelectOption, If, Elif, Else, Text
|
|
from prefab_ui.rx import Rx
|
|
|
|
tier = Rx("tier")
|
|
|
|
with Column(gap=4) as view:
|
|
with Select(name="tier", label="Plan"):
|
|
SelectOption("Free", value="free")
|
|
SelectOption("Pro", value="pro")
|
|
SelectOption("Enterprise", value="enterprise")
|
|
with If(tier == "enterprise"):
|
|
Text("Full access to all features")
|
|
with Elif(tier == "pro"):
|
|
Text("Advanced features unlocked")
|
|
with Else():
|
|
Text("Basic features only")
|
|
|
|
# Pass state={"tier": "free"} to PrefabApp when returning
|
|
```
|
|
|
|
Changes are instant — switching the dropdown re-evaluates the conditions in the browser.
|
|
|
|
## Giving the LLM Context
|
|
|
|
By default, Prefab sends `"[Rendered Prefab UI]"` as the text content for the LLM. If the model needs to reason about the data, wrap your return in a `ToolResult` with a meaningful summary:
|
|
|
|
```python
|
|
from prefab_ui.app import PrefabApp
|
|
from prefab_ui.components import Column, Heading
|
|
from prefab_ui.components.charts import BarChart, ChartSeries
|
|
from fastmcp import FastMCP
|
|
from fastmcp.tools import ToolResult
|
|
|
|
mcp = FastMCP("Sales")
|
|
|
|
|
|
@mcp.tool(app=True)
|
|
def sales_overview(year: int) -> ToolResult:
|
|
"""Show sales data visually and summarize for the model."""
|
|
data = get_sales_data(year)
|
|
total = sum(row["revenue"] for row in data)
|
|
|
|
with Column(gap=4, css_class="p-6") as view:
|
|
Heading("Sales Overview")
|
|
BarChart(data=data, series=[ChartSeries(data_key="revenue")])
|
|
|
|
return ToolResult(
|
|
content=f"Total revenue for {year}: ${total:,} across {len(data)} quarters",
|
|
structured_content=view,
|
|
)
|
|
```
|
|
|
|
The user sees the chart. The LLM sees the summary string.
|
|
|
|
## Advanced
|
|
|
|
<Accordion title="Customizing CSP">
|
|
`app=True` auto-wires the Prefab renderer with default CSP settings. If your app loads external resources — embedding iframes, fetching from APIs, loading scripts — use `PrefabAppConfig` to add the required domains:
|
|
|
|
```python
|
|
from fastmcp.apps import PrefabAppConfig, ResourceCSP
|
|
|
|
@mcp.tool(app=PrefabAppConfig(
|
|
csp=ResourceCSP(frame_domains=["https://example.com"]),
|
|
))
|
|
def dashboard_with_embed() -> PrefabApp:
|
|
...
|
|
```
|
|
|
|
`PrefabAppConfig()` with no arguments is equivalent to `app=True`. It auto-sets the renderer URI and merges the renderer's CSP with any additional domains you provide.
|
|
</Accordion>
|
|
|
|
<Accordion title="Type inference">
|
|
If your return type annotation is a Prefab type — `PrefabApp`, `Component`, or unions containing them — FastMCP enables app rendering automatically, even without `app=True`:
|
|
|
|
```python
|
|
@mcp.tool
|
|
def greet(name: str) -> PrefabApp:
|
|
return PrefabApp(view=Heading(f"Hello, {name}!"))
|
|
```
|
|
|
|
Explicit `app=True` is recommended for clarity.
|
|
</Accordion>
|
|
|
|
<Accordion title="Mixing with custom HTML">
|
|
Prefab tools and [custom HTML tools](/apps/low-level) coexist on the same server:
|
|
|
|
```python
|
|
from fastmcp.apps import AppConfig
|
|
|
|
@mcp.tool(app=True)
|
|
def team_directory() -> PrefabApp:
|
|
...
|
|
|
|
@mcp.tool(app=AppConfig(resource_uri="ui://my-app/map.html"))
|
|
def map_view() -> str:
|
|
...
|
|
```
|
|
</Accordion>
|
|
|
|
## Next Steps
|
|
|
|
- **[FastMCPApp](/apps/interactive-apps)** — Managed tool binding for apps with heavy server interaction
|
|
- **[Patterns](/apps/patterns)** — Charts, tables, dashboards, and other common examples
|
|
- **[Development](/apps/development)** — Preview app tools locally with `fastmcp dev apps`
|
|
- **[Prefab UI Docs](https://prefab.prefect.io)** — Full component reference, advanced state patterns, and more
|