# mcp-ui-org/mcp-ui architecture

> Architecture diagram of the GitHub repository mcp-ui-org/mcp-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-11-24). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/mcp-ui-org/mcp-ui
- Repository: https://github.com/mcp-ui-org/mcp-ui

## Overview

##### 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.)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo SDK Packages
    subgraph "Monorepo Workspaces"
        direction TB
        TSShared["@mcp-ui/shared"]:::sdk
        TSClient["@mcp-ui/client"]:::sdk
        TSServer["@mcp-ui/server"]:::sdk
        PyServer["mcp-ui-server"]:::sdk
        RubyServer["mcp_ui_server"]:::sdk
    end

    %% Server SDK Adapters
    subgraph "Server SDK Adapters"
        direction TB
        Adapter["App SDK Adapter"]:::sdk
    end
    Adapter --> TSServer

    %% Examples & Demos
    subgraph "Examples"
        direction TB
        ExTS["TypeScript Server Demo"]:::example
        ExPy["Python Server Demo"]:::example
        ExRb["Ruby Server Demo"]:::example
        ExApp["ChatGPT Apps SDK Adapter Demo"]:::example
        ExURL["External URL Client Demo"]:::example
        ExRD["Remote-DOM Client Demo"]:::example
        ExWC["Web Component Client Demo"]:::example
        ExFull["Full-stack TS Remix Server Demo"]:::example
    end

    %% Docs and CI
    subgraph "Docs & CI"
        direction TB
        Docs["VitePress Docs Site"]:::infra
        CI["Monorepo CI Workflow"]:::infra
        DeployDocs["Docs Deploy Workflow"]:::infra
    end

    %% External Registries
    subgraph "Registries"
        direction TB
        NPM["npm Registry"]:::external
        PyPI["PyPI"]:::external
        RubyGems["RubyGems"]:::external
    end

    %% Publish flows
    TSServer -->|publishes| NPM
    TSClient -->|publishes| NPM
    TSShared -->|publishes shared| NPM
    PyServer -->|publishes| PyPI
    RubyServer -->|publishes| RubyGems

    %% CI triggers
    CI -->|runs lint/build/tests| TSShared
    CI -->|runs lint/build/tests| TSClient
    CI -->|runs lint/build/tests| TSServer
    CI -->|runs lint/build/tests| PyServer
    CI -->|runs lint/build/tests| RubyServer

    %% Docs deploy
    Docs -->|source| DeployDocs
    DeployDocs -->|deploy site| Docs

    %% Runtime Flow
    TSServer -->|HTTP/SSE UIResource| TSClient
    TSClient -->|postMessage UI Actions| Adapter
    Adapter -->|host API calls| Host["Host Apps (ChatGPT, Postman, etc.)"]:::external
    Host -->|postMessage responses| TSClient

    %% Example integrations
    ExTS -->|uses| TSServer
    ExPy -->|uses| PyServer
    ExRb -->|uses| RubyServer
    ExApp -->|uses adapter| Adapter
    ExURL -->|uses client| TSClient
    ExRD -->|uses client| TSClient
    ExWC -->|uses client| TSClient
    ExFull -->|uses full stack| TSServer
    ExFull -->|uses client| TSClient

    %% Click Events
    click TSShared "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/typescript/shared"
    click TSClient "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/typescript/client"
    click TSServer "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/typescript/server"
    click PyServer "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/python/server"
    click RubyServer "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/ruby"
    click Adapter "https://github.com/mcp-ui-org/mcp-ui/tree/main/sdks/typescript/server/src/adapters/appssdk"
    click ExTS "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/typescript-server-demo"
    click ExPy "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/python-server-demo"
    click ExRb "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/ruby-server-demo"
    click ExApp "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/appssdk-adapter-demo"
    click ExURL "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/external-url-demo"
    click ExRD "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/remote-dom-demo"
    click ExWC "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/wc-demo"
    click ExFull "https://github.com/mcp-ui-org/mcp-ui/tree/main/examples/server"
    click Docs "https://github.com/mcp-ui-org/mcp-ui/tree/main/docs/src"
    click CI "https://github.com/mcp-ui-org/mcp-ui/blob/main/.github/workflows/ci.yml"
    click DeployDocs "https://github.com/mcp-ui-org/mcp-ui/blob/main/.github/workflows/deploy-docs.yml"

    %% Styles
    classDef sdk fill:#D0E6FF,stroke:#0366d6
    classDef example fill:#DFFFE0,stroke:#28a745
    classDef infra fill:#F0F0F0,stroke:#666666
    classDef external stroke-dasharray: 5 5,fill:#ffffff,stroke:#ff0000
```
