ScopeRail

ScopeRail is a scoped local execution runtime for MCP clients that need to work on a real Mac without receiving unrestricted host access by default. Files, processes, browser sessions and native desktop UI are exposed through one workspace capability model with explicit grants and auditable actions.

It is not just a shell MCP. Shell access is one surface inside a broader permission model: a caller starts from a registered workspace, receives only the profiles and grants the operator enabled, and uses retry-safe primitives that return provenance and observable results.

Install and run

Python 3.12+ and pipx on macOS:

brew install pipx  # skip if pipx is already installed
pipx install "https://github.com/HanpuLi/scoperail/releases/download/v0.2.2/scoperail-0.2.2-py3-none-any.whl"
SCOPERAIL_WORKSPACE_ROOT="$PWD" scoperail stdio

The tagged GitHub wheel is the current working install path and is tested with pipx. PyPI Trusted Publishing is prepared but the first PyPI upload still requires the maintainer's one-time PyPI login; after that, pipx install scoperail is equivalent.

Or register once, then start stdio:

scoperail init "$PWD"
scoperail stdio

For the full OAuth HTTP service, launchd installation and optional reverse-proxy/Tailscale deployment, see docs/install.md.

Security: sandboxed execution is the default. trusted-host, desktop control, Git publishing and similar capabilities are explicit operator choices. Read SECURITY.md and docs/security-model.md before enabling them.

Related MCP server: wisp

What is different

ScopeRail does not embed a model. The connected client decides what to do; ScopeRail enforces and records the execution boundary.

MCP client
   |
   +-- local stdio --------------------------------+
   |                                               |
   +-- OAuth 2.1 / remote HTTPS -- public plane ---+
                                                   v
                                      workspace + grant policy
                                      |      |       |
                           +----------+      |       +----------+
                           v                 v                  v
                       files/git        jobs/shells        browser/native UI
                           |                 |                  |
                           +-------- audit + provenance --------+

Platform and client status

ScopeRail is macOS-first. Native Accessibility control and the Seatbelt sandbox are macOS features. Pure policy/file/package tests may run on Linux CI, but Linux and Windows are not currently advertised as complete runtime platforms.

• Generic MCP clients: local stdio transport is supported.

• ChatGPT: remote OAuth/streamable-HTTP is the primary deployed integration and is exercised by the project.

• Claude / Codex / other MCP clients: the stdio server uses the standard MCP SDK transport; client-specific setup is documented as integration work rather than claimed as continuously tested compatibility.

Native semantic UI

The native desktop path prefers Accessibility over coordinate-only clicking. Observation returns semantic elements and bounds; element actions use fingerprinted ax: refs and fail closed when the target becomes stale, ambiguous or materially moves. Secure values are redacted and secure fields reject semantic value-setting.

Screenshot, mouse and keyboard primitives remain available for apps with incomplete Accessibility trees.

Browser sessions

The managed browser uses a ScopeRail-owned profile. A trusted-host workspace may also attach to an already-running Chromium-family browser only through an operator-configured loopback DevTools endpoint. Existing tabs are treated as external resources: detaching the bridge does not close them.

Remote service

A source checkout can run the full HTTP service with OAuth 2.1, PKCE, dynamic client registration, token rotation/revocation and DNS-rebinding protections. The admin plane listens separately on loopback and is not exposed through the public MCP route.

See docs/quickstart.md, docs/permissions.md, docs/workspaces.md, docs/files.md, and docs/audit.md.

Development

python3 -m venv .venv
. .venv/bin/activate
pip install -e '.[dev]'
python -m unittest discover -s tests -p 'test_*.py' -v
ruff check --select E9,F63,F7,F82 bridge tests scripts
python -m build
twine check dist/*

The maintainer's operational repository may contain machine-specific acceptance evidence. Release candidates are produced as an allowlisted fresh-history tree before they reach this public repository. scripts/verify_public_tree.py, CI secret scanning and package checks enforce the public-tree invariants; the private operational Git history is never imported here.

Contributing

Start with CONTRIBUTING.md, the architecture and the security model. Issues intended for contributors describe the problem and acceptance criteria; the project does not create trivial work to inflate contributor counts.

License

Apache-2.0. See LICENSE and THIRD_PARTY_NOTICES.md.