AST MCP — inspect structurally, write safely

A zero-trust MCP boundary for structural code intelligence and deterministic repository writes.

@mwillbanks/ast-mcp gives coding agents one deliberate way to inspect and change a repository. It combines native ast-bro intelligence with bounded file operations, fresh-state checks, structural rewrites, deterministic locks, formatting, and atomic replacement.

The boundary is designed to make the safe path the capable path: agents can map a codebase, trace behavior, inspect impact, and make precise edits without falling back to whole-file source dumps or unguarded editor operations.

What ships

Surface	Purpose
Code intelligence	Maps, symbols, search, context, calls, imports, cycles, impact, and public API inspection
File boundary	Batched hashing, bounded non-AST reads, guarded creation, patching, attributes, and deletion
Routing hooks	Nudge known direct editor and manual mutation attempts toward guarded ast-mcp tools
Agent skill	Teaches the inspection, preview, hash, patch, verify, and recovery workflow
Installer	Reconciles MCP configuration, hooks, skills, and managed instruction blocks
Transports	Protocol-safe stdio and loopback-first Streamable HTTP

The operating model

request
  ├─ inspect source ─► AST intelligence
  ├─ inspect text   ─► bounded file_read
  └─ change files
       ├─ preview intent
       ├─ hash current state
       ├─ acquire deterministic locks
       ├─ apply exact structural or Aider operations
       ├─ format candidate content
       └─ atomically replace ─► verify

AST intelligence stays beneath effective workspace.roots. Version 2 requires explicit [[paths]] rules for external and temporary paths. MCP client roots select projects for global installations. Relative paths resolve from the first effective root. Path rules must authorize symbolic links and their targets.

Overview

What ships

The operating model

Start here

On this page