AST Code Editor MCP Server

A robust, language-agnostic Model Context Protocol (MCP) server that provides AI coding agents with the ability to edit files surgically via Abstract Syntax Trees (AST) instead of relying on token-heavy, brittle search-and-replace or diff operations.

Why AST Edits?

Every non-AST edit format — search/replace, unified diff, whole-file rewrite — requires the model to copy text perfectly from a file it saw once. One whitespace mismatch on a 4,000-line file and the edit fails. AST edits sidestep the problem entirely: the model names the target (e.g., LRUCache.get) and provides the new code; the parser figures out where it lives.

Geometric AGI benchmarked every major format across 4 models and 29 edit tasks. AST edits were the only format to hit 100% correctness on 3 of 4 models, with 18x fewer output tokens than whole-file rewrite, and zero format failures. Full methodology and results: AST Edits: The Code Editing Format Nobody Uses.

Credits

This MCP server was inspired by research from Jack Foxabbott and the team at Geometric AGI. Their full findings, benchmark suite, and data are available here:

• AST Edits: The Code Editing Format Nobody Uses (Blog)

• Jack Foxabbott's original post (LinkedIn)

• GeometricAGI/blog (Benchmark code & data)

Estimated Token Savings

Per-edit output token savings versus other common edit formats:

Per-read input token savings versus reading the entire file:

For daily agent users, a realistic 40-60% reduction in total tokens per session is achievable, on average (combining output savings from surgical edits with input savings from targeted reads).

The savings come from four compounding effects:

• Output tokens: Using prepend_to_body / append_to_body for small additions instead of rewriting whole function bodies

• Input tokens: Using read_symbol / read_interface / read_imports to read only what's needed instead of entire files (~10-20x fewer input tokens per read)

• Discovery: list_symbols / get_signature instead of reading whole files

• Zero format failures: AST edits never fail on whitespace drift, eliminating retry loops that plague other formats.

Supported Languages & Capabilities

Cross-cutting features:

• Decorated functions (Python @decorator): decorators are preserved on body/signature edits and included on delete.

• Byte-correct slicing: multi-byte characters (emoji, ═, →) handled safely in source text.

• Idempotent imports: add_import skips exact duplicates automatically.

Language-specific design decisions

A few tools have language-specific semantics where multiple reasonable interpretations exist. The chosen behavior is documented here for transparency:

add_field (Ruby and Go) — option (a): literal text passthrough

