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.

25.1 KB
Raw Blame

ChatGPT custom MCP app for MSO

For first-time setup and copyable usage examples, start with How to use MSO MCP.

Current ChatGPT-facing reference. MSO is one open-source MCP server. ChatGPT receives a deliberately compact static projection of MSO-owned generic tools; project-owned MCP tool names are never copied into the global catalog or ChatGPT scan snapshot.

ChatGPT's Developer Mode/App UI can change independently of MSO. Use the current OpenAI MCP/App documentation for exact menu labels, and use MSO Settings → MCP / GET /mcp for the live server/profile signatures.

The exact current server/toolset identity plus the full MSO and compact ChatGPT name/scope catalogs are generated from source in generated/MCP-CATALOG.md. GET /mcp and Settings → MCP remain the live deployed signature authority.

Browser-hosted MCP probes from ChatGPT are allowed only when they target the configured public OS_PUBLIC_ORIGIN; arbitrary origins and ChatGPT-origin requests aimed at loopback remain denied. Additional trusted browser hosts can be added explicitly with comma-separated OS_MCP_BROWSER_ORIGINS. Public OAuth discovery and DCR responses carry CORS metadata; authenticated /mcp echoes only an approved exact origin.

The full generic descriptor regression currently measures about 95 KiB JSON for the generated ChatGPT model profile (roughly 23.5k tokens at a 4-byte/token estimate), while each individual descriptor remains below 8 KiB. CI keeps the complete profile below 96 KiB and each descriptor below 8 KiB. Bytes are the deterministic contract; token estimates vary by tokenizer.

Why ChatGPT gets the full generic profile

The full MSO catalog remains available to generic MCP clients. ChatGPT action scanning is different: it freezes names, titles, descriptions, JSON Schemas, safety annotations and security metadata into a cached action snapshot. Sending every internal MSO capability wastes scan/model context and makes refreshes more fragile.

MSO therefore applies a client profile after OAuth identity is known:

full MCP client
  └─ full MSO catalog

ChatGPT
  └─ compact capability-complete MSO operator catalog
       ├─ workflow / skills / durable sessions / Local Agents
       ├─ bounded VPS + filesystem CRUD + managed apps + browser
       ├─ explicit bounded infrastructure operations
       ├─ project snapshot / diff / knowledge / project-agent tasks
       ├─ Convex status + dynamic Convex MCP schemas/calls
       ├─ explicit MCP Block for validation/action/CRUD input-output
       ├─ full MSO Page + reviewed dev/preview/production app embeds
       └─ dynamic project MCP/function seams for project-owned tools

The profile is fail-closed at both tools/list and tools/call: guessing a hidden full-catalog name returns unknown tool. This profile is a compatibility/context boundary, not a privilege escalation mechanism; the OAuth read < write < exec scope is still enforced independently.

Tool metadata contract

Every advertised MSO tool has:

  • a stable machine name owned by MSO;
  • a human-readable title;
  • a concise action-oriented description;
  • bounded inputSchema and an outputSchema for every ChatGPT action; UI/critical tools use typed schemas while dynamic tools share one exact { result } envelope;
  • explicit boolean readOnlyHint, destructiveHint, and openWorldHint annotations;
  • optional idempotentHint where meaningful;
  • matching top-level and _meta.securitySchemes OAuth metadata.

The ChatGPT projection compacts verbose descriptions/schema descriptions without changing names, required arguments, enum/range constraints, scopes, or safety semantics.

Selected lifecycle-sensitive tools also declare an additive mso/actionContract on the full MCP descriptor. The contract names the semantic target, discover/validate/verify path, source-of-truth policy, confirmation mode and concurrency guard. It is documentation/orchestration metadata only: OAuth scope, tool implementation checks, CAS/revision guards, provider policy and explicit confirmations remain authoritative. The compact ChatGPT action snapshot intentionally omits this extra per-tool metadata because the complete ChatGPT profile already sits close to MSO's strict 96 KiB scanner budget; ChatGPT receives the same structured workflow policy through the published skill resources instead, without dropping any action.

Exact ChatGPT model tool profile

The exact current ChatGPT profile is generated under ChatGPT model profile in generated/MCP-CATALOG.md. It automatically projects every MSO-owned generic model/operator tool registered in lib/mcp/tools.ts; only the two compatibility bridges marked app-only remain outside model tool calling. Project-owned MCP names still never enter the global catalog. OAuth read < write < exec remains enforced independently.

