rpg-encoder

Дайте вашему ИИ-агенту мозг для вашей кодовой базы.

ИИ-агенты для программирования тратят большую часть своих вызовов инструментов на беспорядочные поиски по вашей кодовой базе с помощью grep, cat, find и чтения файлов. rpg-encoder исправляет это. Он строит семантический граф вашего кода с помощью Tree-sitter — не только что вызывает что, но и что делает каждая функция — и даёт вашему ИИ-ассистенту понимание всей репозитория через MCP за один вызов инструмента.

Быстрый старт

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 подскажет вашему агенту делегировать цикл подъёма субагенту или более дешёвой модели — извлечение признаков это сопоставление с образцом, а не новое рассуждение. Если в вашем окружении нет механизма субагентов, запустите rpg-encoder lift --provider anthropic|openai из терминала с API-ключом — CLI напрямую управляет внешней LLM без участия агента. После завершения работы CLI вызовите reload_rpg в вашей сессии, чтобы загрузить обновлённый граф. CLI поднимает сущности без признаков; повторный подъём устаревших сущностей (признаки присутствуют, но устарели после изменений кода) обрабатывается внутрисессионным MCP-потоком, а не CLI.

После подъёма попробуйте:

• "Что обрабатывает аутентификацию?" — находит код, даже если ничего не называется "auth"
• "Покажи всё, что зависит от подключения к базе данных"
• "Спланируй изменение для добавления ограничения скорости на API-эндпоинты"

Используйте RPG перед grep, cat, find

Инструкции сервера говорят вашему агенту сначала обращаться к RPG-инструментам для любых вопросов о структуре или поведении кода. Этот рефлекс важен — grep, cat и разовые чтения файлов сжигают токены и упускают семантические связи, которые RPG уже знает.

Возвращайтесь к grep, cat или чтению файлов только когда запрос касается буквального текста (поиск строк, комментарии, TODO, сообщения логов) — не структуры.

Как это работает

1. Parse — Tree-sitter извлекает сущности (функции, классы, методы) и рёбра зависимостей (импорты, вызовы, наследование) из 15 языков.
2. Lift — LLM (ваш агент или дешёвый API вроде Haiku) читает каждую сущность и записывает признаки «глагол-объект»: «проверять JWT-токены», «сериализовать конфиг на диск».
3. Organize — Признаки группируются в трёхуровневую семантическую иерархию (Область → Категория → Подкатегория), которая формируется на основе того, что делает код, а не файлового дерева.
4. Understand — semantic_snapshot сжимает весь граф до примерно 25K токенов. Ваша LLM читает его один раз и знает репозиторий.

Семантический снимок

Вместо поиска по файлам LLM вызывает semantic_snapshot один раз и получает:

• Иерархия — каждая функциональная область со сводными признаками
• Сущности — каждая функция, класс, метод, сгруппированные по областям, со своими семантическими признаками
• Скелет зависимостей — сжатый граф вызовов с полными именами
• Горячие точки — топ-10 наиболее связанных сущностей (архитектурный хребет)

~25K токенов покрывают примерно 1000 сущностей. Это 2-3% от окна контекста в 1M — LLM начинает каждую сессию, уже зная ваш репозиторий.

Самоподдерживающийся граф

При любом изменении рабочего дерева — закоммиченном, в staging или нет — MCP-сервер автоматически персинхронизируется перед ответом на следующий запрос. Хеш изменений по (path, size, mtime) означает, что повторные сохранения одного и того же файла вызывают одну синхронизацию, а запросы в простое не вызывают никакой. Откаты также обнаруживаются: если ранее изменённый файл возвращается к состоянию HEAD, граф восстанавливается.

Два способа подъёма (lifting)

auto_lift вызывает дешёвую внешнюю LLM напрямую — ваша подписка на кодинг никогда не касается работы по подъёму. Используйте api_key_env для разрешения ключей из переменных окружения, чтобы они никогда не появлялись в транскриптах вызовов инструментов.

Архитектура

Семь Rust-крейтов, один бинарник MCP-сервера, один бинарник CLI:

MCP-инструменты (27)

Сборка и обслуживание (4 инструмента)

Навигация и поиск (5 инструментов)

Планирование и анализ (7 инструментов)

Семантический подъём (11 инструментов)

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

15 языков через Tree-sitter:

Установка

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"]
    }
  }
}

Сервер автоматически определяет корень проекта из текущей рабочей директории — аргумент пути не требуется.

CLI

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 и не одобрен ею.

Лицензия

MIT