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

Then use the binary path directly:

{
  "mcpServers": {
    "rpg": {
      "command": "/path/to/rpg-encoder/target/release/rpg-mcp-server"
    }
  }
}

[!TIP] The binary also accepts an optional path argument. Omit it to use the current working directory.

The path argument is optional — the server defaults to the current working directory. This works automatically because MCP clients launch the server from the workspace directory.

Global config (all repos use cwd)

No path needed — each session uses the directory where the MCP client was started:

{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server"]
    }
  }
}

Per-project override (explicit path)

If you need a specific repo, pass the path:

{
  "mcpServers": {
    "rpg": {
      "command": "npx",
      "args": ["-y", "-p", "rpg-encoder", "rpg-mcp-server", "/path/to/this/repo"]
    }
  }
}

The project-level config overrides the global one. Restart Claude Code after creating/modifying configs.

The RPG (Repository Planning Graph) is a hierarchical, dual-view representation from the research papers cited below:

1. Parse — Extract entities (functions, classes, methods) and dependency edges (imports, invocations, inheritance) using tree-sitter. Build a file-path hierarchy.
2. Lift — Your coding agent analyzes entity source code and adds verb-object semantic features (e.g., "validate user credentials", "serialize config to disk") via the MCP interactive protocol (get_entities_for_lifting → submit_lift_results).
3. Hierarchy — Your agent discovers functional domains and assigns entities to a 3-level semantic hierarchy (build_semantic_hierarchy → submit_hierarchy).
4. Ground — Anchor hierarchy nodes to directories via LCA algorithm, resolve cross-file dependency edges.

The graph is saved to .rpg/graph.json and should be committed to your repo — this way all collaborators and AI tools get instant semantic search without rebuilding.

1. Ask your agent to "lift the code" (or call get_entities_for_lifting with a scope)
2. The tool returns entity source code with analysis instructions
3. Your agent analyzes the code and calls submit_lift_results with semantic features
4. The agent continues through all batches automatically, dispatching subagents for large repos
5. After lifting, finalize_lifting → build_semantic_hierarchy → submit_hierarchy

The CLI provides structural operations (no semantic lifting — use the MCP server for that).

# Install
npm install -g rpg-encoder

# Build a graph
rpg-encoder build
rpg-encoder build --include "src/**/*.py" --exclude "tests/**"

# 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

# Incremental update
rpg-encoder update
rpg-encoder update --since abc1234

# Paper-style reconstruction schedule (topological + coherent batches)
rpg-encoder reconstruct-plan --max-batch-size 8 --format text
rpg-encoder reconstruct-plan --format json

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

Create .rpg/config.toml in your project root (all fields optional):

[encoding]
batch_size = 50             # Entities per lifting batch
max_batch_tokens = 8000     # Token budget per batch
drift_threshold = 0.5       # Jaccard distance midpoint reference
drift_ignore_threshold = 0.3  # Below: minor edit, in-place update
drift_auto_threshold = 0.7    # Above: auto-queue for re-routing

[navigation]
search_result_limit = 10

rpg-encoder/
├── rpg-core        Core graph types (RPGraph, Entity, HierarchyNode), storage, LCA
├── rpg-parser      Tree-sitter entity + dependency extraction (15 languages)
├── rpg-encoder     Encoding pipeline, semantic lifting utilities, incremental evolution
│   └── prompts/        Prompt templates (embedded via include_str!)
├── rpg-nav         Search, fetch, explore, TOON serialization
├── rpg-cli         CLI binary (rpg-encoder)
└── rpg-mcp         MCP server binary (rpg-mcp-server)

Do I need an API key or a local LLM?

No. Your connected coding agent (Claude Code, Cursor, etc.) is the LLM. rpg-encoder sends source code to the agent via MCP tools, the agent analyzes it and sends back semantic features. No API keys, no external services, no local model downloads.

How long does lifting take?

Roughly 2 minutes per 100 entities. A small project (50 files, ~200 entities) takes about 5 minutes. A large project (500+ files) should use parallel subagents — your agent handles this automatically. Build and hierarchy steps are near-instant.

What happens when I delete or rename files?

Run update_rpg (or use the pre-commit hook). It diffs against the last indexed commit, removes deleted entities, re-extracts renamed/modified files, and marks changed entities for re-lifting. The graph stays consistent without a full rebuild.

Can I lift only part of the codebase?

Yes. Pass a file glob to get_entities_for_lifting: "src/auth/**", "crates/rpg-core/**", etc. You can also use .rpgignore (gitignore syntax) to permanently exclude files like vendored dependencies or generated code.

What if lifting gets interrupted?

The graph is saved to disk after every submit_lift_results call. Start a new session, call lifting_status, and it picks up exactly where you left off — only unlifted entities are returned.

How does semantic search work?

search_node uses hybrid scoring: BGE-small-en-v1.5 embeddings for semantic similarity plus lexical matching for exact names and paths. Query with intent ("handle authentication") or exact identifiers ("AuthService::validate") — both work.

Should I commit .rpg/ to the repo?

Yes. The .rpg/graph.json file contains the full semantic graph. Committing it means collaborators and CI agents get instant semantic search without re-lifting. The graph is deterministic (sorted maps, stable serialization), so diffs are meaningful.

What about monorepos or very large codebases?

Use scoped lifting to process one area at a time ("packages/api/**", "services/auth/**"). Your coding agent will automatically dispatch parallel subagents for large scopes. The incremental update system (update_rpg) keeps the graph current without full rebuilds. For very large repos, use .rpgignore to exclude vendored code, generated files, and test fixtures.