Installation

Bun is required. The package pins ast-bro and dprint where binary compatibility matters and trusts their pinned install scripts.

From a package registry

Install ast-mcp into a repository so its ast-bro and dprint dependencies remain available, then connect every supported host:

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

When installing with Bun, allow the package's pinned native installers:

bun pm trust @ast-bro/cli dprint

Run the repository-local executable so the configured MCP and hooks retain a stable package path:

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

This installs stdio definitions by default. To install Streamable HTTP definitions, add --transport http --host 127.0.0.1 --port 3768. Add --service for a macOS LaunchAgent or Linux systemd user service; otherwise start the manual HTTP command printed by the installer. Windows supports manual HTTP startup only.

Bun blocks transitive lifecycle scripts by default, so the explicit trust step runs the pinned ast-bro and dprint installers before the MCP starts. If another package manager blocks dependency build scripts, approve @ast-bro/cli and dprint through that manager. npm, pnpm, Yarn Classic, and Yarn 2+ project layouts are supported. Binary lookup checks ancestor package bins, package metadata, package-manager global bins, and PATH.

Targets are codex, claude, copilot, or all. Local installation is the safest default because the generated MCP definition carries AST_MCP_PROJECT_ROOT as a discovery selector. It does not override project ast-mcp.toml values. A global definition stays project-neutral and follows MCP client workspace roots automatically.

ast-bro platform support

@ast-bro/cli@3.0.0 currently publishes a precompiled binary only for macOS Apple Silicon. Before changing host configuration, the ast-mcp installer verifies that the pinned ast-bro binary exists and reports the expected version.

On Linux or macOS Intel, install ast-bro through Cargo and expose its absolute location to the host process:

cargo install ast-bro --version 3.0.0 --locked
export AST_BRO_BINARY="$HOME/.cargo/bin/ast-bro"
printf '%s\n' 'export AST_BRO_BINARY="$HOME/.cargo/bin/ast-bro"' >> "$HOME/.profile"

For Windows PowerShell:

cargo install ast-bro --version 3.0.0 --locked
$env:AST_BRO_BINARY = "$HOME\.cargo\bin\ast-bro.exe"
[Environment]::SetEnvironmentVariable("AST_BRO_BINARY", "$HOME\.cargo\bin\ast-bro.exe", "User")

Install Rust and Cargo from rustup first when needed. The example persists the variable for POSIX login shells; zsh users can write the same line to ~/.zprofile instead. GUI-launched hosts must be started from that configured environment or receive AST_BRO_BINARY through their launcher. Rerun ast-mcp install, then restart the host. If the binary is unavailable or the version is wrong, installation stops before any host file is changed and prints the applicable commands.

From a source checkout

bun install
bun run build
bun run bin/ast-mcp.ts install \
  --scope local \
  --target all \
  --root "$PWD"

Restart or reconnect the host's MCP servers after installation. A configuration file cannot activate a server in an already-running host process.

Verify the installation

Confirm that these file-boundary tools are callable:

• file_hash
• file_read
• file_write
• file_patch
• file_chattr
• file_delete

Then confirm direct intelligence tools such as digest, show, context, impact, and run.

The installed skill includes a checker:

bun run scripts/check-install.ts \
  --scope local \
  --target codex \
  --root "$PWD"

Update or remove

Use update to reconcile every managed MCP entry, hook payload, registration, skill, and marked instruction block. Use uninstall to remove only ast-mcp-managed surfaces.

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

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