How mcp-ui-org/mcp-ui works
Project Type and Purpose
• This is an open-source, multi-language SDK toolkit (monorepo) for the Model Context Protocol (MCP) UI layer.
• It provides:
• A TypeScript Server SDK (@mcp-ui/server) that generates UIResource payloads.
• A TypeScript Client SDK (@mcp-ui/client) featuring <UIResourceRenderer />.
• Language-specific Server SDKs in Python (mcp-ui-server) and Ruby (mcp_ui_server).
• Platform Adapters (App SDK, future hosts).
• Documentation site (VitePress) and numerous examples/demos.
File Structure
• Top-level
• package.json + pnpm-workspace.yaml → monorepo with workspaces.
• docs/ → static docs site powered by VitePress.
• examples/ → client and server demos in TS, Python, Ruby, remote-dom, web-component.
• sdks/ → language SDK projects:
– sdks/typescript/client
– sdks/typescript/server
– sdks/typescript/shared
– sdks/python/server
– sdks/ruby
• CI workflows in .github/workflows/ (build, test, deploy-docs).
• Patterns & Config
• Monorepo via pnpm.
• Package boundary per SDK.
• Examples depend on corresponding SDK packages.
• Docs deployed via GitHub Actions.
README Highlights
• Core Concepts: UIResource payload, mimeType, postMessage protocol.
• Components: Server SDK generates UI resources; Client SDK renders them (iframe or RemoteDOM).
• Adapters: Translate MCP-UI protocol to host APIs (e.g., Apps SDK).
• Examples & Supported Hosts: shows runtime integration.
Main Components & Interactions
a. SDK Packages (Monorepo Workspaces)
• TypeScript Server (@mcp-ui/server)
• TypeScript Client (@mcp-ui/client)
• TypeScript Shared (@mcp-ui/shared)
• Python Server (mcp-ui-server)
• Ruby Server (mcp_ui_server)
b. Examples & Demos
• TS server-demo, Python server-demo, Ruby server-demo
• Client demos: external URL, remote-dom, Web Component
c. Documentation Site
• VitePress builds docs from docs/src → deployed via deploy-docs.yml.
d. CI/CD
• ci.yml runs lint, build, tests across all packages.
• deploy-docs.yml pushes docs to GitHub Pages / custom domain.
e. Runtime Flow
1. Server SDK builds a UIResource (HTML, URL, or RemoteDOM script).
2. Payload travels over MCP (HTTP/SSE).
3. Client SDK <UIResourceRenderer /> chooses:
• <HTMLResourceRenderer> → sandboxed <iframe>
• <RemoteDOMResourceRenderer> → Shopify remote-dom bridge
4. UI Actions posted back via postMessage
5. Adapters intercept & translate postMessage ↔ host APIs (ChatGPT Apps SDK, Postman, etc.)