mcp-widget-authoring

rbarazi's avatarfrom rbarazi

Create ChatKit UI widgets in MCP servers. Use when building visual components that render in ChatKit from tool results. Covers widget templates with JSON Schema validation, WidgetTemplateService for hydration, BaseMCPServer patterns, and multi-channel support for Slack. Triggers on widget template, MCP widget, tool result widget, or ChatKit Card.

⭐0stars🔀0forks📁View on GitHub🕐Updated Jan 7, 2026⬇️1downloads
[Developer Tools]

When & Why to Use This Skill

The MCP Widget Authoring skill enables developers to create and render rich, interactive ChatKit UI components directly from Model Context Protocol (MCP) tool results. It provides a robust framework for building visual widgets—such as cards, text blocks, and images—using JSON Schema validation and the WidgetTemplateService to ensure data hydration and UI consistency across AI-driven interfaces.

Use Cases

  • Enhancing Tool Outputs: Transform plain text tool responses into structured visual cards for better user experience in applications like weather updates, financial data, or project status.
  • Standardized UI Development: Utilize predefined widget templates and JSON Schema validation to maintain consistent design patterns across multiple MCP servers and tools.
  • Cross-Platform Compatibility: Build UI components that seamlessly translate from ChatKit to other channels like Slack using integrated support for Slack Work Objects and Block Kit.
  • Dynamic Data Hydration: Use the WidgetTemplateService to automatically inject real-time tool data into UI templates, reducing manual coding for complex visual components.
namemcp-widget-authoring
descriptionCreate ChatKit UI widgets in MCP servers. Use when building visual components that render in ChatKit from tool results. Covers widget templates with JSON Schema validation, WidgetTemplateService for hydration, BaseMCPServer patterns, and multi-channel support for Slack. Triggers on widget template, MCP widget, tool result widget, or ChatKit Card.

MCP Widget Authoring

Create visual widgets that render in ChatKit from MCP tool results.

Quick Start

Widgets flow from MCP server → tool result → ChatKit rendering:

MCP Server Tool → WidgetTemplateService.hydrate_for_tool_result() → ui:// resource → ChatKit

Key components:

  1. Widget template file (.widget or .yml)
  2. WidgetTemplateService for hydration
  3. BaseMCPServer for tool registration
  4. MCP-compliant tool result format

Widget Template Format

Create templates in config/ui_widget_templates/:

{
  "version": "1.0",
  "name": "weatherCurrent",
  "copy_text": "Weather in {{location}}: {{temperature}}",
  "template": "{\"type\":\"Card\",\"children\":[{\"type\":\"Text\",\"value\":\"{{location}}\"}]}",
  "jsonSchema": {
    "type": "object",
    "properties": {
      "location": { "type": "string" },
      "temperature": { "type": "string" }
    },
    "required": ["location", "temperature"]
  }
}

Using in MCP Server

class WeatherMCPServer::Server < BaseMCPServer
  server_name "weather"
  widget_resource "ui://widgets/weather/{instance_id}",
    name: "Weather Widget",
    description: "Displays current weather"

  tool :get_current_weather

  def get_current_weather(location:, unit: "celsius")
    weather_data = fetch_weather(location, unit)

    WidgetTemplateService.hydrate_for_tool_result(
      template: :weatherCurrent,
      data: { location: location, temperature: "#{weather_data[:temp]}#{unit_symbol}" },
      text: "Current weather in #{location}: #{weather_data[:temp]}",
      tool_name: "weather"
    )
  end
end

Result Format

The tool result embeds a ui:// resource:

{
  "content": [
    { "type": "text", "text": "Current weather in Toronto: 72°F" },
    {
      "type": "resource",
      "resource": {
        "uri": "ui://widgets/weather/abc123",
        "mimeType": "application/vnd.ui.widget+json",
        "text": "{\"widget\":{...},\"copy_text\":\"...\"}"
      }
    }
  ],
  "isError": false
}

Reference Files

For detailed patterns, see: