Optional formatting

Formatting defaults to disabled. File writes and patches preserve their candidate content unless you explicitly enable formatting.

version = 2

[formatting]
enabled = false
fallback = "preserve"

The master switch overrides individual formatter settings. Disabled formatting does not check formatter executables or dprint configuration.

Configure an installed formatterCopy Anchor Link

Install your formatter separately. ast-mcp does not install formatter binaries during file operations. Use an executable available on the server's PATH or its absolute path.

This example runs Prettier with the candidate content on stdin. The formatter must emit only formatted content on stdout.

[formatting]
enabled = true
fallback = "preserve"

[[formatting.formatters]]
id = "prettier"
enabled = true
command = "prettier"
args = ["--stdin-filepath", "{source_file}"]
extensions = [".js", ".jsx", ".ts", ".tsx", ".json", ".css", ".md"]
mode = "stdout"
timeout_ms = 30000

Choose extensions that your installed formatter supports. Alternatively, use globs = ["src/**/*.ts"]. Either a matching extension or glob selects an entry. Entries are evaluated in order; the first enabled match runs.

Commands receive argument arrays without a shell. Do not include shell pipes, redirection, or compound commands. Avoid package launchers that download missing executables.

Other formatters work with the same command contract. Configure each formatter's plugins and supported languages separately.

Paths and configuration discoveryCopy Anchor Link

The working directory is the selected project root, or the containing configured root for an external file. Relative command arguments resolve from that directory. Use explicit configuration arguments when your formatter requires them.

Arguments support these substitutions:

In stdout mode, the formatter receives candidate bytes on stdin. Use the source path for parser selection and configuration discovery. Do not configure commands that modify the live destination.

For a formatter that requires a file, select mode = "in_place". For example:

[[formatting.formatters]]
id = "oxfmt-in-place"
command = "oxfmt"
args = ["--write", "{file}"]
extensions = [".ts", ".tsx", ".json"]
mode = "in_place"
timeout_ms = 30000

ast-mcp stages the candidate in a private sibling directory and retains its basename. Parent configuration discovery can reach the original directory. Relative-path overrides see an additional staging directory; use stdout mode when those overrides require the exact original path.

Failures and guarded writesCopy Anchor Link

Missing executables return formatter_unavailable. Timeouts return formatter_timeout. Invalid UTF-8, oversized output, removed output, and nonregular output return formatter_invalid_output. Formatter rejections return formatter_rejected.

Output is limited to 16 MiB. With the default fallback = "preserve", a failed formatter leaves the candidate content unchanged and the guarded write continues. Set fallback = "reject" to stop the write and return a typed formatter error. Set fallback = "dprint" to try the configured dprint formatter after a matching formatter fails. A staging cleanup failure always stops the write. Hash guards, atomic writes, and OS permissions still apply.

Migrate from implicit dprintCopy Anchor Link

dprint is no longer a runtime dependency, and ast-mcp does not bundle a dprint.json. Remove obsolete dprint trust commands from installation instructions. Install dprint yourself if you want to retain it.

Explicit compatibility remains available:

[formatting]
enabled = true
fallback = "dprint"

With fallback = "dprint", ast-mcp discovers the project-root dprint.json when dprint_config is not overridden. Set dprint_config only when the project uses a different path. Prepare dprint and its configured plugins separately.

To remove an obsolete dprint_config override, call the configuration tool:

config_core({ formatting: { dprint_config: null } });

Here, API null means remove the key. TOML has no null value, so do not write dprint_config = null in ast-mcp.toml.

For mixed formatters, prefer explicit formatter entries and fallback = "preserve". Use fallback = "reject" to reject unmatched files or failed matching formatters when formatting is enabled.

Migration disables formatting when the previous configuration omitted its activation setting. Explicit activation remains explicit. Review the migrated settings before applying changes.