ifcviewx

The pip package behind IFCViewX Local Studio. One install serves the full viewer at http://127.0.0.1:8765 and adds everything a browser tab alone cannot do:

• IFC to .ifcx conversion with IfcOpenShell, with live progress and cancel
• native IfcOpenShell Python, so the browser never downloads a runtime
• model checks and element schedules that need no generated code
• the viewer exposed to MCP clients (Claude Desktop, Claude Code) as tools
• an optional assistant proxy so the provider key never reaches the browser

Everything stays on your machine.

Install and run

Until the package is on PyPI, install the wheel from the latest release by URL. IfcOpenShell comes with it, so there is nothing else to add (~100 MB):

pip install https://github.com/nbharathik/ifc-viewx/releases/latest/download/ifcviewx-0.1.0-py3-none-any.whl
ifcviewx                            # serves the viewer and opens the browser

ifcviewx model.ifc                  # same, with the model staged and opened
ifcviewx model.ifc --convert        # convert to .ifcx first, then open
ifcviewx convert model.ifc          # terminal conversion (also: ifcx-convert)
ifcviewx mcp                        # MCP over stdio, for AI clients

IfcOpenShell is a plain dependency, so conversion, native Python and model checks are there by default. On a Python it has no wheel for, the install still succeeds and those three report themselves as not configured rather than breaking the viewer. A second ifcviewx model.ifc while one instance runs reuses it: the file is staged into the shared store and the browser opens on the running service.

Local Studio is a self-contained app, not an add-on to the hosted viewer. It carries its own copy of the viewer, serves it from 127.0.0.1, and hands that page its session token, so it opens with everything on and nothing to type. The hosted copy is a separate app that never talks to this service: there is no pairing step and no token to paste anywhere.

Working from a checkout: cd local-bridge && pip install -e .. The service then serves the repo's dist/ from npm run build at the root.

CLI flags

Configuration

Environment variables use the IFCVIEWX_ prefix (the pre-rename IFC_BRIDGE_ names are still read as a fallback).

HTTP API

Everything except /health and /models/{sha} requires the X-IFC-Token header.

Security

Transport. Bound to 127.0.0.1 only. The Host header must be localhost, which blocks DNS rebinding that a token check alone would not. Browser origins must be localhost. The only page this service answers is the copy of the viewer it served itself, so no site on the internet is trusted, including the hosted copy of this same viewer. IFCVIEWX_ORIGINS names extra origins for someone hosting the viewer themselves; it is empty by default, and pointing it at a page you do not control hands that page everything the token protects.

Authentication. A 128-bit per-run token gates every route that writes, executes or describes this machine. Comparisons are constant time, and repeated failures from one client are throttled.

Generated code passes through three layers, because any one of them can be wrong:

1. an AST guard, not a regex scan, so getattr(x, "__cla" + "ss__") is caught like any other dunder access. Imports are allowlisted, and eval, exec, compile, open, globals and friends are rejected outright.
2. a throwaway subprocess with curated __builtins__ (the dangerous names are simply absent), an import hook that re-checks the allowlist at runtime, a scrubbed environment, a temporary working directory, and address-space, CPU and file-descriptor limits where the platform provides them.
3. the edit contract: code never touches the stored source. It runs against a fresh handle, writes a separate result file, and the change only reaches the model after the user clicks Apply in the viewer.

The reply carries a measured diff (added / removed / modified GlobalIds) computed by comparing the model before and after, not the summary the code claims. IFCVIEWX_ALLOW_PYTHON=0 removes the capability altogether.

Data. Uploads are content-addressed, sniffed for a STEP header before they are kept, capped per file and in total, and evicted oldest-first past the quota. Unapplied edit results expire. No filename ever comes from a client.

Auditing. Every guarded action appends one line to ~/.cache/ifcviewx/audit.jsonl: what ran, when, from where, and for code its hash and first line, never the source itself.

What this is not. The service executes IfcOpenShell code on your machine by design. The layers above make accidental and casual-hostile code fail closed; they are not a substitute for an OS sandbox. Run with IFCVIEWX_ALLOW_PYTHON=0 if you only want viewing, conversion and checks.

MCP client configuration (Claude Desktop example)

{
  "mcpServers": {
    "ifcviewx": {
      "command": "ifcviewx",
      "args": ["mcp"],
      "env": { "IFCVIEWX_TOKEN": "choose-a-token" }
    }
  }
}

ifcviewx mcp serves the viewer and the HTTP API too, so the browser side of the bridge is the same app at http://127.0.0.1:8765.

Tools

Viewer: get_status, get_model_info, get_spatial_tree, get_selection, select_element, get_properties, set_visibility, show_all, fit_view.

Analysis without generated code: validate_model, element_schedule.

Files and housekeeping: convert_model, list_converted_models, service_status.

No execution tool. There is no run_python and no other way for an MCP client to execute code. A client reads the model, drives the viewport and stages typed edits, and every edit waits for the user to click Apply. Running IfcOpenShell is the user's, in the viewer's Python Console, which only a human click starts. The service still executes Python for that console over HTTP, authenticated with the session token.

Tests and packaging

python -m pytest tests -q

The suite covers guard bypasses, the route authorisation matrix, store quotas and path safety, and sandbox behaviour end to end against a real IFC file.

Building the wheel bundles the viewer: npm run build at the repo root, then python -m build local-bridge. The hatch hook copies dist/ into the package and refuses to pack without it. Tagging v* publishes to PyPI via .github/workflows/publish-pypi.yml (trusted publishing).