Codebase Cartographer

로컬 Python 저장소를 AST 기반 심볼 그래프로 매핑하고, 그 위에서 검증된 다중 파일 리팩터링을 수행하는 MCP 서버입니다.

대부분의 코딩 에이전트는 문자열을 grep하고 찾은 것을 다시 작성하는 방식으로 리팩터링합니다. 그런 접근 방식은 compute() 호출을 우연히 compute라는 이름의 지역 변수와 구분할 수 없고, 이름을 바꿀 때 어떤 12개 파일이 깨질지 전혀 알지 못합니다. 이 서버는 모델에게 실제 인덱스를 제공합니다: 스코프가 해결된 참조, 임포트 그래프, 그리고 검증할 수 없는 것은 쓰기를 거부하는 2단계 편집 프로토콜입니다.

기능

매핑. 저장소를 탐색하고(.gitignore 존중), 모든 모듈을 파싱하고, 함수, 클래스, 메서드, 모듈 수준 변수의 심볼 테이블과 모듈 간 임포트 그래프를 구축합니다.

해석. 실제 스코프 분석(LEGB 체인, global 및 nonlocal 선언, 컴프리헨션 스코프, 월러스 바인딩, 그리고 클래스 본문이 중첩 함수에 보이지 않는다는 규칙)을 사용하여 참조를 찾습니다. 모듈 수준 심볼을 가리는 지역 변수는 그 심볼에 대한 참조가 아니며, 도구는 그 차이를 알고 있습니다.

리팩터링. 심볼을 건드리는 모든 파일에서 이름 변경, 이동, 삭제를 수행합니다 — from x import y, import x + x.y 속성 접근, as 별칭, __all__ 항목을 다시 작성합니다. diff를 본 계획을 적용하기 전에는 아무것도 쓰지 않습니다.

Related MCP server: MCP Python Code Navigation Server

안전 모델

리팩터링은 2단계이며, 첫 번째 단계는 디스크를 건드리지 않습니다.

1. plan_rename_symbol / plan_move_symbol / plan_delete_symbol은 계획 ID, 통합 diff, 경고 목록을 반환합니다. 건드린 모든 파일의 콘텐츠 해시가 기록됩니다.

2. apply_plan은 해당 해시를 다시 확인하고(계획 이후 디스크에서 변경된 것이 있으면 중단), 모든 파일의 새 콘텐츠를 만들고, 각 파일을 다시 파싱하여 파싱할 수 없는 파일이 생기면 쓰기를 거부합니다. 원본은 .cartographer-backups/<plan_id>/에 복사됩니다. 쓰기 중간에 실패하면 모든 파일을 롤백합니다.

추가 안전장치: 매핑된 루트 외부의 경로는 거부됩니다. 메서드 이름 변경은 명시적 allow_heuristic=true가 필요합니다. 속성 일치는 타입 추론 없이는 해결할 수 없기 때문입니다. 여전히 참조가 있는 심볼 삭제는 강제하지 않는 한 거부됩니다.

볼 수 없는 것

정적 분석에는 명확한 한계가 있으며, 도구는 그 한계가 어디인지 말하도록 설계되었습니다. 없는 척하지 않습니다.

find_dynamic_references는 심볼 이름과 일치하는 문자열 리터럴(getattr(mod, "compute"), 플러그인 레지스트리, 점으로 구분된 설정 문자열, 엔트리 포인트 테이블)을 보고하고, 밑줄 접두사 네이티브 모듈의 임포트를 감지합니다. 이러한 경고는 모든 리팩터링 계획에 첨부됩니다.

이것은 구체적으로 중요합니다. stdlib json 패키지의 사본에서 JSONDecodeError 이름을 바꾸면 19개의 Python 참조를 모두 올바르게 다시 작성하지만 패키지는 여전히 깨집니다. _json C 가속기가 C API를 통해 런타임에 그 이름을 해석하기 때문입니다. 순수 Python 분석으로는 그걸 따라갈 수 없습니다. 도구는 네이티브 가속기 임포트를 플래그로 표시하고 수동으로 확인하라고 알려줍니다.

또한 보이지 않는 것: from x import * 재수출(경고로 보고됨), 런타임 몽키 패칭, 다른 언어나 설정 파일의 참조.

도구

설치

pip install -e .

MCP 클라이언트에 등록:

{
  "mcpServers": {
    "codebase-cartographer": {
      "command": "python",
      "args": ["-m", "cartographer"],
      "env": { "CARTOGRAPHER_ROOT": "/path/to/your/repo" }
    }
  }
}

CARTOGRAPHER_ROOT는 map_repository의 기본값일 뿐입니다. 도구는 명시적 root 인수도 받습니다.

일반적인 세션

map_repository(root="~/work/service")
  -> 412 files, 1 import cycle, 38k LOC

impact_of_change(module="service.auth.tokens")
  -> 23 transitive dependents

find_references(qualname="service.auth.tokens.decode_jwt")
  -> 31 references across 12 files

find_dynamic_references(name="decode_jwt")
  -> 1 string literal in service/registry.py:44   <- read this before proceeding

plan_rename_symbol(qualname="service.auth.tokens.decode_jwt", new_name="decode_access_token")
  -> plan 9f2a1c: 31 edits across 12 files, with diff

apply_plan(plan_id="9f2a1c")
  -> written, backed up to .cartographer-backups/9f2a1c/

개발

pip install -e ".[dev]"
pytest

65개의 테스트가 스코프 해결(섀도잉, global, 컴프리헨션, 클래스 본문 가시성), 모든 임포트 스타일의 참조 찾기, 이름 변경/이동/삭제 정확성, 생성된 임포트 스타일, 그리고 적용 단계 보장(오래된 파일 감지, 구문 검증, 롤백)을 다룹니다.

스위트의 가장 강력한 검사는 도구가 자체 소스를 리팩터링한다는 것입니다 — 구현과 테스트에서 함수 이름을 바꾸고, 모듈 간에 이동 — 그 후 전체 스위트가 다시 작성된 사본에 대해 여전히 통과합니다.

요구 사항

Python 3.10+ (ast.alias 위치 속성 사용). Python 소스만.

라이선스

MIT