MCP-сервер AST-редактора кода

Надежный, не зависящий от языка сервер протокола контекста модели (MCP), который предоставляет ИИ-агентам для написания кода возможность хирургического редактирования файлов через абстрактные синтаксические деревья (AST) вместо использования хрупких и затратных по токенам операций поиска-замены или diff.

Почему именно AST-правки?

Любой формат правок, не основанный на AST — поиск/замена, unified diff, полная перезапись файла — требует от модели идеального копирования текста из файла, который она видела один раз. Одно несоответствие пробелов в файле на 4000 строк, и правка не удастся. AST-правки полностью обходят эту проблему: модель называет цель (например, LRUCache.get) и предоставляет новый код; парсер сам определяет, где он находится.

Geometric AGI протестировали все основные форматы на 4 моделях и 29 задачах редактирования. AST-правки оказались единственным форматом, достигшим 100% точности на 3 из 4 моделей, с использованием в 18 раз меньшего количества выходных токенов, чем при полной перезаписи файла, и нулевым количеством ошибок формата. Полная методология и результаты: AST Edits: The Code Editing Format Nobody Uses.

Благодарности

Этот MCP-сервер был вдохновлен исследованиями Джека Фоксаббота и команды Geometric AGI. Их полные выводы, набор тестов и данные доступны здесь:

AST Edits: The Code Editing Format Nobody Uses (Блог)
Оригинальный пост Джека Фоксаббота (LinkedIn)
GeometricAGI/blog (Код и данные тестов)

Оценочная экономия токенов

Экономия выходных токенов на одну правку по сравнению с другими распространенными форматами:

Размер правки	Размер файла	vs полная перезапись	vs unified diff	vs поиск/замена
Правка 1 строки	100 строк	3–5x	~1.5x	~1.5x
Перезапись тела функции	500 строк	8–12x	2–3x	2–3x
Перезапись тела функции	4,000 строк	15–20x	3–5x	3–5x
Добавление 2 строк в функцию	любой	~20x (через `prepend_to_body` / `append_to_body`)	5–10x	3–5x

Экономия входных токенов на чтение по сравнению с чтением всего файла:

Задача чтения	Размер файла	Инструмент чтения AST	vs чтение всего файла
Исходный код одной функции	500 строк	`read_symbol`	~20x меньше токенов
Исходный код одной функции	2,000 строк	`read_symbol`	~50-100x меньше токенов
API класса (10 методов, без тел)	500 строк	`read_interface`	~10x меньше токенов
Только блок импортов	любой	`read_imports`	~20-50x меньше токенов
Структурный обзор (имена + номера строк)	любой	`list_symbols`	~15-30x меньше токенов
Сигнатура одной функции	любой	`get_signature`	~50-200x меньше токенов

Для повседневных пользователей агентов достижимо реальное сокращение общего количества токенов за сессию на 40-60% в среднем (комбинируя экономию выходных токенов от хирургических правок с экономией входных токенов от целевого чтения).

Экономия достигается за счет четырех эффектов:

Выходные токены: Использование prepend_to_body / append_to_body для небольших дополнений вместо перезаписи всего тела функции.
Входные токены: Использование read_symbol / read_interface / read_imports для чтения только необходимого вместо целых файлов (~10-20x меньше входных токенов на чтение).
Обнаружение: list_symbols / get_signature вместо чтения целых файлов.
Нулевые ошибки формата: AST-правки никогда не ошибаются из-за смещения пробелов, устраняя циклы повторных попыток, характерные для других форматов.

Поддерживаемые языки и возможности

Язык	Расширения	Структурные правки	Комментарии	Docstrings	Примечания
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 — используйте `.hpp`/`.hxx`/`.hh` для заголовков C++.
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`) обнаруживаются через BFS в `list_symbols`.
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, @instance_var = nil в initialize или CLASS_CONST = 42).
Go: add_field("Cache", "\tversion int") вставляет строковый литерал внутрь тела struct { ... }. Инструмент не выводит типы из голых имен — вы предоставляете полное объявление поля Go.
Обоснование: соответствует тому, как add_field работает для других языков (Python, JS/TS, C++), где вызывающий предоставляет полный исходный текст. Альтернативный вариант (b) — авто-оборачивание (например, attr_accessor :foo из имени 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 с несколькими именами.

Комментарии и docstrings

Инструмент	Параметры	Описание
`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`	Заменить или вставить docstring функции/класса Python. Только для Python.

Редактирование Dict/list (JSON, YAML, TOML и литералы dict/list на уровне модуля Python)

Инструмент	Параметры	Описание
`replace_value`	`file_path`, `target`, `content`	Заменить значение существующего ключа конфигурации. `target` — путь к ключу через точку.
`add_key`	`file_path`, `parent_target`, `key`, `value`	Добавить пару ключ-значение в dict/объект/отображение/таблицу. Для

ast-editor