AST 코드 에디터 MCP 서버

토큰을 많이 소모하고 오류가 발생하기 쉬운 검색-바꾸기(search-and-replace)나 diff 작업에 의존하는 대신, 추상 구문 트리(AST)를 통해 파일을 정밀하게 편집할 수 있는 기능을 AI 코딩 에이전트에 제공하는 강력하고 언어 중립적인 MCP(Model Context Protocol) 서버입니다.

왜 AST 편집인가?

검색/바꾸기, 통합 diff, 전체 파일 다시 쓰기 등 AST가 아닌 모든 편집 형식은 모델이 한 번 본 파일의 텍스트를 완벽하게 복사해야 합니다. 4,000줄짜리 파일에서 공백 하나만 틀려도 편집은 실패합니다. AST 편집은 이 문제를 완전히 피합니다. 모델이 대상(예: LRUCache.get)을 지정하고 새 코드를 제공하면, 파서가 해당 위치를 찾아냅니다.

Geometric AGI는 4개의 모델과 29개의 편집 작업에 걸쳐 모든 주요 형식을 벤치마킹했습니다. AST 편집은 4개 모델 중 3개에서 100% 정확도를 달성한 유일한 형식이었으며, 전체 파일 다시 쓰기보다 출력 토큰을 18배 적게 사용했고 형식 오류는 0건이었습니다. 전체 방법론 및 결과: 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 (벤치마크 코드 및 데이터)

예상 토큰 절감 효과

다른 일반적인 편집 형식 대비 편집당 출력 토큰 절감 효과:

편집 크기	파일 크기	전체 파일 다시 쓰기 대비	통합 diff 대비	검색/바꾸기 대비
1줄 수정	100 LoC	3–5배	~1.5배	~1.5배
함수 본문 다시 쓰기	500 LoC	8–12배	2–3배	2–3배
함수 본문 다시 쓰기	4,000 LoC	15–20배	3–5배	3–5배
함수에 2줄 추가	모든 크기	~20배 (via `prepend_to_body` / `append_to_body`)	5–10배	3–5배

전체 파일을 읽는 것 대비 읽기 작업당 입력 토큰 절감 효과:

읽기 작업	파일 크기	AST 리더 도구	전체 파일 읽기 대비
한 함수의 소스	500 LoC	`read_symbol`	~20배 적은 토큰
한 함수의 소스	2,000 LoC	`read_symbol`	~50-100배 적은 토큰
클래스 API (메서드 10개, 본문 없음)	500 LoC	`read_interface`	~10배 적은 토큰
import 블록만	모든 크기	`read_imports`	~20-50배 적은 토큰
구조적 개요 (이름 + 줄 번호)	모든 크기	`list_symbols`	~15-30배 적은 토큰
한 함수의 시그니처	모든 크기	`get_signature`	~50-200배 적은 토큰

일일 에이전트 사용자의 경우, 세션당 총 토큰을 평균적으로 40-60% 절감할 수 있습니다 (정밀 편집을 통한 출력 절감과 타겟 읽기를 통한 입력 절감을 결합).

절감 효과는 다음과 같은 네 가지 복합적인 효과에서 비롯됩니다:

출력 토큰: 전체 함수 본문을 다시 쓰는 대신 작은 추가 사항에 prepend_to_body / append_to_body 사용
입력 토큰: 전체 파일 대신 필요한 부분만 읽기 위해 read_symbol / read_interface / read_imports 사용 (읽기당 입력 토큰 약 10-20배 감소)
탐색: 전체 파일을 읽는 대신 list_symbols / get_signature 사용
0건의 형식 오류: 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`는 import로 인식됨.
Go	`.go`	✅	✅ `//` + `/* ... */`	—	`struct`, `interface`, 함수, 메서드. 메서드는 리시버로 지정됨: `Cache.Get`은 최상위 `func (c *Cache) Get(...)`으로 확인됨. 그룹화된 `import (...)` 블록 지원.
Java	`.java`	✅	✅ `//` + `/* ... /` + Javadoc `/* ... */`	—	`class`, `interface`, `enum`, `record`; 메서드, 생성자, 필드. 어노테이션(`@Override`, `@Deprecated`)은 편집 시 메서드와 함께 이동함(`modifiers` 노드에 래핑됨). `enum_body_declarations`에 중첩된 Enum 메서드는 `list_symbols`에서 BFS를 통해 발견됨.
JSON	`.json`	✅ (키, 값, 배열)	— (주석 구문 없음)	—
YAML	`.yml`, `.yaml`	✅ (키, 값, 시퀀스)	✅ `#`	—	블록 및 흐름 시퀀스 지원.
TOML	`.toml`	✅ (키, 값, 배열, 테이블)	✅ `#`	—	`[table]` 헤더는 주석 도구에 대해 이름으로 지정 가능.

교차 기능:

데코레이트된 함수(Python @decorator): 데코레이터는 본문/시그니처 편집 시 유지되며 삭제 시 포함됨.
바이트 단위 슬라이싱: 소스 텍스트에서 멀티바이트 문자(이모지, ═, →)를 안전하게 처리.
멱등성 import: 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 필드 선언을 제공해야 합니다.
근거: 호출자가 전체 소스 텍스트를 제공하는 다른 언어(Python, JS/TS, C++)에서 add_field가 작동하는 방식과 일관됩니다. 옵션 (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`	이름으로 매개변수를 제거합니다.

Import 및 Include

도구	매개변수	설명
`add_import`	`file_path`, `import_text`	`import`/`from`/`#include` 줄을 추가합니다. 중복은 건너뜁니다.
`remove_import`	`file_path`, `import_text`	일치하는 import 줄을 제거합니다.
`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 전용.

Dict/list 편집 (JSON, YAML, TOML 및 Python 모듈 수준 dict/list 리터럴)

도구	매개변수	설명
`replace_value`	`file_path`, `target`, `content`	기존 설정 키의 값을 교체합니다.

ast-editor