Rimcp Hybrid

🚀 RiMCP_hybrid

This project offers a set of retrieval and navigation tools for RimWorld source code and XML definitions. Its core objective is to combine lexical retrieval, semantic retrieval, and graph structure navigation to build a service that can be invoked by AI assistants. The project can be used as a command-line tool or integrated into assistants like Claude Desktop or VS Code Copilot in the form of an MCP server. The current source code includes implementations for index building, hybrid retrieval strategies, cross-layer graph relationships, and full source code location and return.

🚀 Quick Start

To start using this system for interaction or integration, the most straightforward way is to run the MCP server component. The service process exposes interfaces through standard input/output or the JSON-RPC protocol. External AI assistants can send retrieval and navigation requests to it and receive structured responses. You can also run each tool command in the command-line mode for index building, hybrid retrieval, or graph queries, which is convenient for offline testing and scripting.

✨ Features

• Combined Retrieval and Navigation: Integrates lexical retrieval, semantic retrieval, and graph structure navigation to provide a comprehensive search and navigation experience for RimWorld source code and XML definitions.
• Dual Usage Modes: Can be used as a command-line tool or integrated into AI assistants as an MCP server.
• Full - featured Source Code Handling: The source code includes functions such as index building, hybrid retrieval strategies, cross - layer graph relationships, and full source code location and return.

📦 Installation

Prerequisites

• .NET 8.0 SDK: Download from microsoft.com/net.
• Python 3.9+: Download from python.org.
• RimWorld Game Files: Copy Def data from your RimWorld installation directory (e.g., C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Data), and export C# source code using ILSpy or dnspy, then store them in the project root directory /RimWorldData.
• Cross - platform Support: Windows (PowerShell), Linux/macOS (Shell scripts).

Setup Steps

1. Set up the project structure

# Clone or download the project
cd RiMCP_hybrid/

# Place RimWorld data (required)
# Copy Def data from your RimWorld installation directory: C:\Program Files (x86)\Steam\steamapps\common\RimWorld\Data
# Export C# source code using ILSpy or dnspy
# Place them in: RimWorldData/ (at the same level as this README)

# Place the embedding model
# mkdir -p src/RimWorldCodeRag/models/
# Download a model like e5 - base - v2 to: src/RimWorldCodeRag/models/e5 - base - v2/
# Note: This project has special optimizations for e5 - base - v2 (adding "query: " and "passage: " prefixes). Other models can also work but may have slightly reduced performance.

2. Set up the embedding environment (one - time, run before building)

# Windows PowerShell:
.\scripts\setup - embedding - env.ps1

# Linux/macOS:
./scripts/setup - embedding - env.sh

3. Build the project

# Build all components (since .gitignore excludes build outputs)
dotnet build

4. Build the index (one - time, run before actual service)

# Create a search index from RimWorld data
cd src/RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData"

5. Start the service

# Terminal 1: Start the embedding server (keep running in the background, default port 127.0.0.1:5000)
# Windows PowerShell:
.\scripts\start - embedding - server.ps1

# Linux/macOS:
./scripts/start - embedding - server.sh

# Terminal 2: Start the MCP server
cd src\RimWorldCodeRag.McpServer
dotnet run

💻 Usage Examples

CLI Query Commands

Hybrid Retrieval Example

cd src\RimWorldCodeRag
dotnet run -- rough - search --query "weapon gun" --kind def --lexical - k 2000 --max - results 10
# The lexical - k parameter defaults to 1000, representing the results obtained from the first - stage literal similarity rough screening. Semantic similarity retrieval will select from these results. A larger k value increases the likelihood of getting the expected results, but the query will take longer.

Find Symbol Usage

dotnet run -- get - uses --symbol "xml:Gun_Revolver" --kind csharp

Find Who Uses a Symbol

dotnet run -- get - used - by --symbol "RimWorld.CompProperties_Power" --kind xml

Get Full Source Code

dotnet run -- get - item --symbol "RimWorld.Building_Door" --max - lines 200
dotnet run -- get - item --symbol "xml:Door"

VS Code Integration

Create or edit %APPDATA%\Code\User\globalStorage\mcp - servers.json:

{
  "mcpServers": {
    "rimworld - code - rag": {
      "command": "dotnet",
      "args": [
        "run",
        "--project",
        "c:/path/to/RiMCP_hybrid/src/RimWorldCodeRag.McpServer"
      ],
      "env": {
        "RIMWORLD_INDEX_ROOT": "c:/path/to/RiMCP_hybrid/index",
        "EMBEDDING_SERVER_URL": "http://127.0.0.1:5000"
      }
    }
  }
}

📚 Documentation

Overall Idea

The project is mainly divided into three parts: the index building pipeline, retrieval tools, and related components of the MCP server.

Index Building Pipeline

The indexing process starts from raw data, which mainly includes two types: C# source code files and XML definition files (Defs). The goal of indexing is not to store the entire repository intact but to extract the smallest retrievable and understandable units. These units should retain enough context for reading and be small enough for precise matching and semantic vector generation.

