Installation.md

Installation and validation

Dependencies and configuration

The process supervisor requires the macOS os.waitid interface exposed by Python 3.13+. Older interpreters are rejected before any vendor process is started.

Install and authenticate Cursor separately. The native executable version must match cli-tree.json; its executable_checks are applied before CLI calls and before adapter execution. The package does not install/update a vendor, perform interactive login, or copy credentials.

Provide Python 3.13 or newer as python3 on the environment PATH that launches Computer MCP. The packaged executable uses #!/usr/bin/env python3. A host dependency binding alone does not rewrite this interpreter lookup. A supported interpreter is required even when the vendor executable is explicitly bound.

Install the ZIP through Computer MCP's plugin UI or owner CLI. Installation is not activation or a permission grant. Use plugins list/show to obtain the current revision and installation identity. Review Examples/settings.json, replace its placeholder paths, then configure the plugin through the same UI or plugins configure command. The CLI dependency binding selects the vendor for the CLI contribution; the MCP launch args independently supply --executable for the adapter. These two choices should normally point to the same verified installation.

The example exposes this plugin's complete MCP tool catalog with no extra prefix. It is a host choice, not authorization embedded in the package. Authorize the desired tools/registration and project in the calling profile. Obtain projected CLI and MCP names from the actual host tools/list, rather than constructing names. plugins doctor checks files and configuration; an MCP connection check verifies initialization/catalog, not model execution.

Computer MCP publishes plugin configuration changes to connected clients atomically. New calls use the current configuration; existing work keeps its owning runtime until release. Installation does not grant access, and later calls use current authorization.

No host binary replacement or host release is required. Do not restart the active development control connection merely to test installation.

Build

python3 -m unittest discover -s tests -p 'test_*.py' -v
python3 scripts/validate_native.py --executable /absolute/path/to/agent
python3 scripts/build_package.py /new/output/directory

The builder produces cursor.zip and prints an ID/version/SHA-256 receipt. Identical source bytes produce identical archive bytes. It refuses to overwrite a different existing artifact. The archive contains the manifest, canonical CLI tree, adapters, Skills, examples, manuals and notices. It excludes tests, build scripts, local evidence, caches and credentials. Only executable entrypoints receive executable mode.

CI runs deterministic fixture tests and packaging; it does not install a vendor or invoke a model. Native validation checks the actual version/help and required flags only. ACP initialization without authentication is a separate non-model protocol probe for Cursor. Full authenticated prompt execution remains a separately authorized acceptance run because it can consume subscription/API usage and perform vendor actions.

Isolated host interoperability

After packaging, validate the exact ZIP against the reviewed Computer MCP binary. Select its release version explicitly; a mismatch fails before package extraction:

python3 scripts/validate_host.py \
  --host "/absolute/path/to/candidate/computer-mcp" \
  --expected-host-version X.Y.Z \
  --archive /output/PLUGIN.zip \
  --output /new/evidence/directory

Replace X.Y.Z with the selected host's exact release version and PLUGIN.zip with the package's actual archive name. This uses a temporary directory and the selected host's archive worker and standalone MCP entrypoint. It does not connect to the production App's control socket or database. Vendor tool execution is replaced with inert fixtures; the native version/help check is a separate command. A new evidence directory is required to avoid overwriting an earlier run.

For a candidate host implementing the provider-work contract, add --require-work-ownership. This gate verifies the same connection retains an opened session, a detached prompt waiting for input and an idle session, then observes no owners after confirmed session close. It also checks that the gateway does not reexport the downstream-only resource declaration. Hosts without this observation surface can still run the ordinary interoperability gate without that option.

A real ACP handshake can be checked independently, without authenticating, opening a conversation or invoking a model:

python3 scripts/probe_acp.py --executable /absolute/path/to/agent --output /output/acp-probe.json

Result interpretation

Fixture success proves adapter protocol/ownership behavior against the tested peer, not a real account or model. A native version/help check proves the installed command surface, not backend availability. An unchanged-host isolated catalog/call check proves interoperability for that tested configuration; it is not production installation or public release evidence. Keep these results separate in delivery receipts.