Overview
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 and graph intelligence with bounded file operations, fresh-state checks, structural rewrites, deterministic locks, optional 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 | Restricted-by-default guarded file operations |
| Routing hooks | Nudge known direct editor and manual mutation attempts toward guarded ast-mcp tools |
| Agent skill | Serves the canonical workflow through MCP Skills, with explicit export for unsupported clients |
| Installer | Reconciles MCP configuration, hooks, 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
├─ optionally format candidate content
└─ atomically replace ─► verifyIn restricted mode, file operations follow the effective host baseline and [[paths]] rules. Unrestricted file access requires explicit configuration and project-session approval; it does not change intelligence workspace roots. MCP client roots still select projects for global installations. See the filesystem access guide.