openui-mcp - OpenUI Docs via Context7 MCP

What this skill is

A registration entry that wires snappy-os to the OpenUI documentation served through Context7 as a Model Context Protocol (MCP) server. snappy-chat is built on @openuidev/* (the OpenUI fork of Crayon SDK, March 2026 launch); when subagents work on the chat surface they need OpenUI's API surface - and that surface is iterating fast. Bundling the prose into snappy-os would guarantee staleness within a sprint. Querying it through MCP at dispatch time gives every snappy subagent the live docs without us shipping a copy.

The deliverable from snappy-os's perspective is on-demand access to OpenUI docs from any MCP-capable agent runtime, not a runnable command. Eval is auto-shape - score by frontmatter shape + AGENTS.md presence + reachability of the install_check path (a sentinel that the user's MCP client config exists).

The Context7 ecosystem

Context7 is an MCP server gateway by Upstash. It hosts documentation for hundreds of open-source libraries and exposes them through a single MCP server (mcp.context7.com). OpenUI publishes its docs through Context7 - see https://www.openui.com/docs/mcp - under the library reference /thesysdev/openui.

When you query Context7 from inside an agent runtime that has MCP support (Claude Code, Codex, Cursor, OpenCode, etc.), Context7 returns the OpenUI documentation as tool-call results. The agent reads those results inline; no bundled prose needed.

This means three things land in the same box at once:

1. The docs stay fresh - Context7 mirrors OpenUI's repo; the agent always sees

the latest API.

1. The agent doesn't need to grep through node_modules/@openuidev/* to find

types - the docs answer the question directly.

1. snappy-os doesn't carry a stale OpenUI mirror. The crayon-sdk skill

continues to carry production-tested patterns; OpenUI MCP carries the API surface.

Install

npx -y ctx7 setup --claude

What this does (per Context7's docs):

1. Walks the user through OAuth (interactive browser) to mint an API key.
2. Writes a context7 MCP server entry into the target runtime's config -

for --claude that's ~/.claude/settings.json under mcpServers.

1. Idempotent - running twice just re-confirms the wiring.

Per-runtime flag map:

Subagents cannot bootstrap. First-run OAuth requires an interactive browser, which a sandboxed subagent does not have. The user runs npx -y ctx7 setup --claude once on the dev machine; subagents inherit the wired MCP server through ~/.claude/settings.json. If the install_check fails inside a subagent, surface the error so the orchestrator can prompt the user.

Usage from a prompt

Two patterns. Prefer the specific form - Context7 hosts hundreds of libraries; naming the one you want avoids ambiguity and is faster.

use library /thesysdev/openui to answer: what props does <FullScreen> accept?

use context7 to look up the agUIAdapter signature

The library-reference form (/thesysdev/openui) tells Context7's MCP server exactly which library bundle to query. The broad use context7 form lets Context7 pick - useful for cross-library questions but slower.

What you query

OpenUI MCP answers well for these question shapes:

• <FullScreen> props - what does the full-screen chat shell accept?
• useThread() API - return shape, methods, lifecycle.
• createLibrary registration patterns - how do you register a custom

template library in @openuidev?

• AG-UI event types - what events fire on the OpenUI ag-ui adapter?
• streamProtocol adapter shape - how do you wire a custom transport?
• ChatProvider setup - context provider props and required wrappers.
• Conversation state primitives - useThread, useMessages, persistence

patterns from the @openuidev side (NOT the @crayonai side).

• Component prop drift between Crayon SDK and OpenUI - Context7 has both

libraries; you can A/B them in the same query.

• The C1 vs Crayon SDK vs OpenUI ecosystem split - what's hosted, what's

open-source, what's deprecated.

For a concrete cross-reference, state/skills/crayon-sdk/SKILL.md covers the overlapping ground from the Crayon-SDK angle. The Crayon-SDK skill is the offline reference with battle-tested production patterns (Orbiter-tested, 14 hard-won gotchas in gotchas.md). OpenUI-MCP is the live reference for the latest API surface as it evolves.

When to prefer this over crayon-sdk

When they disagree on API, OpenUI-MCP wins (it pulls from the live repo). When they disagree on a production failure mode, crayon-sdk wins (it has the gotchas that broke real shipped code). When in doubt, query both - the delta itself is informative.

Self-bootstrap rule

Before any work that depends on this skill, verify the MCP wiring is reachable:

test -e "$HOME/.claude/settings.json" || npx -y ctx7 setup --claude

bash state/bin/preflight.sh runs this automatically: if install_check fails, it executes install: and re-verifies. The $HOME/.claude/settings.json sentinel is a v1 honesty gap - it proves the settings file exists but does NOT confirm a context7 entry is wired in. A future enhancement could be a small state/bin/openui-mcp/check.sh that greps the settings file for "context7" and exits non-zero if absent. Tracked in this skill body, not yet a Critical Rule.

Gotchas

• First-run OAuth is interactive. Sandboxed subagents cannot complete it.

Brief subagents to fail fast with a clear error if install_check fails; the user runs setup once on the dev machine.

• **~/.claude/settings.json is shared across ALL agent runs on the

machine.** Once Context7 is wired, every agent runtime that reads that file inherits the MCP server. There is no per-skill or per-project gating.

• MCP support is runtime-dependent. Claude Code: yes. Codex: yes. Cursor:

yes. Gemini CLI: depends on version. Sandboxed agent runtimes that do not speak MCP cannot query Context7 at all - they fall back to the offline crayon-sdk skill.

• The Context7 server is global, not per-snappy-os. If multiple snappy

clones exist on a machine (e.g. a worktree fork), they all share the same MCP wiring. Do not try to install Context7 per-clone; it is a runtime-level artifact.

• Library reference uses /thesysdev/openui not /openui or /openuidev.

Context7 library references use /<github-org>/<repo>. Mis-typing returns "library not found" without explanation.

Steps (when invoked as a snappy verb)

1. Read this file's "Install" and "Usage" sections to know how to query.
2. Verify ~/.claude/settings.json exists; if not, run npx -y ctx7 setup --claude.
3. From the prompt, use use library /thesysdev/openui to <question>.
4. Cross-reference state/skills/crayon-sdk/SKILL.md if the question is about

a production pattern (gotchas, SSE wire format, thread persistence).

1. Append an eval row to state/log/evals.ndjson with skill: "openui-mcp",

eval_mode: "shape".

Provenance

• Provider: Context7 (https://context7.com), an MCP gateway by Upstash.
• Library reference: /thesysdev/openui.
• Reproducibility:

  npx -y ctx7 setup --claude

• Absorbed into snappy-os: 2026-04-28, mirroring the canonical-install

pattern landed for crayon-sdk (commit 5474aea) and the reachability invariant landed for external-dep skills (commit f9fbb34).

Eval

Eval mode is auto-shape (no lib, no sidecar). Auto-shape scoring checks:

• frontmatter (name, description, eval) is valid
• AGENTS.md sibling exists
• install_check path ($HOME/.claude/settings.json) is reachable, OR

install command succeeds and the path becomes reachable

openui-mcp - loader

Per-turn rules for accessing live OpenUI docs via Context7 MCP. Full reference: state/skills/openui-mcp/SKILL.md.

Critical Rules

1. Library ref MUST be /thesysdev/openui. Context7 uses the full

GitHub path. Do not shorten it to /openui or /openuidev.

1. Use this for live reference, not UI transport. openui-mcp answers

questions about APIs, signatures, system prompts, renderer behavior, and language rules. It does not teach a saved ui.openui dashboard contract.

1. Two-skill division. Use openui-mcp for current docs and signatures.

Use crayon-sdk for production failure modes, DOM quirks, and SnappyChat integration gotchas.

1. Subagents cannot bootstrap OAuth. If the runtime is missing the

Context7 wiring, fail fast and surface the install issue instead of pretending the docs are available.

1. Never bundle or invent OpenUI docs. Query the live docs. snappy-os

carries pointers, not frozen copies.

1. Do not teach marker emission or file-backed UI. Never tell another

agent to use [[TOOL:Lang]], resources/ui.openui, or per-skill surface files as the OpenUI contract. The current contract is live composition via compose_inline and artifact persistence via lang_body.

1. Prefer precise answers over vague summaries. If the question is about

a specific component, prop, builtin, or grammar rule, query that exact topic and answer from the live reference.

Commands

Known Pitfalls

• Hallucinating builtins or components. If unsure whether a builtin or

component exists, check the docs instead of guessing.

• Teaching outdated UI doctrine. Do not tell agents to write per-shape

TSX, emit [[TOOL:Lang]], or mount resources/ui.openui files.

• Positional-arg confusion. OpenUI Lang args are positional only.

name: value or name=value syntax is wrong.

Self-Test

• [ ] I will use /thesysdev/openui, not a shortened library ref.
• [ ] I know this loader is for live docs and signatures, not a dashboard.
• [ ] I will pair openui-mcp with crayon-sdk when integration gotchas matter.
• [ ] I will not teach [[TOOL:Lang]] or per-skill .openui files.
• [ ] I will answer specific OpenUI questions from live reference instead of memory when precision matters.

Found a gap? Edit this file. <!-- footer-injection-point -->