fastmcp 2.12.1__py3-none-any.whl → 2.13.2__py3-none-any.whl

fastmcp/utilities/ui.py

@@ -0,0 +1,626 @@
+"""
+Shared UI utilities for FastMCP HTML pages.
+
+This module provides reusable HTML/CSS components for OAuth callbacks,
+consent pages, and other user-facing interfaces.
+"""
+
+from __future__ import annotations
+
+import html
+
+from starlette.responses import HTMLResponse
+
+# FastMCP branding
+FASTMCP_LOGO_URL = "https://gofastmcp.com/assets/brand/blue-logo.png"
+
+# Base CSS styles shared across all FastMCP pages
+BASE_STYLES = """
+    * {
+        margin: 0;
+        padding: 0;
+        box-sizing: border-box;
+    }
+
+    body {
+        font-family: -apple-system, BlinkMacSystemFont, 'Segoe UI', Roboto, 'Helvetica Neue', Arial, sans-serif;
+        margin: 0;
+        padding: 0;
+        min-height: 100vh;
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        background: #f9fafb;
+        color: #0a0a0a;
+    }
+
+    .container {
+        background: #ffffff;
+        border: 1px solid #e5e7eb;
+        padding: 3rem 2.5rem;
+        border-radius: 1rem;
+        box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
+        text-align: center;
+        max-width: 36rem;
+        margin: 1rem;
+        width: 100%;
+    }
+
+    @media (max-width: 640px) {
+        .container {
+            padding: 2rem 1.5rem;
+            margin: 0.5rem;
+        }
+    }
+
+    .logo {
+        width: 64px;
+        height: auto;
+        margin-bottom: 1.5rem;
+        display: block;
+        margin-left: auto;
+        margin-right: auto;
+    }
+
+    h1 {
+        font-size: 1.5rem;
+        font-weight: 600;
+        margin-bottom: 1.5rem;
+        color: #111827;
+    }
+"""
+
+# Button styles
+BUTTON_STYLES = """
+    .button-group {
+        display: flex;
+        gap: 0.75rem;
+        margin-top: 1.5rem;
+        justify-content: center;
+    }
+
+    button {
+        padding: 0.75rem 2rem;
+        font-size: 0.9375rem;
+        font-weight: 500;
+        border-radius: 0.5rem;
+        border: none;
+        cursor: pointer;
+        transition: all 0.15s;
+        font-family: inherit;
+    }
+
+    button:hover {
+        transform: translateY(-1px);
+        box-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1);
+    }
+
+    .btn-approve, .btn-primary {
+        background: #10b981;
+        color: #ffffff;
+        min-width: 120px;
+    }
+
+    .btn-deny, .btn-secondary {
+        background: #6b7280;
+        color: #ffffff;
+        min-width: 120px;
+    }
+"""
+
+# Info box / message box styles
+INFO_BOX_STYLES = """
+    .info-box {
+        background: #f0f9ff;
+        border: 1px solid #bae6fd;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+        font-size: 0.9375rem;
+        line-height: 1.5;
+        color: #374151;
+    }
+
+    .info-box p {
+        margin-bottom: 0.5rem;
+    }
+
+    .info-box p:last-child {
+        margin-bottom: 0;
+    }
+
+    .info-box.centered {
+        text-align: center;
+    }
+
+    .info-box.error {
+        background: #fef2f2;
+        border-color: #fecaca;
+        color: #991b1b;
+    }
+
+    .info-box strong {
+        color: #0ea5e9;
+        font-weight: 600;
+    }
+
+    .info-box .server-name-link {
+        color: #0ea5e9;
+        text-decoration: underline;
+        font-weight: 600;
+        cursor: pointer;
+        transition: opacity 0.15s;
+    }
+
+    .info-box .server-name-link:hover {
+        opacity: 0.8;
+    }
+
+    /* Monospace info box - gray styling with code font */
+    .info-box-mono {
+        background: #f9fafb;
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        padding: 0.875rem;
+        margin: 1.25rem 0;
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        text-align: left;
+    }
+
+    .info-box-mono.centered {
+        text-align: center;
+    }
+
+    .info-box-mono.error {
+        background: #fef2f2;
+        border-color: #fecaca;
+        color: #991b1b;
+    }
+
+    .info-box-mono strong {
+        color: #111827;
+        font-weight: 600;
+    }
+
+    .warning-box {
+        background: #f0f9ff;
+        border: 1px solid #bae6fd;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: center;
+    }
+
+    .warning-box p {
+        margin-bottom: 0.5rem;
+        line-height: 1.5;
+        color: #6b7280;
+        font-size: 0.9375rem;
+    }
+
+    .warning-box p:last-child {
+        margin-bottom: 0;
+    }
+
+    .warning-box strong {
+        color: #0ea5e9;
+        font-weight: 600;
+    }
+
+    .warning-box a {
+        color: #0ea5e9;
+        text-decoration: underline;
+        font-weight: 600;
+    }
+
+    .warning-box a:hover {
+        color: #0284c7;
+        text-decoration: underline;
+    }
+"""
+
+# Status message styles (for success/error indicators)
+STATUS_MESSAGE_STYLES = """
+    .status-message {
+        display: flex;
+        align-items: center;
+        justify-content: center;
+        gap: 0.75rem;
+        margin-bottom: 1.5rem;
+    }
+
+    .status-icon {
+        font-size: 1.5rem;
+        line-height: 1;
+        display: inline-flex;
+        align-items: center;
+        justify-content: center;
+        width: 2rem;
+        height: 2rem;
+        border-radius: 0.5rem;
+        flex-shrink: 0;
+    }
+
+    .status-icon.success {
+        background: #10b98120;
+    }
+
+    .status-icon.error {
+        background: #ef444420;
+    }
+
+    .message {
+        font-size: 1.125rem;
+        line-height: 1.75;
+        color: #111827;
+        font-weight: 600;
+        text-align: left;
+    }
+"""
+
+# Detail box styles (for key-value pairs)
+DETAIL_BOX_STYLES = """
+    .detail-box {
+        background: #f9fafb;
+        border: 1px solid #e5e7eb;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    .detail-row {
+        display: flex;
+        padding: 0.5rem 0;
+        border-bottom: 1px solid #e5e7eb;
+    }
+
+    .detail-row:last-child {
+        border-bottom: none;
+    }
+
+    .detail-label {
+        font-weight: 600;
+        min-width: 160px;
+        color: #6b7280;
+        font-size: 0.875rem;
+        flex-shrink: 0;
+        padding-right: 1rem;
+    }
+
+    .detail-value {
+        flex: 1;
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        font-size: 0.75rem;
+        color: #111827;
+        word-break: break-all;
+        overflow-wrap: break-word;
+    }
+"""
+
+# Redirect section styles (for OAuth redirect URI box)
+REDIRECT_SECTION_STYLES = """
+    .redirect-section {
+        background: #fffbeb;
+        border: 1px solid #fcd34d;
+        border-radius: 0.5rem;
+        padding: 1rem;
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    .redirect-section .label {
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-weight: 600;
+        margin-bottom: 0.5rem;
+        display: block;
+    }
+
+    .redirect-section .value {
+        font-family: 'SF Mono', 'Monaco', 'Consolas', 'Courier New', monospace;
+        font-size: 0.875rem;
+        color: #111827;
+        word-break: break-all;
+        margin-top: 0.25rem;
+    }
+"""
+
+# Collapsible details styles
+DETAILS_STYLES = """
+    details {
+        margin-bottom: 1.5rem;
+        text-align: left;
+    }
+
+    summary {
+        cursor: pointer;
+        font-size: 0.875rem;
+        color: #6b7280;
+        font-weight: 600;
+        list-style: none;
+        padding: 0.5rem;
+        border-radius: 0.25rem;
+    }
+
+    summary:hover {
+        background: #f9fafb;
+    }
+
+    summary::marker {
+        display: none;
+    }
+
+    summary::before {
+        content: "▶";
+        display: inline-block;
+        margin-right: 0.5rem;
+        transition: transform 0.2s;
+        font-size: 0.75rem;
+    }
+
+    details[open] summary::before {
+        transform: rotate(90deg);
+    }
+"""
+
+# Helper text styles
+HELPER_TEXT_STYLES = """
+    .close-instruction, .help-text {
+        font-size: 0.875rem;
+        color: #6b7280;
+        margin-top: 1.5rem;
+    }
+"""
+
+# Tooltip styles for hover help
+TOOLTIP_STYLES = """
+    .help-link-container {
+        position: fixed;
+        bottom: 1.5rem;
+        right: 1.5rem;
+        font-size: 0.875rem;
+    }
+
+    .help-link {
+        color: #6b7280;
+        text-decoration: none;
+        cursor: help;
+        position: relative;
+        display: inline-block;
+        border-bottom: 1px dotted #9ca3af;
+    }
+
+    @media (max-width: 640px) {
+        .help-link {
+            background: #ffffff;
+            padding: 0.25rem 0.5rem;
+            border-radius: 0.25rem;
+            box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
+        }
+    }
+
+    .help-link:hover {
+        color: #111827;
+        border-bottom-color: #111827;
+    }
+
+    .help-link:hover .tooltip {
+        opacity: 1;
+        visibility: visible;
+    }
+
+    .tooltip {
+        position: absolute;
+        bottom: 100%;
+        right: 0;
+        left: auto;
+        margin-bottom: 0.5rem;
+        background: #1f2937;
+        color: #ffffff;
+        padding: 0.75rem 1rem;
+        border-radius: 0.5rem;
+        font-size: 0.8125rem;
+        line-height: 1.5;
+        width: 280px;
+        max-width: calc(100vw - 3rem);
+        opacity: 0;
+        visibility: hidden;
+        transition: opacity 0.2s, visibility 0.2s;
+        box-shadow: 0 10px 15px -3px rgba(0, 0, 0, 0.1);
+        text-align: left;
+    }
+
+    .tooltip::after {
+        content: '';
+        position: absolute;
+        top: 100%;
+        right: 1rem;
+        border: 6px solid transparent;
+        border-top-color: #1f2937;
+    }
+
+    .tooltip-link {
+        color: #60a5fa;
+        text-decoration: underline;
+    }
+"""
+
+
+def create_page(
+    content: str,
+    title: str = "FastMCP",
+    additional_styles: str = "",
+    csp_policy: str = "default-src 'none'; style-src 'unsafe-inline'; img-src https: data:; base-uri 'none'",
+) -> str:
+    """
+    Create a complete HTML page with FastMCP styling.
+
+    Args:
+        content: HTML content to place inside the page
+        title: Page title
+        additional_styles: Extra CSS to include
+        csp_policy: Content Security Policy header value.
+            If empty string "", the CSP meta tag is omitted entirely.
+
+    Returns:
+        Complete HTML page as string
+    """
+    title = html.escape(title)
+
+    # Only include CSP meta tag if policy is non-empty
+    csp_meta = (
+        f'<meta http-equiv="Content-Security-Policy" content="{html.escape(csp_policy, quote=True)}" />'
+        if csp_policy
+        else ""
+    )
+
+    return f"""
+    <!DOCTYPE html>
+    <html lang="en">
+    <head>
+        <meta charset="UTF-8">
+        <meta name="viewport" content="width=device-width, initial-scale=1.0">
+        <title>{title}</title>
+        <style>
+            {BASE_STYLES}
+            {additional_styles}
+        </style>
+        {csp_meta}
+    </head>
+    <body>
+        {content}
+    </body>
+    </html>
+    """
+
+
+def create_logo(icon_url: str | None = None, alt_text: str = "FastMCP") -> str:
+    """Create logo HTML.
+
+    Args:
+        icon_url: Optional custom icon URL. If not provided, uses the FastMCP logo.
+        alt_text: Alt text for the logo image.
+
+    Returns:
+        HTML for logo image tag.
+    """
+    url = icon_url or FASTMCP_LOGO_URL
+    alt = html.escape(alt_text)
+    return f'<img src="{html.escape(url)}" alt="{alt}" class="logo" />'
+
+
+def create_status_message(message: str, is_success: bool = True) -> str:
+    """
+    Create a status message with icon.
+
+    Args:
+        message: Status message text
+        is_success: True for success (✓), False for error (✕)
+
+    Returns:
+        HTML for status message
+    """
+    message = html.escape(message)
+    icon = "✓" if is_success else "✕"
+    icon_class = "success" if is_success else "error"
+
+    return f"""
+        <div class="status-message">
+            <span class="status-icon {icon_class}">{icon}</span>
+            <div class="message">{message}</div>
+        </div>
+    """
+
+
+def create_info_box(
+    content: str,
+    is_error: bool = False,
+    centered: bool = False,
+    monospace: bool = False,
+) -> str:
+    """
+    Create an info box.
+
+    Args:
+        content: HTML content for the info box
+        is_error: True for error styling, False for normal
+        centered: True to center the text, False for left-aligned
+        monospace: True to use gray monospace font styling instead of blue
+
+    Returns:
+        HTML for info box
+    """
+    content = html.escape(content)
+    base_class = "info-box-mono" if monospace else "info-box"
+    classes = [base_class]
+    if is_error:
+        classes.append("error")
+    if centered:
+        classes.append("centered")
+    class_str = " ".join(classes)
+    return f'<div class="{class_str}">{content}</div>'
+
+
+def create_detail_box(rows: list[tuple[str, str]]) -> str:
+    """
+    Create a detail box with key-value pairs.
+
+    Args:
+        rows: List of (label, value) tuples
+
+    Returns:
+        HTML for detail box
+    """
+    rows_html = "\n".join(
+        f"""
+        <div class="detail-row">
+            <div class="detail-label">{html.escape(label)}:</div>
+            <div class="detail-value">{html.escape(value)}</div>
+        </div>
+        """
+        for label, value in rows
+    )
+
+    return f'<div class="detail-box">{rows_html}</div>'
+
+
+def create_button_group(buttons: list[tuple[str, str, str]]) -> str:
+    """
+    Create a group of buttons.
+
+    Args:
+        buttons: List of (text, value, css_class) tuples
+
+    Returns:
+        HTML for button group
+    """
+    buttons_html = "\n".join(
+        f'<button type="submit" name="action" value="{value}" class="{css_class}">{text}</button>'
+        for text, value, css_class in buttons
+    )
+
+    return f'<div class="button-group">{buttons_html}</div>'
+
+
+def create_secure_html_response(html: str, status_code: int = 200) -> HTMLResponse:
+    """
+    Create an HTMLResponse with security headers.
+
+    Adds X-Frame-Options: DENY to prevent clickjacking attacks per MCP security best practices.
+
+    Args:
+        html: HTML content to return
+        status_code: HTTP status code
+
+    Returns:
+        HTMLResponse with security headers
+    """
+    return HTMLResponse(
+        content=html,
+        status_code=status_code,
+        headers={"X-Frame-Options": "DENY"},
+    )