open-mcp-apps

English | 简体中文

Give your AI a persistent, reusable UI. It builds the component once — you keep it forever.

open-mcp-apps is an open engine built on the MCP Apps standard (ui://, SEP-1865). It gives any MCP-Apps-capable host (Claude Desktop, claude.ai, …) three things the standard itself doesn't provide:

1. A component registry the AI can write to. Ask for a UI that doesn't exist — the AI reads the authoring guide, writes a single-file HTML component against a tiny window.oma API, and saves it. From that moment open_<name> is a tool, in this chat and every future one.
2. Persistent, versioned data — separate from the UI. Components bind to generic collections of items backed by SQLite plus an append-only change_event ledger. Every mutation is an idempotent domain command (command_id) with optimistic concurrency (expected_version). The AI and the human edit the same store — the widget is just a view.
3. A shell runtime so AI-written components actually work. Serving ui://, the engine wraps the component with the official MCP App bridge, host theming (Claude's design tokens, light/dark), and the window.oma data API. A component is ~50 lines of view code; the protocol, persistence, idempotency and theming are the engine's problem.

The loop

"make me a kanban"
      │
      ▼
list_components ── exists? ──► open_kanban          (reuse, instant)
      │ no
      ▼
get_component_guide ──► AI writes HTML ──► save_component
      │
      ▼
open_kanban  →  rendered inline, themed, persistent — reusable in every future chat

Components accumulate. Each one is single-purpose and independent — a board, a tracker, a splitter — minted for the task in front of you and kept for the next time you need it.

Install (Claude Desktop)

Fastest — hand it to an AI with shell access (Claude Code, or any agent that can run commands). Paste:

Read https://raw.githubusercontent.com/2nd1st/open-mcp-apps/main/INSTALL.md and follow it.

The agent clones, builds, seeds, and registers the server in your Claude Desktop config. (Any install needs a shell — this just hands the shell steps to the agent instead of to you.)

Or do it yourself — one command after cloning:

git clone https://github.com/2nd1st/open-mcp-apps && cd open-mcp-apps
node install.mjs

install.mjs installs deps, builds the shell, seeds the components, and merges an open-mcp-apps entry into claude_desktop_config.json without clobbering your other servers (pinning the exact node that ran it, for the native SQLite ABI). Prefer to wire it up by hand? Run npm install && node build.mjs && node seed.mjs, then add this yourself (Settings → Developer → Edit Config):

{
  "mcpServers": {
    "open-mcp-apps": {
      "command": "node",
      "args": ["/absolute/path/to/open-mcp-apps/src/server.mjs"]
    }
  }
}

Restart Claude Desktop. New here? Open the onboard prompt from the + / slash menu — the AI looks at what you do and proposes a few single-purpose apps worth keeping, then builds the ones you pick. Or just ask directly:

• "show my kanban board" → renders the seed kanban (drag & drop, persistent)
• "make me a habit tracker" → watch it read the guide, write the component, save it, open it
• close the app, reopen, ask again → everything is still there

First-run permissions: the first few tool calls each show an approval dialog — pick "Always allow". The tool set is small and stable on purpose: read-only tools generally skip approval, and the single open_component tool covers opening every component (including ones the AI creates later), so after those first clicks it's zero-prompt forever. You can also batch it in Settings → Connectors → open-mcp-apps → Tool permissions. Note: a Desktop auto-update occasionally resets these decisions (upstream #56954) — just re-allow. Multiple widgets in one conversation work fine (kanban + notes + pomodoro side by side).

What's in the box

src/server.mjs	stdio MCP server; single open_component path (per-component open_<name> tools opt-in)
src/http.mjs	/mcp (stateless Streamable HTTP) + /view/<name> browser viewer, bound to 127.0.0.1
src/store.mjs	SQLite: items + component registry + change_event ledger (idempotent, OCC)
src/shell-runtime.js	browser runtime injected into every component (window.oma)
src/shell.mjs	wraps stored HTML with runtime + design-token fallbacks at serve time
src/guide.mjs	the authoring contract the AI reads before generating a component
components/	seed components — 6 apps (kanban, todo, pomodoro, notes, expense-split, reading-list) + 2 system (settings, dashboard)

node test/server-smoke.mjs   # 113 assertions over real stdio — incl. runtime component creation
node test/http-smoke.mjs     #  16 assertions over the HTTP transport
node test/seed-smoke.mjs     #   7 assertions on the seed / design-kit pipeline

Design positions (why it's built this way)

• UI and data persist separately, both versioned. Components are views; collections are truth; the ledger is history. Swap either without losing the other.
• The AI talks domain commands, never SQL, never raw state. That's what makes human+AI concurrent editing safe (idempotency + optimistic concurrency at the command layer).
• Standard-first. Everything rides the MCP Apps standard bridge — no host-private APIs. One codebase should serve every host that renders ui://.
• Single-purpose, not composite. Each app owns one scenario and its own collection; the engine mints a new one rather than cramming features into an old one. System apps (settings, dashboard) are the deliberate exception — engine-owned, privileged, allowed to see across collections.

Security model

Trust is tiered by where a component came from. Locally-authored and system components run in direct mode. The engine also ships a runner — a sandboxed srcdoc iframe with a CSP-first document and a minimal read-scoped bridge — as the mandatory execution mode for any component that isn't locally trusted, plus reserved security:* / policy:* config keys that generic data writes can't touch and an out-of-band privileged writer.

Honest status: the runner is built and tested but dormant — there is no install-from-elsewhere path yet, so nothing untrusted actually reaches it today. It exists so the door is already the right shape when a shared library lands. Treat it as a foundation, not a shipped guarantee.

Host support (live-tested 2026-07-22)

Host	Renders widgets	Human clicks widget	AI operates data	Same store
Claude Desktop (local stdio)	✅	✅ full loop incl. sendMessage reply	✅	✅
Browser viewer (/view/<name>)	✅	✅ (no chat attached — sendMessage degrades to a notice)	via CLI AI	✅
Codex desktop (ChatGPT app, enable_mcp_apps flag)	✅ experimental	❌ host's widget→server proxy not wired yet (openai/codex#28912)	✅	✅
codex CLI / IDE	— (text fallback by design)	—	✅	✅
ChatGPT web (Work mode)	supported by the standard — needs remote HTTPS (/mcp + tunnel), untested here

Everything rides the standard bridge, so host fixes upstream (e.g. #28912) benefit this project with zero changes.

Status / roadmap

Early v0 — proven end-to-end on Claude Desktop; cross-vendor render + shared store proven on Codex desktop and the browser viewer.

• [x] engine: registry + shell + generic data commands + ledger
• [x] seed components: 6 apps + 2 system components
• [x] AI component creation loop (guide → save → dynamic tool)
• [x] MCP-native onboarding (onboard prompt + instructions hook)
• [x] security foundation: trust tiers + sandboxed runner + reserved config keys
• [ ] npx one-command install
• [ ] remote (Streamable HTTP) mode → claude.ai / ChatGPT / mobile
• [ ] component export/import → sharing → community library
• [ ] activate the runner path for shared/untrusted components

MIT © 2nd1st