Configuration

Files and precedence

The effective value of each field is selected in this order:

1. environment override
2. project ast-mcp.toml
3. global ast-mcp.toml
4. built-in default

The project file is the nearest ast-mcp.toml from the selected workspace root up to its Git boundary. The global file is ${XDG_CONFIG_HOME:-~/.config}/ast-mcp/ast-mcp.toml on POSIX and %APPDATA%\ast-mcp\ast-mcp.toml on Windows. Project selection prefers roots advertised by the MCP client, then AST_MCP_PROJECT_ROOT, legacy AST_MCP_ROOTS, and finally the process working directory.

Objects merge by field and arrays replace the lower-precedence array. Relative paths are resolved from the TOML file that declares them. Unknown sections or keys, unsupported versions, malformed TOML, and invalid values fail with the source path and dotted key instead of being ignored.

Schema

Version 2 is the long-term schema. Omitting version retains version 1 compatibility and emits deprecation diagnostics; ast-mcp never rewrites configuration automatically.

version = 2

[workspace]
roots = [".", "../shared"]
worktrees = "include" # include | request | ignore

[files.read]
modes = ["ast", "text"]

[files.patch]
strategies = ["ast", "aider_block"]
aider_matchers = ["exact", "whitespace", "relative-indentation", "diff-match-patch"]

[formatting]
enabled = true
fallback = "preserve" # preserve | dprint | reject
dprint_config = "./dprint.json"

[[formatting.formatters]]
id = "biome"
enabled = true
extensions = [".ts", ".tsx", ".json"]
command = "bunx"
args = ["biome", "format", "--write", "{file}"]
mode = "in_place" # stdout | in_place
timeout_ms = 30000

[safety]
require_hash = true

[[paths]]
id = "workspace-source"
path = "."
policies = { read = "allow", write = "request" }
follow_symlinks = false
includes = ["**/*"]
excludes = [".git/**"]

[safety.hook]
enabled = true
allow_tools = []
block_tools = []

[dependencies]
ast_bro_binary = "/absolute/path/to/ast-bro"
dprint_binary = "/absolute/path/to/dprint"

[http]
host = "127.0.0.1"
port = 3768
session_timeout_ms = 1800000
session_sweep_interval_ms = 60000

[mcp.configuration]
enabled = true
require_approval = true

Client roots and AST_MCP_PROJECT_ROOT provide the host baseline but are not authorization. Server-side top-level paths rules remain authoritative. A request spanning multiple advertised roots is accepted only when their effective safety, formatting, and dependency policies agree.

workspace.worktrees defaults to include. Linked git worktrees of each configured root join the filesystem baseline and inherit relative [[paths]] directory anchors. request keeps those remapped rules but requires approval for sibling worktree paths. ignore restores the previous behavior, denying sibling worktrees unless an explicit absolute rule covers them. The selected projectRoot stays on the checkout that bears ast-mcp.toml.

File methods

[files.read].modes filters the agent-selectable ast and text modes. [files.patch].strategies filters ast and aider_block; it does not auto-select a strategy. Version 2 enables every supported Aider matcher shown above by default. Repositories may narrow the list when they intentionally require stricter matching; ambiguity still fails closed. file_capabilities reports intrinsic and effective methods for each target.

Formatting

Version 2 defaults to fallback = "preserve". select dprint or reject explicitly when unmatched content must be formatted or rejected. dprint_config accepts absolute paths and resolves relative paths from its declaring TOML file.

Each formatter declares a stable id, command, mode, and at least one extensions or globs selector. Entries are evaluated in declaration order and the first enabled match wins. An entry's enabled value overrides the global formatting default, so a globally disabled configuration can selectively enable a formatter.

In stdout mode, candidate content enters stdin and stdout becomes the formatted result. In in_place mode, ast-mcp writes the candidate to an adjacent staged file, expands {file} to that stage, runs the command, reads the stage, and removes it; the formatter never receives the live target. {source_file} names the logical target and {project_root} names the selected project. Stdout is ignored in in-place mode. Nonzero exits, spawn errors, cleanup failures, or timeouts fail without committing.