• Ruby: add_field("LRUCache", " attr_accessor :capacity") inserts the literal string at the top of the class body. The tool does not auto-wrap bare names in attr_accessor — you provide the exact text you want (whether that's attr_accessor, attr_reader, @instance_var = nil in initialize, or CLASS_CONST = 42).

• Go: add_field("Cache", "\tversion int") inserts the literal string inside the struct { ... } body. The tool does not infer types from bare names — you provide the full Go field declaration.

• Rationale: consistent with how add_field works for other languages (Python, JS/TS, C++) where the caller provides the full source text. The alternative option (b) — auto-wrapping (e.g. attr_accessor :foo from the name foo) — would be more magical but harder to use for edge cases (typed fields, readonly fields, field with default value, etc.).

add_method (Go) — option (a): top-level sibling insertion

• add_method("Cache", "func (c *Cache) Has(key string) bool { ... }") locates the type Cache struct { ... } declaration and inserts the new method immediately after it, at the top level (not inside the struct's braces).

• Rationale: Go methods are lexically top-level, not nested inside their receiver type — this matches how Go code is actually written. The alternative option (b) — refusing because "Go methods aren't inside structs" — would be pedantically correct but force callers to use insert_after("Cache", content) instead, which loses the semantic signal that this is a method addition.

Tools Exposed

All tools require file_path to be an absolute path to an existing file.

Code editing — structural (Python, JS, TS, C, C++, Ruby, Go, Java)

Parameters & signatures

Imports & includes

Comments & docstrings

Dict/list editing (JSON, YAML, TOML, AND Python module-level dict/list literals)

Navigation & reading (read-only)

Target format: Use the exact function name (e.g., get) or dotted Class.method path (e.g., LRUCache.get). Decorated Python functions are fully supported — decorators are preserved when replacing bodies or signatures, and included when deleting or replacing the full function.

Tip: Call list_symbols first to discover exact target names before editing. This avoids guessing and makes subsequent edits much more reliable.

Which tool should I use?

A decision guide grouped by intent. Start at the top and pick the narrowest match.

Discovering what's in a file (do this first)

• Don't know what symbols exist? → list_symbols

• Need just a function's signature? → get_signature

• Need one specific function's full source? → read_symbol (10-20x cheaper than reading the whole file)

• Need a class's public API (methods + fields, no bodies)? → read_interface

• Need to see a file's imports/dependencies? → read_imports

• Where is a symbol used? → find_references

Adding new content

Modifying existing content

Removing content

Anti-patterns to avoid

• Don't use replace_function to add a few lines — use prepend_to_body or append_to_body instead. Rewriting the whole function is wasteful and error-prone.

• Don't use replace_function_body to add a few lines either — same reasoning. Use prepend_to_body/append_to_body.

• Don't use replace_signature to add or remove one parameter — use add_parameter/remove_parameter.

• Don't use replace_value to add a new key — use add_key. replace_value only updates existing keys.

• Don't use add_import to add a name to an existing from X import … — use add_import_name.

• Don't guess at target names. Call list_symbols first. Names are case-sensitive and must match exactly.

Logging & Debugging

The server logs all tool invocations and errors to stderr (safe for stdio transport — does not interfere with JSON-RPC). Logs include timestamps and severity levels.

To inspect logs when running under Claude Desktop, check ~/Library/Logs/Claude/mcp*.log (macOS) or %APPDATA%\Claude\logs\mcp*.log (Windows).

For interactive testing, use the MCP Inspector.

Prerequisites

This MCP server uses uv to manage its Python environment and dependencies automatically. Install uv if you don't have it already:

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows (PowerShell):

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

Homebrew (macOS):

brew install uv

pip (any platform):

pip install uv

Verify the installation:

uv --version

For more options (Docker, Cargo, WinGet, etc.), see the official uv installation docs.

Installation

Note: Replace /absolute/path/to below with the actual path to this repository on your machine.

Method 1: CLI Configuration (Claude Code, Codex, Gemini)

If your agent supports adding servers via CLI, run the following:

Claude Code / Codex CLI / Gemini CLI:

--scope user installs the server globally so it's available in every project on your machine. Drop it if you only want the server active in the current project.

# Claude Code / Codex
[claude|codex] mcp add ast-editor --scope user -- uv --directory /absolute/path/to/mcp-servers/ast-editor run ast-editor-mcp

# Gemini CLI
gemini mcp add --transport stdio --scope user ast-editor -- uv --directory /absolute/path/to/mcp-servers/ast-editor run ast-editor-mcp

Method 2: JSON Configuration

For tools that use a mcp_config.json or settings.json file, add the following block to the appropriate file path.

Important: Use the absolute path to uv for "command", not just "uv". GUI-based MCP clients (Claude Desktop, Cursor, Antigravity) don't always inherit your shell PATH, so a bare "uv" will fail with a "command not found" error. Get your absolute path with:

which uv
# e.g. /Users/you/.local/bin/uv  or  /opt/homebrew/bin/uv

{
  "mcpServers": {
    "ast-editor": {
      "command": "/absolute/path/to/uv",
      "args": [
        "--directory",
        "/absolute/path/to/mcp-servers/ast-editor",
        "run",
        "ast-editor-mcp"
      ]
    }
  }
}

Using Standard Python (Fallback)

If you prefer not to use uv, install manually and point to the .venv executable:

cd mcp-servers/ast-editor && python3 -m venv .venv && source .venv/bin/activate && pip install .

{
  "mcpServers": {
    "ast-editor": {
      "command": "/absolute/path/to/mcp-servers/ast-editor/.venv/bin/python",
      "args": ["-m", "ast_editor.server"]
    }
  }
}

Agent Configuration (Important)

Coding agents are heavily biased toward their default tools. You must explicitly instruct them to use AST tools.

Claude (Code & Desktop)

Add the following block to CLAUDE.md, ~/.claude/CLAUDE.md, or Custom Instructions:

When editing .py, .js, .ts, .c, .cpp, .rb, .go, .java, .json, .yaml, or .toml files, do NOT use the edit tool. Use the ast-editor MCP server instead. It exposes 32 surgical tools for structural code and config edits.

Picking a tool — always start here:

1. Unsure of the file layout? Call list_symbols first. Call get_signature if you only need a signature. Call read_symbol to read one function/class without reading the whole file. Call read_interface to see a class's API (methods + fields, no bodies). Call read_imports to see dependencies. Call find_references before renaming anything.

2. Adding new content — choose the narrowest tool:

   • Top-level (function, class, constant, type alias): add_top_level

   • In a class: add_method, add_field

   • Inside a function body: prepend_to_body, append_to_body

   • Relative to an existing symbol: insert_before, insert_after

   • Imports: add_import (new line) or add_import_name (add to existing from X import …)

   • Parameters: add_parameter

   • Comments/docstrings: add_comment_before, replace_docstring

   • Any dict (config OR Python literal): add_key

   • Any list/array (config OR Python literal): append_to_array

3. Modifying existing content:

   • Full function: replace_function

   • Body only: replace_function_body

   • Signature only: replace_signature

   • Config value: replace_value

   • Leading comment: replace_leading_comment

   • Python docstring: replace_docstring

4. Removing content:

   • Function/class/method: delete_symbol

   • Parameter: remove_parameter

   • Import: remove_import (whole line) or remove_import_name (one name)

   • Leading comment: remove_leading_comment

   • Dict key or list item: delete_key, remove_from_array

Anti-patterns to avoid:

• Don't use replace_function or replace_function_body to add a couple of lines — use prepend_to_body / append_to_body.

• Don't use replace_signature to add one parameter — use add_parameter / remove_parameter.

• Don't use replace_value to add a new key — use add_key.

• Don't use add_import to add a name to an existing from-import — use add_import_name.

• Don't guess target names — call list_symbols first. Names are case-sensitive.

Specific Tool Overrides

Generic / Aider / Gemini CLI

Add to rules or system prompt:

When editing .py, .js, .ts, .c, .cpp, .rb, .go, or .java files, do NOT use your default editing tools (diff, whole, etc.). Instead, use the ast-editor MCP server, which exposes 32 surgical tools for adding/modifying/removing functions, classes, methods, fields, parameters, imports, comments, and docstrings. Start any edit session by calling list_symbols to discover exact target names. For reading, use read_symbol to read one function/class (~10-20x fewer input tokens than reading the whole file), read_interface for a class's API (signatures only, no bodies), or read_imports for dependencies. For small additions to a function body (logging, validation, cleanup), use prepend_to_body / append_to_body — these are the single biggest output-token-saving tools in the suite, giving ~20x fewer output tokens than rewriting the whole body. For .json, .yaml, or .toml files, use replace_value/add_key/append_to_array/delete_key instead of freeform edits.