rpg-encoder

AI 코딩 에이전트는 grep, cat, find, 파일 읽기를 사용해 코드베이스를 헤매면서 대부분의 도구 호출을 낭비합니다. rpg-encoder는 이를 해결합니다. Tree-sitter로 코드의 시맨틱 그래프를 구축합니다 — 무엇이 무엇을 호출하는지뿐 아니라 모든 함수가 무엇을 하는지까지 — 그리고 단 한 번의 도구 호출로 MCP를 통해 AI 어시스턴트에게 전체 저장소 이해력을 제공합니다.

빠른 시작

claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

명령 하나면 됩니다. Claude Code, Cursor, opencode, Windsurf 또는 MCP 호환 에이전트 어디서나 동작합니다. Rust 툴체인도, 클로닝도, 빌드도 필요 없습니다 — npx가 플랫폼용 사전 빌드 바이너리를 다운로드합니다.

그런 다음 아무 저장소나 열고 에이전트에게 말하세요:

"이 저장소의 RPG를 빌드하고 리프트하세요"

에이전트가 모든 것을 처리합니다: 엔티티를 인덱싱하고(몇 초), 각 함수를 읽고 의도 수준의 피처를 추가하며(몇 분), 이를 시맨틱 계층 구조로 정리한 다음 .rpg/graph.json을 팀을 위해 커밋합니다.

엔티티가 ~100개 이상인 저장소에서는 lifting_status가 에이전트에게 리프팅 루프를 서브 에이전트나 더 저렴한 모델에 위임하라고 지시합니다 — 피처 추출은 패턴 매칭이지 새로운 추론이 아닙니다. 런타임에 서브 에이전트 메커니즘이 없다면 터미널에서 API 키와 함께 rpg-encoder lift --provider anthropic|openai를 실행하세요 — CLI가 에이전트 개입 없이 외부 LLM을 직접 구동합니다. CLI가 끝난 후 세션에서 reload_rpg를 호출하여 업데이트된 그래프를 로드하세요. CLI는 피처가 없는 엔티티만 리프트합니다. 코드 변경 후 피처는 존재하지만 오래된 스테일 엔티티의 재리프팅은 CLI가 아닌 세션 내 MCP 흐름에서 처리합니다.

리프팅이 끝나면 다음을 시도해 보세요:

• "인증을 처리하는 것은 무엇인가요?" — "auth"라는 이름이 없어도 코드를 찾아냅니다

• "데이터베이스 연결에 의존하는 모든 것을 보여주세요"

• "API 엔드포인트에 속도 제한을 추가하는 변경을 계획해 주세요"

Related MCP server: code-intel

grep, cat, find보다 먼저 RPG를 사용하세요

서버 지침은 코드 구조나 동작에 관한 모든 질문에 대해 에이전트가 RPG 도구를 먼저 사용하도록 안내합니다. 이 습관이 중요합니다 — grep, cat, 임시 파일 읽기는 토큰을 소모하고 RPG가 이미 알고 있는 시맨틱 관계를 놓칩니다.

grep, cat, 파일 읽기는 쿼리가 리터럴 텍스트(문자열 검색, 주석, TODO, 로그 메시지)에 관한 것일 때만 사용하세요 — 구조에 관한 것이 아닐 때만요.

작동 방식

1. 파싱 — Tree-sitter가 15개 언어에서 엔티티(함수, 클래스, 메서드)와 의존성 엣지(임포트, 호출, 상속)를 추출합니다.

2. 리프팅 — LLM(당신의 에이전트 또는 Haiku 같은 저렴한 API)이 각 엔티티를 읽고 동사-목적어 피처를 작성합니다: "JWT 토큰 검증", "설정을 디스크에 직렬화".

3. 정리 — 피처가 코드가 수행하는 작업에서 도출된 3단계 시맨틱 계층 구조(영역 → 카테고리 → 하위 카테고리)로 클러스터링됩니다. 파일 트리가 아니라요.

4. 이해 — semantic_snapshot이 전체 그래프를 ~25K 토큰으로 압축합니다. LLM은 한 번 읽고 저장소를 이해합니다.

시맨틱 스냅샷

LLM은 파일을 grep하는 대신 semantic_snapshot을 한 번 호출하여 다음을 받습니다:

• 계층 구조 — 집계 피처를 포함한 모든 기능 영역

• 엔티티 — 영역별로 그룹화된 모든 함수, 클래스, 메서드와 해당 시맨틱 피처

