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

• Library ref MUST be /thesysdev/openui - Context7 uses /<github-org>/<repo>. Do NOT use /openui or /openuidev.
• Prefer Specificity - Use use library /thesysdev/openui to <question> instead of broad use context7 to avoid 300+ library ambiguity.
• Two-Skill Division - Use openui-mcp for API signatures and types; use crayon-sdk for production failure modes and battle-tested gotchas.
• Subagents cannot bootstrap - OAuth requires a browser. If ~/.claude/settings.json is missing, fail fast and prompt the user.
• Never bundle OpenUI docs - Always query live. snappy-os carries pointers, not copies, to prevent staleness.

Commands

| ui dashboard | state/skills/openui-mcp/resources/ui.openui |

OpenUI Resource

• Skill-owned OpenUI Lang resource: state/skills/openui-mcp/resources/ui.openui. Read it before rendering or editing this skill's generated component surface.
• Treat this resource as a first-class artifact of the skill, not a generic chat response. Improve it when the skill's user-facing output needs to become richer.
• System resources compose OpenUI primitives and inherit SnappyChat tokens. Use ui_contract: branded in SKILL.md only for deliberate platform or client visuals.

Known Pitfalls

• Hallucinating Primitives - Inventing @Operators (like @Mean) that don't exist in the library. Always check the docs if unsure of a builtin.
• Drafting per-shape files - Agents often try to write new .tsx components for UI. This is a failure. Always use OpenUI Lang composition via [[TOOL:Lang]].
• Positional Arg Confusion - Lang args are positional only. Using name: value or name=value will break the renderer.

Self-Test

An agent reading this should correctly:

1. [ ] Route a question about <FullScreen> props to openui-mcp?
2. [ ] Use the full /thesysdev/openui path in the query?
3. [ ] Recommend a follow-up check in crayon-sdk for complex integration patterns?
4. [ ] Refuse to write a new .tsx component if the task can be achieved via Lang primitives?

Self-report

If this loader fell short, append a line:

echo "[$(date -u +%FT%TZ)] openui-mcp: <what was missing>" >> state/log/loader-feedback.log