RPG-Encoder

Repository Planning Graph - encode codebases as hierarchical semantic graphs for AI-powered code understanding.

RPG-Encoder is an MCP (Model Context Protocol) server that parses source code repositories into structured semantic graphs. It creates hierarchical nodes (directories, modules, classes, functions, methods, variables) connected by typed edges (contains, imports, calls, inherits, uses_type), enabling AI assistants to efficiently navigate and understand codebases.

Features

• Multi-language parsing: Python (stdlib ast), TypeScript/JavaScript (tree-sitter), with generic fallback
• Hierarchical graph structure: Directory > Module > Class > Method/Function > Variable
• Semantic lifting: Optional LLM-powered descriptions for each node via OpenAI API
• Incremental updates: Git-diff based updates that only re-process changed files
• 6 MCP tools: rpg_init, rpg_update, rpg_search, rpg_fetch, rpg_explore, rpg_status
• Caching: Content-hash based semantic cache to avoid redundant LLM calls

Requirements

• Python >= 3.11
• uv (recommended package manager)

Installation

# Clone the repository
git clone https://github.com/young5lee/rpg.git
cd rpg

# Install dependencies
uv sync

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your OpenAI API key (optional, for semantic lifting)

Configuration

Environment Variables (.env)

Variable	Description	Default
OPENAI_API_KEY	OpenAI API key for semantic lifting	(none)
RPG_OPENAI_MODEL	LLM model for descriptions	gpt-4o-mini
RPG_SEMANTIC_LIFT_ENABLED	Enable/disable semantic lifting	true
RPG_MAX_CONCURRENT_LLM_CALLS	Max parallel LLM requests	5

YAML Config (config/default.yaml)

Controls file scanning behavior: excluded directories, excluded extensions, max file size, and LLM parameters.

Usage

As an MCP Server

Add to your Claude Code MCP configuration (.mcp.json):

{
  "mcpServers": {
    "rpg-encoder": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/rpg", "rpg-encoder"]
    }
  }
}

MCP Tools

Tool	Description
rpg_init	Parse a project and build the full semantic graph
rpg_update	Incrementally update the graph based on git changes
rpg_search	Search nodes by name, semantic description, or file path
rpg_fetch	Get detailed info about a specific node (metadata, source, edges)
rpg_explore	BFS traversal from a node (children, parents, dependencies, dependents)
rpg_status	Check graph statistics and metadata

Example

# Initialize a project graph
rpg_init(project_path="/path/to/your/project")

# Search for authentication-related code
rpg_search(project_path="/path/to/project", query="authenticate", node_type="function")

# Explore what a class contains
rpg_explore(project_path="/path/to/project", node_id="src/auth.py::AuthService", direction="children")

Graph Structure

Directory
  └── Module (file)
        ├── Class
        │     ├── Method
        │     └── Method
        ├── Function
        └── Variable

Edge Types

• contains: Parent-child hierarchy (directory->module, module->class, class->method)
• imports: Module-level import relationships
• calls: Function/method call relationships
• inherits: Class inheritance
• uses_type: Type annotation references

Development

# Run tests
uv run pytest

# Run a specific test file
uv run pytest tests/test_python_parser.py -v

Storage

Graph data is stored in .rpg/ directory within each analyzed project:

.rpg/
  ├── manifest.json       # Graph metadata and statistics
  ├── edges.jsonl          # All edges in JSONL format
  ├── nodes/
  │     ├── index.json     # Node ID -> filename mapping
  │     └── *.json         # Individual node files
  └── cache/
        └── semantic/      # LLM description cache

License

MIT