Skip to main content
Glama
widget-studio

widget-studio

by ericlewis

widget-studio

An agent capability for creating and displaying rich UI widgets (cards, dashboards, task lists, charts, forms, tables) inline in conversations — packaged as a Claude Code plugin, an Agent Skill, standalone CLI scripts, and an MCP server with MCP Apps support. Widgets use the ChatKit widget JSON format, generated by prompting Widget Studio's hosted generator; the JSON is edited directly only for small tweaks.

Architecture

The MCP server is optional — the skills + CLI deliver the full generate→render loop on their own. The server is the layer that adds interactive inline widgets in MCP Apps hosts. Each host gets the richest rendering it supports:

Layer

What it provides

Who uses it

Skills (skills/)

/widget-studio:make — how to prompt the generator well; :tweak — instant JSON edits + re-display; :preview — render saved JSON to PNG/HTML; :doctor — install/render/API health checks

Any skills-capable agent

Reference (skills/make/references/chatkit-widgets.md)

ChatKit component schema for reading and making small edits to generated widgets before re-display

The model, on demand

Scripts (scripts/, bin/)

widget-generate (prompt → widget via hosted API), widget-render (JSON → PNG / standalone HTML), widget-export (→ .widget file for the Widget Studio editor) — self-locating, on PATH in plugin sessions

The full capability, no MCP needed

MCP server (src/)

generate_widget, display_widget, and export_widget (.widget files) tools; interactive MCP Apps iframe with a copy/export action bar in capable hosts, automatic PNG fallback elsewhere

MCP Apps hosts (interactive) + any other MCP client (PNG)

Evals (evals/)

Deterministic golden-render suite (npm run eval) + skill-creator-format LLM eval cases (skills/make/evals/evals.json)

CI / skill iteration

Rendering paths

  • MCP Apps hosts (Claude Desktop, claude.ai, ChatGPT): interactive iframe via the standard _meta.ui.resourceUri → ui://widget-studio/widget.html, a fully self-contained HTML renderer (CSP-safe, light/dark, actions post back to chat). Legacy openai/outputTemplate alias included for older ChatGPT builds.

  • Non-UI MCP clients (Claude Code CLI, others): the server detects the missing MCP Apps capability at initialize and attaches a PNG image of the widget to the tool result instead (see PNG rendering). Override with WIDGET_STUDIO_IMAGE=auto|always|never.

  • No MCP at all: widget-render (scripts/render-widget.mjs) produces the same PNG or a self-contained HTML preview from a widget JSON file.

Related MCP server: ggui

Install

Note: the npx forms and one-click badges below go live with the first npm release of widget-studio-mcp. Until then, use the from-source form — everything else is identical.

Install in Cursor Install in VS Code Install in LM Studio

/plugin marketplace add ericlewis/widget-studio-mcp
/plugin install widget-studio@widget-studio

The plugin registers the MCP server, puts widget-generate/widget-render/widget-export on PATH, and installs the skill family (/widget-studio:make, :tweak, :preview, :doctor). dist/ ships self-contained bundles — no npm install needed.

MCP server, per host

claude mcp add widget-studio -- npx -y widget-studio-mcp@latest

claude_desktop_config.json (Settings → Developer → Edit Config):

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }

Use the install badge above, or .cursor/mcp.json:

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }
code --add-mcp '{"name":"widget-studio","command":"npx","args":["-y","widget-studio-mcp@latest"]}'
codex mcp add widget-studio -- npx -y widget-studio-mcp@latest

Or ~/.codex/config.toml:

[mcp_servers.widget-studio]
command = "npx"
args = ["-y", "widget-studio-mcp@latest"]

As an extension (bundles the MCP server and skills):

gemini extensions install https://github.com/ericlewis/widget-studio-mcp

~/.codeium/windsurf/mcp_config.json:

{ "mcpServers": { "widget-studio": { "command": "npx", "args": ["-y", "widget-studio-mcp@latest"] } } }
goose session --with-extension "npx -y widget-studio-mcp@latest"
amp mcp add widget-studio -- npx -y widget-studio-mcp@latest

