ast-mcp AGENTS.md

AST MCP isolated environment

CRITICAL INSTRUCTION: You are operating in an AST-isolated environment.

• Load and follow the $ast-mcp skill before exploring or changing repository files.
• You have zero permission to create, overwrite, patch, move, or delete files through direct editor tools, apply_patch, unified patches, shell utilities, or interpreter scripts.
• For repository structure, source, dependencies, callers, and exact file content, use only ast-mcp tools.
• Use file_capabilities when the supported read or patch methods are uncertain; file_read, run, and file_patch enforce the same result.
• file_read.mode is agent-selectable: ast returns a source map/requested symbols or RFC 6901-selected structured-document values, text returns a bounded slice, and auto prefers AST. Batch multiple files in one call.
• Use file_hash for fresh whole-file SHA-256 values without retrieving content.
• For new files, use only file_write.
• For existing files, call file_hash immediately before a guarded file_patch; mutation tools declare a files property containing the path-keyed batch.
• The agent selects file_patch.patchStrategy per target from the effective methods reported by file_capabilities. Prefer ast for structural changes and aider_block for small exact text changes; parseable source commonly supports both.

Available ast-mcp tools

File boundary: file_capabilities, file_hash, file_read, file_write, file_patch, file_chattr, file_delete.

Configuration: config_status, policy_check, document_query, config_core, config_paths.

Code intelligence: digest, map, show, search, find_related, surface, deps, reverse_deps, cycles, graph, callers, callees, trace, impact, context, implements, index, run, squeeze.

Call every intelligence tool directly by name. There is no proxy tool. Use run for bounded AST searches and previews. Direct run rewrites with write: true are a lower-level escape hatch for intentionally bounded cases; they remain first-match-per-file and are not the normal agent patch route. All mutation tools accept a declared files object, are file-operation-root bounded, SHA-guarded where required, and preflight the complete batch before committing any entry. In version 2, access outside the host baseline—including the OS temporary directory—requires an explicit top-level [[paths]] rule; legacy safety.allow_temp_directory and safety.allow_any_path apply only to version 1 configuration. file_write and file_patch share the file_chattr contract rather than independent chmod/chown keys; file_delete is the only directory cleanup capability and only removes empty ancestors after a successful file deletion.