Servidor MCP de Editor de Código AST

Un servidor robusto y agnóstico al lenguaje del Protocolo de Contexto de Modelo (MCP) que proporciona a los agentes de codificación de IA la capacidad de editar archivos quirúrgicamente mediante Árboles de Sintaxis Abstracta (AST) en lugar de depender de operaciones de búsqueda y reemplazo o diff frágiles y pesadas en tokens.

¿Por qué ediciones AST?

Cada formato de edición que no es AST (buscar/reemplazar, diff unificado, reescritura de archivo completo) requiere que el modelo copie el texto perfectamente desde un archivo que vio una vez. Un desajuste de espacios en blanco en un archivo de 4,000 líneas y la edición falla. Las ediciones AST evitan el problema por completo: el modelo nombra el objetivo (p. ej., LRUCache.get) y proporciona el nuevo código; el analizador determina dónde vive.

Geometric AGI evaluó todos los formatos principales en 4 modelos y 29 tareas de edición. Las ediciones AST fueron el único formato en alcanzar el 100% de precisión en 3 de 4 modelos, con 18 veces menos tokens de salida que la reescritura de archivo completo y cero fallos de formato. Metodología y resultados completos: AST Edits: The Code Editing Format Nobody Uses.

Créditos

Este servidor MCP fue inspirado por la investigación de Jack Foxabbott y el equipo de Geometric AGI. Sus hallazgos completos, conjunto de pruebas comparativas y datos están disponibles aquí:

AST Edits: The Code Editing Format Nobody Uses (Blog)
Publicación original de Jack Foxabbott (LinkedIn)
GeometricAGI/blog (Código y datos de referencia)

Ahorro estimado de tokens

Ahorro de tokens de salida por edición frente a otros formatos de edición comunes:

Tamaño de edición	Tamaño de archivo	vs reescritura de archivo completo	vs diff unificado	vs buscar/reemplazar
Ajuste de 1 línea	100 LoC	3–5x	~1.5x	~1.5x
Reescritura de cuerpo de función	500 LoC	8–12x	2–3x	2–3x
Reescritura de cuerpo de función	4,000 LoC	15–20x	3–5x	3–5x
Añadir 2 líneas a una función	cualquier tamaño	~20x (vía `prepend_to_body` / `append_to_body`)	5–10x	3–5x

Ahorro de tokens de entrada por lectura frente a leer el archivo completo:

Tarea de lectura	Tamaño de archivo	Herramienta de lectura AST	vs lectura de archivo completo
Fuente de una función	500 LoC	`read_symbol`	~20x menos tokens
Fuente de una función	2,000 LoC	`read_symbol`	~50-100x menos tokens
API de clase (10 métodos, sin cuerpos)	500 LoC	`read_interface`	~10x menos tokens
Solo bloque de importación	cualquier tamaño	`read_imports`	~20-50x menos tokens
Resumen estructural (nombres + números de línea)	cualquier tamaño	`list_symbols`	~15-30x menos tokens
Firma de una función	cualquier tamaño	`get_signature`	~50-200x menos tokens

Para usuarios diarios de agentes, es alcanzable una reducción realista del 40-60% en el total de tokens por sesión, en promedio (combinando el ahorro de salida de las ediciones quirúrgicas con el ahorro de entrada de las lecturas dirigidas).

Los ahorros provienen de cuatro efectos compuestos:

Tokens de salida: Uso de prepend_to_body / append_to_body para pequeñas adiciones en lugar de reescribir cuerpos de funciones completos.
Tokens de entrada: Uso de read_symbol / read_interface / read_imports para leer solo lo necesario en lugar de archivos completos (~10-20x menos tokens de entrada por lectura).
Descubrimiento: list_symbols / get_signature en lugar de leer archivos completos.
Cero fallos de formato: Las ediciones AST nunca fallan por deriva de espacios en blanco, eliminando los bucles de reintento que plagan otros formatos.

Lenguajes y capacidades compatibles

