Documentation

What is AST MCP Server?

AST MCP Server is an open-source Model Context Protocol (MCP) server that gives AI coding agents compiler-aware, structural access to TypeScript and JavaScript projects. Instead of loading entire source files into the model context, agents can retrieve exact symbol declarations, compiler-resolved references, and bounded file sections.

It is built on ts-morph, which wraps the TypeScript compiler API, and exposes a set of MCP tools that any MCP-compliant coding agent with local stdio support can call directly. Six agents have verified guided setup: Claude Code, Hermes, OpenCode, Codex CLI, Gemini CLI, and GitHub Copilot CLI.

How it works

When the server starts, it opens a TypeScript compiler project for the target directory. Incoming tool calls are resolved against that project model: symbol lookups use the compiler's type checker, reference searches use the language service, and diagnostics are collected from the compiler output. Results are returned as structured, bounded JSON objects with freshness metadata.

Write operations follow a three-step workflow: a change is first prepared in memory, then reviewed with compiler evidence (affected files, diagnostic delta, plan hash), and only applied after explicit approval with an immutable hash check.

Requirements

Installation

Install globally with --ignore-scripts, then run the guided setup. The setup command detects supported coding agents, installs the structural-code-editing skill, registers the local stdio server, and verifies the connection.

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.

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.

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

The server communicates over stdio only. HTTP mode is not supported. ast-mcp-server is launched by the agent — you do not invoke it directly.

First compiler-backed read

The recommended read sequence uses four tools in order. Start by checking compiler and freshness state, then discover the symbol, retrieve its source, and optionally gather cross-file evidence.

ast_get_project_status

ast_get_project_status({
  project_root?: string
}): ProjectStatus

ast_search_symbols

ast_search_symbols({
  query: string,
  limit?: number,
  project_root?: string
}): SymbolMatch[]

ast_get_symbol_source

ast_get_symbol_source({
  file_path: string,
  symbol_path: string,
  project_root?: string
}): SymbolSource

ast_find_references

ast_find_references({
  file_path: string,
  symbol_path: string,
  project_root?: string
}): ReferenceResult[]

ast_get_impact

ast_get_impact({
  file_path: string,
  symbol_path: string,
  project_root?: string
}): ImpactResult

ast_explore

ast_explore({
  file_path: string,
  project_root?: string
}): ExploreResult

Freshness metadata

Every bounded result includes a meta object describing the reliability of the returned data:

interface ResultMeta {
  fresh: boolean;       // true if the project snapshot is current
  truncated: boolean;   // true if the result was cut off at a size limit
  resolved: boolean;    // true if the symbol was compiler-resolved (not guessed)
  incomplete: boolean;  // true if cross-file analysis may be partial
}

Check meta.fresh and meta.resolved before acting on a result. If fresh is false, re-run ast_get_project_status to refresh the snapshot.

Prepare

Run a pipeline that ends with a prepare step (e.g. ast_rename_symbol or ast_replace_symbol_body). The server validates the selector against the compiler model and builds the change in memory. Nothing is written to disk at this stage.

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

Review

Inspect the output: affected files, diagnostic delta, complete preview, operation_id, and plan_hash. A human or an agent must verify the change is correct before proceeding. AST-aware editing reduces common targeting and freshness errors, but it does not prove semantic correctness.

Apply

Apply the .astplan file using ast-tool apply with the --plan-hash flag. The hash is verified server-side before any file is written, ensuring the change applied is exactly the change that was reviewed.

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

Immutable hashes

The SHA-256 hash assigned to a prepared plan is computed from the full change payload including the diff, affected files, and selector. If anything is modified between preparation and application, the hash will not match and the apply call will be rejected. This prevents an agent from silently altering a change after a human has reviewed it.

Local setup

The project uses TypeScript throughout and Yarn 4 via Corepack. Tests are written with Vitest. Before submitting a pull request, run the test suite and linter to verify your changes.

git clone https://github.com/yailPeralta/ast-mcp-server
cd ast-mcp-server
corepack enable
yarn install
yarn dev

Running benchmarks

The repository includes a reproducible benchmark suite that measures context reduction against a set of reference TypeScript projects. Results from this suite are the source of the numbers shown on the homepage.

yarn benchmark

Benchmark results depend on the reference projects included in the suite. They are not universal guarantees and actual results will vary by project and workflow.