Installation

Bun is required. The package pins its native intelligence dependencies. Runtime formatting is disabled by default and uses only formatters that you install and configure.

From a package registryCopy Anchor Link

Install ast-mcp into a repository so its native intelligence dependencies remain available, then connect every supported host:

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

No formatter installation or trust step is required. To enable formatting, install a formatter separately and follow the optional formatting guide.

Run the repository-local executable to install host entries for the project package:

./node_modules/.bin/ast-mcp install \
  --scope local \
  --target all

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.

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. ast-mcp never downloads formatter binaries during file operations.

Targets are codex, claude, copilot, or all. Local stdio definitions use absolute Bun runtime and CLI entry paths, pass mcp, and set the project directory as cwd; global definitions use a recognized Bun, npm, pnpm, or Yarn global-bin alias. Generated definitions omit MCP environment fields. Local installation creates project configuration. Global installation creates project-neutral user configuration. Clients that support MCP Skills can discover the canonical skill from the server. Unsupported clients can use ast-mcp skills export <destination>; see the skills guide.

Platform supportCopy Anchor Link

The native Bun implementation supports macOS, Linux, and Windows without a Rust or Cargo prerequisite.

Optional native parser or embedding artifacts report explicit capability errors when a platform package is unavailable.

From a source checkoutCopy Anchor Link

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

Restart or reconnect the host's MCP servers after installation. A configuration file cannot activate a server in an already-running host process. If startup fails or tools disappear, follow the connection diagnosis guide.

Verify the installationCopy Anchor Link

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. If the host supports MCP Skills, verify that it can discover and load the ast-mcp skill. Otherwise, export the skill explicitly and configure the host to load that directory.

An exported ast-mcp skill includes an installation checker. From the exported skill root, run:

bun run scripts/check-install.ts \
  --scope local \
  --target codex

Update or removeCopy Anchor Link

Use update to reconcile managed surfaces and migrate version 1 configuration. Use uninstall to remove managed host surfaces while preserving configuration. --root remains deprecated for one release.

./node_modules/.bin/ast-mcp update \
  --scope local --target all

./node_modules/.bin/ast-mcp uninstall \
  --scope local --target all