Skip to content

armgit / mso

Public Imported from GitHub
0

Browser-based graphical shell and control plane for a Linux server you own — real terminal, file manager, live metrics and BYOK AI in one mobile-first workspace. Next.js 16 · React 19 · node-pty · Tailwind v4 · shadcn/ui. Public alpha, self-hosted.

11.4 KB
Raw Blame

ChatGPT MCP App UI

MSO exposes three product presentation resources plus one deliberately minimal Native UI diagnostic probe. Ordinary data tools and workflow startup stay headless; clients without MCP Apps keep structured/text results. The model fetches data first, then chooses List, Block or Page as a separate render step. The probe exists only to distinguish server-side resource binding from ChatGPT host mounting and contains no product routing or interaction logic.

Surface Entry tool Resource Purpose
List render_mso_list ui://mso/list-v3.html Searchable compact collections and item actions
Block render_mso_block ui://mso/block-v5.html Validation, actions, bounded CRUD input/output
Page render_mso_page, integration_setup_open ui://mso/page-v16.html Native workspaces, session assets and reviewed project previews
Native probe mso_native_ui_probe ui://mso/native-probe-v2.html Static diagnostic text only; no bridge, iframe, fetch, router or external dependency

Layout and identity

Page fills the host's declared containerDimensions.height, or the full containerDimensions.maxHeight allowance. Legacy window.openai.maxHeight is the fallback, followed by a 680 px working area when no constraint is supplied. The former 48% cap is removed. Height never derives from the current iframe viewport, preventing resize feedback. One Page body owns scrolling; fullscreen uses the actual viewport.

Page reports measured dimensions through ui/notifications/size-changed after the MCP Apps handshake. Legacy hosts can use notifyIntrinsicHeight. The host controls the enclosing frame and may impose a smaller fixed height. Fullscreen/PiP require an explicit click and are hidden when the host declares them unsupported.

Standard host context controls theme, display mode, dimensions and safe-area insets. Standard styles.variables supplies host colors, type, font family and corners; removing an override restores the shared defaults. Legacy OpenAI globals and the browser color-scheme remain compatible fallbacks. Layout responds to the container, including a 320 × 200 viewport; narrow Integrations uses a native service selector instead of a nested scrolling rail. The compact header, readable controls, flat navigation and shared integration styles follow the existing MSO workbench. List, Block, Page and native Integrations embed the existing public/icon.svg mark without an image request; the shell uses that same public asset. Presentation colors, fonts, type scale, spacing, control size, focus, radii and scroll tokens remain in lib/presentation/widget-tokens.ts.

List behavior

List is a pure presentation tool. The model first calls a normal list/search/read tool, reasons over the returned structured data, and then passes only the selected bounded items to render_mso_list. It accepts at most 40 items, four metadata pairs per item, two item actions and three collection actions. layout is list or grid; optional local search filters only the already-rendered items and makes no network request. Icons are semantic tokens, not arbitrary image URLs.

List actions behave like Block actions: a click sends a bounded follow-up message to ChatGPT with the item id/title and requested continuation. The widget never names or directly calls an MSO mutation tool, so OAuth scope, confirmations, concurrency guards, audit and workflow ownership remain authoritative.

Block behavior

Block accepts bounded structured fields, checks, scalar outputs and up to eight actions; it never accepts raw HTML or an arbitrary tool name. A click sends a bounded follow-up message containing the selected action and field values. The agent then uses ordinary scoped tools. Server authorization, validation, rate limits and audit remain authoritative. Private widget state contains current form values. Block has no network or frame allowlist.

Page routes and trust

Route Context / behavior
/ Workspace navigation
/integrations Shared connection manager, Add MCP and private credential forms
/monitor Bounded server status through vps_status
/project Explicit project context; project_get
/diff Explicit project and optional SHA; project_diff
/sessions Latest 50 safe saved conversation summaries belonging to the authenticated MCP client
/assets Paginated private session assets and bounded image/JSON previews through existing artifact tools
/browser Open the MSO remote browser
/apps/<reviewed-id> Reviewed sandboxed iframe preview, or explicit remote-browser handoff

Page mounts a nested frame only for an owner-reviewed registry row with renderer:"iframe". It accepts neither arbitrary HTML nor external URLs from the model. The bounded owner registry (~/.mso/surface-apps.json, or the explicit MSO_SURFACE_APPS_JSON override) supplies app identity, HTTPS origin and approved path. Public source defaults to an empty app catalog. Resource reads rebuild this safe catalog; the browser rechecks app identity, origin and path before mounting or opening it. Resource HTML and frame CSP are built from the same snapshot. Optional project identifies the reviewed project; a conflicting context fails explicitly. Sandbox tokens come only from that snapshot, default to allow-scripts, and exclude top navigation. The cockpit/widget origin is always remote-only. Preview failure exposes Open preview / MSO Browser without stripping frame headers or passing MSO credentials.