Lenguaje	Extensiones	Ediciones estructurales	Comentarios	Docstrings	Notas
Python	`.py`	✅	✅ `#`	✅ función/clase	Decoradores preservados. Literales `dict`/`list` a nivel de módulo editables vía `add_key` / `append_to_array`.
JavaScript	`.js`, `.jsx`, `.mjs`, `.cjs`	✅	✅ `//` + `/* ... */`	—
TypeScript	`.ts`, `.tsx`	✅	✅ `//` + `/* ... */`	—	Las interfaces se tratan como clases para `add_method` / `add_field`.
C	`.c`, `.h`	✅	✅ `//` + `/* ... */` (línea única + múltiple)	—	`.h` por defecto es C — use `.hpp`/`.hxx`/`.hh` para cabeceras C++.
C++	`.cpp`, `.cc`, `.cxx`, `.hpp`, `.hxx`, `.hh`	✅	✅ `//` + `/* ... */` (línea única + múltiple)	—	Soporta `class`, `struct`, `union`, `enum`, `namespace`; los nombres calificados `Class::method` se resuelven correctamente.
Ruby	`.rb`	✅	✅ `#`	—	Clases, módulos, métodos de instancia, `singleton_method` (métodos de clase vía `def self.foo`). `require`/`require_relative`/`load`/`autoload` reconocidos como importaciones.
Go	`.go`	✅	✅ `//` + `/* ... */`	—	`struct`, `interface`, funciones, métodos. Los métodos se direccionan por receptor: `Cache.Get` se resuelve en el `func (c *Cache) Get(...)` de nivel superior. Bloques `import (...)` agrupados soportados.
Java	`.java`	✅	✅ `//` + `/* ... /` + Javadoc `/* ... */`	—	`class`, `interface`, `enum`, `record`; métodos, constructores, campos. Las anotaciones (`@Override`, `@Deprecated`) viajan con su método en las ediciones (envueltas en el nodo `modifiers`). Métodos de Enum (anidados en `enum_body_declarations`) descubiertos vía BFS en `list_symbols`.
JSON	`.json`	✅ (claves, valores, arrays)	— (sin sintaxis de comentarios)	—
YAML	`.yml`, `.yaml`	✅ (claves, valores, secuencias)	✅ `#`	—	Secuencias de bloque y flujo soportadas.
TOML	`.toml`	✅ (claves, valores, arrays, tablas)	✅ `#`	—	Cabeceras `[table]` direccionables por nombre para herramientas de comentarios.

Características transversales:

Funciones decoradas (Python @decorator): los decoradores se preservan en ediciones de cuerpo/firma e incluidos en la eliminación.
Slicing correcto de bytes: caracteres multibyte (emoji, ═, →) manejados de forma segura en el texto fuente.
Importaciones idempotentes: add_import omite duplicados exactos automáticamente.

Decisiones de diseño específicas del lenguaje

Algunas herramientas tienen semánticas específicas del lenguaje donde existen múltiples interpretaciones razonables. El comportamiento elegido se documenta aquí para mayor transparencia:

add_field (Ruby y Go) — opción (a): paso de texto literal

Ruby: add_field("LRUCache", " attr_accessor :capacity") inserta la cadena literal en la parte superior del cuerpo de la clase. La herramienta no envuelve automáticamente nombres desnudos en attr_accessor — usted proporciona el texto exacto que desea (ya sea attr_accessor, attr_reader, @instance_var = nil en initialize, o CLASS_CONST = 42).
Go: add_field("Cache", "\tversion int") inserta la cadena literal dentro del cuerpo struct { ... }. La herramienta no infiere tipos de nombres desnudos — usted proporciona la declaración completa del campo Go.
Justificación: consistente con cómo funciona add_field para otros lenguajes (Python, JS/TS, C++) donde el llamador proporciona el texto fuente completo. La opción alternativa (b) — auto-envoltura (p. ej., attr_accessor :foo desde el nombre foo) — sería más mágica pero más difícil de usar para casos extremos (campos tipados, campos de solo lectura, campos con valor predeterminado, etc.).

add_method (Go) — opción (a): inserción de hermano de nivel superior

add_method("Cache", "func (c *Cache) Has(key string) bool { ... }") localiza la declaración type Cache struct { ... } e inserta el nuevo método inmediatamente después, en el nivel superior (no dentro de las llaves de la estructura).
Justificación: Los métodos de Go son léxicamente de nivel superior, no anidados dentro de su tipo receptor — esto coincide con cómo se escribe realmente el código Go. La opción alternativa (b) — rechazar porque "los métodos de Go no están dentro de structs" — sería pedantemente correcta pero obligaría a los llamadores a usar insert_after("Cache", content) en su lugar, lo que pierde la señal semántica de que se trata de una adición de método.

