Skip to main content

​
Host Contract

What prism install promises to the MCP server runtime, and what runtime is allowed to assume.

​
Core principle

Cross-platform is a core tenant of Prism. Prism-the-process (MCP server) detects its OS at runtime. Prism-the-project (the codebase) must ship code that runs correctly on macOS, Linux, and Windows.
The install does all host detection once, at install time, and writes the results into each editor’s MCP env block. Runtime reads env. This eliminates detection drift between install and runtime, and between different agents running against the same install.

​
What install writes into each editor’s MCP env block

​
What runtime is allowed to assume

  1. PRISM_API_URL + PRISM_API_KEY are set and reachable via HTTP. If not, preflight warns; backend calls fail cleanly.
  2. PROJECT_ROOT is writable by the user running the MCP server.
  3. PRISM_HOST_OS is one of darwin, linux, win32. If unset, runtime falls back to live platform.system() and logs the gap.
  4. PRISM_GITHUB_USER is a valid GitHub handle (no spaces, no slashes). If unset, prism_clone’s auto-derive attempts git config user.name live.
  5. Binaries on PATH: git, python3.11+, node (for npx of the filesystem MCP; only needed at editor-runtime, not install-time).

​
What runtime is NOT allowed to assume

  • A specific package manager (brew / winget / apt). That’s install’s concern; runtime never invokes them.
  • A specific Python other than 3.11+. The venv at mcp/.venv/bin/python (or Scripts\python.exe on Windows) is the interpreter; install set it up.
  • A specific shell. Runtime subprocesses use the binary directly (git, docker), never bash -c "..." style.
  • Internet access during normal tool calls (except git clone, which is explicit user intent and fails with a clear error if offline).

​
Host-side vs backend-side execution contract

Rule of thumb: if it touches the caller’s OS/filesystem/git/editors, it runs in the MCP server (Python, host-side). If it touches Prism’s data stores, it runs in the backend (Docker).

​
Backend deploy shapes

Three backend targets, all independent of host OS: The MCP server’s only connection to the backend is PRISM_API_URL + PRISM_API_KEY. Backend never knows what OS the caller is on. That’s orthogonal to everything else.

​
Per-OS config file locations

Editors’ MCP config files — where install writes, runtime reads: If any of these change upstream (editor vendor moves the config), update the clients() function in cli/src/index.ts and re-run prism install. Runtime picks up the new path via whatever the TS CLI writes into each editor’s MCP block. (The legacy Python install/ tree is deprecated per the TS migration — do not add new client paths there.)

​
Re-running install when host state changes

The install manifest is pinned at install time. If any of these change, re-run prism install to refresh (idempotent, auto-detects existing backend, preserves user-added env keys unless --force is passed):
  • OS upgrade (Windows 10 → 11; macOS major version)
  • New editor installed (Codex was absent, now installed)
  • New git identity (git config --global user.name changed)
  • $PROJECT_ROOT relocated
Runtime won’t notice these automatically — by design. Re-install is cheap and idempotent.

​
Dev-side invariants

When adding new host-touching features:
  1. Never call platform.system() in runtime code. Use os.environ["PRISM_HOST_OS"].
  2. Never call Path.home() for config paths. Use PRISM_APP_SUPPORT / PROJECT_ROOT.
  3. Never assume a package manager. If install is wrong, fix it in install.
  4. Add any new host-dependent value to the install env block + this doc + the _startup_preflight() check list in mcp/server.py.
Last modified on April 24, 2026