Filesystem access modes

File operations default to restricted access. Configure the mode globally or in a project's ast-mcp.toml:

version = 2

[safety]
filesystem = "restricted"

Restricted mode enforces configured path policies, file-operation boundaries, and symlink restrictions. Explicit approved external path rules remain usable when a workspace is selected.

Enable unrestricted accessCopy Anchor Link

Set filesystem = "unrestricted" to bypass file path policies, boundaries, and symlink restrictions:

[safety]
filesystem = "unrestricted"

Unrestricted file access preserves OS permissions, SHA-256 guards, atomic operations, and immutable revision protection. It does not change workspace selection, intelligence roots, indexing, or storage. Intelligence calls still require paths inside their selected workspace.

A global unrestricted setting applies as the host's configuration. A project unrestricted setting requires host approval for a stable MCP session. Approve the session request presented by the MCP client. Modern stateless HTTP has no trusted caller session for host approval, so operations requiring elicitation fail closed with approval_required, including project access that needs cross-request approval. Use stdio or a legacy HTTP session for project-scoped approval; changing the configuration approval setting does not bypass this activation requirement.

Approval binds to the server session, project, and effective safety and path configuration. Stdio keeps one connection state per process, while legacy HTTP sessions remain isolated. Changing safety or path settings requires fresh approval. Restarting the server also requires fresh project approval. Formatter or telemetry changes do not invalidate an otherwise unchanged filesystem approval.

Use config_status to inspect the effective configuration and its provenance. Use policy_check to inspect path decisions. Apply configuration changes through config_core and config_paths when using the configuration tools.

Diagnose denied changesCopy Anchor Link

A policy denial differs from an operating-system permission error. Unrestricted mode permits paths through ast-mcp's file policy; it cannot grant OS access.

Missing files, stale hashes, and stale preview receipts require different recovery:

1. Read the typed error and inspect its suggested next call.
2. Re-read changed content when necessary.
3. Obtain a fresh whole-file hash with file_hash.
4. Preview and retry the guarded patch.

A stale receipt can indicate changed content, configuration, or workspace binding. Rebuild its preview instead of reusing it.

Explicit revision selectors require a selected workspace. If the host advertises no roots, open the repository with workspace_open and pass its workspaceId. Otherwise, the server returns workspace_required before reading, hashing, or modifying files.

Ambiguous Aider matches remain rejected. Diagnostics contain bounded candidates and recovery guidance. Narrow the search block with unique surrounding content, then retry with a fresh hash. Cleanup preserves the original failure when secondary cleanup also fails.

Before deleting source files, file_delete scans the applicable readable reference tree for relative imports in files with a registered AST language. It skips hidden entries, node_modules, and JSON, JSONC, TOML, and YAML files. A parser error, invalid UTF-8, a per-file parse timeout, or a scan over the inventory and byte limits returns reference_verification_failed before any batch target is deleted. The scan allows 1 second per parsed file, 2 MiB per file, 16 MiB of source in total, 100,000 inventory entries, and 30 seconds overall. Cancellation during preflight also leaves all batch targets unchanged.

For each relative import, matching compares its resolved base with the target path, the target path with its extension appended, and an index file using the target extension. It does not resolve aliases or remap extensions; for example, ./foo.js does not match foo.ts. If verification cannot complete, inspect the candidate sources and retry after resolving the error. forceReferences: true is an explicit reviewed bypass for reference verification; it does not bypass file authorization or SHA-256 guards. Files without a registered AST language are not inspected for imports, so review those formats before deleting their dependencies.

While waiting for mutation locks, caller cancellation aborts before the delete transaction starts and leaves targets unchanged. After deletion commits, directory cleanup cannot change the successful deletion result, and caller cancellation does not interrupt it. Waiting for a contended cleanup lock has a separate 1-second deadline. This bounds contention waits, not all path resolution, filesystem operations, or lease publication; those can take longer. If the deadline expires, the response reports cleanup: { status: "deferred", code: "lock_deadline" }. Other cleanup exceptions report status: "failed" with lock_fenced, EACCES, EPERM, or cleanup_failed. In either case, removedDirectories is empty; directories that cleanup did not remove may remain. Do not retry the deletion based on a cleanup status.