ChatGPT connects to remote MCP servers only. Run the HTTP transport behind a tunnel or deploy, then add the URL under Settings → Connectors (developer mode):

npx -y widget-studio-mcp@latest --http 3400   # stateless streamable HTTP, POST /mcp

ChatGPT implements the MCP Apps standard natively, so widgets render interactively; in --http mode the server also always attaches the PNG. Bridge for stdio-only hosts hitting a remote: npx -y mcp-remote https://your-host/mcp.

git clone https://github.com/ericlewis/widget-studio-mcp && cd widget-studio-mcp
npm install && npm run build
claude mcp add widget-studio -- node "$(pwd)/dist/index.js"   # or the equivalent for your host

PNG rendering

Built in — pure JS/WASM (satori + resvg with bundled Inter fonts). No browser, no playwright/puppeteer, no native dependencies, nothing to install.

Develop

npm run build   # typecheck + bundle the iframe app and self-contained server into dist/
npm test        # protocol smoke test (incl. one real API generation)
npm run eval    # render golden fixtures to PNG + offline protocol checks

Manual preview of any widget JSON:

node scripts/render-widget.mjs --in evals/golden/sales-dashboard.json --png dashboard.png
node scripts/render-widget.mjs --in evals/golden/sales-dashboard.json --html dashboard.html

dist/ is committed on purpose: plugin installs copy the repo as-is, so the bundles must ship prebuilt. Rebuild before committing changes under src/.

Notes

  • The Widget Studio API is the unauthenticated hosted service behind the public editor; requests carry a stable random user ID (WIDGET_STUDIO_USER_ID to pin).

  • The renderer covers the full ChatKit component set; unknown components degrade to rendering their children. External images are blocked by host CSP in interactive mode (placeholder shown) but fine in PNG/HTML output.

Available Tools

3 tools
display_widgetDisplay a widgetA
Read-only

Instantly re-render a widget JSON tree from a previous generate_widget result — as-is, or with small edits (fix a label, change a color, update a value). Pass the complete widget node tree as JSON. For new widgets or layout changes, prefer generate_widget.

Inputs: widget (required), name.

export_widgetExport a .widget fileA

Export a generated widget as a .widget file — the Widget Studio editor's format (importable at widgets.chatkit.studio). Pass the generationId from a generate_widget result. Optionally pass a path to also write the file to disk (recommended in local sessions; defaults to .widget in the current directory when path is 'auto').

Inputs: generationId (required), path.

generate_widgetGenerate a widgetA
Read-only

Generate a rich inline UI widget from a natural-language prompt using the Widget Studio designer. This is the primary way to create widgets. Prompt recipe: name the widget kind ('a weather card', 'a leaderboard', 'a boarding pass'), enumerate ALL real data it should show (every number, name, and label — the generator renders exactly what you give it and invents placeholders for what you omit), and add layout/style hints when you care ('use the Table component', 'with a bar chart', 'dark-themed', 'compact'). For static widgets add 'display only, no buttons' — otherwise the generator may invent buttons with made-up action types. Takes 20-60 seconds. To iterate, call again with a refined prompt that restates everything plus the changes (the service is stateless); for tiny tweaks, edit the returned widget JSON and use display_widget instead.

Inputs: prompt (required).

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A4.6/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a distinct role: generate_widget creates new widgets from prompts, display_widget re-renders or lightly edits existing widget JSON, and export_widget persists to a file. The descriptions clearly delineate when to use display instead of generate, avoiding overlap.

    Naming Consistency5/5

    All three tools follow the consistent verb_noun pattern: generate_widget, display_widget, export_widget. Naming is predictable and uniform.

    Tool Count5/5

    Three tools cover the entire widget workflow—creation, editing/rendering, and export—without unnecessary extras. Each tool earns its place, and the count is well-scoped for the server's purpose.

    Completeness5/5

    The tool surface fully covers the widget lifecycle: generate from natural language, display/iterate on JSON, and export to a file. There are no dead ends or obvious missing operations for the stated domain.

    Maintenance

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers