AST 代码编辑器 MCP 服务器

一个强大且语言无关的 Model Context Protocol (MCP) 服务器，它使 AI 编码代理能够通过抽象语法树 (AST) 对文件进行外科手术式的编辑，而不是依赖于消耗大量 Token 且脆弱的搜索替换或 diff 操作。

为什么选择 AST 编辑？

每种非 AST 编辑格式——搜索/替换、统一 diff、全文件重写——都要求模型从它看过一次的文件中完美地复制文本。在 4,000 行的文件中出现一个空格不匹配，编辑就会失败。AST 编辑完全避开了这个问题：模型命名目标（例如 LRUCache.get）并提供新代码；解析器会找出它所在的位置。

Geometric AGI 在 4 个模型和 29 个编辑任务中对每种主要格式进行了基准测试。AST 编辑是唯一在 4 个模型中的 3 个上达到 100% 正确性的格式，输出 Token 比全文件重写少 18 倍，且格式错误率为零。 完整的方法论和结果：AST Edits: The Code Editing Format Nobody Uses。

致谢

此 MCP 服务器受到 Jack Foxabbott 和 Geometric AGI 团队研究的启发。他们的完整发现、基准测试套件和数据可在此处获得：

AST Edits: The Code Editing Format Nobody Uses (博客)
Jack Foxabbott 的原始帖子 (LinkedIn)
GeometricAGI/blog (基准测试代码和数据)

预估 Token 节省

与其它常见编辑格式相比，每次编辑的输出 Token 节省情况：

编辑大小	文件大小	vs 全文件重写	vs 统一 diff	vs 搜索/替换
1 行调整	100 行代码	3–5 倍	~1.5 倍	~1.5 倍
函数体重写	500 行代码	8–12 倍	2–3 倍	2–3 倍
函数体重写	4,000 行代码	15–20 倍	3–5 倍	3–5 倍
向函数添加 2 行	任意大小	~20 倍 (通过 `prepend_to_body` / `append_to_body`)	5–10 倍	3–5 倍

与读取整个文件相比，每次读取的输入 Token 节省情况：

读取任务	文件大小	AST 读取工具	vs 读取完整文件
一个函数的源码	500 行代码	`read_symbol`	~20 倍更少 Token
一个函数的源码	2,000 行代码	`read_symbol`	~50-100 倍更少 Token
类 API (10 个方法，无函数体)	500 行代码	`read_interface`	~10 倍更少 Token
仅导入块	任意大小	`read_imports`	~20-50 倍更少 Token
结构概览 (名称 + 行号)	任意大小	`list_symbols`	~15-30 倍更少 Token
一个函数签名	任意大小	`get_signature`	~50-200 倍更少 Token

对于日常代理用户，平均而言，每次会话的总 Token 减少 40-60% 是可以实现的（结合了外科手术式编辑带来的输出节省和目标读取带来的输入节省）。

节省来自四个复合效应：

输出 Token： 使用 prepend_to_body / append_to_body 进行小规模添加，而不是重写整个函数体
输入 Token： 使用 read_symbol / read_interface / read_imports 仅读取所需内容，而不是整个文件（每次读取减少约 10-20 倍输入 Token）
发现： 使用 list_symbols / get_signature 而不是读取整个文件
零格式错误： AST 编辑从不会因为空格漂移而失败，消除了困扰其它格式的重试循环。

支持的语言与功能