Safety

Version 2 grants no implicit OS-temporary access. Each top-level [[paths]] rule anchors an exact file or directory; globs belong in includes and excludes, with exclusions winning. Policies are allow, request, or deny, and omitted delete inherits write.

Exact files outrank directories; otherwise the deepest anchor and longest include literal prefix wins. Equal specificity resolves deny before request before allow. Rename needs source delete and destination write; metadata uses write; hashing and intelligence use read. Both a symlink and its resolved target must be authorized, and the winning rule must enable follow_symlinks.

Project rules that broaden beyond the host baseline are reduced from allow to request. Once/session approvals bind connection, generation, rule, operation, and canonical path. Persistent approvals create the narrowest user-global rule. Active configuration files are protected targets for file_write and file_patch and always require explicit approval for those mutations. Grouped config_core / config_paths edits follow [mcp.configuration] instead. Clients without elicitation fail closed with approval_required remediation.

require_hash = false makes expectedSha256 optional for guarded mutations, but supplied hashes are always checked. Hook allow/block settings affect only the host hook and never weaken server-side path, symlink, approval, or hash enforcement.

MCP configuration tools

[mcp.configuration] is enabled by default and requires host approval by default. Set enabled = false to fail closed on config_core and config_paths (the tools stay registered). Set require_approval = false to skip elicitation for ordinary grouped edits; changing [mcp.configuration] itself always requires approval, including turning the surface off or disabling approval. Direct file_write and file_patch of active configuration files remain protected targets.

Agents must use the grouped tools rather than rewriting ast-mcp.toml as a whole file:

• config_core updates workspace, safety, files, formatting scalars (enabled, fallback, dprint_config), http, dependencies, and mcp.configuration. Batch every key that belongs to those sections in one call. It does not change [[paths]] or [[formatting.formatters]].
• config_paths adds, updates, or removes [[paths]] rules in one operations batch. A single path rule can be fully specified in one add or update; partial policies updates merge with the existing rule. It does not change core sections.
• target is project or global and defaults to project. Version 1 files must be migrated first.

A successful write validates version 2 schema, replaces the file atomically, invalidates the process-wide registry, and returns the new generation so later tool calls use the updated snapshot without restarting the MCP server. Claude, Codex, Grok, and other elicitation-capable hosts receive a standard request approval; hosts without elicitation fail closed with approval_required.

Environment compatibility

Boolean environment values accept 1, 0, true, or false. Invalid explicit overrides are errors.

Inspect and refresh

ast-mcp config validate
ast-mcp config show
ast-mcp config migrate          # preview
ast-mcp config migrate --check  # 0 current, 2 required, 1 invalid
ast-mcp config migrate --write  # atomic write plus .v1.bak

The config_status tool returns redacted effective configuration, including mcp.configuration, provenance, generation, formatter order, and health. policy_check reports side-effect-free decisions. A process-wide registry watches global and discovered project configuration, debounces atomic reloads, and periodically reconciles fingerprints. Ordinary tool calls use immutable in-memory snapshots. config_core and config_paths invalidate that registry after a successful write so the next snapshot is the new generation. Invalid reloads mark the root unhealthy and fail closed while retaining the last valid snapshot only for diagnostics.

Local installer definitions omit environment fields and use project ast-mcp.toml. Global definitions remain project-neutral. AST_MCP_PROJECT_ROOT, AST_MCP_ROOTS, and --root remain deprecated for one release.

Extension policy

The strict top-level namespaces separate workspace selection, safety, formatting, dependency binaries, and transport settings so later hook, formatter, safety, and plugin features can extend their owning section without weakening validation. Keys are added only when runtime behavior exists; the loader does not accept misleading no-op placeholders.