mcpbundles-app-ui

Python library for building MCP App UIs. Define an app declaratively in Python, get self-contained HTML with built-in MCP protocol support and interactive charts.

Installation

pip install mcpbundles-app-ui

Quick Start

from mcpbundles_app_ui import App, LightTheme, Stats, Stat, Card

class MyApp(App):
    name = "My App"
    subtitle = "Analytics overview"
    theme = LightTheme(accent="#3b82f6")

    layout = [
        Stats(
            Stat("preview.total", "Total", primary=True),
            Stat("preview.thisWeek", "This Week"),
        ),
        Card(title="Select an option to explore"),
    ]

# Generate self-contained HTML
html = MyApp().render()

Features

• Declarative components: Stats, Stat, Card, Grid, Chart.bar(), BarList, RecentList, and more
• Theme system: LightTheme and DarkTheme with customizable accent colors, fonts, and all design tokens
• Interactive charts: Built-in canvas chart engine (18 chart types, CSP-safe, zero dependencies) with declarative Python components
• MCP protocol client: Built-in JavaScript for initializeMCP(), callTool(), sendMessage(), askAI()
• Navigation: Breadcrumb system with setBreadcrumbs(), pushBreadcrumb(), popBreadcrumb()
• Loading states: showLoading(), hideLoading(), withLoading(), paginateAll()
• Export utilities: copyToClipboard(), toCSV(), exportAsCSV()
• Toast notifications: showToast() for success/error feedback
• Path-based assets: custom_head and custom_scripts accept Path objects for file-based CSS/JS
• Zero Python dependencies: Only stdlib. Produces standalone HTML with all CSS/JS inline.

Charts

Charts are defined declaratively in your Python layout using Chart factory methods:

from mcpbundles_app_ui import Chart, Grid

layout = [
    Grid(cols=2)(
        Chart.bar("data.byMonth", title="Monthly Revenue"),
        Chart.comparison("data.thisWeek", "data.lastWeek", title="Week over Week"),
    ),
    Chart.funnel("data.pipeline", title="Sales Pipeline"),
    Chart.distribution("data.byCategory", title="Category Breakdown"),
]

The library includes two rendering engines:

• Chart engine — 18 canvas chart types (candlestick, line, area, bar, column, dual axes, scatter, pie, treemap, radar, histogram, heatmap, funnel, table, and 4 card types). Used by chart-driven apps where the user controls views via dropdowns and selectors.
• Tabbed engine — Multi-tool apps where each tab calls a different MCP tool. Charts render within tab content areas with a shared period toolbar.

Charts automatically use the app's theme colors (--chart-1 through --chart-6).

Components

Themes

from mcpbundles_app_ui import LightTheme, DarkTheme

# Custom accent color
theme = LightTheme(accent="#8b5cf6")

# Custom fonts
theme = LightTheme(
    accent="#3b82f6",
    font_family="'Inter', system-ui, sans-serif",
    font_url="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&display=swap",
)

File-Based Assets

Load CSS/JS from files instead of inline strings:

from pathlib import Path
from mcpbundles_app_ui import App, LightTheme

class MyApp(App):
    name = "My App"
    theme = LightTheme()
    custom_head = Path(__file__).parent / "assets/styles.html"
    custom_scripts = Path(__file__).parent / "assets/app.js"

License

MIT