🚧 Public preview — pre-1.0. All 32 @ggui-ai/* packages ship in lockstep minor waves — the badges below show the current one; the protocol is a draft and may still change between waves. Pin exact versions (see badges below) and watch Releases for each wave's notes; marks the protocol freeze.
The iframe-local GGUI runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the GGUI design system so
2026-11-14
Sao
—
Công cụ
—
Thời gian hoạt động
—
v1.0
Agents describe what they need in natural language; GGUI generates ephemeral, interactive interfaces over MCP. No frontend code, no React templates, no custom components — agents talk, users see UI.
This repo is the open protocol + reference runtime. Self-host with ggui serve; pair against any MCP-aware agent runtime (Claude Desktop, Claude Code, claude.ai, Cursor, ChatGPT desktop, Goose, your own). Zero account required, zero managed infrastructure required, zero cloud dependency.
Quick start — pick your path
1. Composed golden path — platform-composed (guuey-sdk)
One flow from a guuey.json to a rendered, interactive todo UI — every piece a published SDK. guuey's dev tooling runs the agent (@guuey/cli + @guuey/worker), the GGUI runtime is the dev router's injected MCP default, and the web client talks to the router with @guuey/agent-client. This path is platform-composed: it drives the GGUI protocol through guuey's published SDKs. The protocol itself has no guuey dependency — paths 2–4 run without it, and the framework-native samples (path 2) stay first-class.
Prerequisites: Node.js 22+, pnpm, and an ANTHROPIC_API_KEY (one key drives both the agent and GGUI's UI generation).
git clone https://github.com/ggui-ai/ggui && cd ggui
pnpm install # workspace deps — `guuey dev` spawns the colocated
# todo MCP from samples/mcp-servers/todo
export ANTHROPIC_API_KEY=sk-ant-… # in every terminal below
# terminal 1 — the ggui runtime MCP (guuey's dev router injects ggui → this port).
# --dev-allow-all admits the bearer-less local callers (the router's ggui
# connection and the web page's relay). Local dev only.
npx -y @ggui-ai/cli serve --mcp-only --dev-allow-all # http://127.0.0.1:6781/mcp
# terminal 2 — the agent half: guuey.json + a Claude agent worker
cd samples/agents/with-guuey
npm install
npm run dev # guuey dev --serve → http://localhost:6790
# terminal 3 — the web half: chat + rendered ggui cards
cd samples/apps/with-guuey-web
npm install
npm run dev # http://127.0.0.1:6890
Browser-based clients. Pages served from localhost reach the MCP
endpoint out of the box. A page on any other origin — a deployed site,
an Electron renderer — must be allowlisted:
(repeatable; or GGUI_BROWSER_ORIGINS=a,b). The allowlist drives both
MCP-wire Origin validation and the CORS response headers, so one flag
covers both. It is not authentication: it does not change the bearer check on /mcp.
Non-browser clients (Claude Desktop, agents, curl) are unaffected: they
connect server-to-server and ignore CORS entirely.
Open http://127.0.0.1:6890 and ask for your todos: the agent calls the todo MCP, renders an interactive todo UI through GGUI, and your clicks flow back to the agent. Per-sample detail (ports, env vars, known limitations): samples/agents/with-guuey · samples/apps/with-guuey-web. Prefer a scaffolded start? npx @guuey/create-agentic-app scaffolds a guuey agentic app of the same shape (agent + MCP + GGUI + web) in one command.
Dev-server trust:guuey dev runs your agent unjailed with your environment — standard dev-server trust; run it in a container if that posture doesn't fit.
2. Bring your own framework — build from the framework-native samples
The framework-native path to ship an agent end-to-end — no guuey dependency. The canonical samples are complete, runnable pieces of an agentic app — an agent backend per SDK, a stock GGUI server config, a reference MCP server, and a web client. Compose them into a workspace and run the whole thing:
git clone https://github.com/ggui-ai/ggui && cd ggui
# your app = four samples composed into one pnpm workspace:
# samples/agents/<sdk>/ → servers/agent/ (claude-agent-sdk | openai-agents-sdk | google-adk)
# samples/gguis/default/ → servers/ggui/ (stock `ggui serve` config)
# samples/mcp-servers/todo/ → servers/mcps/todo/ (reference domain MCP)
# samples/apps/ggui-basic-web/ → apps/web/ (Vite + React chat client)
# (e2e/samples-render/app-shell/ is the reference root wrapper — package.json
# with the dev scripts + pnpm-workspace.yaml + the `pnpm dev` orchestrator.)
pnpm install
# put your LLM API key in .env.local, then:
pnpm dev # starts ggui + MCP servers + agent + web, then opens the app
pnpm dev brings all four services up together and opens http://localhost:6890 once it's ready — so you never have to guess which port to visit (server logs are hidden by default; pnpm dev --verbose streams them). The full loop runs locally: you type → the agent calls domain tools and renders a React UI → you click in that UI → the agent reacts. Each sample carries its own README with standalone run instructions.
Building a hosted agent instead? See guuey.com — the managed platform for running agents (not a drop-in replacement for the samples path).
3. Self-host the OSS MCP server + test from claude.ai
For testing the GGUI protocol against a real chat host. Localhost won't work from claude.ai — you need a public HTTPS URL, which cloudflared provides for free.
# terminal 1 — a public HTTPS URL for port 6781 (no Cloudflare account needed)
cloudflared tunnel --url http://127.0.0.1:6781 # prints https://<random>.trycloudflare.com
# terminal 2 — boot the OSS MCP server behind that URL
npm install -g @ggui-ai/cli
ANTHROPIC_API_KEY=sk-… ggui serve --mcp-only --oauth \
--public-base-url https://<random>.trycloudflare.com # banner prints the pair code
Browser-based clients. Pages served from localhost reach the MCP
endpoint out of the box. A page on any other origin — a deployed site,
an Electron renderer — must be allowlisted:
(repeatable; or GGUI_BROWSER_ORIGINS=a,b). The allowlist drives both
MCP-wire Origin validation and the CORS response headers, so one flag
covers both. It is not authentication: it does not change the bearer check on /mcp.
Non-browser clients (Claude Desktop, agents, curl) are unaffected: they
connect server-to-server and ignore CORS entirely.
--oauth lets claude.ai connect without a pre-shared bearer, and --public-base-url makes the server answer on the tunnel host and hand claude.ai URLs it can reach. Then in claude.ai → Settings → Connectors → Add custom connector, paste https://<random>.trycloudflare.com/mcp and leave the OAuth Client ID and Secret empty (the server uses Dynamic Client Registration). Click Connect: your server's consent page asks for the pair code from the ggui serve banner. The code works once and expires after about 10 minutes; restart ggui serve for a fresh one. Ask Claude to render any UI; the server generates the component and serves it back as a rich rendered card inside the chat.
Install cloudflared via your package manager: brew install cloudflared (macOS), apt install cloudflared (Debian), or grab a binary from cloudflare.com/products/tunnel.
4. Use the hosted GGUI cloud — mcp.ggui.ai
To skip self-hosting, use the hosted service (Public preview): sign in at the GGUI console → create an app → mint a connector key. Paste the bare https://mcp.ggui.ai endpoint into your chat host's connector settings — no tunnel, no server to run.
The ggui CLI
@ggui-ai/cli ships the ggui binary — the single entrypoint for every OSS workflow. Five verbs cover the core workflow:
Verb
What it does
ggui serve
Boot the OSS MCP server (/mcp), session viewer (/r/<shortCode>), pairing endpoints, and live-channel WebSocket. --mcp-only skips agent supervision — fastest first-run. --port, --host adjust binding.
ggui dev
Local UI registry + compile-on-demand dev hub for iterating on a ggui.json project. Optional tunnel, agent supervision, browser auto-open. Run ggui --help for the full flag list.
ggui blueprint
Author + publish + install cached UI templates — create, publish, install. Blueprints make a known screen cheap, repeatable, and visually consistent by matching before falling back to full LLM generation.
ggui gadget
Author + publish + install client-side libraries (maps, charts, camera, clipboard, anything) wrapped as GGUI hooks/components so the generator can use them — create, publish, install.
ggui theme
Validate and inspect ggui.json#theme DTCG documents — ggui theme validate <path>. Catches schema errors before they reach the runtime.
Plus auth verbs for the hosted path: ggui login / ggui logout / ggui whoami / ggui keys. Run ggui --help for the top-level overview, or ggui <verb> --help for per-command flags.
samples/gguis/ — ready-to-run project configs (default, leaflet-demo, mapbox-demo, canvas-demo) showing how a ggui.json is shaped.
samples/agents/ — framework-native reference agents per SDK (Claude Agent SDK, OpenAI Agents SDK, Google ADK) talking to GGUI as an MCP server.
samples/agents/with-guuey + samples/apps/with-guuey-web — the platform-composed (guuey-sdk) golden-path pair: a guuey.json Claude agent served by @guuey/cli's dev router, and a web client on @guuey/agent-client rendering GGUI cards (see path 1 above).
samples/gadgets/ — example component / hook gadgets for the marketplace.
samples/mcp-servers/ — minimal domain MCP servers (e.g. a todo server) you can pair against.
Honest scope today
✅ Local server, viewer, cookie-authenticated WebSocket subscribe → ack all work end-to-end.
✅ ggui_render mints shortCodes and lands on the same-origin viewer.
✅ Component-code generation is wired on the OSS path via createUiGenerator() from @ggui-ai/ui-gen (the same harness the hosted runtime uses). When no BYOK credentials resolve (no ANTHROPIC_API_KEY / OPENAI_API_KEY / etc.), ggui_render returns an isError: true tool result whose structuredContent.error.code is NO_CREDENTIALS; supply a key to get full generation locally.
🔒 ggui serve defaults to strict pairing: only pair-minted bearers reach /mcp (--dev-allow-all admits any bearer, or none, for local dev only). Embedding createGguiServer() without an auth option admits any bearer, or none, as builder; pass a real AuthAdapter via createGguiServer({ auth }) before exposing it beyond 127.0.0.1.
Your agent uses MCP tools to push UIs and receive user events. The protocol is defined by @ggui-ai/protocol; the reference server lives in @ggui-ai/mcp-server; embedding host-helpers ship in @ggui-ai/mcp-apps-react (web) and @ggui-ai/mcp-apps-react-native (React Native).
MCP tools (primary surface)
Tool
Description
ggui_render
Render a UI for the user (natural-language prompt + data)
ggui_update
Update props on an existing UI (no regeneration, ~200ms)
ggui_handshake
Initial session bootstrap
ggui_consume
Long-poll for user gestures (clicks, form submits)
Plus a blueprint family (ggui_search_blueprints, ggui_render_blueprint, ggui_list_featured_blueprints, …) for catalogue lookups. Full reference: MCP Protocol Reference.
Zero agent code (MCP config only)
If your agent runtime supports MCP natively, skip the SDK entirely. Run ggui serve --dev-allow-all for local development and add it as an MCP server:
--dev-allow-all accepts any bearer, so dev is a placeholder. Without the flag, ggui serve admits only pair-minted bearers: pair with the code on its boot banner (landing page or POST /pair) and put the token you receive in place of dev.
The runtime's native tool-calling loop discovers ggui_render, ggui_update, ggui_consume, and the blueprint catalogue tools directly. Working examples per framework: Claude, OpenAI, Gemini, generic MCP.
Embedding UIs
On web, <AppRenderer> — imported directly from @mcp-ui/client, the spec-canonical MCP Apps host — is the canonical consumer primitive, driven by GGUI's useMcpAppsChat hook from @ggui-ai/mcp-apps-react. <AppRenderer> mounts each GGUI render inside a sandboxed iframe; the iframe owns the WebSocket lifecycle and renderer bundle, so host code never touches render internals or WebSocket machinery directly.
Author wrappers for 3rd-party libs (Leaflet, Mapbox, …)
Plus 26 supporting packages under packages/ spanning the runtime (@ggui-ai/mcp-server-core, @ggui-ai/mcp-server-handlers, @ggui-ai/ui-gen, @ggui-ai/negotiator), authoring (@ggui-ai/project-config, @ggui-ai/ui-registry), registry (@ggui-ai/registry-core, @ggui-ai/registry-server), and dev tooling (@ggui-ai/dev-stack, @ggui-ai/agent-runtime, @ggui-ai/console). See each subdirectory for details.
Hosted providers
Self-hosting is the primary path. For managed infrastructure (no server to run, no LLM key to wire, hosted dashboards), the first-party hosted endpoint at mcp.ggui.ai is live — see path 4 above. Guuey hosts an upgraded experience built on top of the protocol. The protocol is identical on all paths — you can move between self-hosted and hosted without rewriting anything against this SDK.
The iframe-local GGUI runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI.
The iframe-local GGUI runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the GGUI design system so
Công cụ
Công cụ
Chưa có danh sách công cụ. Máy chủ từ xa sẽ có danh sách sau lần kiểm tra tình trạng đầu tiên.
Câu hỏi thường gặp
Câu hỏi
Làm thế nào để cài đặt @ggui Ai/iframe Runtime?
Sao chép cấu hình stdio cho Cursor, Claude Desktop, Claude Code hoặc VS Code trên trang này. Cấu hình dùng bản cài đặt của nhà phát hành, không phải proxy của PlugMCP.
Bản ghi này không liệt kê biến môi trường bắt buộc nào.
@ggui Ai/iframe Runtime dùng giao thức truyền tải nào?
@ggui Ai/iframe Runtime chạy cục bộ qua stdio.
@ggui Ai/iframe Runtime được kiểm tra lần cuối khi nào?
Kiểm tra lần cuối: 2026-11-14. The iframe-local GGUI runtime: a self-contained ESM bundle that boots inside an MCP Apps host iframe, runs the protocol-version handshake, opens the live-channel WebSocket, and mounts the rendered UI. Bundles React, ReactDOM, and the GGUI design system so
