fastmcp-apps-sdk

Widgets SDK for FastMCP targeting OpenAI Apps SDK. It provides a simple @widget(...) decorator and helpers to:

• Register a text/html+skybridge resource with CSP hints
• Expose a tool with openai/outputTemplate and widget metadata
• Return structured content + narration with build_widget_tool_response

Install

• pip: pip install fastmcp-apps-sdk
• uv: uv add fastmcp-apps-sdk

Usage

from fastmcp import FastMCP
from fastmcp_apps_sdk import widget, build_widget_tool_response, register_decorated_widgets

@widget(
    identifier="pizza-map",
    title="Show Pizza Map",
    template_uri="ui://widget/pizza-map.html",
    invoking="Hand-tossing a map",
    invoked="Served a fresh map",
    html=(
        '<div id="pizzaz-root"></div>\n'
        '<link rel="stylesheet" href="https://persistent.oaistatic.com/ecosystem-built-assets/pizzaz-0038.css">\n'
        '<script type="module" src="https://persistent.oaistatic.com/ecosystem-built-assets/pizzaz-0038.js"></script>'
    ),
    description="Show Pizza Map",
)
def show_pizza_map_widget(pizza_topping: str):
    normalized = pizza_topping.strip()
    if not normalized:
        raise ValueError("Provide a pizza topping to render the widget.")
    return build_widget_tool_response(
        response_text="Rendered a pizza map!",
        structured_content={"pizza_topping": normalized},
    )

mcp = FastMCP(name="demo", instructions="Demo widgets")
register_decorated_widgets(mcp)
mcp.run(transport="http", host="0.0.0.0", port=8080)

Publish to PyPI

See PUBLISH.md for publishing instructions.

Examples / Demo

• See examples/ for Solar System and Pizza widgets.
• Run locally (with uv):
  • uv pip install -e . (or pip install -e .)
  • uv run examples/server.py
  • ngrok http 8080 and use the HTTPS URL as the MCP endpoint.
• Connect to ChatGPT following https://developers.openai.com/apps-sdk/deploy/connect-chatgpt