语言	扩展名	结构编辑	注释	文档字符串	备注
Python	`.py`	✅	✅ `#`	✅ 函数/类	装饰器被保留。模块级 `dict`/`list` 字面量可通过 `add_key` / `append_to_array` 编辑。
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`	✅	✅ `//` + `/* ... */`	—
TypeScript	`.ts`, `.tsx`	✅	✅ `//` + `/* ... */`	—	接口被视为类以进行 `add_method` / `add_field` 操作。
C	`.c`, `.h`	✅	✅ `//` + `/* ... */` (单行 + 多行)	—	`.h` 默认为 C — C++ 头文件请使用 `.hpp`/`.hxx`/`.hh`。
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.hh`	✅	✅ `//` + `/* ... */` (单行 + 多行)	—	支持 `class`, `struct`, `union`, `enum`, `namespace`；`Class::method` 限定名称可正确解析。
Ruby	`.rb`	✅	✅ `#`	—	类、模块、实例方法、`singleton_method`（类方法通过 `def self.foo`）。`require`/`require_relative`/`load`/`autoload` 被识别为导入。
Go	`.go`	✅	✅ `//` + `/* ... */`	—	`struct`, `interface`, 函数, 方法。方法通过接收者寻址：`Cache.Get` 解析为顶层 `func (c *Cache) Get(...)`。支持分组 `import (...)` 块。
Java	`.java`	✅	✅ `//` + `/* ... /` + Javadoc `/* ... */`	—	`class`, `interface`, `enum`, `record`；方法、构造函数、字段。注解 (`@Override`, `@Deprecated`) 在编辑时随其方法移动（包装在 `modifiers` 节点中）。枚举方法（嵌套在 `enum_body_declarations` 中）通过 `list_symbols` 中的 BFS 发现。
JSON	`.json`	✅ (键, 值, 数组)	— (无注释语法)	—
YAML	`.yml`, `.yaml`	✅ (键, 值, 序列)	✅ `#`	—	支持块和流序列。
TOML	`.toml`	✅ (键, 值, 数组, 表)	✅ `#`	—	`[table]` 标题可通过名称进行注释工具寻址。

跨语言特性：

装饰函数 (Python @decorator)：装饰器在函数体/签名编辑时被保留，并在删除时包含在内。
字节正确切片：源文本中的多字节字符（表情符号、═, →）可安全处理。
幂等导入：add_import 会自动跳过完全重复的导入。

语言特定的设计决策

一些工具在存在多种合理解释的情况下具有语言特定的语义。为了透明起见，所选行为记录如下：

add_field (Ruby 和 Go) — 选项 (a)：字面文本透传

Ruby： add_field("LRUCache", " attr_accessor :capacity") 将字面字符串插入到类体顶部。该工具不会自动将裸名称包装在 attr_accessor 中——您提供您想要的精确文本（无论是 attr_accessor、attr_reader、initialize 中的 @instance_var = nil，还是 CLASS_CONST = 42）。
Go： add_field("Cache", "\tversion int") 将字面字符串插入到 struct { ... } 体内。该工具不会从裸名称推断类型——您提供完整的 Go 字段声明。
基本原理： 与 add_field 在其它语言（Python, JS/TS, C++）中的工作方式一致，即调用者提供完整的源文本。选项 (b)——自动包装（例如从名称 foo 生成 attr_accessor :foo）——会更具“魔法”感，但对于边缘情况（类型化字段、只读字段、带默认值的字段等）更难使用。

add_method (Go) — 选项 (a)：顶层同级插入

add_method("Cache", "func (c *Cache) Has(key string) bool { ... }") 定位 type Cache struct { ... } 声明，并将新方法紧随其后插入到顶层（而不是在结构体的大括号内）。
基本原理： Go 方法在词法上是顶层的，而不是嵌套在其接收者类型内部——这符合 Go 代码的实际编写方式。选项 (b)——因为“Go 方法不在结构体内部”而拒绝——虽然在语法上是正确的，但会迫使调用者使用 insert_after("Cache", content)，这会丢失这是方法添加的语义信号。

暴露的工具

所有工具都要求 file_path 为现有文件的绝对路径。

代码编辑 — 结构化 (Python, JS, TS, C, C++, Ruby, Go, Java)

