Home DocsCLI Reference

ast-tool CLI reference

ast-mcp-server runs the local MCP stdio server. ast-tool provides guided setup, pipeline validation and execution, reviewed plan application, cache management, and skill installation.

Two executables

Installing ast-mcp-server provides two binaries with distinct roles. Understanding which one to use avoids the most common setup mistakes.

ast-mcp-server

Runs the local MCP stdio server. Launched automatically by your coding agent via the MCP client configuration — you do not invoke it directly in normal use.

ast-tool

The interactive CLI for setup, pipeline execution, plan application, cache management, and skill installation. This is the command you run in your terminal.

Installation

Install globally with --ignore-scripts, then run the guided setup. The setup command handles agent detection, skill installation, and server registration in one step.

bash

npm install --global ast-mcp-server --ignore-scripts
ast-tool setup

Requires Node.js 22.13.0 or newer. Linux is the verified platform for managed setup; review the support policy before using other platforms.

Commands

Guided setup

Detects supported coding agents, installs the structural-code-editing skill, registers the local stdio server, and verifies the connection. Supports Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI, and GitHub Copilot CLI.

bash

ast-tool setup

Setup all agents non-interactively

Run setup for all supported agents without prompts. Useful for CI or shared dev environments.

bash

ast-tool setup --agents all --yes

Validate a pipeline

Check a pipeline JSON file for schema errors and unresolvable $ref references before running it.

bash

ast-tool validate pipeline.json

Run a pipeline

Execute a pipeline file. Results are written to stdout. Use --output-format toon to get a token-optimised output.

bash

ast-tool run pipeline.json

Run with TOON output

Emit results in TOON (Token-Optimised Object Notation) format, which reduces token consumption when the output is fed back to an agent.

bash

ast-tool run pipeline.json --output-format toon

Apply a reviewed plan

Apply a prepared .astplan file. The --plan-hash flag is required and must match the SHA-256 of the plan as reviewed — this prevents silent modification between review and apply.

bash

ast-tool apply plan.astplan --plan-hash <reviewed-sha256>

Inspect cache

Show the current compiler cache state, including project snapshots and freshness metadata.

bash

ast-tool cache inspect

Clear cache

Evict all cached compiler snapshots. Use when the cache is stale after large refactors or dependency changes.

bash

ast-tool cache clear --yes

Install skills

Install all available skills, including the structural-code-editing skill used by supported agents.

bash

ast-tool install-skill all

Pipeline file schema

A pipeline file is a JSON document with a version, project_root, and a steps array. Each step has an id, a tool name, and an input object. Steps can reference outputs of earlier steps using $ref pointers. The emit field selects which step result is written to stdout.

json

{
  "version": 1,
  "project_root": "/absolute/path/to/project",
  "steps": [
    {
      "id": "search",
      "tool": "ast_search_symbols",
      "input": {
        "query": "UserService",
        "limit": 20
      }
    },
    {
      "id": "source",
      "tool": "ast_get_symbol_source",
      "input": {
        "file_path": { "$ref": "#/steps/search/symbols/0/file" },
        "symbol_path": { "$ref": "#/steps/search/symbols/0/selector" }
      }
    }
  ],
  "emit": { "$ref": "#/steps/source" }
}

A pipeline may end with at most one prepare step (e.g. ast_rename_symbol). ast_apply_operation is never allowed inside a pipeline — apply is always a separate reviewed step using ast-tool apply.

Validate before running

Always validate a pipeline before executing it. Validation catches schema errors and unresolvable $ref pointers without touching the filesystem.

bash

ast-tool validate pipeline.json
ast-tool run pipeline.json

Applying a plan

Write operations produce a .astplan file. Review the affected files, diagnostic delta, and complete preview before applying. The --plan-hash flag is required and must match the SHA-256 of the plan exactly as reviewed — this prevents silent modification between review and apply.

bash

# 1. Run a pipeline that ends with a prepare step
ast-tool run rename-pipeline.json

# 2. Review the output: affected files, diagnostic delta, plan_hash

# 3. Apply only after review — hash must match
ast-tool apply plan.astplan --plan-hash <reviewed-sha256>

AST-aware editing reduces common targeting and freshness errors, but it does not prove semantic correctness or provide a filesystem-wide transaction. Always review the diagnostic delta before applying.

Exit codes

Successful output is written to stdout. Errors are emitted as structured JSON on stderr.

Code	Meaning
0	Success. Output written to stdout.
1	Execution or apply failure. Structured error JSON written to stderr.
2	Usage or schema error (invalid flag, malformed pipeline, etc.).

MCP client configuration

After running ast-tool setup, the server is registered automatically for supported agents. If you need to register it manually, add the following to your client's MCP configuration file:

json

{
  "mcpServers": {
    "ast-mcp": {
      "command": "ast-mcp-server"
    }
  }
}

The server communicates over stdio only. HTTP mode is not supported.

Back to Documentation View on GitHub