Herramientas expuestas

Todas las herramientas requieren que file_path sea una ruta absoluta a un archivo existente.

Edición de código — estructural (Python, JS, TS, C, C++, Ruby, Go, Java)

Herramienta	Parámetros	Descripción
`replace_function`	`file_path`, `target`, `content`	Reemplazar una definición de función completa (firma + cuerpo + decoradores).
`replace_function_body`	`file_path`, `target`, `content`	Reemplazar solo el cuerpo de una función, preservando la firma y los decoradores.
`replace_signature`	`file_path`, `target`, `new_signature`	Reemplazar solo la firma, preservando el cuerpo y los decoradores.
`prepend_to_body`	`file_path`, `target`, `content`	Insertar contenido en la parte superior del cuerpo de una función.
`append_to_body`	`file_path`, `target`, `content`	Insertar contenido en la parte inferior del cuerpo de una función.
`add_top_level`	`file_path`, `content`	Añadir cualquier contenido de nivel superior (función, clase, constante, alias de tipo) al final del archivo.
`add_method`	`file_path`, `class_target`, `content`	Añadir un método al final del cuerpo de una clase.
`add_field`	`file_path`, `class_target`, `content`	Añadir un campo/atributo/miembro en la parte superior del cuerpo de una clase.
`insert_before`	`file_path`, `target`, `content`	Insertar un hermano inmediatamente antes de un símbolo nombrado.
`insert_after`	`file_path`, `target`, `content`	Insertar un hermano inmediatamente después de un símbolo nombrado.
`delete_symbol`	`file_path`, `target`	Eliminar un bloque de definición de función o clase (incluyendo decoradores).

Parámetros y firmas

Herramienta	Parámetros	Descripción
`add_parameter`	`file_path`, `target`, `parameter`, `position`	Añadir un parámetro a una firma de función (`position`: `"start"` o `"end"`).
`remove_parameter`	`file_path`, `target`, `parameter_name`	Eliminar un parámetro por nombre.

Importaciones e inclusiones

Herramienta	Parámetros	Descripción
`add_import`	`file_path`, `import_text`	Añadir una línea `import`/`from`/`#include`. Omite duplicados.
`remove_import`	`file_path`, `import_text`	Eliminar una línea de importación coincidente.
`add_import_name`	`file_path`, `module`, `name`	Añadir un nombre a un `from <module> import a, b` existente. Solo Python.
`remove_import_name`	`file_path`, `module`, `name`	Eliminar un nombre de una importación from de múltiples nombres en Python.

Comentarios y docstrings

Herramienta	Parámetros	Descripción
`add_comment_before`	`file_path`, `target`, `comment`	Insertar un bloque de comentarios inmediatamente antes de un símbolo nombrado. Funciona para Python/Ruby/YAML/TOML (`#`), JS/TS/C/C++/Go/Java (`//` o `/* /`; Javadoc de Java `/* */` soportado).
`remove_leading_comment`	`file_path`, `target`	Eliminar el bloque de comentarios contiguo sobre un símbolo. Reconoce tanto comentarios de línea como bloques `/* ... */` de estilo C de una o varias líneas.
`replace_leading_comment`	`file_path`, `target`, `new_comment`	Reemplazar el bloque de comentarios inicial sobre un símbolo (o insertar uno si no existe).
`replace_docstring`	`file_path`, `target`, `new_docstring`	Reemplazar o insertar un docstring de función/clase de Python. Solo Python.

Edición de Dict/list (JSON, YAML, TOML, Y literales de dict/list a nivel de módulo de Python)

Herramienta	Parámetros	Descripción
`replace_value`	`file_path`, `target`, `content`	Reemplazar el valor de una clave de configuración existente. `target` es la ruta de clave punteada.
`add_key`	`file_path`, `parent_target`, `key`, `value`	Añadir un par clave-valor a un dict/objeto/mapeo/tabla. Para Python, `parent_target` es el nombre de la variable dict; para configuración, una ruta punteada (use `""` para la raíz).
`delete_key`	`file_path`, `target`	Eliminar un par clave-valor. Para Python, el objetivo es `DictName.keyExpr`. Para JSON, también elimina la coma adyacente.
`append_to_array`

ast-editor