工具	参数	描述
`replace_function`	`file_path`, `target`, `content`	替换完整的函数定义（签名 + 函数体 + 装饰器）。
`replace_function_body`	`file_path`, `target`, `content`	仅替换函数体，保留签名和装饰器。
`replace_signature`	`file_path`, `target`, `new_signature`	仅替换签名，保留函数体和装饰器。
`prepend_to_body`	`file_path`, `target`, `content`	在函数体顶部插入内容。
`append_to_body`	`file_path`, `target`, `content`	在函数体底部插入内容。
`add_top_level`	`file_path`, `content`	将任何顶层内容（函数、类、常量、类型别名）追加到文件末尾。
`add_method`	`file_path`, `class_target`, `content`	在类体末尾添加方法。
`add_field`	`file_path`, `class_target`, `content`	在类体顶部添加字段/属性/成员。
`insert_before`	`file_path`, `target`, `content`	在命名符号之前立即插入同级内容。
`insert_after`	`file_path`, `target`, `content`	在命名符号之后立即插入同级内容。
`delete_symbol`	`file_path`, `target`	删除函数或类定义块（包括装饰器）。

参数与签名

工具	参数	描述
`add_parameter`	`file_path`, `target`, `parameter`, `position`	向函数签名添加参数（`position`：`"start"` 或 `"end"`）。
`remove_parameter`	`file_path`, `target`, `parameter_name`	按名称删除参数。

导入与包含

工具	参数	描述
`add_import`	`file_path`, `import_text`	添加 `import`/`from`/`#include` 行。跳过重复项。
`remove_import`	`file_path`, `import_text`	删除匹配的导入行。
`add_import_name`	`file_path`, `module`, `name`	向现有的 `from <module> import a, b` 添加一个名称。仅限 Python。
`remove_import_name`	`file_path`, `module`, `name`	从多名称 Python from-import 中删除一个名称。

注释与文档字符串

工具	参数	描述
`add_comment_before`	`file_path`, `target`, `comment`	在命名符号之前立即插入注释块。适用于 Python/Ruby/YAML/TOML (`#`), JS/TS/C/C++/Go/Java (`//` 或 `/* /`; 支持 Java Javadoc `/* */`)。
`remove_leading_comment`	`file_path`, `target`	删除符号上方的连续注释块。识别行注释和 C 风格的单行或多行 `/* ... */` 块。
`replace_leading_comment`	`file_path`, `target`, `new_comment`	替换符号上方的引导注释块（如果不存在则插入）。
`replace_docstring`	`file_path`, `target`, `new_docstring`	替换或插入 Python 函数/类文档字符串。仅限 Python。

字典/列表编辑 (JSON, YAML, TOML, 以及 Python 模块级字典/列表字面量)

工具	参数	描述
`replace_value`	`file_path`, `target`, `content`	替换现有配置键的值。`target` 是点号分隔的键路径。
`add_key`	`file_path`, `parent_target`, `key`, `value`	向字典/对象/映射/表添加键值对。对于 Python，`parent_target` 是字典变量名；对于配置，是点号路径（根路径使用 `""`）。
`delete_key`	`file_path`, `target`	删除键值对。对于 Python，目标是 `DictName.keyExpr`。对于 JSON，还会删除相邻的逗号。
`append_to_array`	`file_path`, `target`, `value`	将字面值追加到列表/数组/序列。对于 Python，`target` 是列表变量名；对于配置，是点号路径。
`remove_from_array`	`file_path`, `target`, `value_match`	从列表/数组/序列中删除第一个匹配的元素。

导航与读取 (只读)

工具	参数	描述
`list_symbols`	`file_path`	所有顶层函数、类和方法的格式化大纲，包含行号。
`get_signature`	`file_path`, `target`	以纯文本形式返回函数签名。
`find_references`	`file_path`, `target`	标识符所有出现位置的语法搜索（无作用域感知）。
`read_symbol`	`file_path`, `target`	返回单个命名符号（函数、类、方法、配置键）的完整源文本。通常比读取整个文件少 10-20 倍 Token。
`read_imports`	`file_path`	返回文件中的所有导入/包含语句。
`read_interface`	`file_path`, `target

ast-editor