Host installation

The installer reconciles four managed surfaces: MCP configuration, hook payloads and registration, the ast-mcp skill, and a marked instruction block.

Global installation uses each host's home configuration. Managed blocks and entries have exact identities so unrelated MCP servers, hooks, skills, and instructions remain untouched.

Scope and targets

Install the package locally with the package manager used by the repository:

npm install --save-dev @mwillbanks/ast-mcp

When installing with Bun, allow the pinned native installers:

bun pm trust @ast-bro/cli dprint

Then manage local host surfaces through the stable repository-local executable:

./node_modules/.bin/ast-mcp install --scope local --target codex --root "$PWD"
./node_modules/.bin/ast-mcp update --scope local --target all --root "$PWD"
./node_modules/.bin/ast-mcp uninstall --scope local --target all --root "$PWD"

Stdio is the default. For Streamable HTTP, supply the endpoint and optionally manage it as a user service:

./node_modules/.bin/ast-mcp install \
  --scope local --target all --root "$PWD" \
  --transport http --host 127.0.0.1 --port 3768 --service

Without --service, start the printed manual command before connecting the host. update preserves an existing transport when --transport is omitted; pass an explicit transport when selected host entries disagree. Use --no-service to remove a managed service without uninstalling host entries.

For a persistent global installation:

npm install --global @mwillbanks/ast-mcp

Then manage the global host surfaces:

ast-mcp install --scope global --target claude
ast-mcp update --scope global --target all
ast-mcp uninstall --scope global --target all

Yarn 2+ should use a project-local installation because it does not provide Yarn Classic's global workflow. The package must remain installed so the configured mcp and hook subcommands can resolve ast-bro and dprint from its stable dependency tree. Binary lookup checks ancestor package bins, package metadata, package-manager global bins, and PATH. Bun's explicit trust step runs the pinned ast-bro and dprint installers instead of leaving their lifecycle scripts blocked. If another manager blocks dependency build scripts, approve those packages through that manager.

Local scope requires a root and records it as AST_MCP_PROJECT_ROOT, a discovery selector that does not override ast-mcp.toml. Global scope writes a project-neutral definition; each connected MCP client supplies workspace roots, with process working directory fallback for clients that do not advertise roots. Install and update validate the applicable layered configuration before changing host files, while uninstall remains available to recover from invalid configuration.

The pinned npm package currently provides a precompiled ast-bro binary only for macOS Apple Silicon. The installer checks the binary before changing host files and prints platform-specific Cargo and AST_BRO_BINARY commands when manual setup is required. See the installation guide for Linux, Windows, and macOS Intel instructions.

Routing hooks

The installed pre-tool hook is a best-effort routing aid. It rejects direct editor tool calls and known manual write, patch, delete, and rename escape hatches so the agent is nudged toward AST intelligence and guarded file tools. It deliberately does not police Git operations, output redirection, repository scripts, or arbitrary process execution; the host agent framework and its sandbox remain responsible for execution security.