Native integration forms and tools use the same capability/connection contracts as the browser. Credentials travel directly to MSO using private, expiring setup authorization, never through chat or ordinary tool arguments. Public guides remain readable without write access. Project MCP and automation contracts are in automation flows.

User-installed HTML apps cannot grant themselves Page trust. The authenticated cockpit retains its framing protections; external sites keep their own authentication boundaries.

Bridge, metadata and compatibility

The MCP transport advertises the standard io.modelcontextprotocol/ui extension with mimeTypes: ["text/html;profile=mcp-app"] in both legacy initialize and modern server/discover. A native host must advertise the matching extension/MIME in its client capabilities for MCP Apps presentation to be negotiated. Without that bilateral capability, MSO remains usable as a normal structured/text MCP server instead of assuming that a ui.resourceUri descriptor alone proves host support.

For host-boundary debugging, the owner-private MCP activity stream records protocol.initialize / protocol.discover with client-ui=true|false plus resources.list / resources.read URI, MIME, result state and duration. It never records the resource HTML itself. This makes a missing host resource fetch observable without exposing widget bytes, OAuth material or tool arguments.

Page initializes MCP Apps protocol 2026-01-26, then sends ui/notifications/initialized. Only parent-source messages are accepted. Tool result notifications and legacy wrapped window.openai.toolOutput use the same route validator. Unchanged outputs do not remount views; teardown clears active forms and observers.

List, Block and Page use the standards-first MCP Apps bridge (ui/initialize, tool-result notifications and ui/message/tools/call where applicable). Their render tools keep _meta.ui.resourceUri as the canonical MCP Apps binding and also mirror it into the compatibility _meta["ui/resourceUri"] key used by the official ext-apps registration helper. resources/list preserves each canonical resource's _meta.ui listing metadata instead of stripping it, so hosts can index the same UI contract before resources/read. Block additionally retains its existing ChatGPT openai/outputTemplate compatibility binding; the other surfaces do not. The Native UI probe remains dependency-free static HTML, but now uses the same descriptor compatibility normalization as the product surfaces. Every ChatGPT tool has an output schema; exact tools, counts and scopes are generated in the catalog.

Resource CSP is explicit: Block allows no nested frames; Page includes only exact reviewed iframe origins and permits its MSO origin for private setup requests. OpenAI requires stricter review for frameDomains; this is an official review boundary, not a blanket iframe ban. OS_MCP_UI_ORIGIN controls the widget origin, otherwise the configured public origin derives it. Legacy redirect metadata supports Open in MSO.

The three product resources and the isolated Native UI diagnostic probe are listed. Immediately previous canonical URIs remain read aliases after a cache-busting release (list-v2, block-v4, page-v15, native-probe-v1), together with the older compatibility aliases. Only the newest canonical URIs are advertised by resources/list. workflow_status and render_mso_surface remain app-only compatibility tools. workflow_start has no UI binding.

Verification and deployment

Run node scripts/e2e/mcp-page.mjs for a small initial host frame, standard-versus-legacy height precedence, fixed/flexible resize, light/dark theme, 280–1280 px widths and 320 × 200 layouts, logo, Add MCP, native sessions/assets/monitor, host design tokens, interactive sandboxed demos, WCAG checks and fullscreen. The release gate runs this browser contract automatically. node scripts/e2e/integrations.mjs adds shared manager user CRUD, keyboard selection, provider search and 320–1920 px reflow. Production release journeys verify authorization, real server handlers and provider revocation using synthetic stores.

After shipping, compare live discovery/version/hash against lib/mcp/toolset.ts and the generated catalog, verify the three product resource URIs plus ui://mso/native-probe-v2.html, call mso_native_ui_probe from a directly selected registered app context, render a List, and reopen the Page. Also inspect the browser network request to /backend-api/ecosystem/widget: success requires that ChatGPT resolves the current template_pointer instead of returning 404. Hosts cache tool and resource descriptors, so a development-app Scan Tools/Refresh and a new conversation are required after a canonical URI/toolset change. The server cannot replace an already mounted document in an old conversation.

Official references:

Per-installation registered app binding

Native MSO UI must be invoked through the registered ChatGPT MCP App rather than a nested function wrapper. Each MSO installation therefore keeps its registered OpenAI App ID in the owner-private OpenAI / ChatGPT App Integrations connection. The public source repository does not contain the maintainer's App ID.

Users get their own ID by enabling ChatGPT developer mode, registering their MSO remote MCP endpoint, completing tool scan/OAuth, and copying the App ID from app details (or the equivalent plugin_asdk_app_... technical ID from the browser URL). The private staging command writes canonical asdk_app_... only into the owner-private package. Version IDs are version-scoped metadata; MSO intentionally does not store or use them.