'%20stroke-width='14'%20opacity='.16'%20filter='url(%23soft)'/%3e%3cpath%20d='M246%2056%2098%20141v118'%20fill='none'%20stroke='url(%23frame)'%20stroke-width='18'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M98%20259%2067%20290l31%2031v50l148%2085'%20fill='none'%20stroke='url(%23frame)'%20stroke-width='18'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M266%2056%20414%20141v102'%20fill='none'%20stroke='url(%23frame)'%20stroke-width='18'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M414%20337v34l-148%2085'%20fill='none'%20stroke='url(%23frame)'%20stroke-width='18'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M256%20117v278'%20fill='none'%20stroke='url(%23tree)'%20stroke-width='13'%20stroke-linecap='round'/%3e%3cpath%20d='M256%20169%20205%20132h-43'%20fill='none'%20stroke='url(%23tree)'%20stroke-width='11'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M256%20214%20196%20252h-50'%20fill='none'%20stroke='url(%23tree)'%20stroke-width='11'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M256%20260%20206%20299l-38%2055'%20fill='none'%20stroke='url(%23tree)'%20stroke-width='11'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='M256%20321%20210%20350v33'%20fill='none'%20stroke='url(%23tree)'%20stroke-width='11'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cg%20fill='%230e1831'%20stroke='url(%23tree)'%20stroke-width='9'%3e%3ccircle%20cx='148'%20cy='132'%20r='14'/%3e%3ccircle%20cx='132'%20cy='252'%20r='14'/%3e%3ccircle%20cx='158'%20cy='367'%20r='14'/%3e%3ccircle%20cx='210'%20cy='397'%20r='14'/%3e%3c/g%3e%3cpath%20d='m302%20174-31%2031%2031%2031'%20fill='none'%20stroke='url(%23patch)'%20stroke-width='13'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3cpath%20d='m350%20174%2031%2031-31%2031'%20fill='none'%20stroke='url(%23patch)'%20stroke-width='13'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3ccircle%20cx='326'%20cy='193'%20r='6'%20fill='%238d48f2'/%3e%3ccircle%20cx='326'%20cy='217'%20r='6'%20fill='%238d48f2'/%3e%3cg%20fill='none'%20stroke='url(%23patch)'%20stroke-width='11'%20stroke-linecap='round'%3e%3cpath%20d='M293%20279h111'/%3e%3cpath%20d='M312%20313h92'%20opacity='.9'/%3e%3cpath%20d='M282%20347h63'%20opacity='.82'/%3e%3cpath%20d='M363%20347h41'%20opacity='.55'/%3e%3c/g%3e%3cpath%20d='M256%20365%20297%20338'%20fill='none'%20stroke='url(%23patch)'%20stroke-width='11'%20stroke-linecap='round'/%3e%3cpath%20d='m297%20338%2013%2013%2024-27'%20fill='none'%20stroke='url(%23patch)'%20stroke-width='10'%20stroke-linecap='round'%20stroke-linejoin='round'/%3e%3c/svg%3e)
Concepts
Write boundary
The guarded state machine behind structural and text-file changes.
A requested edit is not enough to authorize a write. ast-mcp requires a route that matches the target's capabilities and proves the caller is operating on current state.
Route selection
| Target | Required route |
|---|---|
| New file | file_write |
| Parseable rewrite-supported source | file_patch with patchStrategy: "ast" |
| Unsupported, unparseable, or inspection-only file | file_patch with patchStrategy: "aider_block" |
| Rename | file_rename |
| Metadata-only change | file_chattr |
| Deletion | file_delete |
Commit sequence
- Resolve the path under an allowed root.
- Confirm the requested route matches the file's capabilities.
- Compare the supplied SHA-256 with current state.
- Build candidate content from reviewed operations.
- Assert that dprint can format the candidate.
- Acquire cooperating locks in deterministic path order.
- Recheck the hash inside the lock.
- Format and atomically replace the file.
- Release locks on success or failure.
A stale hash, ambiguous Aider block, unexpected AST match count, capped preview, formatter rejection, or lost MCP connection is a safe stop.
Concurrency
In-process queues coordinate calls inside one server. Filesystem lock files coordinate cooperating processes. Sorting multi-file lock acquisition prevents lock-order inversions, and the hash recheck inside the lock closes the race between preview and commit.