The restored Original MSO operator primitives (sys_*, fs_usage + full bounded filesystem CRUD, apps_*, browser power/status, and Dokploy/Cloudflare/Hostinger operations) are again first-class ChatGPT actions. Fresh 3 adds vps_status, project snapshot/diff/history/knowledge, private project-agent message/status, connection inventory, and Convex database seams without removing the lower-level primitives. This is intentional: aggregate tools optimize common turns; bounded primitives preserve direct operator control.

Project-owned MCP names and Convex's own dynamic schemas still load on demand through project_mcp_tools / project_mcp_call and project_database_tools / project_database_call. That is how MSO keeps a bounded static model profile instead of copying every downstream provider/project action into ChatGPT.

ChatGPT presentation is explicit rather than attached to every operation. workflow_start is headless. render_mso_list renders a compact searchable list/grid from data already fetched by ordinary tools; it is the default lightweight surface for projects, files, sessions, workflows, apps, integrations and agents. render_mso_block opens the compact validation/action/CRUD component and accepts only bounded fields, checks, outputs, and follow-up actions; a button cannot execute a mutation inside either compact widget. render_mso_page opens native MSO views or a code-reviewed development/preview/production app. It accepts only MSO-style routes and server-owned app ids, never arbitrary HTML or an external URL. mso_surface_apps_list exposes the reviewed Page catalog. Apps outside the reviewed Page catalog use the remote browser. Nested frames are limited to code-reviewed exact origins and registry policy; arbitrary third-party URLs are never accepted. User-installed runtime HTML apps do not inherit this trust automatically. render_mso_surface and workflow_status remain app-only compatibility shims for cached clients.

The MCP server also advertises capabilities.extensions["io.modelcontextprotocol/ui"] with the MCP App HTML MIME in legacy initialize and modern server/discover. Native presentation is therefore negotiated explicitly with a host that advertises the same extension; an orchestration/function wrapper may still call the tool while omitting that host-owned presentation context.

render_mso_list, render_mso_page and integration_setup_open use the standard MCP Apps ui.resourceUri binding. List and Page intentionally omit the legacy openai/outputTemplate; Block retains it only for compatibility. Do not mirror openai/outputTemplate onto Page tools: the current ChatGPT host already supports the standard binding, and dual Page bindings can mount the same UI twice. The current Page therefore uses one modern binding and keeps earlier Page URIs only as non-advertised read aliases.

Page enters in inline mode and fills standard MCP Apps containerDimensions.height or maxHeight, with legacy maxHeight and a 680 px fallback. Measured size notifications resize flexible host frames without viewport feedback. Fullscreen and supported PiP remain explicit user actions. See the UI contract.

Structured-result contract

After the Fresh 3 rescan exposed Output schema recommended on non-UI actions, the ChatGPT profile now advertises an output schema on all current ChatGPT transport actions without duplicating dozens of provider/project result definitions. Tools with stable UI-critical shapes keep their explicit typed schemas. Every other ChatGPT action uses one exact outer { result: ... } contract and returns the already-bounded JSON value inside structuredContent.result; its text content is a short acknowledgement so the same payload is not duplicated in the conversation transcript. Full/generic MCP clients keep the historical text-only contract unless a tool explicitly declares structured output. screen_capture keeps the image in MCP content and exposes only safe dimensions/URLs/expiry metadata in the structured envelope—never base64 image bytes.

Native MCP skill snapshot

Fresh 3 also advertises the bounded io.modelcontextprotocol/skills extension. skills/list, skills/get, and resources/read publish a submission-time snapshot of exactly five general official MSO skills: mso-agent-bootstrap, mso, mso-repo-work, mso-service-debug, and mso-deploy. mso-agent-bootstrap is first: it is the first-call orientation sequence for MCP agents. Implementer skill mso-mcp-feature-engineering stays in the live skills_search catalog. Each published skill is now a reviewed bundle containing SKILL.md, contract.yaml, and agents/openai.yaml (plus any skill-specific resources). contract.yaml carries structured routing/lifecycle/safety metadata; agents/openai.yaml carries concise OpenAI display/default-prompt metadata. Publication fails closed when either structured file is missing or invalid. The manifest still includes complete resources plus sha256: digests, refuses symlinks/path normalization conflicts/oversize files, and never publishes operator, project, verified-third-party, or untrusted skill roots. The ordinary skills_search/list/read actions remain the live runtime catalog for the rest.

