Migrate configuration to version 2

Version 2 replaces permissive safety booleans with explicit path policies and makes formatter input/output behavior unambiguous. Version 1 remains readable for compatibility, but ast-mcp never migrates a file automatically.

Preview firstCopy Anchor Link

ast-mcp config migrate
ast-mcp config migrate --file ./ast-mcp.toml
ast-mcp config migrate --global

Preview is the default and does not write. Use --check in CI: exit code 0 means current, 2 means migration is required, and 1 means the input is invalid or unsupported.

Write atomicallyCopy Anchor Link

ast-mcp config migrate --to 2 --write
ast-mcp config migrate --global --write --no-backup

A write uses an adjacent temporary file and atomic replacement, preserves file mode and newline style, and creates <file>.v1.bak unless --no-backup is explicit. Comments and untouched source bytes remain intact. Re-running migration on version 2 is idempotent.

Compatibility mappingCopy Anchor Link

• Existing custom formatters gain a stable id, enabled = true, and mode = "stdout" because v1 consumed stdout.
• Formatting gains fallback = "dprint" where needed to preserve v1 unmatched-file behavior.
• Workspace roots become explicit top-level [[paths]] rules.
• Enabled temporary-directory access becomes an explicit OS-temp rule.
• allow_any_path = true becomes an explicit catch-all rule and emits an UNRESTRICTED warning.
• delete inherits write when omitted; migrated compatibility rules spell out all policies.

Review every generated rule before writing, especially catch-all, temporary, external, or symlink-enabled rules. Prefer request for access that is not universally safe. New configurations restrict file access by default. If the project needs unrestricted file operations, configure that mode explicitly and obtain the required session approval; it does not broaden intelligence workspace roots. Persistent user approvals belong only in the user-global version 2 configuration. See the filesystem access guide.

Telemetry defaultsCopy Anchor Link

When telemetry.enabled is omitted, telemetry is enabled by default in both configuration versions. Set it to false in global configuration to disable analytics for all projects, or in project configuration to suppress that project's events. The global setting is a ceiling. See the telemetry guide for collected fields and opt-out instructions.

Intelligence defaultsCopy Anchor Link

Migrated configurations retain deterministic structural behavior. Version 2 adds global LanceDB storage, disabled federation, disabled semantic retrieval, the pinned small Granite embedding profile, and disabled generation as resolved defaults. Migration does not download a model, move old caches, enable cross-repository access, or enable an external provider.

Configure intelligence.storage.placement before indexing when global storage is unsuitable. Enable federation only for intended cross-repository queries. Enable generation only after choosing an MCP sampling or HTTP provider.

RolloutCopy Anchor Link

After migration, restart or reconnect long-lived MCP hosts once so they discover the new server/tool schemas. Subsequent configuration changes hot reload in place. Run config_status to verify the effective generation and formatter order, then use policy_check for representative read, write, delete, and external paths before the first mutation. For startup failures or missing tools, follow the connection diagnosis guide.