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

Every key is optional. Omitting version means version 1. The following example shows the complete current schema:

version = 1

[workspace]
roots = [".", "../shared"]

[safety]
allow_external_roots = false
follow_symlinks = false
require_hash = true

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

[formatting]
enabled = true
dprint_config = "./dprint.json"

[[formatting.formatters]]
extensions = [".rs"]
globs = ["generated/**/*.txt"]
command = "./scripts/format"
args = ["--stdin-file", "{file}", "--root", "{project_root}"]
timeout_ms = 30000

[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

Advertised MCP roots and AST_MCP_PROJECT_ROOT are trusted project boundaries. Additional configured roots outside that boundary require safety.allow_external_roots = true. A request spanning multiple advertised roots is accepted only when their effective safety, formatting, and dependency policies agree.

Formatting

Formatting is enabled by default. dprint_config defaults to the package configuration, accepts absolute paths, and resolves relative paths from the TOML file that declares it. Enabled configurations are checked for existence, regular-file type, and valid JSONC during resolution. Set enabled = false to skip dprint, external formatters, and atomic formatter rewrites entirely.

Each [[formatting.formatters]] entry must declare command and at least one extensions or globs selector. Extensions are case-insensitive; globs match project-relative paths with / separators. Entries are evaluated in declaration order and the first match wins. An unmatched file falls back to dprint.

External formatters receive file content on stdin and must return formatted content on stdout. They execute directly without a shell, from the project root. Bare command names use normal executable lookup; relative commands containing a path separator resolve from the declaring TOML file. Arguments may include {file} for the absolute target path and {project_root} for the absolute selected project. A nonzero exit, spawn error, or timeout fails the write without committing. timeout_ms defaults to 30000 and may not exceed 120000.

Safety

Secure defaults preserve the existing boundary: external roots are rejected, symbolic links are rejected, mutation hashes are required, and the hook remains enabled. follow_symlinks = true permits a final symlink only when its resolved target remains inside an effective workspace root. require_hash = false makes expectedSha256 optional for file_patch, existing-file file_write, file_rename, and file_delete; a supplied hash is always verified.

Under [safety.hook], enabled = false disables hook blocking. block_tools explicitly denies matching full or short tool names before normal rules, while allow_tools explicitly bypasses normal hook rules. A tool cannot appear in both lists. These settings affect the host hook only; they do not weaken MCP root, symlink, or stale-hash validation.

Environment compatibility

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

Inspect and refresh

ast-mcp config validate --root "$PWD"
ast-mcp config show --root "$PWD"

Both commands emit stable JSON. show includes absolute resolved values, source files, environment names, and dotted-key provenance. The runtime caches parsed and resolved layers per project, stats the source files on access, and reloads when a file is created, changed, or deleted. Invalid updated configuration fails closed rather than continuing with stale values.

Local installer definitions use AST_MCP_PROJECT_ROOT only to select the project. Global definitions remain project-neutral and use client-advertised roots automatically. Older definitions using AST_MCP_ROOTS remain compatible and are migrated by ast-mcp update.

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.