Architecture

ast-mcp separates protocol handling from repository policy and mutation mechanics.

MCP host
  │
  ├─ stdio transport ───────┐
  └─ Streamable HTTP ───────┤
                             ▼
                       MCP server
                             │
           ┌─────────────────┴─────────────────┐
           ▼                                   ▼
  direct ast-bro tools                 file lifecycle tools
           │                                   │
           └──────────── root policy ──────────┘
                                               │
                                  patch state machine
                                               │
                                dprint candidate formatting
                                               │
                                  deterministic file locks
                                               │
                                    atomic replacement

Protocol layer

The stdio transport supports JSON-RPC batches while preserving one framed response per request and no response for notifications. Streamable HTTP uses SSE by default and maintains MCP sessions with bounded idle cleanup.

Policy layer

Every path-bearing intelligence and file operation passes through the same configured-root policy. This keeps discovery and mutation inside one trust boundary.

Mutation layer

Structural patches and Aider blocks converge on the same candidate pipeline: validate current state, transform, format, lock, recheck, and atomically replace. The operation never treats successful text generation as permission to overwrite stale state.

Helper boundaries

Cross-cutting normalization, parsing, process capture, installer routing, configuration traversal, and MCP schema contracts live in src/helpers/, segmented by responsibility. Public modules keep their established entry points while delegating pure transformations to these focused helpers, which keeps protocol and mutation orchestration small and independently testable. Website-only URL normalization follows the same boundary under website/src/helpers/.

Fallow analyzes every duplicated pair (minOccurrences = 2) so reusable behavior is consolidated early instead of growing into parallel implementations.

Distribution

The package publishes one Bun-bundled ast-mcp executable with three operational subcommands:

• ast-mcp mcp starts stdio by default; --transport http starts Streamable HTTP
• ast-mcp hook runs blocking host hooks
• ast-mcp install reconciles installation surfaces; update and uninstall manage them afterward

The installed CLI resolves ast-bro and dprint from the package's stable dependency tree. The source and templates remain in the package because the runtime, installer, and generated host surfaces reference them.