For the complete non-ChatGPT MSO catalog, scopes, limits, A2A, providers, Tool Forge and other generic capabilities, see MCP.md.

OpenAI plugin package

The portable OpenAI package is generated privately by bun run plugin:stage-private; the source repository remains operator-neutral. Staging projects the reviewed claude-skills/ SSOT into the portable package's required root skills/ directory, generates a root Agent Plugins plugin.json using the supported https://agent-plugins.org/schemas/1.0.0/plugin.schema.json schema, and writes the OpenAI-specific app/interface metadata under extensions.com.openai. A rewritten .codex-plugin/plugin.json is retained only as a compatibility fallback for older clients.

The staged package deliberately does not declare a bundled mcp.json: the live web-capable MSO MCP connection remains the separately authorized registered app at /mcp, preserving OAuth scopes, server-side credentials, dynamic project MCP seams and browser/mobile availability. The repository .app.json stays empty (apps: {}) so a maintainer-specific registered App ID is never committed. Staging resolves the exact App ID from private MSO Integrations, writes it only into the owner-private staged package, and redacts it from command output. A registered-app reference does not install, refresh, select, or authorize the app in ChatGPT.

The source and staged shapes are therefore intentionally different:

MSO source                                  owner-private staged package
├── .codex-plugin/plugin.json               ├── plugin.json
├── .app.json            apps: {}           ├── .app.json       real id, private
├── claude-skills/<skill>/                  ├── skills/<skill>/
└── /mcp + /oauth/*                         └── .codex-plugin/plugin.json

Use bun run plugin:stage-private to regenerate the portable private package and bun run plugin:doctor-private to verify portable/compatibility manifests, skill projection, private modes and redacted app binding. Installation/refresh remains a ChatGPT client action; after a package/app update, reload or refresh the app as required and test native UI in a new conversation launched with the registered app/plugin selected.

Dynamic project capabilities without global project tools

MSO is generic and must not publish another project's MCP tool names.

project_capabilities(project) returns only safe project capability metadata. For a project .mcp.json, it exposes server aliases, transport kind and auth class only — never config contents, env values, headers, tokens or project MCP tool names.

Then:

projects_list
   ↓
project_capabilities
   ↓
project_mcp_tools(project, server)   # exec: may start project code or contact a remote service
   ↓
project_mcp_call(project, server, tool, arguments)

project_mcp_tools starts/connects only the explicitly selected project server and returns its tool schemas on demand. project_mcp_call executes one exact dynamic tool. Those dynamic names remain data and never change MSO's global toolset hash or ChatGPT scan snapshot.

Supported KISS bridge modes:

  • stdio project MCP — fixed command/argv from the project's .mcp.json, no shell; cwd must stay inside the selected project; child environment starts from MSO's credential-scrubbed environment plus only project-declared env;
  • remote HTTP MCP — guarded HTTPS transport with DNS-rebinding/SSRF checks and bounded responses; static project-config headers stay server-side;
  • project OAuth MCP — reported as auth=oauth but fails closed unless that project has an explicit server-side authorization configuration. MSO never copies, invents or exposes another project's OAuth credential implicitly.

Project .mso/functions.json remains a separate generic seam: project_capabilities returns public function schemas and project_function_call executes one fixed-argv function at exec scope.

Local Agent two-way ChatGPT sessions

Each ChatGPT conversation is bound to a separate durable MSO AgentSession using a privacy-safe hash of the host conversation id. Raw ChatGPT conversation ids are not persisted.

The ChatGPT model profile includes:

  • local_agents_list
  • local_agent_message_send
  • local_agent_inbox
  • local_agent_reply
  • local_agent_request_wait
  • local_agent_standby
  • local_agent_request

local_agent_inbox(wait_ms=1..20000) keeps only the current foreground MCP request open, registers the existing in-process Local Agent receiver, and returns early when another same-principal session sends a message. Durable file-backed mailbox state remains authoritative and closes the read→subscribe race. There is no DB, webhook, broker, WebSocket or spawned worker in this path.

local_agent_standby(mode="listen", workflow_id=...) adds a different contract: the exec-scoped call returns immediately and arms server-native durable standby for that exact ChatGPT-bound AgentSession/workflow. After the assistant turn ends, an authorized same-owner correlated request can be claimed by MSO, executed through the existing bounded durable-session/A2A task machinery, replied to, and returned to waiting without another user [continue]. consumerConnected remains false unless a real foreground inbox receiver is actually subscribed.

This capability wakes the durable MSO worker, not the ChatGPT browser tab. MSO does not claim that an inactive ChatGPT conversation UI will spontaneously render a new assistant bubble; host-side relay/rendering is separate. A write-only caller cannot authorize standby execution, notify-only mail never executes, workflow finish/cancel disarms standby, and restart reconciliation rereads the durable mailbox after reinstalling standby listeners.

Original-byte file transfer

MSO exposes two bounded file bridges instead of treating screenshots/previews as general transfer:

ChatGPT file parameter                         VPS file
        │                                         │
        ▼                                         ▼
 fs_upload_file                              fs_export_file
        │                                         │
        ├─ PNG/WebP/JPEG/JSON/ZIP only            ├─ OS_FS_READ_ROOTS + credential denylist
        ├─ 20 MiB streamed cap                     ├─ original bytes, max 10 MiB
        ├─ provenance-bound OpenAI/Azure host       ├─ SHA-256
        ├─ full image/JSON/ZIP validation           ├─ owner+session mso-file resource
        ├─ conflict guard / CAS replace             └─ private browser temp-share fallback
        └─ OS_FS_WRITE_ROOTS

Upload trusts *.oaiusercontent.com directly. When OAuth proves a chatgpt.com callback, openai/fileParams may also use ChatGPT's rotating oaisdmntpr<region>.blob.core.windows.net temporary-file family. A self-declared client name never unlocks that family; generic MCP clients need exact OS_MCP_OPENAI_FILE_HOSTS entries. Raster uploads must fully decode; JSON and ZIP are structurally validated. Identical retries are unchanged, different existing bytes fail by default, deterministic rename is explicit, and replace requires the current expected_sha256. Export returns an owner+conversation-session-bound mso-file:///… resource_link; resources/read returns the exact original blob with expiry/read limits. A separate approved-device browser URL remains available as a human fallback. session_artifacts is still a preview workflow and may recompress large images, so it is not the original-file export path.

OAuth contract

For origin https://mso.example.com:

Purpose URL
MCP server/resource https://mso.example.com/mcp
OAuth authorization https://mso.example.com/oauth/authorize
OAuth token https://mso.example.com/oauth/token
Dynamic client registration https://mso.example.com/oauth/register
Authorization-server metadata https://mso.example.com/.well-known/oauth-authorization-server
Protected-resource metadata https://mso.example.com/.well-known/oauth-protected-resource

MSO OAuth uses authorization code + PKCE S256 for public clients and supports rotating refresh tokens. New OAuth grants are bound to the exact resource=https://<origin>/mcp throughout authorization, code exchange, refresh and MCP bearer validation.

New OAuth access tokens are short-lived (1 hour); refresh credentials rotate and expire after 90 days. Authorization codes are single-use and expire after 60 seconds. Access tokens, refresh tokens and authorization codes are stored only as SHA-256 hashes. Revoking one access token revokes its OAuth grant family, including refresh credentials.

Legacy MSO bearers minted before resource binding remain accepted during migration until they expire/revoke. A fresh ChatGPT reauthorization receives the new resource-bound/refreshable contract.

Streamable HTTP contract

MSO uses Streamable HTTP JSON-RPC over POST /mcp.

  • initialize negotiates a supported MCP protocol version;
  • subsequent requests may send MCP-Protocol-Version; unsupported versions fail before dispatch;
  • the optional GET /mcp SSE listener is not implemented, so Accept: text/event-stream returns 405 Method Not Allowed, as required when a Streamable HTTP server does not provide that listener;
  • non-SSE GET /mcp remains an operator diagnostics endpoint showing the full and ChatGPT toolset signatures;
  • browser Origin validation remains enabled to prevent DNS-rebinding access to local MCP listeners.

Setup / refresh sequence

  1. Deploy MSO over a stable reachable HTTPS origin. Fresh installs already write OS_MCP_ENABLED=1; existing installs preserve their current MCP setting during update.
  2. Set the maximum bearer scope intentionally with OS_MCP_MAX_SCOPE=read|write|exec. Fresh installs default to exec; lower it when a connector needs less privilege.
  3. In ChatGPT Developer Mode / Apps, create or edit the MSO custom MCP app using the /mcp URL.
  4. Choose OAuth and complete the MSO consent flow on an approved owner device.
  5. Select the lowest useful MSO tier. After changing OS_MCP_MAX_SCOPE, rebuild/restart MSO and repeat consent so the connector receives the new ceiling.
  6. Run Scan Tools / Refresh in ChatGPT.
  7. Compare the action snapshot with the current scope-filtered ChatGPT profile in the generated catalog and the live GET /mcp signature. Do not rely on a fixed historical tool count.
  8. Start a new chat when testing a newly scanned draft/action snapshot.

After a schema/profile change, changing production code alone does not replace ChatGPT's frozen action snapshot. Refresh/re-scan (or recreate/republish where the workspace UI requires it) after deployment.

Troubleshooting Scan Tools

If Scan Tools fails, validate in this order:

  1. both OAuth .well-known documents return 200 over public HTTPS;
  2. authorization redirects back with matching state and iss;
  3. authorization/token requests preserve the exact /mcp resource;
  4. the access token is accepted by POST /mcp;
  5. initialize and scoped tools/list succeed;
  6. every tool has title + required safety annotations + matching security schemes;
  7. the ChatGPT descriptor set stays under the in-repo budget gate;
  8. GET /mcp with Accept:text/event-stream returns 405 rather than JSON pretending to be an SSE stream;
  9. the ChatGPT app was actually refreshed/re-scanned after the latest toolset signature changed.

The live diagnostic GET /mcp returns both toolset (full MSO) and chatgptToolset signatures so profile drift is visible without exposing credentials.

Security boundaries

  • MCP tokens never grant SSH/Linux credentials; they authorize MSO tools only.
  • exec_run, project functions and dynamic project MCP calls require exec scope.
  • Project MCP config/env/header values are never model-visible.
  • MSO credentials are scrubbed before child project processes; project-declared env is a project-owned boundary.
  • File operations retain MSO path-root and credential-path guards.
  • Remote HTTP project MCP calls retain MSO's public-address / SSRF / DNS-rebinding guard.
  • Tool hiding is not a substitute for scope checks; list-time and call-time scope enforcement both remain mandatory.
  • Hidden ChatGPT transcript, private chain-of-thought and credentials are never copied into Local Agent/project MCP messages.
  • MSO Block accepts only bounded fields/checks/outputs/actions and never executes a mutation directly; MSO Page never accepts raw HTML/arbitrary URL input, and nested iframe origins are code-reviewed, exact-origin CSP entries revalidated in the widget.
  • The authenticated MSO cockpit stays non-frameable, and user-installed HTML/runtime manifests cannot promote themselves into the ChatGPT frame allowlist.

Private per-installation app binding

The source repository intentionally keeps .app.json free of maintainer-specific App IDs. Each installation can create an OpenAI / ChatGPT App connection in MSO Integrations. The registered App ID is stored only in the owner-private integration store and is redacted from model/tool responses.

To obtain the ID, enable ChatGPT developer mode, register the installation's remote /mcp endpoint, complete Scan Tools and OAuth, then copy the App ID from the registered app details. A browser URL may expose the equivalent technical plugin_asdk_app_... identifier; MSO normalizes that to canonical asdk_app_.... The Version ID shown by ChatGPT is version-scoped metadata and is intentionally not stored or used by MSO.

Use bun run plugin:stage-private to create an owner-private plugin package at ~/.mso/private/plugin-packages/mso. Its generated .app.json contains the selected installation's binding, while the Git checkout remains portable. bun run plugin:link-app without an explicit ID resolves the default private Integrations connection and redacts the ID from stdout. Explicit ID arguments remain only for compatibility/tests and should not be used for personal IDs in shell history.

Staging is preparation, not installation. It does not install, publish, refresh, or select the app in ChatGPT. bun run plugin:doctor-private reports only redacted staging/install-state facts for the machine on which it runs. A local marketplace/plugin cache belongs to that client machine; staging on a remote VPS does not make a ChatGPT web or desktop conversation use that package.

For native MCP Apps acceptance, start a new conversation through the registered MCP App/direct app context (or an actually installed plugin package that references it). A generic function, dynamic-tool, Code Mode, or plugin orchestration wrapper may preserve the tool schema while unwrapping the MCP result and omitting the host-owned app resource context. If render_mso_block returns only structured data in such a wrapper, that is not evidence that the server resource, HTML, CSP, or bridge is broken. Verify that the host invocation retains the app resource binding before changing renderer code. Only a visually mounted component and a real component action round-trip count as native UI acceptance.