@mwillbanks/ast-mcp

@mwillbanks/ast-mcp combines native AST intelligence, deterministic file operations, state-machine-enforced edits, best-effort routing hooks, and agent guidance. It gives Codex, Claude Code, GitHub Copilot, and VS Code Copilot a capable repository workflow without granting them an unbounded editor.

Read the documentation

Why ast-mcp

Coding agents need more than a text editor. They need a way to understand code relationships, preserve current state, and prove that an intended change is the change that reaches disk.

| Capability | What it provides | | ----------------------- | --------------------------------------------------------------------------------------------------------------------- | | Structural intelligence | Directory digests, symbols, semantic search, context, calls, dependencies, cycles, impact, and public API inspection | | Guarded file operations | Batched hashing, bounded text reads, deterministic creation, exact patches, attributes, and reference-aware deletion | | Root isolation | One shared path policy for every file and ast-bro operation, with symlink rejection and explicit external-root opt-in | | Safe commits | Fresh SHA-256 checks, deterministic cross-process locks, candidate formatting, hash rechecks, and atomic replacement | | Agent routing | Best-effort hooks, a unified skill, and idempotent installers for Codex, Claude, Copilot, and VS Code |

AST-capable files stay on the intelligence path instead of being retrieved as whole-file text. Unsupported formats use bounded reads and exact Aider search/replace blocks.

The guarded workflow

1. Map the target with digest, show, context, or another direct intelligence tool.
2. Use impact before changing shared or public behavior.
3. Preview exact structural matches with run.
4. Hash every target immediately before mutation.
5. Apply ordered astRules or aiderBlocks through a keyed file_patch batch.
6. Verify the resulting structure and run the repository's own quality gates.

A stale hash, ambiguous match, capped preview, unsupported route, formatter rejection, or lost MCP connection stops the write. ast-mcp never chooses a weaker editor path to force an edit through.

Distribution

Bun is required. The package publishes one Bun-bundled ast-mcp CLI with install, update, uninstall, hook, and mcp subcommands. Host configurations reference the stable installed CLI, so its pinned @ast-bro/cli and dprint dependencies remain available for the lifetime of the installation.

Runtime dependencies are pinned where binary compatibility matters. @ast-bro/cli powers code intelligence and structural rewrites; dprint and its configured plugins format candidate writes across supported languages.

Install

Install the MCP server, best-effort routing hooks, unified skill, and managed instructions into the current repository:

The hooks nudge common direct editor and manual mutation attempts toward ast-mcp. They are not a security boundary and deliberately leave Git operations, output redirection, repository scripts, and arbitrary execution to the host framework and sandbox.

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

When installing with Bun, allow the pinned native installers:

bun pm trust @ast-bro/cli dprint

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

Stdio remains the default. To generate Streamable HTTP entries instead, select HTTP and an endpoint:

./node_modules/.bin/ast-mcp install \
  --scope local \
  --target all \
  --transport http \
  --host 127.0.0.1 \
  --port 3768

Add --service to create and start a macOS LaunchAgent or Linux systemd user unit. Local services require an explicit port. Without --service, the installer prints the manual ast-mcp mcp --transport http startup command. Windows supports manual HTTP startup but not managed services.

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 before configuring a host. npm, pnpm, Yarn Classic, and Yarn 2+ project installations are supported. The runtime resolves binaries from ancestor package bins, package metadata, package-manager global bins, and then PATH.

Targets are codex, claude, copilot, or all. Local surfaces always use ./node_modules/.bin/ast-mcp; global surfaces use a recognized Bun, npm, pnpm, or Yarn global-bin alias. The installer creates version 2 configuration and omits MCP environment fields. Uninstall preserves configuration.

ast-bro platform support

@ast-bro/[email protected] currently publishes a precompiled binary only for macOS Apple Silicon. The ast-mcp installer verifies that the pinned binary can execute before writing host configuration. On Linux, Windows, or macOS Intel, install it through Cargo and set AST_BRO_BINARY to the resulting executable before rerunning the installer:

cargo install ast-bro --version 4.2.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 4.2.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 they are not already available. 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. Restart the host after installation. The installer fails without changing host configuration when the binary is missing or has the wrong version.

From a source checkout:

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

Configuration

Install or update ast-mcp to create ast-mcp.toml. The installer migrates version 1 files and preserves version 2 files.

version = 2

[workspace]
roots = ["."]

[safety]
require_hash = true

[[paths]]
id = "workspace"
path = "."
policies = { read = "allow", write = "allow", delete = "deny" }
follow_symlinks = false
includes = ["**/*"]
excludes = [".git/**"]

[safety.hook]
enabled = true

[formatting]
enabled = true
dprint_config = "./dprint.json"

[[formatting.formatters]]
extensions = [".rs"]
command = "rustfmt"
args = ["--emit", "stdout"]

[http]
host = "127.0.0.1"
port = 3768

Resolution is deterministic: environment overrides, project ast-mcp.toml, the platform global ast-mcp/ast-mcp.toml, then built-in defaults. The server uses MCP client workspace roots when available, so one global installation automatically selects the connected project. Existing environment variables remain supported as explicit overrides.

Formatting uses dprint by default and supports shell-free external formatters. Mutation tools expose a declared files batch. Version 2 requires explicit [[paths]] rules outside the host baseline, including temporary paths. Path rules control symlinks, hashes, and hook policy.

Inspect the result with ast-mcp config validate and ast-mcp config show. See the configuration reference for the full schema, discovery rules, cache behavior, formatter contract, safety semantics, and migration guidance.

MCP configuration

A stdio definition contains the stable local or package-manager global executable alias and mcp subcommand. Generated definitions omit environment fields. Project configuration supplies local roots. Select --transport http during install to generate native URL entries for Codex, Claude Code, Copilot CLI, and VS Code.

Start HTTP manually with ast-mcp mcp --transport http [--host <address>] [--port <number>], or install a user service with --service. CLI flags override environment variables, project TOML, global TOML, and built-in defaults. The endpoint is /mcp; wildcard bind addresses generate loopback client URLs, while explicit non-loopback addresses deliberately expose the server. MCP session IDs correlate requests and are not authentication; stdio remains the trusted default transport. HTTP uses SSE by default and emits one event per request; JSON-array responses require enableJsonResponse.

SIGTERM, SIGINT, and SIGHUP all initiate graceful shutdown. The stdio process closes its MCP server; the HTTP process stops accepting requests, closes every active MCP session, then closes remaining connections. Successful cleanup exits 0, cleanup failure exits 1, and a second signal forces exit 1 while cleanup is pending. SIGHUP intentionally exits after cleanup so the host supervisor can restart ast-mcp from refreshed code and configuration.

Documentation

The full documentation covers installation, host surfaces, code-intelligence selection, file tools, root isolation, the write state machine, Streamable HTTP, evaluation workflows, configuration, and limitations.

Open the documentation website →

Contributing

See CONTRIBUTING.md for the development workflow, quality gates, documentation checks, pull-request expectations, and automated release process.

License

MIT