ggui-ai/ggui

GGUI 是通用的 MCP-UI 协议——AI 代理与人类用户之间通过运行时协商达成的数据合同。

文档 · 发行作品

🚧 积极开发 — 1.0 之前。 所有32个@ggui-ai/*包均以同步小波形发布——下方徽章显示当前版本;协议为草稿，波浪间仍可能变化。固定精确版本（见下方徽章）并关注每波的音符发布;v1.0标记协议冻结。

---

代理用自然语言描述他们的需求;GGUI 通过 MCP 生成短暂的交互式接口。没有前端代码，没有 React 模板，没有自定义组件——代理说话，用户看到界面。

该仓库是开放协议+参考运行时。自主机为ggui serve;与任何支持MCP的代理运行时（Claude Desktop、Claude Code、claude.ai、Cursor、ChatGPT桌面、Goose、你自己的）配对。无需账户，无需托管基础设施，无需依赖云。

---

快速入门——选择你的道路

1.Composed golden path — platform-composed （guuey-sdk）

从guuey.json到渲染的互动待办事项UI的流程——每个部分都是发布的SDK。

GGUI is an open protocol for generative UI — a runtime-negotiated data contract between AI agents and human users.

Docs · Releases

🚧 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; v1.0 marks the protocol freeze.

---

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