1. File Scanning and Classification: Scan the file system, read files one by one (glob), and classify them. Record basic metadata such as file path, encoding, and timestamp as input identifiers for index items.
2. Text Block Generation: Split long texts into several blocks. For C# code, split based on syntax symbols (e.g., classes, methods, properties, or comment blocks), and record the start and end offsets of each fragment in the source file. For XML Defs, usually keep the string representation of the entire definition node as a block.
3. Index Storage: Write each block into two different storage layers in parallel: an inverted index for traditional lexical retrieval (implemented with Lucene) and a vector index for semantic retrieval.

Retrieval and Recall

There are four retrieval and recall tools: rough_search, two - direction dependency tree searches (uses and used_by), and full - code recall (get_item). The core idea is to minimize the direct return of useless source code blocks to reduce noise in the large - model context.

Future Iteration Directions

• Abandon Hybrid Retrieval: Abandon the hybrid two - stage retrieval architecture and directly adopt full - vector retrieval. Faiss is expected to provide sufficient algorithm acceleration.
• Edge Weight Algorithm: Design a weight algorithm to assign priority weights to graph edges, reducing noise in the information obtained by the large model.
• Other Improvements: Implement features such as remote embedding API calls and SSE transmission.

Quick Commands and Explanations

Index Building Commands

• Minimum Index Building Command:

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData"

• Embedding Generation Batch Size Example:

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --python - batch 128 --embedding - server "http://127.0.0.1:5000"

• Use a Persistent Embedding Server:

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --embedding - server "http://127.0.0.1:5000"

• New Feature: Use Remote Embedding API:

cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --embedding - server "https://api.openai.com/v1/embeddings" --api - key "sk - 1234567890abcdefghijklmnopqrstuvwxyz" --model - name "text - embedding - 3 - small"

• Force Reconstruction:

# Force reconstruct all indexes
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force all --embedding - server "http://127.0.0.1:5000" --python - batch 512

# Only force reconstruct the Lucene lexical index
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force lucene

# Only force reconstruct the vector embedding index
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force embed --embedding - server "http://127.0.0.1:5000" --python - batch 512

# Only force reconstruct the graph relationship index
cd src\RimWorldCodeRag
dotnet run -- index --root "..\..\RimWorldData" --force graph

MCP Server Configuration

Environment Variable Configuration

# Required: Point to the index folder path created in step 3
$env:RIMWORLD_INDEX_ROOT = "c:\path\to\RiMCP_hybrid\index"

# Optional: Embedding server URL (default: http://127.0.0.1:5000)
$env:EMBEDDING_SERVER_URL = "http://127.0.0.1:5000"

Alternative: appsettings.json Configuration

{
  "McpServer": {
    "IndexRoot": "c:/path/to/RiMCP_hybrid/index",
    "EmbeddingServerUrl": "http://127.0.0.1:5000"
  }
}

Testing the MCP Server

Basic Test

cd src\RimWorldCodeRag.McpServer
# Windows PowerShell:
.\test - mcp.ps1

# Linux/macOS (if available):
./test - mcp.sh

Manual JSON - RPC Test

# Start the server in one terminal
dotnet run

# Test in another terminal
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05"}}' | dotnet run

MCP Tool Explanation

• rough_search: Hybrid semantic search. Use natural language queries to search for RimWorld code symbols and XML definitions.
• get_uses: Dependency analysis (downstream). Find what a symbol depends on.
• get_used_by: Reverse dependency analysis (upstream). Find what uses a symbol.
• get_item: Precise source code retrieval. Retrieve the full source code and metadata of a specific symbol.

🔧 Technical Details

Index Building

The index building process involves scanning files, splitting text, and storing data in an inverted index and a vector index. The inverted index uses Lucene, and the vector index requires text - to - vector conversion.

Retrieval Strategy

The retrieval strategy combines lexical retrieval and semantic retrieval. The rough_search tool first uses Lucene for rough screening and then performs semantic similarity scoring on the selected results.

Graph Relationship

The project builds graph relationships between code elements, which can be used for cross - layer queries, such as finding which Defs use a specific C# component.

📄 License

This project follows the MIT license, which means the code can be freely used by all creatures in the solar system.

⚠️ Important Note

--force forces the clearing/refreshing of existing indexes and rebuilds from scratch. It is suitable for full reconstruction after changes in field storage or splitting rules. For regular updates, you can remove --force to start incremental building, which is faster and retains unchanged data.

💡 Usage Tip

The optimal batch size is related to VRAM. On a Geforce rtx4060 laptop with 16GB VRAM, a batch size of 256 - 512 is appropriate. Exceeding this value will cause some data to be dynamically migrated to the CPU, significantly reducing embedding efficiency. You can experiment to find the optimal batch size. Also, using --embedding - server can connect to a running embedding server, avoiding the overhead of reloading the model for each batch. You need to start the embedding server first: .\scripts\start - embedding - server.ps1.