• 의존성 스켈레톤 — 정규화된 이름을 가진 압축 콜 그래프

• 핫스팟 — 가장 많이 연결된 상위 10개 엔티티 (아키텍처 백본)

~25K 토큰이 ~1000개 엔티티를 담습니다. 이는 1M 컨텍스트 윈도우의 2-3%입니다 — LLM은 매 세션을 시작할 때 이미 저장소를 알고 있습니다.

자가 유지 그래프

작업 트리가 변경될 때마다 — 커밋되었든, 스테이징되었든, 커밋되지 않았든 — MCP 서버는 다음 쿼리에 응답하기 전에 자동으로 다시 동기화합니다. (path, size, mtime)에 대한 체인지셋 해시는 동일한 파일의 반복 저장이 한 번의 동기화만 유발하고, 유휴 쿼리는 동기화를 유발하지 않음을 의미합니다. 되돌리기도 감지합니다: 이전에 변경되었던 파일이 HEAD 상태로 돌아오면 그래프가 복원됩니다.

두 가지 리프팅 방식

auto_lift는 저렴한 외부 LLM을 직접 호출합니다 — 코딩 구독이 리프팅 작업에 관여하지 않습니다. api_key_env를 사용하면 환경 변수에서 키를 가져오므로 키가 도구 호출 기록에 절대 나타나지 않습니다.

아키텍처

7개의 Rust 크레이트, 1개의 MCP 서버 바이너리, 1개의 CLI 바이너리:

MCP 도구 (27)

지원 언어

Tree-sitter를 통한 15개 언어:

설치

MCP 서버(권장)

# Claude Code
claude mcp add rpg -- npx -y -p rpg-encoder rpg-mcp-server

# Cursor — add to ~/.cursor/mcp.json
{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"]
    }
  }
}

서버는 현재 작업 디렉터리에서 프로젝트 루트를 자동으로 감지합니다 — 경로 인수가 필요 없습니다.

npm install -g rpg-encoder

# Build a graph
rpg-encoder build

# Query
rpg-encoder search "parse entities from source code"
rpg-encoder fetch "src/parser.rs:extract_entities"
rpg-encoder explore "src/parser.rs:extract_entities" --direction both --depth 2
rpg-encoder info

# Autonomous lifting via API
rpg-encoder lift --provider anthropic --dry-run  # estimate cost
rpg-encoder lift --provider anthropic           # lift with Haiku (~$0.02/100 entities)

# Incremental update
rpg-encoder update

# Pre-commit hook (auto-updates graph on commit)
rpg-encoder hook install

git clone https://github.com/userFRM/rpg-encoder.git
cd rpg-encoder && cargo build --release

그런 다음 MCP 설정이 target/release/rpg-mcp-server를 가리키게 하세요.

문서

• RPG 비교 — GitNexus, Serena, Repomix 및 다른 도구들과의 솔직한 비교

• 논문 충실도 — 연구 논문과의 알고리즘별 비교

• 사용 사례 — RPG가 지원하는 실용적인 예시

• CHANGELOG — 릴리스 내역

영감 및 참고 자료

rpg-encoder는 RPG-Encoder 연구 논문의 이론적 프레임워크를 기반으로 구축되었으며, 코드 인텔리전스 환경 전반의 도구에서 영감을 받은 독자적인 확장 기능을 포함합니다:

• RPG-Encoder 논문 (Luo et al., 2026, Microsoft Research) — 시맨틱 리프팅 모델, 3단계 계층 구조 구축, 점진적 진화 알고리즘, 형식 그래프 모델 G = (V_H ∪ V_L, E_dep ∪ E_feature).

• GitNexus — 사전 계산된 관계형 인텔리전스, 블래스트 반경 분석, Claude Code 훅. 코드 그래프 도구가 필수적이 되려면 보이지 않아야 한다는 것을 보여주었습니다.

• Serena — LSP를 통한 심볼 수준 정밀도. 실시간 코드 인지가 배치 분석보다 더 중요하다는 것을 입증했습니다.

• TOON — LLM 최적화 출력을 위한 토큰 지향 객체 표기법.

이것은 독립적인 구현입니다. 모든 코드는 MIT 라이선스 하의 독창적인 작업입니다. Microsoft와 제휴하지 않았으며 Microsoft의 보증도 받지 않았습니다.

라이선스

MIT